From 80a60f9db49489c63820436c397e938e8a357be6 Mon Sep 17 00:00:00 2001 From: Beth Skurrie Date: Thu, 22 Aug 2024 11:50:52 +1000 Subject: [PATCH] chore: database-migrations.md --- .../on-premises/upgrading/database-migrations.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/website/docs/docs/on-premises/upgrading/database-migrations.md b/website/docs/docs/on-premises/upgrading/database-migrations.md index 400f8737..df31afaa 100644 --- a/website/docs/docs/on-premises/upgrading/database-migrations.md +++ b/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.