Mojo SDK

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.

Getting started

Learn

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.

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:secret
        ),
    )

    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.

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.

Contributing

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

Sources

• •

  GitHub repository