SQL command

The SQL command starts a REPL for running or piping SurrealQL queries to a local or remote SurrealDB database server.

BEFORE YOU START

Make sure you’ve installed SurrealDB — it should only take a second!

Command options

--auth-level option

Available since: v2.0.0

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 accessing 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 for accessing the entire database server and if not specific is the default value.

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

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

surreal sql --endpoint http://localhost:8000 --namespace test --database test --auth-level namespace --username username --password password

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

surreal sql --endpoint http://localhost:8000 --namespace test --database test --auth-level database --username username --password password

--token option

Available since: v2.0.0

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.

surreal sql --endpoint http://localhost:8000 --namespace test --database test --token <token>

Example usage

To start a terminal-based REPL and run or pipe queries to a local or remote SurrealDB database, in a terminal run the surreal sql command with the required arguments.

Once you see the > character you can type your SurrealQL query, 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.

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

It is also possible to pipe a set of statements to a remote database. This functionality is only designed for submitting a small number of queries to the database server. For a large number of queries, use the import command.

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

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.

surreal sql --help

The output of the above command:

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] [aliases: conn]
  -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>  Authentication level to use when connecting [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

Using environment variables

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

Important

Most of the flags mentioned in the command output above also mention a corresponding environment variables.

For example, the --database flag can be configured with the SURREAL_DATABASE environment variable instead.

For more on the environment variables available for CLI commands or SurrealDB instances in general, see the environment variables page.