From 6c3e4d788055af049a30bdb3fc7f901e0bb1b001 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20B=C3=B6hmer?= <mail@jan-boehmer.de>
Date: Sat, 10 Jan 2026 21:14:27 +0100
Subject: [PATCH] Added documentation about the database conversion command

---
 docs/installation/choosing_database.md | 24 ++++++++++++++++++++++--
 docs/usage/console_commands.md         |  1 +
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/docs/installation/choosing_database.md b/docs/installation/choosing_database.md
index 8a070120..27d70e54 100644
--- a/docs/installation/choosing_database.md
+++ b/docs/installation/choosing_database.md
@@ -21,8 +21,8 @@ differences between them, which might be important for you. Therefore the pros a
 are listed here.
 
 {: .important }
-You have to choose between the database types before you start using Part-DB and **you can not change it (easily) after
-you have started creating data**. So you should choose the database type for your use case (and possible future uses).
+While you can change the database platform later (see below), it is still experimental and not recommended. 
+So you should choose the database type for your use case (and possible future uses).
 
 ## Comparison
 
@@ -180,3 +180,23 @@ and it is automatically used if available.
 For SQLite and MySQL < 10.7 it has to be emulated if wanted, which is pretty slow. Therefore it has to be explicitly enabled by setting the
 `DATABASE_EMULATE_NATURAL_SORT` environment variable to `1`. If it is 0 the classical binary sorting is used, on these databases. The emulations
 might have some quirks and issues, so it is recommended to use a database which supports natural sorting natively, if you want to use it.
+
+## Converting between database platforms
+
+{: .important }
+The database conversion is still experimental. Therefore it is recommended to backup your database before performing a conversion, and check if everything works as expected afterwards.
+
+If you want to change the database platform of your Part-DB installation (e.g. from SQLite to MySQL/MariaDB or PostgreSQL, or vice versa), there is the `partdb:migrations:convert-db-platform` console command, which can help you with that:
+
+1. Make a backup of your current database to be safe if something goes wrong (see the backup documentation).
+2. Ensure that your database is at the latest schema by running the migrations: `php bin/console doctrine:migrations:migrate`
+3. Change the `DATABASE_URL` environment variable to the new database platform and connection information. Copy the old `DATABASE_URL` as you will need it later.
+4. Run `php bin/console doctrine:migrations:migrate` again to create the database schema in the new database. You will not need the admin password, that is shown when running the migrations.
+5. Run the conversion command, where you have to provide the old `DATABASE_URL` as parameter: `php bin/console partdb:migrations:convert-db-platform <OLD_DATABASE_URL>`
+   Replace `<OLD_DATABASE_URL` with the actual old `DATABASE_URL` value (e.g. `sqlite:///%kernel.project_dir%/var/app.db`):
+   ```bash
+   php bin/console partdb:migrations:convert-db-platform sqlite:///%kernel.project_dir%/var/app.db
+   ```
+6. The command will purge all data in the new database and copy all data from the old database to the new one. This might take some time and memory depending on the size of your database.
+7. Clear the cache: `php bin/console partdb:cache:clear`
+8. You can login with your existing user accounts in the new database now. Check if everything works as expected.
diff --git a/docs/usage/console_commands.md b/docs/usage/console_commands.md
index 2ca35ec4..b42bb757 100644
--- a/docs/usage/console_commands.md
+++ b/docs/usage/console_commands.md
@@ -68,6 +68,7 @@ docker exec --user=www-data partdb php bin/console cache:clear
   deleted!*
 * `settings:migrate-env-to-settings`: Migrate configuration from environment variables to the settings interface.
 The value of the environment variable is copied to the settings database, so the environment variable can be removed afterwards without losing the configuration.
+* `partdb:migrations:convert-db-platform`: Convert the database platform (e.g. from SQLite to MySQL/MariaDB or PostgreSQL, or vice versa).
 
 ## Database commands