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

Arguments		Description
-e / --endpoint / --conn OPTIONAL		Sets the url of the database server to connect to
-u / --user REQUIRED		Sets master username for the database
-p / --pass REQUIRED		Sets master password for the database
--nsOPTIONAL		Sets the desired namespace in which to import data
--dbOPTIONAL		Sets the desired database into which to import data
--auth-levelOPTIONAL		The authentication level to use when connecting to the server.
-t / --token OPTIONAL		Sets the authentication token to use when connecting to the server. Connect to SurrealDB using a JWT instead of user credentials
--prettyOPTIONAL		Sets whether database responses should be pretty printed
--jsonOPTIONAL		Sets whether to emit results in JSON
--multiOPTIONAL		Sets whether omitting semicolon causes a newline
-h / --help OPTIONAL		Prints help

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

Start an SQL REPL in your terminal with pipe support

USAGE:
surreal sql [OPTIONS]

ARGS:
<file> Path to the sql file to import

OPTIONS:
-e, --endpoint <ENDPOINT>                Remote database server url to connect to [default: ws://localhost:8000] [aliases: conn]

--db <db>                               The database selected for the operation [env: SURREAL_DATABASE=] [aliases: db]

-h, --help                              Print help information

--ns <ns>                               The namespace selected for the operation [env: SURREAL_NAMESPACE=] [aliases: ns]

-p, --pass <pass>                       Database authentication password to use when connecting [env: SURREAL_PASS=] [aliases:pass]

-u, --user <user>                       Database authentication username to use when connecting [env: SURREAL_USER=] [aliases:user]

--auth-level <auth-level>               The authentication level to use when connecting to the database [default: root] [possible values: root, namespace, database]

--pretty                                Whether database responses should be pretty printed

-json                                   Whether to emit results in JSON

--multi                                 Whether omitting semicolon causes a newline

What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.