Module command

Available since: v3.0.0-beta

The module command is used to compile, manage and execute Surrealism plugin modules.

BEFORE YOU START

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

Command options

--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 authenticating as users defined on 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 to access the database server as a root user, and if not specified 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 this level is specified, 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 this level is specified, 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>

Experimental capabilities

Available since: v2.2.1

To use experimental capabilities, set the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable to the experimental capability you want to allow.

For example, to use Surrealism extensions, set the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable to surrealism.

SURREAL_CAPS_ALLOW_EXPERIMENTAL="surrealism" surreal sql ...

or, using the --allow-experimental flag:

surreal sql -e [CONNECTION_STRING] --allow-experimental surrealism

Multiple experimental capabilities can be enabled by separating them with a comma.

SURREAL_CAPS_ALLOW_EXPERIMENTAL="surrealism, graphql" surreal sql ...

-- OR 

surreal sql -e [CONNECTION_STRING] --allow-experimental surrealism,graphql

The current experimental targets are graphql, define_api, files, and surrealism.

Note

The experimental capability is completely hidden in the CLI help command, and --allow-all will not enable the experimental capabilities by default.

Default namespace and database

Available since: v3.0.0-beta

As the surreal start command defaults to defining a namespace and database by the name main upon starting up, the surreal sql command also connects to these two by default. As such, a command like surreal sql --user root --pass secret or even just surreal sql (for an instance with authentication disabled) is all that is needed to connect and begin using an instance via the CLI.

Example usage

To start a REPL and run or pipe queries to a local or remote SurrealDB database, run the surreal sql command in a terminal 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

Using environment variables

When using the surreal sql command, you can also use environment variables to set the values for the command-line flags.

Important

Most of the flags mentioned in the command output above also mention a corresponding environment variables.

For example, the --database flag can be configured with the SURREAL_DATABASE environment variable instead.

For more on the environment variables available for CLI commands or SurrealDB instances in general, see the environment variables page.

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

The output of the above command:

Manage and execute WASM modules

Usage: surreal module [OPTIONS] <COMMAND>

Commands:
  run    Run a function with arguments
  sig    Show the function signature
  info   Show the module information
  build  Build a WASM module
  help   Print this message or the help of the given subcommand(s)

Options:
  -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]