Using the database

surreal db is the database component. It starts a server, opens an interactive SurrealQL shell, moves data in and out, and checks that a server is ready. Everything after db is forwarded to the database unchanged, so every database flag and environment variable works the way its reference page describes.

The database is installed by the install script by default. If it is not installed, surreal db <command> offers to install it the first time you run it.

Commands

Upgrading the database is not a database command. Use surreal upgrade db.

Run a database for development

Start an in-memory server with a root user. It listens on 127.0.0.1:8000.

surreal db start --user root --pass secret

Add a storage path to keep the data between runs.

surreal db start --user root --pass secret surrealkv:mydata

A relative path is resolved from the folder you run the command in. See surreal db start for the storage engines, binding, TLS and capabilities.

In a second terminal, open a shell against it.

surreal db sql --username root --password secret --pretty

The shell connects to ws://localhost:8000 and the main namespace and database. Name others with --namespace and --database. To run queries from a script instead, pipe them in.

echo "SELECT * FROM person;" | surreal db sql --username root --password secret --hide-welcome

Check that a server is ready

surreal db is-ready exits successfully once a server accepts connections, which suits a health check or a wait loop in a script.

surreal db start --user root --pass secret &
until surreal db is-ready --endpoint http://localhost:8000; do sleep 1; done

Move data in and out

Export a database to a SurrealQL file, and import it into another.

surreal db export --endpoint http://localhost:8000 --username root --password secret --namespace app --database main backup.surql
surreal db import --endpoint http://localhost:8000 --username root --password secret --namespace app --database main backup.surql

Both commands need a namespace and a database. surreal db export writes to standard output when you give it no file, or - as the file, so it composes with other tools.

To import into or export from a SurrealDB Cloud instance, use surreal cloud instance import and surreal cloud instance export, which resolve the endpoint and credentials and then run these commands for you.

Validate query files

surreal db validate parses SurrealQL files without running them. With no argument it checks every **/*.surql file under the current folder, so it fits a pre-commit hook or a CI step.

surreal db validate
surreal db validate "schema/**/*.surql"

Run a different database version

The launcher keeps several database versions side by side. Run one command against another version with +VERSION, or change the default with surreal use.

surreal +2.6.5 db export --endpoint http://localhost:8000 --namespace app --database main
surreal use db@2

See Managing components for installing, pinning and upgrading versions.

The deprecated top-level commands

The database's commands also run without db, and print a warning that names the replacement.

surreal start

warning: `surreal start` is deprecated; use `surreal db start`.

The set of commands that still run this way is closed: start, sql, import, export, isready, is-ready, validate, fix, ml, module and mcp, and database options placed before a command, as in surreal --log debug start. The warning goes to stderr and names only the command, never an argument, so it is safe in CI logs. A command the database adds later runs only as surreal db <command>. Change scripts and service definitions to the surreal db form.

Environment variables

surreal db reads the same SURREAL_* variables as before. SURREAL_USER, SURREAL_PASS, SURREAL_NAMESPACE, SURREAL_DATABASE and the rest are listed on the database environment variables page. The launcher's own variables start with SURREAL_CLI_, and it never reads SURREAL_* itself, so the two sets stay apart.