# sql

A command that starts a command-line REPL to make SurrealQL to a local or remote SurrealDB database server.

Start a SurrealQL REPL in your terminal, with pipe support for one-shot queries.

> [!NOTE]
> **Before you start** — make sure you’ve [installed SurrealDB](/docs/running/installation.md).

<Synopsis>
surreal sql [OPTIONS]
</Synopsis>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--endpoint",
            "short": "-e",
            "value": "<ENDPOINT>",
            "default": "ws://localhost:8000",
            "description": "Remote database server URL to connect to, or an embedded storage path such as `memory` or `rocksdb://mydb`. Alias: `--conn`."
        },
        {
            "name": "--username",
            "short": "-u",
            "value": "<USERNAME>",
            "env": "SURREAL_USER",
            "description": "Database authentication username to use when connecting. Alias: `--user`."
        },
        {
            "name": "--password",
            "short": "-p",
            "value": "<PASSWORD>",
            "env": "SURREAL_PASS",
            "description": "Database authentication password to use when connecting. Alias: `--pass`."
        },
        {
            "name": "--token",
            "short": "-t",
            "value": "<TOKEN>",
            "env": "SURREAL_TOKEN",
            "description": "Authentication token in JWT format, used instead of a username and password. Cannot be combined with `--username`, `--password` or `--auth-level`."
        },
        {
            "name": "--auth-level",
            "value": "<AUTH_LEVEL>",
            "default": "root",
            "env": "SURREAL_AUTH_LEVEL",
            "description": "Level on which the authenticating user is defined. Possible values: `root`, `namespace` (`ns`), `database` (`db`)."
        },
        {
            "name": "--namespace",
            "value": "<NAMESPACE>",
            "env": "SURREAL_NAMESPACE",
            "description": "The namespace to select. Alias: `--ns`. Defaults to `main` from SurrealDB 3.0."
        },
        {
            "name": "--database",
            "value": "<DATABASE>",
            "env": "SURREAL_DATABASE",
            "description": "The database to select. Alias: `--db`. Defaults to `main` from SurrealDB 3.0."
        },
        {
            "name": "--pretty",
            "description": "Whether database responses should be pretty printed."
        },
        {
            "name": "--json",
            "description": "Whether to emit results in JSON."
        },
        {
            "name": "--multi",
            "description": "Whether omitting a semicolon causes a newline instead of submitting the statement."
        },
        {
            "name": "--hide-welcome",
            "env": "SURREAL_HIDE_WELCOME",
            "description": "Whether to hide the welcome message, which is useful when piping statements in."
        },
        {
            "name": "--allow-experimental",
            "value": "<TARGETS>",
            "env": "SURREAL_CAPS_ALLOW_EXPERIMENTAL",
            "description": "Experimental capabilities to enable, as a comma-separated list. Possible values: `files`, `surrealism`."
        },
        {
            "name": "--log",
            "short": "-l",
            "value": "<LOG>",
            "default": "info",
            "env": "SURREAL_LOG",
            "description": "The logging level for the command-line tool. Possible values: `none`, `full`, `error`, `warn`, `info`, `debug`, `trace`."
        }
    ]}
/>

