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.
--prettyOPTIONAL		Sets wheter database respones 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

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

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.