validate | CLI commands

Validate SurrealQL query files, or a query read from standard input, with the installed surreal CLI and without connecting to a server.

Usage

surreal db validate [OPTIONS] [PATTERNS]...

Arguments

Name	Default	Description
`[PATTERNS]...`	`*/.surql`	Glob pattern for the files to validate. Several paths or patterns can be given at once.

Options

Name	Default	Environment variable	Description
`--stdin`	None	None	Read the query from standard input instead of from files.
`--json, -j`	None	None	From 4.0.0. Print one JSON document on stdout, with `valid` and a `files` array holding the `path` and `valid` of each file, and the `error` of a file that is not valid. When a file is not valid, the document is a JSON error object on stderr instead, with the same `files` array.
`--log, -l<LOG>`	`info`	`SURREAL_LOG`	The logging level for the command-line tool. Possible values: `none`, `full`, `error`, `warn`, `info`, `debug`, `trace`.

Example usage

To perform validation on a SurrealQL local file, in a terminal run the surreal db validate command with the required argument.

Using the command on its own will validate all the .surql files in the current directory and its subdirectories.

surreal db validate

user1.surql: OK
user2.surql: OK
user3.surql: OK

You can perform validation on a single file, regardless of extension.

surreal db validate user.surql
surreal db validate user.txt

You can also perform validation on multiple files using a single glob pattern:

# equivalent to "surreal db validate"
surreal db validate **/*.surql

Finally, you can also perform validation on multiple files using multiple paths/patterns:

surreal db validate index.surql schemas/*.surql queries/*.surql
surreal db validate *.(txt|surql)

The command checks every file, and exits with an error if any of them is invalid.

surreal db validate

user1.surql: OK
user2.surql: FAIL
Parse error: Unexpected token `an identifier`, expected Eof
 --> [1:15]
  |
1 | CREATE person SE name = "Billy";
  |               ^^

Validating input from stdin

Available since: v3.1.0

In addition to files, this command can also be used on the terminal with the --stdin flag to validate input from stdin.

An example of a valid query:

echo "SELECT * FROM example;" | surreal db validate --stdin

<stdin>: OK

An example of an invalid query:

echo "CREATE WHERE value = ''" | surreal db validate --stdin

<stdin>: FAIL
Parse error: Unexpected token `VALUE`, expected Eof
 --> [1:14]
  |
1 | CREATE WHERE value = ''
  |              ^^^^^

Command help

To see the help information and usage instructions, in a terminal run the surreal db validate --help command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the validate command.

surreal db validate --help

The output of the above command:

Validate SurrealQL query files

Usage: surreal validate [OPTIONS] [PATTERNS]...

Arguments:
  [PATTERNS]...  Glob pattern for the files to validate [default: **/*.surql]

Options:
      --stdin  Read query from standard input
  -j, --json   Emit machine-readable JSON on stdout
  -h, --help   Print help

Logging:
  -l, --log <LOG>                              The logging level for the command-line tool [env: SURREAL_LOG] [default: info] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>                The format for terminal log output [env: SURREAL_LOG_FORMAT] [default: text] [possible
                                               values: text, json]
      --log-socket <LOG_SOCKET>                Send logs to the specified host:port [env: SURREAL_LOG_SOCKET]
      --log-file-level <LOG_FILE_LEVEL>        Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL] [possible values:
                                               none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>        Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>    Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>  The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT] [default: text] [possible
                                               values: text, json]
      --log-file-enabled                       Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED]
      --log-file-path <LOG_FILE_PATH>          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH] [default: logs]
      --log-file-name <LOG_FILE_NAME>          The name of the log file [env: SURREAL_LOG_FILE_NAME] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>      The format for log file output [env: SURREAL_LOG_FILE_FORMAT] [default: text] [possible
                                               values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>  The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION] [default: daily] [possible
                                               values: daily, hourly, never]