chore: database-migrations.md

website/docs/docs/on-premises/upgrading/database-migrations.md

@@ -6,14 +6,16 @@ title: Database migrations
 
 Schema migrations are run automatically on start up, unless the [PACTFLOW_DATABASE_AUTO_MIGRATE](../environment-variables#pactflow_database_auto_migrate) environment variable is set to `false`. Data migrations are also run automatically on start up, after the schema migrations, and ensure that any data inserted into the database by a previous version of the application are migrated. This allows you to perform no-downtime, rolling upgrades across your cluster, ensuring any data inserted into latest database schema by the nodes running the previous version of the application are safely migrated.
 
+Each schema migration will only ever be applied to the database once. Each data migration is executed during every application start up, as this provides the simplest mechanism for ensuring that all data is correctly migrated during rolling deployments. If this is undesirable, then manual migrations can be performed.
+
 ## Manual migration
 
-The migrations can be run manually against the database before upgrading the PactFlow Docker image if desired (however, this is generally not necessary).
+The migrations can be run manually against the database before upgrading the PactFlow Docker image if desired. The `db-migrate` entrypoint will run both the schema and the data migrations.
 
 ```sh
 docker pull quay.io/pactflow/enterprise
 
-# Identify the current version before migrating
+# Identify the current version before migrating, in case a rollback is required
 docker run --rm \
   --env PACTFLOW_DATABASE_URL="postgres://username:password@host:port/database" \
   --entrypoint db-version \
@@ -26,6 +28,13 @@ docker run --rm \
   quay.io/pactflow/enterprise
 ```
 
+To perform a manual no-downtime deployment that does not rely on the "auto migrate" feature:
+
+1. Execute the `db-migrate` entrypoint from the Docker image of the desired version. This will run both the schema and data migrations.
+2. In the Pactflow application environment variables, set the `PACTFLOW_DATABASE_AUTO_MIGRATE` environment variable to `false`, and update the Pactflow image version to the desired tag. Allow your container management system to apply the rollout of the new Docker image.
+3. Execute the `db-migrate` entrypoint again. This will run only the data migrations, as the schema migrations have already run. It is necessary to run the data migrations again to ensure that any data that was inserted into the new schema via the old API (during the rolling upgrade) is correctly migrated.
+
+
 ## Rollback
 
 To perform a manual rollback, first identify the number of the migration target using the PactFlow image with the tag you wish to rollback to.