Upgrading

Before you upgrade#

1. Read the changelog from your version to the target, especially "Breaking changes" and the "Upgrade notes" of each release in between.
2. Back up the database: an on-demand backup, taken just before (see Backup and restore).
3. Keep tools and plugins within the nistor-core range they declare; see Versioning.
4. If you set NAMESPACE_ISOLATION_ENFORCED, read the changelog's team-scoped access note first: the variable is retired, and a deployed instance with it set true and no ACCESS_ENFORCEMENT kind enforced refuses to start.

Which path is supported#

Upgrade one minor release at a time (1.0 → 1.1 → 1.2), to the latest patch of each. Two rules make skipping risky:

• Something deprecated stays for at least one minor release, with a warning, before it is removed. If you skip that release, you never see the warning.
• Database changes come in two steps: a release first adds the new tables or columns (expand), and a later release removes the old ones (contract). nistor migrate --check-gap <distribution.lock> checks, without migrating anything, that every removal the target release would apply has its addition already run by an earlier release. It exits with code 3 when it has not: upgrade through the release in between first.

Only the latest minor of the current major is supported (see Versioning).

Order#

1. Upgrade the platform train together: the images (nistor-runtime, nistor-shell) and any package you install beside them move to the same version.
2. Run the database migrations once, with one process: on GCP execute the migrate Cloud Run job (nistor migrate from the release image). Migrations only move forward.
3. Start the roles. They check the schema revision at startup. A role whose database is behind logs DATABASE SCHEMA IS BEHIND THE CODE and answers 503 on /ready until the migrations have run.
4. Upgrade tools and plugins to versions that support the new core API.

Per installation method#

Google Cloud, with the reference root#

1. In your deployment repository, change the ref of every module source to the new release tag (?ref=v<version>), and the image references to the new release's images, copied into your registry.

2. terraform plan, review, terraform apply. The services move to the new images.

3. Execute the migrate job (output migrate_job_name):

   gcloud run jobs execute <migrate job name> --region=<region> --project=<project> --wait
   

4. Check the installation as in Install on GCP.

If your pipeline deploys for you, it runs the same steps: new images, migrate job, then traffic to the new revisions.

Docker Compose, from source#

git fetch --tags && git checkout v<version>
make runtime-image
docker compose up -d

The migrate service runs first, and the other roles start once it has finished.

Docker Compose, from published images#

If your compose file runs the published images (see Quickstart), change their tags to the new version, then docker compose pull and docker compose up -d.

Between release candidates and releases#

A release candidate (1.0.0-rc.1) is for testing and may change before 1.0.0. Do not run one against data you cannot restore.

The legacy names are retired by two consecutive releases, an expand and a contract (Versioning). Upgrade through the expand release: nistor migrate --check-gap <lock> refuses a release whose contract revisions need an expand that no earlier release ran.

Rolling back#

Migrations only move forward. Once a release has migrated the database, an older release's migrate refuses it: Refused: a newer release migrated this database … a release never migrates back. So you cannot roll back by deploying the older release again (its lock, its images, its migrate job): the deployment stops at the migrate step and nothing changes. This holds even when the newer release's migrations were expand-only.

There are two ways back:

• Send the traffic back to the previous revisions, and keep the newer schema. On Google Cloud, route each role's traffic to the revision that served before the upgrade (gcloud run services update-traffic <service> --to-revisions=<previous revision>=100 --region=<region>); a deploy pipeline does this by itself when a release fails its checks. Do not run the older release's migrate job. The added tables and columns stay, and the older code ignores them. This works only while the newer release's migrations were expand-only; the changelog's upgrade notes say when a release is not like that. On Docker Compose there are no previous revisions to route to: every role waits for the migrate service, which refuses the newer database, so the older images do not start.
• Restore the backup taken before the upgrade, together with the previous images. This is the only way back to the older schema. Anything written since that backup is lost.

Notes per release#

Release-specific steps are listed in the changelog section of each version. There are none before 1.0.0. Each release's notes carry this section when it has upgrade steps:

### Upgrade notes

- **Before:** what to do before upgrading (a setting to add, a backup to take).
- **Migrations:** expand-only, or the contract revisions it applies and the release that added their expands.
- **After:** what to check or change once it runs.
- **Rolling back:** whether the previous images work on the migrated database.