docs: event tag migration guide

docs/src/main/paradox/migration.md

@@ -1,5 +1,35 @@
 # Migration
 
+## Migrating to version 5.4.0
+
+Release `5.4.0` change the schema of `event_tag` table.
+
+The previous version was using an auto-increment column as a primary key and foreign key on the `event_tag` table. As a result, the insert of multiple events in batch was not performant.
+
+While in `5.4.0`, the primary key and foreign key on the `event_tag` table have been replaced with a primary key from the `event_journal` table. In order to migrate to the new schema, we made a [**migration script**](https://github.com/akka/akka-persistence-jdbc/tree/master/core/src/main/resources/schema) which is capable of creating the new column, migrate the rows and add the new constraints.
+
+By default, the plugin will behave as in previous version. If you want to use the new `event_tag` keys, you need to multiple-phase rollout:
+
+1. apply the first part of the migration script and then redeploy your application on default settings.
+2. apply the second part of the migration script that will migrate the rows and adapt the constraints.
+3. redeploy the application by disabling the legacy-mode:
+
+```config
+jdbc-journal {
+  tables {
+    // ...
+    event_tag {
+      // ...
+      // enable the new tag key
+      legacy-tag-key = false
+    } 
+  }
+}
+// or simply configue via flatting style
+jdbc-journal.tables.event_tag.legacy-tag-key = false
+```
+
+
 ## Migrating to version 5.2.0
 
 **Release `5.2.0` updates H2 to version 2.1.214 which is not compatible to the previous 1.4.200***