Managing components

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

How components are stored

Every component version is a separate executable under the SurrealDB home, ~/.surrealdb unless SURREAL_CLI_HOME says otherwise.

~/.surrealdb/components/<name>/<version>/surreal-<name>   the executable
~/.surrealdb/components/<name>/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. 1.

   The version named with +VERSION, from the store.

2. 2.

   The pinned version, from the store.

3. 3.

   A surreal-<name> beside the surreal executable, which is how a package that ships several binaries together provides them.

4. 4.

   A surreal-<name> 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.

See what is installed

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

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.

surreal install db@2 --pin

Upgrade

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.

surreal upgrade --dry-run

To upgrade only some things, or to move to a particular version, name them.

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.

Pin or switch a version

surreal use makes an installed version the default. It never downloads.

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@<VERSION> --pin or surreal upgrade db@<VERSION>.

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.

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

surreal uninstall db@2.7.0
surreal uninstall cloud

surreal uninstall <component>@<version> 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.

surreal install db cloud --no-input

Environment variables

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