# upgrade

A command to change the current version of SurrealDB to another one, including the latest version, specified version, or nightly.

Replace the installed `surreal` executable with another version: the latest stable release, a specific version, or a pre-release build.

> [!NOTE]
> **Before you start** - make sure you’ve [installed SurrealDB](/docs/running/installation.md).

<Synopsis>
surreal upgrade [OPTIONS]
</Synopsis>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--nightly",
            "description": "Install the latest nightly version of SurrealDB."
        },
        {
            "name": "--alpha",
            "description": "Install the latest alpha version of SurrealDB."
        },
        {
            "name": "--beta",
            "description": "Install the latest beta version of SurrealDB."
        },
        {
            "name": "--version",
            "value": "<VERSION>",
            "description": "Install a specific version of SurrealDB."
        },
        {
            "name": "--dry-run",
            "description": "Report what would happen without replacing the currently installed executable."
        },
        {
            "name": "--log",
            "short": "-l",
            "value": "<LOG>",
            "default": "info",
            "env": "SURREAL_LOG",
            "description": "The logging level for the command-line tool. Possible values: `none`, `full`, `error`, `warn`, `info`, `debug`, `trace`."
        }
    ]}
/>

## Example usage

This example shows how you can use the upgrade command to upgrade to the latest version of SurrealDB.

```bash
surreal upgrade
```

## Global install

If SurrealDB is installed globally on your system, you might need to run the upgrade command with elevated permissions, such as `sudo` on Unix-based systems or with administrator privileges in Windows.

```bash
sudo surreal upgrade
```

## Install a specific version

Use the `--version` flag to upgrade to a specific version of SurrealDB.

```bash
surreal upgrade --version [VERSION]

# For example
surreal upgrade --version 2.6.0
```

For a list of available versions and their release notes, see the [releases](/releases) page.

## Install the alpha release

Use the `--alpha` flag to upgrade to the latest alpha version of SurrealDB.

```bash
surreal upgrade --alpha
```

## Install the beta release

Use the `--beta` flag to upgrade to the latest beta version of SurrealDB.

```bash
surreal upgrade --beta
```

## Install the nightly release

Use the `--nightly` flag to upgrade to the latest nightly version of SurrealDB.

```bash
surreal upgrade --nightly
```

## Copies installed by surrealctl

[`surrealctl`](/docs/reference/cli/surrealctl/overview.md) can download a copy of the `surreal` binary for you when a command such as `surrealctl instance sql` needs it. That copy lives in `~/.config/surrealctl/bin/` and is only used when no `surreal` binary is found on `PATH`, so a version installed normally always takes precedence.

## Command help

To see the help information and usage instructions, in a terminal run the `surreal upgrade --help` command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the `upgrade` command.

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

The output of the above command:

```text
Upgrade to the latest stable version

Usage: surreal upgrade [OPTIONS]

Options:
      --nightly            Install the latest nightly version
      --alpha              Install the latest alpha version
      --beta               Install the latest beta version
      --version <VERSION>  Install a specific version
      --dry-run            Don't actually replace the executable
  -h, --help               Print help

Logging:
  -l, --log <LOG>                              The logging level for the command-line tool [env: SURREAL_LOG=] [default: info] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>                The format for terminal log output [env: SURREAL_LOG_FORMAT=] [default: text] [possible
                                               values: text, json]
      --log-socket <LOG_SOCKET>                Send logs to the specified host:port [env: SURREAL_LOG_SOCKET=]
      --log-file-level <LOG_FILE_LEVEL>        Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL=] [possible values:
                                               none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>        Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL=] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>    Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL=] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>  The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT=] [default: text] [possible
                                               values: text, json]
      --log-file-enabled                       Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED=]
      --log-file-path <LOG_FILE_PATH>          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH=] [default: logs]
      --log-file-name <LOG_FILE_NAME>          The name of the log file [env: SURREAL_LOG_FILE_NAME=] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>      The format for log file output [env: SURREAL_LOG_FILE_FORMAT=] [default: text] [possible
                                               values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>  The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION=] [default: daily] [possible
                                               values: daily, hourly, never]
```