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

# surreal upgrade db

How to upgrade the database component with the launcher command surreal upgrade db, to the latest release, a specific version, or an alpha, beta or nightly build. surreal db upgrade is refused.

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`.

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

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

```text
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.
```

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--nightly",
            "description": "Upgrade the database to the latest nightly build. Equivalent to `db@nightly`."
        },
        {
            "name": "--alpha",
            "description": "Upgrade the database to the latest alpha release. Equivalent to `db@alpha`."
        },
        {
            "name": "--beta",
            "description": "Upgrade the database to the latest beta release. Equivalent to `db@beta`."
        },
        {
            "name": "--version",
            "value": "<VERSION>",
            "description": "Upgrade the database to this version. Equivalent to `db@<VERSION>`."
        },
        {
            "name": "--dry-run",
            "description": "Say what would change without changing it."
        }
    ]}
/>

The launcher's other options, such as `--json`, `--plain`, `--yes` and `--no-input`, apply as well. They are listed in the [launcher reference](/docs/reference/cli/launcher.md).

## 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.

```bash
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.

```bash
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](/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](/docs/explore/cli/components.md).

## 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.

```bash
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.

```bash
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`](/docs/reference/cli/cloud.md) 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.

```bash
surreal upgrade --help
```

The output of the above command:

```text
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
```