# Upgrades & patching

Upgrade SurrealDB safely: binary replacement, surreal fix for major versions, migrations, and cluster rolling upgrades.

**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`](/docs/reference/cli/surrealdb-cli/commands/fix.md) to migrate data between layouts, and follow [Migrating from older SurrealDB versions](/docs/build/migrating/from-old-surrealdb-versions/overview.md) 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`](/docs/reference/cli/surrealdb-cli/commands/export.md) 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

_(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:

- **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`](/docs/reference/cli/surrealdb-cli/commands/export.md) 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.

> [!NOTE]
> The first migration fixes a key layout in which `DEFINE SEQUENCE` definitions overlapped tables whose names begin with `sq`. On 3.0 to 3.2, a database containing such a table fails `INFO FOR DB`, fails `REMOVE DATABASE` - leaving the database undroppable - and fails an export that includes sequences. No sequence needs to exist for this to happen. Upgrading to 3.3.0 repairs it.