Migrations and upgrades
Prepare the io.sign database, run migrations, and upgrade or roll back the self-hosted backend
The migrations image creates and updates the io.sign database schema. Run it before you first start the backend, and again before every upgrade.
Use the compatible API and migrations image versions that io.finnet supplies for your environment, together with the registry, image names, version tags, and pull credentials. The documentation version v2.0 isn't 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 only 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. It applies the schema, then writes the default settings:
docker run --rm --env-file ./prod.env <registry>/<migrations-image>:<tag>After the initial migration, follow Start the service.
Upgrades and rollback
Upgrade
- Pull the new image tag.
- Run migrations against the live database using Run migrations.
- Run the webhooks migrations image against the webhooks database. See Webhooks service.
- Roll both the REST API and gRPC API deployments to the new image tag, then the orchestrator, then cron, then the webhooks service.
Upgrade every component to the same release. Check the release notes from io.finnet for any steps specific to that release.
Roll back
-
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.
-
Revert the last migration by running the migrations image with an override command. Use the tag of the release you're rolling back from, not the previous release. Each run reverts one migration.
docker run --rm --env-file ./prod.env \ <registry>/<migrations-image>:<tag> \ npm run database -- migrate:down
Rolling back a migration can drop columns or reverse data transforms, and you can't undo that without a backup. Take a database backup before you run
migrate:downin 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 only DML.
Updated 17 days ago