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

# Using the database

Run the SurrealDB database through the surreal launcher: surreal db start, sql, import, export, is-ready, validate, fix, ml and mcp. Workflows for local development, moving data, and checking a server, plus the deprecated surreal start forms.

`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](/docs/reference/cli/db.md) describes.

The database is installed by the [install script](/docs/explore/cli/install.md) by default. If it is not installed, `surreal db <command>` offers to install it the first time you run it.

## Commands

| Command | Use it to |
| --- | --- |
| [`surreal db start`](/docs/reference/cli/db/commands/start.md) | Run a server, in memory or on disk |
| [`surreal db sql`](/docs/reference/cli/db/commands/sql.md) | Open a SurrealQL shell, or pipe queries into a server |
| [`surreal db import`](/docs/reference/cli/db/commands/import.md) | Load a SurrealQL file into a database |
| [`surreal db export`](/docs/reference/cli/db/commands/export.md) | Write a database out as a SurrealQL file |
| [`surreal db is-ready`](/docs/reference/cli/db/commands/isready.md) | Check that a server accepts connections |
| [`surreal db validate`](/docs/reference/cli/db/commands/validate.md) | Check that SurrealQL files parse |
| [`surreal db fix`](/docs/reference/cli/db/commands/fix.md) | Repair storage issues |
| [`surreal db ml`](/docs/reference/cli/db/commands/ml.md) | Import and export machine-learning models |
| [`surreal db mcp`](/docs/reference/cli/db/commands/mcp.md) | Run the Model Context Protocol server over stdio |
| [`surreal db version`](/docs/reference/cli/db/commands/version.md) | Print the database version, or a server's |

Upgrading the database is not a database command. Use [`surreal upgrade db`](/docs/explore/cli/components.md#upgrade).

## Run a database for development

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

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

Add a storage path to keep the data between runs.

```bash
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`](/docs/reference/cli/db/commands/start.md) for the storage engines, binding, TLS and capabilities.

In a second terminal, open a shell against it.

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

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

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

```bash
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`](/docs/explore/cli/cloud/instances.md#connect-to-an-instance), 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.

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

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

See [Managing components](/docs/explore/cli/components.md) 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.

```bash
surreal start
```

```text title="Output"
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.

> [!NOTE]
> Docker and other container images run the database directly. Inside an image, the command is `surreal start` and not `surreal db start`, and the examples in [Running with Docker](/docs/running/docker.md) use that 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](/docs/reference/cli/db/environment-variables.md) page. The launcher's own variables start with `SURREAL_CLI_`, and it never reads `SURREAL_*` itself, so the two sets stay apart.