From d0a1ee6ac4180c9acb8d0a436feca2e4e6d41d11 Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Fri, 31 Jul 2026 11:45:46 -0400 Subject: [PATCH 1/3] docs: document MariaDB/MySQL binary logging prerequisite Migrations create triggers on the roms table, which MariaDB/MySQL refuse when binary logging is on and the RomM user lacks SUPER, aborting startup with a raw traceback. Add the fix (log_bin_trust_function_creators or a BINLOG ADMIN/SUPER grant) to the Databases page, and point at it from troubleshooting, the quick start, and the Unraid guide. Refs rommapp/romm#3932 Co-Authored-By: Claude Opus 5 (1M context) --- docs/getting-started/quick-start.md | 2 +- docs/install/databases.md | 37 ++++++++++++++++++++++++++++- docs/install/unraid.md | 2 +- docs/troubleshooting/index.md | 1 + 4 files changed, 39 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index bd79db92..98a164fc 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -57,7 +57,7 @@ From the directory containing your `docker-compose.yml`: docker compose up -d ``` -On the first run Docker will pull `rommapp/romm:latest` and `mariadb:latest`, bring up the database, wait for the healthcheck, then bring up the app. Verify everything is running: +On the first run Docker will pull `rommapp/romm:latest` and `mariadb:latest`, bring up the database, wait for the healthcheck, then bring up the app. If you dropped the `romm-db` service and pointed RomM at a MariaDB or MySQL server you already run, read the [binary logging prerequisite](../install/databases.md#binary-logging-and-trigger-privileges) first, because migrations fail at startup without it. Verify everything is running: ```sh docker ps -f name=romm diff --git a/docs/install/databases.md b/docs/install/databases.md index d627ed96..f9762a51 100644 --- a/docs/install/databases.md +++ b/docs/install/databases.md @@ -10,7 +10,7 @@ RomM uses SQLAlchemy + Alembic for persistence. Three drivers are supported, so | Driver | `ROMM_DB_DRIVER` | Image | Default port | Notes | | ---------------------------------- | ---------------- | ------------- | ------------ | ---------------------------------------------- | | **MariaDB** (default, recommended) | `mariadb` | `mariadb:11` | `3306` | What the reference compose uses. Well-tested. | -| **MySQL** | `mysql` | `mysql:8` | `3306` | Largely interchangeable with MariaDB for RomM. | +| **MySQL** | `mysql` | `mysql:8` | `3306` | Largely interchangeable with MariaDB for RomM, but see [binary logging](#binary-logging-and-trigger-privileges). | | **PostgreSQL** | `postgresql` | `postgres:16` | `5432` | Use if you already run Postgres. | ## MariaDB (default) @@ -66,6 +66,41 @@ services: retries: 5 ``` +## Binary logging and trigger privileges + +RomM's migrations create triggers on the `roms` table. MariaDB and MySQL refuse trigger DDL when binary logging is enabled and the connecting user lacks `SUPER`, so the container aborts during startup with: + +``` +sqlalchemy.exc.OperationalError: (mariadb.OperationalError) You do not have the SUPER +privilege and binary logging is enabled (you *might* want to use the less safe +log_bin_trust_function_creators variable) +ERROR: [RomM][init] Failed to run database migrations +``` + +This mainly affects external or managed database servers, because binary logging is on by default on MySQL 8 and is commonly enabled on hardened or replicated MariaDB instances. The `mariadb:11` container from the reference Compose is not affected out of the box. + +Both fixes below have to be applied by an admin or root database user rather than the RomM user. The quickest one sets the global flag, though it is lost when the database restarts: + +```sql +SET GLOBAL log_bin_trust_function_creators = 1; +``` + +To make it survive a restart, add it under `[mysqld]` in the server's option file and restart the database (see [Configuring MariaDB with option files](https://mariadb.com/docs/server/server-management/install-and-upgrade-mariadb/configuring-mariadb/configuring-mariadb-with-option-files)). That file is usually `my.cnf`, or `custom.cnf` under `/config` on the linuxserver image: + +```cnf +[mysqld] +log_bin_trust_function_creators = 1 +``` + +Alternatively, grant the privilege to the RomM user itself: + +```sql +GRANT BINLOG ADMIN ON *.* TO 'romm-user'@'%'; -- MariaDB 10.5+ +GRANT SUPER ON *.* TO 'romm-user'@'%'; -- older MariaDB, or MySQL +``` + +Restart RomM once the change is in place. A migration that failed this way is safe to re-run, so it picks up from wherever it stopped and completes. + ## PostgreSQL ```yaml diff --git a/docs/install/unraid.md b/docs/install/unraid.md index c74bee2a..ad67d030 100644 --- a/docs/install/unraid.md +++ b/docs/install/unraid.md @@ -34,7 +34,7 @@ docker network ls # confirm `romm` is listed 1. Install MariaDB -From **Apps** → search `mariadb`. Only the [official `mariadb`](https://hub.docker.com/_/mariadb) and [linuxserver/docker-mariadb](https://github.com/linuxserver/docker-mariadb/pkgs/container/mariadb) templates are supported. **Prefer the official one.** +From **Apps** → search `mariadb`. Only the [official `mariadb`](https://hub.docker.com/_/mariadb) and [linuxserver/docker-mariadb](https://github.com/linuxserver/docker-mariadb/pkgs/container/mariadb) templates are supported. **Prefer the official one.** If you point RomM at an existing MariaDB or MySQL server instead, check the [binary logging prerequisite](databases.md#binary-logging-and-trigger-privileges) before starting the app. ![community apps search results for MariaDB](https://github.com/user-attachments/assets/76f4b6ef-5b63-454f-9357-d2920b9afd0e) diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md index 9776abe5..18c31501 100644 --- a/docs/troubleshooting/index.md +++ b/docs/troubleshooting/index.md @@ -9,6 +9,7 @@ description: Diagnose common issues by symptom - Container crashes immediately → check `docker logs romm`. If it's `invalid host in "tcp://..."` you're on Kubernetes, see [Kubernetes Troubleshooting](kubernetes.md). - Database connection errors → verify `DB_HOST`/`DB_PASSWD` match your DB container, and that the DB has finished initialising (first run takes longer than you'd think). +- `Failed to run database migrations` with `You do not have the SUPER privilege and binary logging is enabled` → your MariaDB/MySQL server needs `log_bin_trust_function_creators = 1`, or the RomM database user needs the privilege granted (see [Databases → Binary logging and trigger privileges](../install/databases.md#binary-logging-and-trigger-privileges)). - "Page not found" on first load → wait, because initial migrations and resource seeding take a minute. ## No Setup Wizard From c2cad770b8e1d57ec7295562ab8b25c6348ab554 Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Fri, 31 Jul 2026 11:48:57 -0400 Subject: [PATCH 2/3] docs: fix formatting and add language to traceback fence Co-Authored-By: Claude Opus 5 (1M context) --- docs/install/databases.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/install/databases.md b/docs/install/databases.md index f9762a51..047d95a1 100644 --- a/docs/install/databases.md +++ b/docs/install/databases.md @@ -7,11 +7,11 @@ description: Supported database drivers RomM uses SQLAlchemy + Alembic for persistence. Three drivers are supported, so pick based on what you already run. -| Driver | `ROMM_DB_DRIVER` | Image | Default port | Notes | -| ---------------------------------- | ---------------- | ------------- | ------------ | ---------------------------------------------- | -| **MariaDB** (default, recommended) | `mariadb` | `mariadb:11` | `3306` | What the reference compose uses. Well-tested. | +| Driver | `ROMM_DB_DRIVER` | Image | Default port | Notes | +| ---------------------------------- | ---------------- | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- | +| **MariaDB** (default, recommended) | `mariadb` | `mariadb:11` | `3306` | What the reference compose uses. Well-tested. | | **MySQL** | `mysql` | `mysql:8` | `3306` | Largely interchangeable with MariaDB for RomM, but see [binary logging](#binary-logging-and-trigger-privileges). | -| **PostgreSQL** | `postgresql` | `postgres:16` | `5432` | Use if you already run Postgres. | +| **PostgreSQL** | `postgresql` | `postgres:16` | `5432` | Use if you already run Postgres. | ## MariaDB (default) @@ -70,7 +70,7 @@ services: RomM's migrations create triggers on the `roms` table. MariaDB and MySQL refuse trigger DDL when binary logging is enabled and the connecting user lacks `SUPER`, so the container aborts during startup with: -``` +```text sqlalchemy.exc.OperationalError: (mariadb.OperationalError) You do not have the SUPER privilege and binary logging is enabled (you *might* want to use the less safe log_bin_trust_function_creators variable) From 6a4894d606255e4483722504826a802dab81deca Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Fri, 31 Jul 2026 11:49:45 -0400 Subject: [PATCH 3/3] docs: drop binary logging pointer from driver table Co-Authored-By: Claude Opus 5 (1M context) --- docs/install/databases.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/install/databases.md b/docs/install/databases.md index 047d95a1..f8145332 100644 --- a/docs/install/databases.md +++ b/docs/install/databases.md @@ -7,11 +7,11 @@ description: Supported database drivers RomM uses SQLAlchemy + Alembic for persistence. Three drivers are supported, so pick based on what you already run. -| Driver | `ROMM_DB_DRIVER` | Image | Default port | Notes | -| ---------------------------------- | ---------------- | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- | -| **MariaDB** (default, recommended) | `mariadb` | `mariadb:11` | `3306` | What the reference compose uses. Well-tested. | -| **MySQL** | `mysql` | `mysql:8` | `3306` | Largely interchangeable with MariaDB for RomM, but see [binary logging](#binary-logging-and-trigger-privileges). | -| **PostgreSQL** | `postgresql` | `postgres:16` | `5432` | Use if you already run Postgres. | +| Driver | `ROMM_DB_DRIVER` | Image | Default port | Notes | +| ---------------------------------- | ---------------- | ------------- | ------------ | ---------------------------------------------- | +| **MariaDB** (default, recommended) | `mariadb` | `mariadb:11` | `3306` | What the reference compose uses. Well-tested. | +| **MySQL** | `mysql` | `mysql:8` | `3306` | Largely interchangeable with MariaDB for RomM. | +| **PostgreSQL** | `postgresql` | `postgres:16` | `5432` | Use if you already run Postgres. | ## MariaDB (default)