Upgrade and support window
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.
| Point | PostgreSQL migrations | ClickHouse migrations |
|---|---|---|
v0.1.9 | 39 | 5 |
6f12c96c (2026-11-10) | 58 | 6 |
current main head | 76 | 6 |
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.mdrequires 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:
- 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. - 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 destructiveup, or running adownagainst 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
downfile. - 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.envwhen 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.
Related
- v1-single-node profile — start, upgrade, and rollback procedure.
- Production readiness — the promotion checklist and open gates.
- Environment variables — the configuration registry.

