docs: event tag migration guide (akka#781)

* docs: event tag migration guide * Update docs/src/main/paradox/migration.md Co-authored-by: Renato Cavalcanti <[email protected]> * Update docs/src/main/paradox/migration.md Co-authored-by: Renato Cavalcanti <[email protected]> * Update docs/src/main/paradox/migration.md Co-authored-by: Renato Cavalcanti <[email protected]> * fix: guide for multi-phase rollout * Update docs/src/main/paradox/migration.md Co-authored-by: Renato Cavalcanti <[email protected]> * Update docs/src/main/paradox/migration.md Co-authored-by: Renato Cavalcanti <[email protected]> --------- Co-authored-by: Renato Cavalcanti <[email protected]>
Bugsource · Jan 8, 2024 · 66dd4b0 · 66dd4b0
1 parent 4c5eab8
commit 66dd4b0
Showing 1 changed file with 33 additions and 3 deletions.
diff --git a/docs/src/main/paradox/migration.md b/docs/src/main/paradox/migration.md
@@ -1,11 +1,41 @@
 # Migration
 
-## Migrating to version 6.0.0
+## Migrating to version 5.4.0
 
-**Release `6.0.0` updates H2 to version 2.1.212 which is not compatible to the previous 1.4.200***
+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 run a multiple-phase rollout:
+
+1. apply the first part of the migration script and then redeploy your application with the 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***
 
 H2 has undergone considerable changes that broke backwards compatibility to make H2 SQL Standard compliant.
-For migration please refer to the H2 [migration guide](http://www.h2database.com/html/migration-to-v2.html)
+For migration please refer to the H2 [migration guide](https://www.h2database.com/html/migration-to-v2.html)
 
 
 ## Migrating to version 5.0.0