> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt # Managing components How surreal installs, upgrades, pins, switches and removes components, how version names work (3.3.2, 2, beta, nightly), running another version once with +VERSION, and offline or unattended use. `surreal` runs components, and it is the only thing that installs, upgrades or removes them. Five launcher commands cover the whole life of a component: `surreal install`, `surreal upgrade`, `surreal use`, `surreal uninstall` and `surreal version`. A component never installs or upgrades another one, and `surreal ...` always belongs to the component itself. This page explains how components are stored, how to name a version, and how to install, upgrade, pin, switch and remove them. The reference for each command is [Launcher commands](/docs/reference/cli/launcher.md). ## How components are stored Every component version is a separate executable under the SurrealDB home, `~/.surrealdb` unless `SURREAL_CLI_HOME` says otherwise. ```text ~/.surrealdb/components///surreal- the executable ~/.surrealdb/components//pin the version that runs by default ``` Several versions of one component can sit side by side. The **pin** names the one that runs when you type `surreal db ...`, and nothing else decides it. The first install of a component pins it, a later install leaves the pin alone, and only `surreal use`, `surreal upgrade` and `surreal uninstall` move it. That is why installing a second database version cannot quietly change which database `surreal db start` runs. When you run a component, `surreal` looks for its executable in this order: 1. The version named with `+VERSION`, from the store. 2. The pinned version, from the store. 3. A `surreal-` beside the `surreal` executable, which is how a package that ships several binaries together provides them. 4. A `surreal-` on your `PATH`. A name that is not a component, such as `surreal foo`, runs a `surreal-foo` from your `PATH` if one exists, and reports an unknown component otherwise. ## Naming a version Commands that take `COMPONENT[@VERSION]` accept these forms. | Form | Meaning | | --- | --- | | `db` | The newest stable release. While a component has no stable release, its newest beta, then its newest alpha | | `db@3.3.2` | That exact release (`db@v3.3.2` also works) | | `db@2` | The newest stable release on major line 2 | | `db@latest` | The newest stable release | | `db@beta`, `db@alpha` | The newest release on that prerelease channel | | `db@nightly` | The latest nightly build. Only the database publishes nightlies | ## See what is installed ```bash surreal version ``` The table shows each component, the version that runs, where that version comes from, every installed version, and the path it runs from. In the `SOURCE` column, `pinned` is a version the launcher installed and pinned, and `path` is a copy found beside `surreal` or on `PATH`. `surreal version --json` prints the same information as one JSON document, and `surreal --version` prints it on a few lines. ## Install a component ```bash surreal install cloud surreal install db@3.3.2 cloud@0.1.0 ``` `surreal install` downloads each release, checks it against its published SHA-256, runs it once to confirm it starts, and only then puts it in place. The first install of a component becomes its default. Installing another version of a component you already have installs it beside the pinned one and leaves the pin where it was. To make what you install the default, add `--pin`. A version you name exactly becomes the default whatever it was before. A channel's release, such as `db@2` or `db@beta`, becomes the default unless the current default is a later release. ```bash surreal install db@2 --pin ``` ## Upgrade ```bash surreal upgrade ``` With no arguments, `surreal upgrade` upgrades the launcher and every installed component that has a default version. Each follows the channel its default is on: a stable release stays on its major line, so a database on 2.x upgrades to the newest 2.x, and a prerelease follows its own channel. The `--dry-run` flag says what would change without changing it. ```bash surreal upgrade --dry-run ``` To upgrade only some things, or to move to a particular version, name them. ```bash surreal upgrade cloud surreal upgrade db@3.3.2 surreal upgrade db@3 surreal upgrade cli ``` `cli` is the launcher itself. Naming a version moves the default to it, installing it first if needed. The database also takes its familiar release flags, which are shorthand for naming the channel or version. | Flag | Same as | | --- | --- | | `surreal upgrade --nightly` | `surreal upgrade db@nightly` | | `surreal upgrade --beta` | `surreal upgrade db@beta` | | `surreal upgrade --alpha` | `surreal upgrade db@alpha` | | `surreal upgrade --version ` | `surreal upgrade db@` | > [!NOTE] > The database no longer upgrades itself. `surreal db upgrade` is not run and points you to `surreal upgrade db`. ## Pin or switch a version `surreal use` makes an installed version the default. It never downloads. ```bash surreal use db@3.3.2 surreal use db@2 ``` A major line or channel, such as `db@2`, selects the newest installed release on it. To pin a version that is not installed yet, use `surreal install db@ --pin` or `surreal upgrade db@`. ## Run another version once `+VERSION` as the first argument runs one version of whatever follows, for that command only. The pin does not change. If that version is not installed, `surreal` offers to install it first, under the rules in [Offline and unattended use](#offline-and-unattended-use). ```bash surreal +2.6.5 db start --user root --pass secret surreal +2 db export --endpoint http://localhost:8000 backup.surql ``` The version takes the same forms as in `COMPONENT@VERSION`: a release, a major line, or `latest`, `beta`, `alpha` or `nightly`. This is how you run an older database against data that has not been migrated yet, or compare two releases. ## Remove a component ```bash surreal uninstall db@2.7.0 surreal uninstall cloud ``` `surreal uninstall @` removes that version. Naming a component alone removes every version of it and its default. The default version is removed by name only when nothing else is installed, so move the pin with `surreal use` first. ## Offline and unattended use A component is never fetched behind your back. - **At a terminal**, `surreal` names the download host and asks before it installs a missing component. `surreal db start` on a machine without the database offers to install it. - **Unattended** (a CI runner, an agent, `--no-input`, a pipe on standard input, or a dumb terminal), `surreal` makes no request, and exits with code 12 and the command that would install the component. The `SURREAL_CLI_YES` variable does not count as consent to a download in the middle of another command; to install without a prompt, run `surreal install` explicitly, with `--yes` if you wish. - **With `SURREAL_CLI_OFFLINE=1`**, the network is never touched, and a missing component fails at once. In a pipeline, install what you need in an early step. ```bash title="CI step" surreal install db cloud --no-input ``` ## Environment variables | Variable | Effect | | --- | --- | | `SURREAL_CLI_HOME` | Where the SurrealDB home is. Defaults to `~/.surrealdb` | | `SURREAL_CLI_OFFLINE` | `1` forbids every network request | | `SURREAL_CLI_DOWNLOAD_ROOT` | Replaces the download host, for a mirror | | `SURREAL_CLI_NO_BANNER` | Hides the banner above `surreal help` | | `SURREAL_CLI_JSON`, `SURREAL_CLI_PLAIN` | Same as `--json` and `--plain` on the launcher's commands | These are the launcher's variables. Variables that start with `SURREAL_` and not `SURREAL_CLI_` belong to the database, and the launcher never reads them. Cloud's variables start with `SURREAL_CLOUD_`. See [Launcher commands](/docs/reference/cli/launcher.md) for exit codes and the full list. ## Package managers and shared machines Where a package manager such as Homebrew or Nix owns `surreal`, the launcher refuses to install or replace anything in its place, and the package manager upgrades it. Components that the package provides beside `surreal` run before any pinned copy in the store, so a package upgrade is not shadowed by an older pinned version.