Upgrades & patching

Routine upgrades typically follow: quiesce or drain clients if your SLA allows, stop the server gracefully, replace the surreal binary with the new release, then start with unchanged data paths and reviewed configuration.

Read the release notes for breaking changes, new defaults, or removed flags before you cut over. Re-run integration tests against the new version before promoting the change across your organisation.

Across major versions, on-disk formats may change. When documentation requires it, run surreal fix to migrate data between layouts, and follow Migrating from older SurrealDB versions plus any linked guides (for example between specific major lines).

Rolling upgrades in clustered setups usually upgrade one node at a time: verify cluster health, upgrade a member, wait for replication or quorum to stabilise, then continue.

Never skip staging validation for production-like data volumes. If the cluster spans regions, plan maintenance windows that respect dependency order between tiers.

Before any upgrade, take a fresh backup—surreal export for a logical copy and/or a storage snapshot—so you can revert if migration or client incompatibility surfaces after deploy.

Patch security releases promptly: subscribe to SurrealDB advisories, test the patch build in staging, then roll out using the same stop–replace–start or rolling pattern your architecture supports. Document the upgraded version in your asset inventory for compliance reviews.

Automatic data migrations

From SurrealDB 3.3.0, a datastore records the version that last opened it and applies any pending data migrations on startup, before it serves the first query. Migrations are recorded in a cluster-wide ledger, so each one runs once no matter how many nodes start against the same datastore, and an interrupted run resumes rather than restarts. A migration that fails aborts startup.

A datastore created on 3.3.0 or later records the full migration set as applied when it is created, so it never runs a historical migration.

Two consequences for planning an upgrade:

• •

  A downgrade is refused if the datastore has run a migration the older build does not ship. The server reports the migration by name and stops. Reverting past a migration therefore needs surreal export and a reimport into a datastore created by the older version.

• •

  Do not run DEFINE SEQUENCE during a rolling upgrade to 3.3.0. Sequence definitions move to a new key layout. Upgraded nodes still read the old layout, so existing sequences keep working throughout the rollout, but a sequence created on an upgraded node is not visible to a node still on the previous release. Wait until every node has been upgraded.