---
title: "Upgrades & patching"
description: "Upgrade SurrealDB safely: binary replacement, major-version data migration, automatic data migrations, and cluster rolling upgrades."
canonical_url: "https://surrealdb.com/docs/operate/self-hosted/upgrades-and-patching"
section: "Self-hosted"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Upgrades & patching

Upgrade SurrealDB safely: binary replacement, major-version data migration, automatic data 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. Follow [Migrating from older SurrealDB versions](/docs/operate/upgrading/overview.md) 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](/docs/operate/upgrading/2x-to-3x.md). https://github.com/orgs/surrealdb/discussions/4809
Moving from 1.x to 2.x is described in [Migrating from 1.x to 2.x](/docs/operate/upgrading/1x-to-2x.md), which also lists the breaking changes in SurrealQL and the SDKs. [`surreal db fix`](/docs/reference/cli/db/commands/fix.md) 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 db export`](/docs/reference/cli/db/commands/export.md) for a logical copy and/or a storage snapshot - so you can revert if migration or client incompatibility surfaces after deploy. Some minor upgrades can only be reverted this way, including [2.6 to 2.7](/docs/operate/upgrading/26-to-27.md#rolling-back-to-26) and [3.2 to 3.3](/docs/operate/upgrading/32-to-33.md#rolling-back-to-32).

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:

- **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 db export`](/docs/reference/cli/db/commands/export.md) taken before the upgrade into a datastore created by the older version. See [Rolling back to 3.2](/docs/operate/upgrading/32-to-33.md#rolling-back-to-32).
- **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.

> [!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.4, 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. SurrealDB 3.2.5 skips such a table when it lists sequence definitions, so these operations work again. Upgrading to 3.3.0 repairs the key layout.
