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 | |
---|---|---|
| Sets the url of the database server to connect to | |
| Sets master username for the database | |
| Sets master password for the database | |
--ns | Sets the desired namespace in which to import data | |
--db | Sets the desired database into which to import data | |
--auth-level | The authentication level to use when connecting to the server. | |
| Sets the authentication token to use when connecting to the server. Connect to SurrealDB using a JWT instead of user credentials | |
--pretty | Sets whether database responses should be pretty printed | |
--json | Sets whether to emit results in JSON | |
--multi | Sets whether omitting semicolon causes a newline | |
| 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