Click here to sign up to SurrealDB Cloud
Back to top
Documentation Command-line tool SQL command

SQL command

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

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

Command options

Argument Description
-e / --endpoint Optional Sets the url of the database server to connect to

Default is ws://localhost:8000
-u / --username Required Sets the root, namespace, or database user
-p / --password Required Sets the password for the specified user
--namespace Optional Sets the desired namespace into which to import data
--database Optional Sets the desired database into which to import data
--pretty Optional Sets whether database responses should be pretty printed
--json Optional Sets whether to emit results in JSON
--multi Optional Sets whether omitting semicolon causes a newline
-h / --help Optional Prints help

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.

user@localhost % surreal sql --endpoint http://localhost:8000 --username root --password root --namespace test --database test
>

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.

user@localhost % 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.

user@localhost % surreal sql --help
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]
      --namespace <NAMESPACE>  The namespace selected for the operation [env: SURREAL_NAMESPACE=] [aliases: ns]
      --database <DATABASE>    The database selected for the operation [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
  -h, --help                   Print help