Skip to main content
Version: 1.x

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

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

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

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]

--pretty Whether database responses should be pretty printed

-json Whether to emit results in JSON

--multi Whether omitting semicolon causes a newline