SurrealDB World   |   Join us in September
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
-c / --conn Optional Sets the url of the database server to connect to

Default is https://cloud.surrealdb.com
-u / --user Required Sets the root, namespace, or database user
-p / --pass Required Sets the password for the specified user
--ns Optional Sets the desired namespace into which to import data
--db Optional Sets the desired database into which to import data
--pretty Optional Sets whether database responses should be pretty printed

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 --conn http://localhost:8000 --user root --pass root --ns test --db 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 --conn http://localhost:8000 --user root --pass root --ns test --db 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] --ns <ns> --db <db>

OPTIONS:
    -c, --conn <conn>    Remote database server url to connect to [default:
                         https://cloud.surrealdb.com]
        --db <db>        The database to export the data from
    -h, --help           Print help information
        --ns <ns>        The namespace to export the data from
    -p, --pass <pass>    Database authentication password to use when connecting [default: root]
        --pretty         Whether database responses should be pretty printed
    -u, --user <user>    Database authentication username to use when connecting [default: root]