# Versions and upgrades

Change the SurrealDB release an instance runs, and what happens to the instance during the upgrade.

Change the SurrealDB release an instance runs from **Instance settings → Version** in [SurrealDB Studio](https://app.surrealdb.com).

You pick the release when you [create the instance](/docs/manage/instances/create.md). The running image is then replaced for you, so there are no binaries to swap and no rolling restart to orchestrate yourself.

## Changing the version

1. Open the instance in [SurrealDB Studio](https://app.surrealdb.com).
2. Go to **Instance settings → Version**.
3. Select the release you want. Each entry links to its release notes.
4. Apply the change.

Only upgrades are offered. The flow will not move an instance to an older release. On-disk data written by a newer version is not readable by an older one.

On paid instance types a snapshot is taken before the change, and it appears in the [backup list](/docs/manage/instances/backups.md) of the instance. That snapshot is the way back if the new version behaves differently than you expected. Restoring it produces a new instance on a compatible version.

> [!NOTE]
> Pre-release builds, such as nightly or beta tags, are only offered when they have been enabled for your organisation. Keep production on stable releases unless you are deliberately testing a preview.

## What happens during the upgrade

| Plan | Behaviour |
| --- | --- |
| **Start** | The single node restarts on the new image. Expect a short window where connections fail and clients reconnect. |
| **Scale** | The new image rolls through nodes one at a time while the storage layer keeps data consistent. The cluster stays reachable, and query capacity dips while each node restarts. |

Timing depends on the instance size, the dataset size, and the cluster layout. Watch [metrics and logs](/docs/manage/instances/monitoring.md) during and after the change. Confirm that query latency and error rates return to their previous level.

## Planning an upgrade

1. **Read the [release notes](https://surrealdb.com/releases)** for the target version and for every version between it and your current one. Look for breaking changes, changed defaults, and removed options.
2. **Test against a non-production instance** on the target version, with your own application and SDK versions. SDK and server versions are released independently, so check both.
3. **Confirm you have a recent snapshot.** For a copy that lives outside the platform, take a [logical export](/docs/manage/instances/import-and-export.md) instead.
4. **Apply the change**, then run your smoke tests. Cover health checks, the queries your critical paths depend on, and anything that touches features named in the release notes.

For a major-version change that migrates data on disk, work through [Migrating from older SurrealDB versions](/docs/build/migrating/from-old-surrealdb-versions/overview.md) against a staging instance before you touch production.

`surrealctl instance update` sets the version from a terminal, and `surrealctl instance status` reports what an instance is running. The second command is useful for checking a fleet at once. See [surrealctl instances](/docs/manage/surrealctl/instances.md).

## Compared with self-hosting

Self-hosted operators replace the `surreal` binary, run `surreal fix` where a release requires it, and coordinate the restart order across nodes themselves. On an instance, the control plane does that work.

The underlying mechanics, and the release-specific migration notes, are in [Self-hosted upgrades and patching](/docs/manage/self-hosted/upgrades-and-patching.md).