Migrations and upgrades

Use compatible API and migrations image versions supplied for your environment. Obtain the registry, image names, version tags, and pull credentials from io.finnet. The documentation version v2.0 is not a container tag.

Prepare the database

Create an empty database and a user with DDL privileges (CREATE, ALTER, and DROP on the target schema, not just DML). Run migrations once against it before you start the app, and re-run them on every upgrade before you roll the app.

Run migrations

Configure the database connection in your environment file using the Postgres settings. Run the migrations image once before starting or upgrading the API:

docker run --rm --env-file ./prod.env <registry>/<migrations-image>:<tag>

If you run migrations from the io.sign source checkout, use:

DB_HOST=<host> DB_PORT=5432 DB_NAME=<db> DB_USER=<user> DB_PASSWORD=<pw> \
  npm run database:migrate

After the initial migration, follow Start the service.

Upgrades and rollback

Upgrade

1. Pull the new image tag.
2. Run migrations against the live database using Run migrations.
3. Roll both the REST API and gRPC API deployments to the new image tag, then the orchestrator, then cron.

Roll back

1. Roll both the REST API and gRPC API deployments back to the previous image tag, then the orchestrator, then cron. Complete all application rollbacks before reverting the database schema.
2. Revert the last migration by running the migrations image with an override command. Use the current release's tag, the one you just deployed, because the down() function for the newly applied migration lives in that image. Each run reverts one migration.

docker run --rm --env-file ./prod.env \
  <registry>/<migrations-image>:<tag> \
  npm run database -- migrate:down

🚧

Back up before reverting migrations

Rolling back a migration can be destructive: it may drop columns or reverse data transforms. Take a database backup before you run migrate:down in production.

Troubleshooting

If migrations fail with a Postgres error such as permission denied for schema "public", check that the database user has DDL privileges, not just DML.