Deployment

Upgrade and support window

The v0.1.9 → head upgrade reference — migration counts, the irreversible migration families, the backup precondition, rollback limits, and what is and is not supported today.
Provisional Ledger class: provisional
Verified 2026-11-17Migration counts and rollback limits are verified from the tree; no version support window is signed

This page is the release-level upgrade reference. The step-by-step procedure — drain, stop, snapshot, migrate, provision, start, and the digest-based rollback — is on the v1-single-node profile page. This page adds what that procedure depends on: how many migrations you are applying, which ones cannot be undone, what must exist before you start, and what a rollback cannot recover.

Versions and migrations

The proposed reference path is v0.1.9 → current main head. The PostgreSQL counts below are .up.sql files under infra/migrations/postgres/, applied in order by the migration runner; the ClickHouse counts are .up.sql files under infra/migrations/clickhouse/, and only a deployment that runs ClickHouse applies them.

PointPostgreSQL migrationsClickHouse migrations
v0.1.9395
6f12c96c (2026-11-10)586
current main head766

An upgrade from v0.1.9 therefore applies 37 PostgreSQL migrations. The v1-single-node profile runs PostgreSQL migrations only; the one additional ClickHouse migration applies only to a deployment that runs ClickHouse separately. The counts are a property of the checkout you build from, not of the tag you are leaving: the migrate one-shot is built from the target checkout, so build and migrate from the same commit.

The v0.1.9 row is checkable rather than remembered: infra/migrations/postgres/testdata/released/v0.1.9.sha256 pins the digest of all 78 migration files (39 up, 39 down) as they stood at the tag, and TestUnit_ReleasedMigrationSetImmutable fails if any of them changes.

Precondition: a snapshot and a restore you have run

The upgrade and the rollback both rest on one database snapshot, so the snapshot is not optional and neither is the proof that it restores.

  • Take the snapshot after draining and stopping, as the profile page's procedure states.
  • Rehearse the restore before the change window. 05.v1-single-node.md requires both directions to be rehearsed from a real snapshot of the previous release, with the commands, image IDs, and row counts recorded.
  • Keep the window between snapshot and rollback short, and keep token revocations, deletion requests, and legal-hold records outside the database so they can be re-applied.

The command surface exists, and it fails closed rather than pretending. make v1-backup (TYPE=full|diff|incr), make v1-restore and make v1-pitr TARGET=<ISO8601> wrap pgBackRest (Makefile:232-242 → infra/scripts/dev-tool.sh:709-731), and before any of them reaches pgBackRest they require a real infra/backup/pgbackrest/pgbackrest.conf: the shipped .example is refused by path identity and a missing file is refused too (dev-tool.sh:556-580). A restore is destructive and verified, not fire-and-forget: it stops Postgres, restores with --delta, checks PG_VERSION before the server starts, and prints ok only once pg_is_in_recovery() is false — then leaves the cluster running and verified (infra/scripts/platform/pgbackrest-restore.sh:276-281,314-319,330-344,401). make v1-pitr is supported: it restores to the timestamp with --type=time --target-action=promote and rewrites the ISO-8601 T and Z forms that pgBackRest's parser rejects (pgbackrest-restore.sh:157-181). Rehearse a target on a scratch volume first — make v1-pitr TARGET=… SCRATCH_VOLUME=<name> restores beside the live cluster, stops nothing, and leaves the restored copy stopped for inspection (:241-274). The restore runbook exists — engineering/runbooks/RUNBOOK-restore.md, linked from RUNBOOKS.md — and it requires you to establish what should be absent from a source outside the restored database, because a receipt inside that database is a row of the database being restored (RUNBOOK-restore.md:274-294). The committed drill evidence is still a pg_dump fallback report that records rpo_pass: false, and no restore has been rehearsed end to end for this release. So the precondition is reachable only with an operator-built repository configuration, and the rehearsal is an operator step the upgrade depends on rather than one it performs.

Irreversible migration families

Migrations are forward-only in production: starting an older image against the migrated schema is not a supported rollback (DEPLOYMENT.md §7.2). Two families cannot be undone by a down migration even in development:

  1. Memory lifecycle (000045_memory_lifecycle). The down migration is safe only before lifecycle events have been consumed or used as authority. Once published, lifecycle history is not reconstructible (infra/migrations/postgres/000045_memory_lifecycle.down.sql:1-3). A rollback after a consumer has acted on outbox rows needs an explicit recovery plan, not the down file.
  2. ClickHouse analytics migrations (infra/migrations/clickhouse/). ClickHouse has no transactional rollback for most DDL, and the down files drop the tables they created. Applying a destructive up, or running a down against a live database, destroys analytics rows with no recovery path — which is why the migration suite gates destructive DDL before it can be applied (infra/migrations/clickhouse/destructive_ddl_unit_test.go:11-13).

Both families make the snapshot the only recovery path. Neither is repaired by re-running a migration.

Rollback limits

Rollback restores the snapshot and starts the previous image digests; it is not a schema downgrade. The limits that matter:

  • Forward-only schema. An older image against the migrated schema is unsupported. The rollback unit is the snapshot, not the down file.
  • Stop the stack; do not rebuild. A rebuild replaces the images you are trying to recover. Retag each recorded image ID onto its Compose name and start with --no-build.
  • Transient Redis state is lost. Reset the extraction queue, the result backend, and the caches; re-submit extraction work accepted after the snapshot.
  • Database state moves back in time. Re-apply token and PAT revocations, user suspensions, legal-hold creations and clearances, accepted deletion requests, and completed forgets, in that order, before reopening traffic. A hold must be replayed before the deletion it blocks is judged. The profile page lists the full sequence.
  • Capability-login verifiers revert. They live in pg_authid. The recreated one-shots rewrite them from the current .env, so a credential rotated after the snapshot must still be in .env when the stack starts.

A rollback that has never been executed is not evidence. Rehearse both directions and record both. The migration span now has an executed rehearsal — TestUpgradeRehearsal_V019ToHead runs v0.1.9 → head → v0.1.9 → head against seeded tenant rows in the db-migrate CI job, removing the tombstoned memory before it rewinds because 000045's down guard refuses to roll past one. That is a test database, not a deployment: it starts no application, restores no snapshot, exercises no concurrency, and rewinds no further than v0.1.9.

Support window

No version support window or support matrix is signed. What is true today:

  • There is exactly one supported deployment profile, v1-single-node, selected by ADR-0097. Kubernetes, Helm, and HA topologies are outside it.
  • There is no hosted offering and no hosted support claim.
  • No document states how long a released version receives fixes, or which version-to-version skips are supported. The only upgrade path this page proposes is the v0.1.9 → head reference path; its migration counts are read from the tree. That one skip is exercised at migration level with data present (see Rollback limits) and no other is: no upgrade has been rehearsed end to end — no deployment, no application start, no concurrency, and no ClickHouse.

A support window and support matrix are therefore an open owner decision, not a policy this page can state. The remaining v1 gaps record the item as P1-46 in 35-v1-remaining-gaps-staged-2026-11-13.md §3, and the open owner questions are §9 of the same document. Until the owner signs a window, treat every release as supported only at the version you are running, upgrade one rehearsal at a time, and do not promise a customer a maintenance or upgrade window from this page.