macOS

The install script installs surreal, the SurrealDB command-line tool, and the database with it. surreal installs, updates and runs the database as a component, so surreal db start works from then on without a network connection. Homebrew is also available.

Installing with the install script

The install script downloads surreal and the database for your platform and CPU type, checks each download against its published SHA-256, and installs surreal into /usr/local/bin. If that folder is not writable, it installs into ~/.surrealdb and prints the PATH line to add.

curl -sSf https://install.surrealdb.com | sh

Pass options to the script after sh -s --. The database is installed by default; --no-db installs surreal alone, and the database installs on first use instead.

curl -sSf https://install.surrealdb.com | sh -s -- --no-db

See Install the SurrealDB CLI for every option, including the SURREAL_CLI_INSTALL_DB environment variable and installing the Cloud component alongside.

Installing a specific version of the database

Use -v or --version to install and pin a database release.

curl -sSf https://install.surrealdb.com | sh -s -- --version <version>

SurrealDB 4.0 is in beta. To install it, use --beta instead. See Install the beta.

Updating

Once installed, surreal upgrades itself and every installed component. The database stays on its current major line.

surreal upgrade

To move the database to another release, name it: surreal upgrade db@<version>. See Managing components.

Installing with Homebrew

The surreal Homebrew formula installs surreal, the SurrealDB command-line tool, without the database. Install the database with surreal afterwards:

brew install surrealdb/tap/surreal
surreal install db

surreal then installs, upgrades and runs the database as a component, as it does after the install script, so surreal db start and surreal upgrade work in the same way. Homebrew updates only surreal itself:

brew upgrade surrealdb/tap/surreal

Installing only the database

To have Homebrew install and update the database instead, use the surreal-db formula. It installs the database as surreal-db, because surreal is the command-line tool:

brew install surrealdb/tap/surreal-db
surreal-db start

When surreal is also installed and has no database component of its own, surreal db runs this surreal-db.

The surreal-db formula can also run the database as a background service, which starts again when you sign in to your Mac:

brew services start surreal-db

The service starts the database with the root user root and the password root, and keeps its data in surreal.db in Homebrew's var directory ($(brew --prefix)/var). Change the root password after the first start if anything other than your own machine can reach the server. brew services stop surreal-db stops it. The surreal formula is the command-line tool and has no service, so brew services start surreal does not start a database.

Confirming the installation

Run the following command to check that the database component runs.

surreal db version

4.0.0 for macos on aarch64

To list surreal and every component with the version that runs, use surreal list.