Upgrading SurrealDB

This document records per-release operational notes for SurrealDB administrators: wire-format rotations, removed features, configuration changes, and other impacts that aren't apparent from version numbers alone. Read this before deploying a new release onto an existing database.

For the release process (how releases are cut and shipped), see RELEASING.md. For end-user release notes, see https://surrealdb.com/releases.

v3.1.0 — rev-2 on-disk wire format for Value, Array, Object, Set

Impact: irreversible on-disk format rotation for every row that contains a Value, Array, Object, or Set.

Important: once a v3.1.0+ binary writes a row of any of these types, the bytes are in the new revision(2, optimised) format. A pre-v3.1.0 binary cannot read them. Binary downgrade is one-way for any database the new build has touched, even with no other schema change. The runtime MajorVersion guard (surrealdb/core/src/kvs/ds.rs::check_version) does not catch this — the rotation happens inside the existing major version, so an older binary opening a v3.1.0-written database will see the expected MajorVersion and then fail at the per-row deserialize_revisioned step when it encounters the unrecognised rev-2 envelope.

What still works:

• Reading existing rev-1 rows under v3.1.0+ (forward migration is fully supported; the multi-revision walker handles both encodings transparently).
• All SurrealQL semantics — no query-level behaviour change.
• Replication and failover between v3.1.0+ nodes.

What doesn't:

• Restoring a backup taken from v3.1.0+ onto a pre-v3.1.0 binary.
• Failover from v3.1.0+ data to a pre-v3.1.0 node in a mixed cluster.
• Re-mounting a v3.1.0+ on-disk store with a pre-v3.1.0 build.

If you need the option to roll back, take and verify a logical backup (surreal export) before running v3.1.0+ against the live data — that backup is plain SurrealQL and can be replayed onto any binary that supports its statements.

See the rationale block at the top of the Value enum in surrealdb/core/src/val/mod.rs for the implementation-side explanation, and doc/UPGRADING.md will gain a new section per future release that introduces another operational impact of this kind.