How can I safely roll back a FaunaDB cluster after a failed schema migration upgrade?

Confirmed facts

FaunaDB treats each successful fauna schema push as an immutable version. A failed migration leaves the cluster with the last good schema version still active; no automatic rollback occurs. Pushing an older schema version does not delete data—it only changes the validation rules applied to future reads and writes. If the failed migration attempted to modify existing data, additional transformation may be required before the old schema can be reapplied.

Likely explanation of the mixed state

When a migration job stops part‑way, some nodes may have acknowledged the new schema version while others remain on the previous version, causing a temporary version mismatch. The cluster will not converge until all nodes agree on a single schema version.

Steps to restore consistency

1. Identify the last known good schema version

   fauna schema list

   Look for the version with status ACTIVE that preceded the failed push. Note its name or number.
2. Determine if data was altered (diagnostic detail that changes the recommendation)
   • If the failed migration only added/changed indexes, constraints, or collection definitions, the existing data remains compatible.
   • If it attempted to transform documents (e.g., field renames, type changes), you must first apply the inverse transformation or restore from a snapshot.
   Ask: Did the failed migration attempt to modify existing document data?
3. Push the old schema version (only if data is compatible)

   fauna schema push <path-to-old-schema> --name <old-version-name>

   This re‑applies the prior validation rules across the cluster.
4. Verify the schema version across all nodes

   fauna schema list

   Ensure only the intended version appears with status ACTIVE.

fauna schema get <old-version-name>

Confirm the definition matches the expected prior schema.
5. Run a sanity check
   • Write a test document to a collection.
   • Read it back and verify that no validation errors occur.
6. If data incompatibility exists or you prefer a guaranteed clean state
   1. Ensure you have a recent snapshot taken before the migration (FaunaDB backup or export).
   2. Restore the snapshot to a new cluster or replace the current data using fauna backup restore.
   3. After restore, push the old schema version (which will already be the version stored in the snapshot).
   4. Validate that no transactions committed after the snapshot are lost; if such transactions exist, they must be replayed manually.

Verification checklist before deciding on a recovery path

• fauna schema list shows a single active version.
• fauna schema get <version> matches the expected schema definition.
• A read/write test on a small subset of data succeeds without schema errors.
• If using a snapshot, confirm the restore completed successfully and that the backup timestamp precedes the migration start.