`surreal sql` also accepts the capability flags shown under `Capabilities` in the [command help](#command-help) — `--allow-all`, `--allow-funcs`, `--deny-net`, and the rest. Where they take effect depends on how you connect; see [Capabilities and remote connections](#capabilities-and-remote-connections).

## Using environment variables

> [!IMPORTANT]
> Most of the flags above have a corresponding [environment variable](/docs/reference/cli/surrealdb-cli/environment-variables.md#command-environment-variables).
> For example, the `--database` flag can be configured with the `SURREAL_DATABASE` environment variable instead.

When using the `surreal sql` command, you can also use environment variables to set the values for the command-line flags.

For more on the environment variables available for CLI commands or SurrealDB instances in general, see the [environment variables](/docs/reference/cli/surrealdb-cli/environment-variables.md#command-environment-variables) page.

## `--auth-level` option

The `--auth-level` option sets the authentication level to use when connecting to the database. The option has three possible values: `root`, `namespace`, and `database`. The `root` value is the highest level of authentication, while the `namespace` and `database` values are used for authenticating as users defined on a specific namespace or database.

There are a few things to keep in mind when using the `--auth-level` option:

- The `root` value is used to access the database server as a root user, and if not specified is the default value.

```bash
surreal sql --endpoint http://localhost:8000 --namespace main --database main --auth-level root --username username --password password
```

- The `namespace` value is used for accessing a specific namespace and all databases within that namespace. When this level is specified, a namespace must be provided via `--namespace`.

```bash
surreal sql --endpoint http://localhost:8000 --namespace main --database main --auth-level namespace --username username --password password
```

- The `database` value is used for accessing a specific database within a namespace. When this level is specified, a namespace and a database must be provided via `--namespace` and `--database`.

```bash
surreal sql --endpoint http://localhost:8000 --namespace main --database main --auth-level database --username username --password password
```

## `--token` option

The `--token` option sets the authentication token to use when connecting to the server. This option allows you to connect to SurrealDB using a JWT instead of user credentials. The token is used to authenticate the user and provide access to the database server which means it cannot be provided at the same time as `--username`, `--password` or `--auth-level`.

```bash
surreal sql --endpoint http://localhost:8000 --namespace main --database main --token <token>
```

## Capabilities and remote connections

Both `surreal sql` and [`surreal start`](/docs/reference/cli/surrealdb-cli/commands/start.md) accept the same capability flags (`--allow-funcs`, `--allow-eval-query`, `--allow-experimental`, and so on). **Where those flags take effect depends on how you connect.**

| Connection | Examples | Where capabilities are enforced |
| --- | --- | --- |
| **Remote server** | `ws://localhost:8000`, `http://…`, `grpc://…` with sign-in | On the **server** process started with `surreal start` |
| **Embedded engine** | `memory`, `rocksdb://…`, `surrealkv://…` (no separate server) | On the **`surreal sql` process** itself |

> [!NOTE]
> `grpc://` and `grpcs://` endpoints are accepted from SurrealDB 3.3.0. The server always mounts the gRPC transport, and the `surreal` binary now ships the client, so `surreal sql --endpoint grpc://127.0.0.1:8000` connects without a custom build. On earlier versions the endpoint was rejected as an invalid connection string or an invalid URI.

When you use `surreal sql` against a **running instance**, flags on the REPL command do **not** change what the server allows at execution time. Configure [`surreal start`](/docs/reference/cli/surrealdb-cli/commands/start.md) (or the server's environment variables) instead — including for [`eval::*`](/docs/reference/query-language/functions/database-functions/eval.md), arbitrary-query gates, and experimental features such as Surrealism.

Capability flags on `surreal sql` still matter in two cases:

- **Embedded storage** — there is no separate server; pass the flags on `surreal sql` directly.
- **REPL syntax validation** — the client uses its capability set when checking whether a line parses before you submit it. That can affect experimental syntax in the prompt; it is **not** the security boundary for remote execution.

## Experimental capabilities

_(since v2.2.1)_

> [!NOTE]
> The experimental capability is completely hidden in the CLI help command, and `--allow-all` will not enable the experimental capabilities by default.

To use experimental capabilities, set the `SURREAL_CAPS_ALLOW_EXPERIMENTAL` [environment variable](/docs/reference/cli/surrealdb-cli/environment-variables.md) to the experimental capability you want to allow.

For **embedded** `surreal sql` (for example `surreal sql memory`), set the variable or flag on the REPL command. For a **remote** server, set it on [`surreal start`](/docs/reference/cli/surrealdb-cli/commands/start.md#experimental-capabilities) instead — see [Capabilities and remote connections](#capabilities-and-remote-connections).

For example, to use [Surrealism](/docs/learn/extensions/plugins/overview.md) extensions in an embedded session:

```bash
SURREAL_CAPS_ALLOW_EXPERIMENTAL=surrealism surreal sql ...
```

or, using the `--allow-experimental` flag:

```bash
surreal sql -e [CONNECTION_STRING] --allow-experimental surrealism
```

Multiple experimental capabilities can be enabled by separating them with a comma.

```bash
SURREAL_CAPS_ALLOW_EXPERIMENTAL=surrealism,files surreal sql ...

-- OR

surreal sql -e [CONNECTION_STRING] --allow-experimental surrealism,files
```

The current experimental targets are `files` and `surrealism`. The legacy tag `gql` is still accepted for compatibility but has no effect from 3.3.0 — [ISO GQL](/docs/learn/querying/gql/overview.md) is enabled by default.

| Example feature/statement | Tag |
| --- | --- |
| [DEFINE BUCKET](/docs/reference/query-language/statements/define/bucket.md) | `files` |
| [DEFINE MODULE](/docs/reference/query-language/statements/define/module.md) | `surrealism` |

> [!NOTE]
> When connecting to a **remote** server (`ws://`, `http://`, …), experimental features are enforced on the server. Configure them with [`surreal start`](/docs/reference/cli/surrealdb-cli/commands/start.md#experimental-capabilities) (or the server's `SURREAL_CAPS_ALLOW_EXPERIMENTAL`). Flags on `surreal sql` only affect [embedded connections](#capabilities-and-remote-connections) or REPL parse validation. From 3.3.0, [ISO GQL](/docs/learn/querying/gql/overview.md) does not need an experimental flag; `eval::gql` still needs [`--allow-eval-query`](/docs/learn/security/authorization/capabilities.md#eval-queries) on the server.

### Default namespace and database

_(since v3.0.0)_

As the `surreal start` command defaults to defining a namespace and database by the name `main` upon starting up, the `surreal sql` command also connects to these two by default. As such, a command like `surreal sql --user root --pass secret` or even just `surreal sql` (for an instance with authentication disabled) is all that is needed to connect and begin using an instance via the CLI.

## Example usage

To start an interactive REPL, run the `surreal sql` command with the required arguments. Once you see the `>` character you can type SurrealQL, followed by the `enter` key. The command has support for `↑` and `↓` arrows for selecting previous SQL statements, and stores the statement history in a `history.txt` file. To exit the REPL, use the `ctrl + c` or `ctrl + d` key combinations.

```bash
surreal sql --endpoint http://localhost:8000 --namespace main --database main --auth-level root --username username --password password
```

For a one-shot query without staying in the REPL, pipe SurrealQL into `surreal sql`. This is only for a small number of statements; for larger scripts use the [import command](/docs/reference/cli/surrealdb-cli/commands/import.md).

**Bash**

```bash
echo 'INFO FOR DB;' | surreal sql --endpoint http://localhost:8000 --username root --password root --namespace main --database main --pretty --hide-welcome
```

**PowerShell**

```powershell
'INFO FOR DB;' | surreal sql --endpoint http://localhost:8000 --username root --password root --namespace main --database main --pretty --hide-welcome
```

You can also pipe a file:

```bash
cat myfile.surql | surreal sql --endpoint http://localhost:8000 --username root --password root --namespace main --database main
```

## Connecting to a Cloud instance

`surrealctl instance sql <name>` wraps this command: it resolves the endpoint and credentials of a SurrealDB Cloud instance and then hands off to `surreal sql`, passing through any flags given after `--`. Everything on this page applies to that session. See the [surrealctl reference](/docs/reference/cli/surrealctl/overview.md) for the control-plane side.

## Command help

To see the help information and usage instructions, in a terminal run the `surreal sql --help` command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the `sql` command.

```bash
surreal sql --help
```

The output of the above command:

```text
Start an SQL REPL in your terminal with pipe support

Usage: surreal sql [OPTIONS]

Options:
  -e, --endpoint <ENDPOINT>
          Remote database server url to connect to

          [default: ws://localhost:8000]

  -u, --username <USERNAME>
          Database authentication username to use when connecting

          [env: SURREAL_USER=]
          [aliases: --user]

  -p, --password <PASSWORD>
          Database authentication password to use when connecting

          [env: SURREAL_PASS=]
          [aliases: --pass]

  -t, --token <TOKEN>
          Authentication token in JWT format to use when connecting

          [env: SURREAL_TOKEN=]

      --auth-level <AUTH_LEVEL>
          Level on which the authenticating user is defined

          [env: SURREAL_AUTH_LEVEL=]
          [default: root]
          [possible values: root, namespace, ns, database, db]

      --namespace <NAMESPACE>
          The selected namespace

          [env: SURREAL_NAMESPACE=]
          [aliases: --ns]

      --database <DATABASE>
          The selected database

          [env: SURREAL_DATABASE=]
          [aliases: --db]

      --pretty
          Whether database responses should be pretty printed

      --json
          Whether to emit results in JSON

      --multi
          Whether omitting semicolon causes a newline

      --hide-welcome
          Whether to show welcome message

          [env: SURREAL_HIDE_WELCOME=]

  -h, --help
          Print help (see a summary with '-h')

Capabilities:
  -A, --allow-all
          Allow all capabilities except for those more specifically denied

          [env: SURREAL_CAPS_ALLOW_ALL=]

      --allow-scripting
          Allow execution of embedded scripting functions

          [env: SURREAL_CAPS_ALLOW_SCRIPT=]

      --allow-guests
          Allow guest users to execute queries

          [env: SURREAL_CAPS_ALLOW_GUESTS=]

      --allow-funcs [<ALLOW_FUNCS>...]
          Allow execution of all functions except for functions that are specifically denied. Alternatively, you can provide a
          comma-separated list of function names to allow
          Specifically denied functions and function families prevail over any other allowed function execution.
          Function names must be in the form <family>[::<name>]. For example:
           - 'http' or 'http::*' -> Include all functions in the 'http' family
           - 'http::get' -> Include only the 'get' function in the 'http' family

          [env: SURREAL_CAPS_ALLOW_FUNC=]

      --allow-arbitrary-query [<ALLOW_ARBITRARY_QUERY>...]
          Allow execution of arbitrary queries by certain user groups except when specifically denied. Alternatively, you can provide a
          comma-separated list of user groups to allow
          Specifically denied user groups prevail over any other allowed user group.
          User groups must be one of "guest", "record" or "system".

          [env: SURREAL_CAPS_ALLOW_ARBITRARY_QUERY=]

      --allow-net [<ALLOW_NET>...]
          Allow all outbound network connections except for network targets that are specifically denied. Alternatively, you can provide a
          comma-separated list of network targets to allow
          Specifically denied network targets prevail over any other allowed outbound network connections.
          Targets must be in the form of <host>[:<port>], <ipv4|ipv6>[/<mask>]. For example:
           - 'surrealdb.com', '127.0.0.1' or 'fd00::1' -> Match outbound connections to these hosts on any port
           - 'surrealdb.com:80', '127.0.0.1:80' or 'fd00::1:80' -> Match outbound connections to these hosts on port 80
           - '10.0.0.0/8' or 'fd00::/8' -> Match outbound connections to any host in these networks

          [env: SURREAL_CAPS_ALLOW_NET=]

      --allow-rpc [<ALLOW_RPC>...]
          Allow all RPC methods to be called except for routes that are specifically denied. Alternatively, you can provide a comma-separated
          list of RPC methods to allow.

          [env: SURREAL_CAPS_ALLOW_RPC=]
          [default: ]

      --allow-http [<ALLOW_HTTP>...]
          Allow all HTTP routes to be requested except for routes that are specifically denied. Alternatively, you can provide a
          comma-separated list of HTTP routes to allow.

          [env: SURREAL_CAPS_ALLOW_HTTP=]
          [default: ]

  -D, --deny-all
          Deny all capabilities except for those more specifically allowed

          [env: SURREAL_CAPS_DENY_ALL=]

      --deny-scripting
          Deny execution of embedded scripting functions

          [env: SURREAL_CAPS_DENY_SCRIPT=]

      --deny-guests
          Deny guest users to execute queries

          [env: SURREAL_CAPS_DENY_GUESTS=]

      --deny-funcs [<DENY_FUNCS>...]
          Deny execution of all functions except for functions that are specifically allowed. Alternatively, you can provide a
          comma-separated list of function names to deny.
          Specifically allowed functions and function families prevail over a general denial of function execution.
          Function names must be in the form <family>[::<name>]. For example:
           - 'http' or 'http::*' -> Include all functions in the 'http' family
           - 'http::get' -> Include only the 'get' function in the 'http' family

          [env: SURREAL_CAPS_DENY_FUNC=]

      --deny-arbitrary-query [<DENY_ARBITRARY_QUERY>...]
          Deny execution of arbitrary queries by certain user groups except when specifically allowed. Alternatively, you can provide a
          comma-separated list of user groups to deny
          Specifically allowed user groups prevail over a general denial of user group.
          User groups must be one of "guest", "record" or "system".

          [env: SURREAL_CAPS_DENY_ARBITRARY_QUERY=]

      --deny-net [<DENY_NET>...]
          Deny all outbound network connections except for network targets that are specifically allowed. Alternatively, you can provide a
          comma-separated list of network targets to deny.
          Specifically allowed network targets prevail over a general denial of outbound network connections.
          Targets must be in the form of <host>[:<port>], <ipv4|ipv6>[/<mask>]. For example:
           - 'surrealdb.com', '127.0.0.1' or 'fd00::1' -> Match outbound connections to these hosts on any port
           - 'surrealdb.com:80', '127.0.0.1:80' or 'fd00::1:80' -> Match outbound connections to these hosts on port 80
           - '10.0.0.0/8' or 'fd00::/8' -> Match outbound connections to any host in these networks

          [env: SURREAL_CAPS_DENY_NET=]

      --deny-rpc [<DENY_RPC>...]
          Deny all RPC methods from being called except for methods that are specifically allowed. Alternatively, you can provide a
          comma-separated list of RPC methods to deny.

          [env: SURREAL_CAPS_DENY_RPC=]

      --deny-http [<DENY_HTTP>...]
          Deny all HTTP routes from being requested except for routes that are specifically allowed. Alternatively, you can provide a
          comma-separated list of HTTP routes to deny.

          [env: SURREAL_CAPS_DENY_HTTP=]

Logging:
  -l, --log <LOG>
          The logging level for the command-line tool

          [env: SURREAL_LOG=]
          [default: info]
          [possible values: none, full, error, warn, info, debug, trace]

      --log-format <LOG_FORMAT>
          The format for terminal log output

          [env: SURREAL_LOG_FORMAT=]
          [default: text]
          [possible values: text, json]

      --log-socket <LOG_SOCKET>
          Send logs to the specified host:port

          [env: SURREAL_LOG_SOCKET=]

      --log-file-level <LOG_FILE_LEVEL>
          Override the logging level for file output

          [env: SURREAL_LOG_FILE_LEVEL=]
          [possible values: none, full, error, warn, info, debug, trace]

      --log-otel-level <LOG_OTEL_LEVEL>
          Override the logging level for OpenTelemetry output

          [env: SURREAL_LOG_OTEL_LEVEL=]
          [possible values: none, full, error, warn, info, debug, trace]

      --log-socket-level <LOG_SOCKET_LEVEL>
          Override the logging level for unix socket output

          [env: SURREAL_LOG_SOCKET_LEVEL=]
          [possible values: none, full, error, warn, info, debug, trace]

      --log-socket-format <LOG_SOCKET_FORMAT>
          The format for socket output

          [env: SURREAL_LOG_SOCKET_FORMAT=]
          [default: text]
          [possible values: text, json]

      --log-file-enabled
          Whether to enable log file output

          [env: SURREAL_LOG_FILE_ENABLED=]

      --log-file-path <LOG_FILE_PATH>
          The directory where log files will be stored

          [env: SURREAL_LOG_FILE_PATH=]
          [default: logs]

      --log-file-name <LOG_FILE_NAME>
          The name of the log file

          [env: SURREAL_LOG_FILE_NAME=]
          [default: surrealdb.log]

      --log-file-format <LOG_FILE_FORMAT>
          The format for log file output

          [env: SURREAL_LOG_FILE_FORMAT=]
          [default: text]
          [possible values: text, json]

      --log-file-rotation <LOG_FILE_ROTATION>
          The log file rotation interval

          [env: SURREAL_LOG_FILE_ROTATION=]
          [default: daily]
          [possible values: daily, hourly, never]
```