Installation

In this section, you will learn how to install the SurrealDB Mojo SDK and add it to your project.

Requirements

The only runtime dependency is Mojo itself, pinned to 0.26.1.x. The project uses pixi to manage the Mojo toolchain.

Install the SDK

Clone the repository and install the toolchain with pixi:

git clone https://github.com/surrealdb/surrealdb.mojo
cd surrealdb.mojo
pixi install

To use the SDK from your own project, either vendor src/surrealdb into your Mojo package path, or build it into a .mojopkg:

pixi run check     # produces build/surrealdb.mojopkg

Import the SDK into your project

Import the client and connection options from the surrealdb package:

from surrealdb import AsyncSurrealClient, ConnectOptions
from std.collections import Optional

For the blocking client, import SurrealClient instead:

from surrealdb import SurrealClient

Run your program

Run a Mojo file with the SDK source on the include path:

pixi run mojo run -I src yourfile.mojo

Build with HTTPS

The TLS code sits behind a compile-time gate, so mojo run invocations without HTTPS keep working with no OpenSSL on the system. To connect over https:// or wss://, build your program with mojo build, define the HTTPS flag, and link against libssl and libcrypto from the pixi environment:

PIXI_ENV=$(pwd)/.pixi/envs/default
pixi run mojo build -I src -o app \
  -D HTTPS=1 \
  -Xlinker -L$PIXI_ENV/lib \
  -Xlinker -lssl -Xlinker -lcrypto \
  yourfile.mojo

DYLD_LIBRARY_PATH=$PIXI_ENV/lib ./app  # macOS
LD_LIBRARY_PATH=$PIXI_ENV/lib ./app    # Linux

If you use an https:// URL without -D HTTPS=1, the SDK raises a ConnectionError that names the build flags you need.

Next steps

• Quickstart for a complete working example.

• Connecting to SurrealDB for connection options and transports.

• Authentication for signing in and managing credentials.