> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrades and rollback

> Check release compatibility and understand the limits of application rollback.

Formation exposes release compatibility metadata at
`GET /.well-known/mesh-release`. Deployment tooling can use it when deciding
whether a specific older application image has been approved as a rollback
target. **The endpoint does not perform a rollback**, and this repository does
not implement a hosted deployment controller.

## Inspect a release

```sh theme={null}
curl --fail --silent --show-error \
  https://mesh.example.com/.well-known/mesh-release
```

The response is public JSON with `Cache-Control: no-store`:

| Field | Meaning |
| - | - |
| `protocol` | Metadata format version; currently `1`. |
| `schema` | SHA-256 fingerprint of the compiled, ordered migration filenames and SQL bytes. |
| `rollbackTo` | Full Git revisions explicitly approved as predecessors of this build. |

These are build facts, not tenant data or secrets. The fingerprint describes the
binary's embedded migrations, not a live inspection of its database. It also
does not identify the running image or Git revision; deployment tooling must
obtain that identity independently from its image registry or hosting provider.

The current approval file is empty. There are **no approved predecessors** in
this build. An older image without this endpoint cannot supply the metadata
required by this contract.

## What an approval means

This contract supports application rollback only across **identical migration
bundles**, and only after explicit compatibility testing. Matching fingerprints
alone are insufficient: application code can change stored data formats,
background work, authentication behavior, or external protocols without changing
SQL migrations.

Approval does not reverse migrations, restore a backup, bypass startup guards,
undo external effects, or certify arbitrary earlier releases.

## Approving a predecessor

For a release maintainer adding a revision to
[`internal/release/rollback-predecessors.json` (repository)](https://github.com/TextureHQ/formation/blob/main/internal/release/rollback-predecessors.json):

1. Verify that the candidate and exact predecessor have identical migration
   bundles. Retain their immutable images and establish their Git revisions.
2. On an isolated database with representative data, run the predecessor, upgrade
   to the candidate, and exercise affected writes, jobs, settings, and sign-in.
3. Stop the candidate, run that exact predecessor against the resulting database
   and configuration, and verify reads, writes, sign-in, and recovery.
4. Record the rehearsal in the release PR and add the full predecessor revision.
   Recheck or remove approval when later behavior changes invalidate it.

The JSON file accepts unique, full 40-character lowercase Git revisions. Its
presence records an explicit maintainer decision; the runtime does not run the
compatibility rehearsal itself.

## Deployment-controller responsibilities

A controller adopting this contract must retain the previous healthy image
identity and compatibility evidence before replacement. It must compare the
actual candidate and predecessor, refuse missing or incompatible metadata, and
retain evidence outside a process that may become unhealthy. Whether a hosted
service supplies these behaviors depends on that service's implementation;
Formation's public manifest alone does not establish them.

For an incompatible release, use a corrective release or a separately planned
database restore. A restore can lose subsequent writes and cannot undo external
side effects. Preserve the required key material with the database; see
[secrets and recovery](https://docs.formation.texturehq.com/secrets-and-recovery.md).

Implementation: [`internal/release/manifest.go` (repository)](https://github.com/TextureHQ/formation/blob/main/internal/release/manifest.go)
and [`internal/migrate` (repository)](https://github.com/TextureHQ/formation/tree/main/internal/migrate).

## Continuous rehearsal

Every PR and main push now rehearses each declared predecessor with
`tools/release/rehearse-rollback.sh <full-revision>`. It rejects different migration
bundles, builds both exact source versions, boots old → new → old against an
isolated database, compares runtime schema fingerprints, and verifies encrypted
writes made before and after upgrade using both binaries. Application/configuration
compatibility still requires review; this drill cannot prove every connector or
external side effect. Do not approve a predecessor merely because this test passes.

Revision `26804ad1ef531d8c0110d3adf170510f16d9ebe2` was rehearsed on
2026-10-14, before the content-key and dreaming-cycle migrations landed. Those
migrations invalidate its schema compatibility with the current build, so that
approval has been removed. This build declares no compatible predecessor.

When adding migrations, remove incompatible approvals instead of bypassing the
check. An empty list explicitly means no rollback support for that release; the
console keeps the disabled rollback action visible with its reason. Keep the
previous image in the registry. Before a customer has run this approved predecessor,
this release does not invent historical eligibility for older installations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.