Change the SurrealDB release an instance runs from Instance settings → Version in SurrealDB Studio.
You pick the release when you create the instance. 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
Open the instance in SurrealDB Studio.
Go to Instance settings → Version.
Select the release you want. Each entry links to its release notes.
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 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.
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 during and after the change. Confirm that query latency and error rates return to their previous level.
Planning an upgrade
Read the release notes for the target version and for every version between it and your current one. Look for breaking changes, changed defaults, and removed options.
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.
Confirm you have a recent snapshot. For a copy that lives outside the platform, take a logical export instead.
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 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.
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.