Feature flags¶

oneiriq-surql is a large crate with several orthogonal subsystems. Every optional dependency lives behind a feature flag so library-only consumers (e.g. schema / migration tooling that renders SurrealQL but never opens a socket) do not pull in tokio, surrealdb, redis, or any binary-only dependencies.

Summary¶

Picking a profile¶

Library-only (render SurrealQL, no network)¶

[dependencies]
oneiriq-surql = { version = "0.2", default-features = false }

Gives you the schema DSL, migration renderer, query builder, and typed result helpers. Everything under types::, schema::, query::* (except executor, crud, typed, graph), migration::models / diff / generator / versioning / discovery, and the parser remains available.

Default async client (rustls TLS)¶

[dependencies]
oneiriq-surql = "0.2"

Equivalent to features = ["client-rustls"]. Brings in tokio, surrealdb, and the full async surface (DatabaseClient, executor::fetch_all, crud::*, graph::*, batch::*_many, Transaction). TLS is handled by rustls + webpki-roots, so no openssl-sys is linked, no libssl-dev is needed at build time, and the dependency graph is portable across glibc / musl / cross-compile targets.

Async client with native-tls¶

[dependencies]
oneiriq-surql = { version = "0.2", default-features = false, features = ["client"] }

Same API surface as client-rustls, but TLS is delegated to the system native-tls stack (links openssl-sys on Linux, Security.framework on macOS). Use this when you must validate against the OS trust store or interop with a TLS extension that is only implemented by OpenSSL.

Picking a TLS backend¶

Pick exactly one of client or client-rustls:

Enabling both at once compiles, but doubles the TLS dependency set. If you are consuming this crate from multiple workspace members, pick one variant and hold it consistent via a workspace-level feature flag.

CLI / service binary¶

[dependencies]
oneiriq-surql = { version = "0.2", features = ["cli"] }

Implies client, orchestration, and settings. Adds the surql binary. See CLI reference.

Cache layer¶

[dependencies]
oneiriq-surql = { version = "0.2", features = ["cache"] }
# or with Redis:
oneiriq-surql = { version = "0.2", features = ["cache-redis"] }

cache enables MemoryCache + CacheManager. cache-redis additionally enables the redis backend (implies cache).

Orchestration (standalone)¶

[dependencies]
oneiriq-surql = { version = "0.2", features = ["orchestration"] }

Pulls in the async client (orchestration requires live connections) plus the EnvironmentRegistry, MigrationCoordinator, and the four deployment strategies (sequential, parallel, rolling, canary).

Settings¶

[dependencies]
oneiriq-surql = { version = "0.2", features = ["settings"] }

Enables the layered Settings loader (env vars, .env, Cargo.toml [package.metadata.surql]). Pure dependency - does not require a client.

Schema watcher¶

[dependencies]
oneiriq-surql = { version = "0.2", features = ["watcher"] }

Filesystem watcher for schema / migration files - useful for cargo watch-style development loops.

WebAssembly support¶

[dependencies]
oneiriq-surql = { version = "0.2", default-features = false, features = ["client-wasm"] }

Tracks Oneiriq/surql-rs#115. Enables the same DatabaseClient / executor::* / crud::* / graph::* / batch::*_many API as client-rustls, but compiles cleanly to wasm32-unknown-unknown:

• surrealdb is pulled with protocol-ws + kv-mem only. Browsers terminate TLS at the WebSocket layer, so neither rustls (which pulls ring's C glue) nor native-tls is enabled. kv-mem lets wasm callers run an embedded engine for local state and tests with no server roundtrip.
• reqwest is not pulled. It is unused in surql's source path and reqwest's default TLS stacks do not link on wasm.
• tokio is reduced to ["sync", "macros", "rt", "time"]. tokio::spawn is not available; if you need to fan out, use wasm-bindgen-futures::spawn_local from the caller crate.

Build prerequisites¶

surrealdb-core 3.x pulls ring 0.17 with its wasm32_unknown_unknown_js feature, but ring's build script still invokes the system C compiler with --target=wasm32-unknown-unknown. On macOS, Apple's /usr/bin/clang does not include a wasm32 backend; install Homebrew LLVM and point cc-rs at it:

brew install llvm
export CC_wasm32_unknown_unknown="$(brew --prefix llvm)/bin/clang"
export AR_wasm32_unknown_unknown="$(brew --prefix llvm)/bin/llvm-ar"

Modern Linux distributions (Ubuntu 22.04+ clang-15, Fedora clang) ship with the wasm32 backend built in -- no override needed.

The crate ships .cargo/config.toml with the --cfg=getrandom_backend="wasm_js" rustflag (required by getrandom 0.3 on wasm; the feature flag alone is insufficient -- see https://docs.rs/getrandom/0.3/#webassembly-support) and a scripts/check-wasm.sh wrapper that auto-detects Homebrew LLVM and runs the canonical:

cargo build \
    --target wasm32-unknown-unknown \
    --no-default-features \
    --features client-wasm \
    -p oneiriq-surql

This is the gate downstream consumers (pixel-stroke-persistence, etc.) should mirror in their own CI.

Build-time guarantees¶

• #![deny(missing_docs)] is enforced on every feature combination.
• #![forbid(unsafe_code)] at the crate root.
• cargo doc --no-deps --all-features succeeds with -D warnings.
• cargo clippy --all-targets --all-features -- -D warnings is part of CI and the pre-push hook (see CONTRIBUTING.md).

What's next¶

• Installation - crate + binary install recipes.
• CLI reference - subcommand tree.
• Query UX helpers - type_record, extract_many, aggregate_records, Query::execute.