SurrealDB.jl

Julia client for SurrealDB. Talks to a remote surreal server over WebSocket or HTTP, or runs the database in-process via libsurreal. Same API regardless of backend. Default wire is CBOR.

Status: alpha. Pre-1.0. API may break between minor versions; pin a specific version to avoid breakage.

Install

using Pkg
Pkg.add(url="https://github.com/danvinci/SurrealDB.jl", rev="v0.2.0-alpha.1")

Not yet in the General registry. The embedded backend needs libsurreal; see Embedded mode.

Quickstart

using SurrealDB

db = SurrealDB.connect("ws://localhost:8000";
                       ns="test", db="test",
                       auth=SurrealDB.RootAuth("root", "root"))

alice = SurrealDB.create(db, "user", Dict("name" => "Alice", "age" => 30))
bob   = SurrealDB.create(db, rid"user:bob", Dict("name" => "Bob", "age" => 25))

users = SurrealDB.select(db, "user")
SurrealDB.update(db, alice["id"], Dict("age" => 31))
SurrealDB.delete(db, rid"user:bob")

results = SurrealDB.query(db, "SELECT * FROM user WHERE age > 18")

SurrealDB.close!(db)

Do-block form auto-closes via finally:

SurrealDB.connect("ws://localhost:8000"; ns="test", db="test") do db
    SurrealDB.query(db, "SELECT * FROM user")
end

Connection modes

URL scheme	Backend	Notes
ws://, wss://	Remote WS	Live queries, sessions, transactions, ping, auto-reconnect
http://, https://	Remote HTTP	Stateless. live() raises UnsupportedFeatureError
mem://, memory://	Embedded	In-memory, in-process via libsurreal
surrealkv://path	Embedded	File-backed, in-process

mem:// / memory:// and surrealkv://path are URL conventions shared with the official JS, Python, and .NET SDKs.

Documentation

Full reference at danvinci.github.io/SurrealDB.jl:

• Record IDs: RecordID(t, i), rid"t:i" macro, StringRecordID
• Wire format: CBOR + JSON, typed round-trips, NONE / NULL
• Authentication: root / namespace / scoped, refresh tokens, state replay
• Live queries: subscriptions, multi-subscriber fan-out, reconnect handling, server-initiated KILLED
• Transactions: v2 client RPC, v3 session-scoped SurrealTransaction, session variables
• Reconnect: tuning, lifecycle observability, closed-handle semantics
• Errors: typed hierarchy
• Integrations: StructTypes, Tables.jl, MetaGraphsNext
• API reference: full surface

Cross-SDK conformance

Selected Go testsets ported as Julia testsets; Python interop verified via fixture round-trips. JS + Rust planned (roadmap).

Comparative reference set: Go, Python, JS, Rust, .NET.

Requirements

• Julia 1.10+
• Remote: SurrealDB server v2.x or v3.x
• Embedded: libsurreal from surrealdb/surrealdb.c

Testing

# SDK suite (fast, offline, prereq-self-skipping):
julia --project=test test/runtests.jl

# Conformance suites (cross-SDK + upstream language-tests + wire):
bash scripts/setup-upstream.sh
bash scripts/setup-server.sh
bash scripts/run-conformance.sh

# CI-1:1 parity locally (forces Docker like CI):
SURREALDB_BACKEND=docker bash scripts/setup-server.sh

# Surgical iteration on a single file:
julia --project=test test/sdk/cbor/test_cbor_io.jl

Unit layer needs no network; integration needs surreal start --bind 127.0.0.1:8001 (CI + conformance use :8000); embedded needs libsurreal. Layers self-skip when prerequisites are missing.

Development

scripts/setup-upstream.sh      # clone upstream test corpus (sparse-blobless)
scripts/setup-sdk-refs.sh      # clone peer SDKs (Go/Py/JS/.NET) for reference reading
scripts/setup-server.sh        # provision surreal binary
scripts/regen-cbor-fixtures.sh # regenerate Rust CBOR fixtures (run after corpus changes)
scripts/run-conformance.sh     # orchestrate the conformance suites

All idempotent and identical local/CI.

Roadmap

• libsurrealdb_c_jll: pre-built dylibs via Yggdrasil for one-line Pkg.add.
• Cross-SDK interop matrix: extend the Python / Go fixture harness to cover JS and Rust × JSON × CBOR × every Surreal type.
• General registry submission once API stabilizes.

License

MIT. See LICENSE.