surreal upgrade db

The launcher upgrades the database, so the command is surreal upgrade db, not a surreal db subcommand. It replaces the installed database component with another version: the latest stable release, a specific version, or a pre-release build. This page sits with the database commands because it is the way to change the version of surreal db.

surreal upgrade db[@<VERSION>] [OPTIONS]

surreal db upgrade is refused, and exits with status 2 and a message that points to the launcher command:

error: The CLI manages the database's versions, so `surreal db upgrade` is not run. Use `surreal upgrade db`, or `surreal upgrade db@<VERSION>` for a particular release.

The launcher's other options, such as --json, --plain, --yes and --no-input, apply as well. They are listed in the launcher reference.

Example usage

Upgrade the database to the newest release on the channel it already follows, a stable release along its major line or a pre-release along its own channel.

surreal upgrade db

Running surreal upgrade with no component upgrades the launcher and every component that has a default version, the database included. Use surreal upgrade cli to upgrade the launcher alone.

Install a specific version

Name the version after db@, or use the --version flag.

surreal upgrade db@3.2.4

# The same, with the flag
surreal upgrade db --version 3.2.4

For a list of available versions and their release notes, see the releases page. To keep an older version installed beside a newer one, use surreal install db@<VERSION> and choose between them with surreal use, as described in Components.

Install the alpha, beta or nightly release

Use the --alpha, --beta or --nightly flag, or the matching db@alpha, db@beta or db@nightly form.

surreal upgrade db --alpha
surreal upgrade db --beta
surreal upgrade db --nightly

Preview an upgrade

Use --dry-run to see what would change without changing it.

surreal upgrade db --dry-run

Where the database is installed

The launcher keeps each installed version of the database under its home directory, ~/.surrealdb by default or the directory in SURREAL_CLI_HOME, and an upgrade installs the new version there. surreal cloud uses this same installation when surreal cloud instance sql, import or export needs the database, and offers to install it if it is missing.

Command help

To see the help information and usage instructions, run surreal upgrade --help in a terminal.

surreal upgrade --help

The output of the above command:

Upgrade the CLI and every installed component

Usage: surreal upgrade [OPTIONS] [COMPONENT[@VERSION] | cli]...

Arguments:
  [COMPONENT[@VERSION] | cli]...  Upgrade only these, each to the newest release on the channel its
                                   default follows - a stable release along its major line, a
                                   prerelease along its own channel - or to the version named,
                                   either way. `cli` is the launcher. Without any: the launcher and
                                   every component with a default version

Options:
      --nightly            Upgrade the database to the latest nightly build: `db@nightly`
      --alpha              Upgrade the database to the latest alpha release: `db@alpha`
      --beta               Upgrade the database to the latest beta release: `db@beta`
      --version <VERSION>  Upgrade the database to this version: `db@<VERSION>`
      --dry-run            Say what would change without changing it
      --json               Print one JSON document on stdout
      --plain              Plain text: no tables, no colour, no animation
      --color <WHEN>       When to use colour [default: auto] [possible values: auto, always, never]
  -q, --quiet              Print only results and errors
  -y, --yes                Answer yes to every question
      --no-input           Never prompt; fail where a question would be asked
  -h, --help               Print help