Merge pull request 'Better document database differences for Pleroma migrations' (#699) from Oneric/akkoma:doc_pleroma-migration-db into develop

Reviewed-on: #699

docs/docs/installation/migrating_to_akkoma.md

@@ -21,6 +21,33 @@ fork of Akkoma - luckily this isn't very hard.
 You'll need to update the backend, then possibly the frontend, depending
 on your setup.
 
+## Backup diverging features
+
+As time goes on Akkoma and Pleroma added or removed different features
+and reorganised the database in a different way. If you want to be able to
+migrate back to Pleroma without losing any affected data, you’ll want to
+make a backup before starting the migration.  
+If you're not interested in migrating back, skip this section
+*(although it might be a good idea to temporarily keep a full DB backup
+just in case something unexpected happens during migration)*
+
+As of 2024-02 you will want to keep a backup of:
+
+- the entire `chats` and `chat_message_references` tables
+
+The following columns are not deleted by a migration to Akkoma, but a migration
+back to Pleroma or future Akkoma upgrades might affect them, so perhaps back them up as well:
+
+- the `birthday` of users and their `show_birthday` setting
+- the `expires_at` key of in the `user_relationships` table
+    *(used by temporary mutes)*
+
+The way cached instance metadata is stored differs, but since those
+will be refetched and updated anyway, there’s no need for a backup.
+
+Best check all newer migrations unique to Akkoma/Pleroma
+to get an up-to-date picture of what needs to be kept.
+
 ## From Source
 
 If you're running the source Akkoma install, you'll need to set the
@@ -34,16 +61,7 @@ git pull -r
 # to run "git merge stable" instead (or develop if you want)
 ```
 
-### WARNING - Migrating from Pleroma Develop
+And compile as usual.
-If you are on pleroma develop, and have updated since 2022-08, you may have issues with database migrations.
-
-Please roll back the given migrations:
-
-```bash
-MIX_ENV=prod mix ecto.rollback --migrations-path priv/repo/optional_migrations/pleroma_develop_rollbacks -n5
-```
-
-Then compile, migrate and restart as usual.
 
 ## From OTP
 
@@ -53,15 +71,44 @@ This will just be setting the update URL - find your flavour from the [mapping o
 export FLAVOUR=[the flavour you found above]
 
 ./bin/pleroma_ctl update --zip-url https://akkoma-updates.s3-website.fr-par.scw.cloud/stable/akkoma-$FLAVOUR.zip
-./bin/pleroma_ctl migrate
 ```
 
-Then restart. When updating in the future, you canjust use
+When updating in the future, you can just use
 
 ```bash
 ./bin/pleroma_ctl update --branch stable
 ```
 
+
+## Database Migrations
+### WARNING - Migrating from Pleroma past 2022-08
+If you are on Pleroma stable >= 2.5.0 or Pleroma develop, and
+have updated since 2022-08, you may have issues with database migrations.
+
+Please first roll back the given migrations:
+
+=== "OTP"
+    ```bash
+    ./bin/pleroma_ctl rollback --migrations-path priv/repo/optional_migrations/pleroma_develop_rollbacks -n5
+    ```
+=== "From Source"
+    ```bash
+    MIX_ENV=prod mix ecto.rollback --migrations-path priv/repo/optional_migrations/pleroma_develop_rollbacks -n5
+    ```
+
+### Applying Akkoma Database Migrations
+
+Just run
+
+=== "OTP"
+    ```bash
+    ./bin/pleroma_ctl migrate
+    ```
+=== "From Source"
+    ```bash
+    MIX_ENV=prod mix ecto.migrate
+    ```
+
 ## Frontend changes
 
 Akkoma comes with a few frontend changes as well as backend ones,
@@ -130,3 +177,4 @@ MIX_ENV=prod mix ecto.rollback --to 20210416051708
 ```
 
 Then switch back to Pleroma for updates (similar to how was done to migrate to Akkoma), and remove the front-ends. The front-ends are installed in the `frontends` folder in the [static directory](../configuration/static_dir.md). Once you are back to Pleroma, you will need to run the database migrations again. See the Pleroma documentation for this.
+After this use your previous backups to restore data from diverging features.