From fb435eff4135629827f5ea2a0dedf870f591147f Mon Sep 17 00:00:00 2001 From: Thomas Date: Wed, 7 Oct 2026 11:14:45 +0200 Subject: [PATCH] fix(db): explain unsupported MySQL upgrade options (#7063) --- apps/docs/docs/advanced/mysql-to-sqlite.mdx | 8 +++++++- packages/core/src/infrastructure/db/env.ts | 5 ++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/apps/docs/docs/advanced/mysql-to-sqlite.mdx b/apps/docs/docs/advanced/mysql-to-sqlite.mdx index 1bc53e24d..1127cda56 100644 --- a/apps/docs/docs/advanced/mysql-to-sqlite.mdx +++ b/apps/docs/docs/advanced/mysql-to-sqlite.mdx @@ -4,7 +4,13 @@ title: Move from MySQL to SQLite # Move from MySQL to SQLite -Homarr v2 supports SQLite (the default) and PostgreSQL. MySQL installations must convert before upgrading to v2. +Homarr v2 supports SQLite (the default) and PostgreSQL. MySQL and MariaDB are no longer supported; migrate before upgrading to v2. Changing the database connection settings alone does not move your existing data. + +## Choose a database + +Use SQLite for an instance with its own persistent database volume. Do not synchronize a running SQLite database between Swarm nodes with tools such as Syncthing. + +For a shared database in a multi-node deployment, use PostgreSQL. The converter below targets **SQLite only**; Homarr does not currently provide a MySQL-to-PostgreSQL converter. PostgreSQL connection settings are documented under [environment variables](/docs/advanced/environment-variables#database), but those settings do not import your MySQL data. Keep your previous Homarr image and database available until you have a validated migration plan. The standalone converter is tested against the **Homarr v1.77.1 database schema** and writes its corresponding SQLite database. Homarr v2 applies its normal migrations when it first opens that file. The converter does not modify the source database. diff --git a/packages/core/src/infrastructure/db/env.ts b/packages/core/src/infrastructure/db/env.ts index b153118d9..3e949f3d8 100644 --- a/packages/core/src/infrastructure/db/env.ts +++ b/packages/core/src/infrastructure/db/env.ts @@ -8,7 +8,10 @@ if ( /^(mysql|mariadb):/i.test(process.env.DB_URL ?? "") ) { throw new Error( - "MySQL and MariaDB are no longer supported. Migrate your database to SQLite or PostgreSQL before starting Homarr.", + "MySQL and MariaDB are no longer supported in Homarr v2. Migrate your database to SQLite or PostgreSQL before starting Homarr. " + + "Keep your previous Homarr image and back up your database before upgrading. " + + "For SQLite conversion instructions and PostgreSQL guidance for shared deployments, see https://homarr.dev/docs/advanced/mysql-to-sqlite. " + + "Changing DB_DRIVER or DB_URL alone does not migrate your data.", ); }