add some mdbook documentation

1 files changed, 38 insertions, 0 deletions

diff --git a/doc/migration.md b/doc/migration.md
new file mode 100644
index 0000000..089ebf7
--- /dev/null
+++ b/doc/migration.md
@@ -0,0 +1,38 @@
+# Migrating the Database
+
+With some updates the database serialization for changes. This requires a
+migration process. You need to follow this procedure either with every update.
+
+## 1. Export the database
+
+Use the `jellytool` of the previous version to export the database to JSON.
+
+```sh
+mv /path/to/db /path/to/db.old # Rename the DB to avoid conflict later
+jellytool.old migrate export /path/to/db.old export /tmp/jdb
+```
+
+## 2. Run migrations on the JSON dump
+
+> This is not implemented yet. It usually just works without anyway.
+
+## 3. Import the database
+
+Now import your library back to where it usually lives using the `jellytool` of
+the current version.
+
+```sh
+jellytool migrate export /path/to/db import /tmp/jdb
+```
+
+## 4. Delete old Databases
+
+Delete the old database and the JSON dump, they are not required anymore.
+
+> [!CAUTION]
+> Confirm that everything still works and no data ist lost
+
+```
+rm /path/to/db.old
+rm -r /tmp/jdb
+```