> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# surreal db

The database component of the surreal CLI, run as surreal db. It can be used to export a dataset as SurrealQL from a local or remote SurrealDB database, import SurrealQL data into a local or remote database, and start a single SurrealDB instance or distributed cluster.

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

<Synopsis>
surreal db [OPTIONS] <COMMAND>
</Synopsis>

> [!IMPORTANT]
> Install the `surreal` CLI first. The installer also installs the database component by default, as described in [Install the CLI](/docs/explore/cli/install.md). To run SurrealDB in other ways, see the [installation](/docs/running/installation.md) pages. To experiment with SurrealDB before installing, see the [SurrealDB Studio sandbox](https://studio.surrealdb.com/) 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](/docs/reference/cli/launcher.md) and [Components](/docs/explore/cli/components.md) 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](/docs/reference/cli/db/commands.md).

For a quickstart, [`surreal db start`](/docs/reference/cli/db/commands/start.md) and [`surreal db sql`](/docs/reference/cli/db/commands/sql.md) will be enough to get you started.

```bash
surreal db start --user root --pass secret
```

Unless you specify otherwise, the CLI will start a database [in memory](/docs/running/in-memory.md) 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.

```bash
# 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.

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

```surql title="Output"
[
	{
		age: 20,
		id: person:6jodx8xv39jsxdgykt0t
	}
]

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

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

## Next steps

- [CLI commands](/docs/reference/cli/db/commands.md) - every subcommand, with its arguments and options.
- [Environment variables](/docs/reference/cli/db/environment-variables.md) - the `SURREAL_*` variables that mirror the flags on this page.
- [Launcher](/docs/reference/cli/launcher.md) - installing, upgrading and selecting versions of the database and other components.
- [surreal cloud](/docs/reference/cli/cloud.md) - managing organisations and Cloud instances from the command line.

## Learn more about this topic

- [Chapter 1: One year later](https://surrealdb.com/learn/book/chapter-01#getting-started-with-surrealdb) (SurrealDB University, section "Getting started with SurrealDB")