Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

fix(db): explain unsupported MySQL upgrade options (#7063)

Thomasfb435eff4135
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.",
);
}