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. Follow Migrating from older SurrealDB versions and the guide for your pair of major versions. Moving from 2.x to 3.x uses a v3-compatible export from the 2.x data, imported into 3.x, as described in Migrating from 2.x to 3.x. surreal fix converts 1.x data to the 2.x layout, and only 2.x binaries implement it.

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

Available since: v3.3.0

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:

• •

  Reverting past a migration needs an export. From 3.3.0, a build that lacks a migration the datastore has recorded refuses to start and names the migration. A build older than 3.3.0 records no migrations and checks only the major version, so it starts on a migrated datastore and reads it wrongly. In both cases the way back is to restore a surreal export taken before the upgrade into a datastore created by the older version. See Rolling back to 3.2.

• •

  Define new sequences once every node runs 3.3.0. The migration copies each sequence definition to a new key layout and leaves the original in place, so existing sequences keep working on nodes of either version throughout the rollout. A sequence created on an upgraded node exists only in the new layout, so a node still on the previous release cannot see it.