surreal db | Database

surreal db is the database component of the surreal CLI. It starts a server, opens an interactive SurrealQL shell, moves data in and out of a database, and reports on the version and readiness of an instance.

Usage

surreal db [OPTIONS] <COMMAND>

Important

Install the surreal CLI first. The installer also installs the database component by default, as described in Install the CLI. To run SurrealDB in other ways, see the installation pages. To experiment with SurrealDB before installing, see the SurrealDB Studio sandbox online. To persist your Sandbox data while still experimenting, click on Deploy to Cloud in SurrealDB Studio to create a free SurrealDB Cloud instance.

surreal db and the launcher

The surreal command is a launcher that installs, versions and runs components, and db is the component that holds the database. The launcher installs and upgrades the database (surreal install db, surreal upgrade db), and everything after db is forwarded to the database unchanged, so the flags on these pages are the database's own flags. See the launcher reference and Components for how components are installed and selected.

The older top-level forms, such as surreal start and surreal sql, still run but print a deprecation warning that names the surreal db form to use instead. Scripts that call them keep working, and can be moved to surreal db at any time.

Getting started

This documentation provides detailed information on each command, including usage examples and options. For a concise map of every subcommand, see CLI commands.

For a quickstart, surreal db start and surreal db sql will be enough to get you started.

surreal db start --user root --pass secret

Unless you specify otherwise, the CLI will start a database in memory that serves at 127.0.0.1:8000 (or http://localhost:8000). This database has a single root user named root and a password secret.

In another window, you can then open up an interactive shell to make queries using the surreal db sql command. As of SurrealDB 3.0, the sql command will connect to the default 'main' name for both namespace and database.

# Connect to namespace 'main' and database 'main'
surreal db sql --username root --password secret --pretty

# Connect to a different namespace and database
surreal db sql --namespace ns --database db --username root --password secret --pretty

Warning

Using generic usernames and passwords is not recommended for production use. Please replace the authentication credentials with your own.

This will start an interactive shell to make queries. The output below shows what you will see when logged in as the root user inside a namespace called main and a database called main, with pretty (easily readable) output per query.

You can then try out a few queries and see the output.

main/main> CREATE person SET age = 20;
main/main> CREATE person SET age = 30;
main/main> SELECT * FROM person WHERE age > 25;

Output

[
	{
		age: 20,
		id: person:6jodx8xv39jsxdgykt0t
	}
]

[
	{
		age: 30,
		id: person:10bcq2owseyqqoinjgxl
	}
]

[
	{
		age: 30,
		id: person:10bcq2owseyqqoinjgxl
	}
]

Next steps

CLI commands - every subcommand, with its arguments and options.
Environment variables - the SURREAL_* variables that mirror the flags on this page.
Launcher - installing, upgrading and selecting versions of the database and other components.
surreal cloud - managing organisations and Cloud instances from the command line.