Skip to main content
Version: 2.x(alpha)

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

ArgumentsDescription

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

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

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