Mojo SDK | SurrealDB

The SurrealDB SDK for Mojo enables simple and advanced querying of a remote database over HTTP, HTTPS, and WebSocket.

The SurrealDB SDK for Mojo lets you connect to a SurrealDB instance from your Mojo applications and run queries, manage data, call database functions, authenticate, and subscribe to changes with live queries. It speaks both CBOR-RPC and JSON-RPC over the same /rpc endpoint, and ships transports for http://, https://, ws://, and wss://.

The SDK has no third-party Mojo dependencies. The transport sits on a small libc-socket layer, and TLS is backed by a thin OpenSSL FFI with certificate verification against the system root store.

Important

The SDK requires Mojo >= 0.26.1.0, < 0.26.2.0, and is managed with pixi. The current SDK version is 0.2.0.

Note

The SDK works with SurrealDB 3.x, ensuring compatibility with the latest version, v3.1.5.

Choosing a client

The SDK provides two clients with the same surface:

AsyncSurrealClient for asynchronous applications.
SurrealClient, a thin blocking wrapper around the async client.

Async client

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


def main():
    var client = AsyncSurrealClient()
    _ = client.connect(
        "http://localhost:8000/rpc",
        ConnectOptions(
            namespace=Optional(String("test")),
            database=Optional(String("test")),
            access_token=Optional(String("Basic cm9vdDpyb290")),  # root:root
        ),
    )

    var resp = client.query("RETURN 1 + 1;")
    if resp.is_ok():
        print("result:", resp.result.value() if resp.result else "null")
    else:
        print("error:", resp.error_message().value())

Transports

HTTP and HTTPS are the recommended transports for everyday querying, and are the most thoroughly tested path. WebSocket (ws:// and wss://) unlocks SurrealDB's stateful features: authenticated sessions, server-side transactions that span multiple requests, and live-query notifications delivered out of band.

Note

WebSocket support is rolling out. For request and response querying, including atomic multi-statement transactions, use the HTTP or HTTPS transport.

The wire format is configurable. CBOR is the default and the most compact on the wire; JSON is useful when you want to inspect traffic or proxy through a JSON-only gateway. See Connecting to SurrealDB for the full set of options.

Get started

Installation to add the SDK to your project.
Quickstart for a complete working example.
Connecting to SurrealDB for connection options and transports.
SDK methods for the full method reference.

Sources

GitHub repository

To contribute to the SDK code, submit an Issue or Pull Request in the Mojo SDK repository. To contribute to this documentation, submit an Issue or Pull Request in the docs.surrealdb.com repository.