SurrealDB 3 Skill
Expert-level SurrealDB 3 architecture, development, and operations. Covers SurrealQL, multi-model data modeling, graph traversal, vector search, security, deployment, performance tuning, SDK integration, and the full SurrealDB ecosystem.
For AI Agents
Get a full capabilities manifest, decision trees, and output contracts:
uv run {baseDir}/scripts/onboard.py --agent
See AGENTS.md for the complete structured briefing.
| Command | What It Does |
|---|
uv run {baseDir}/scripts/doctor.py | Health check: verify surreal CLI, connectivity, versions |
uv run {baseDir}/scripts/doctor.py --check | Quick pass/fail check (exit code only) |
uv run {baseDir}/scripts/schema.py introspect | Dump full schema of a running SurrealDB instance |
uv run {baseDir}/scripts/schema.py tables | List all tables with field counts and indexes |
uv run {baseDir}/scripts/onboard.py --agent | JSON capabilities manifest for agent integration |
Prerequisites
- surreal CLI --
brew install surrealdb/tap/surreal (macOS) or see install docs
- Python 3.10+ -- Required for skill scripts
- uv --
brew install uv (macOS) or pip install uv or see uv docs
Optional:
- Docker -- For containerized SurrealDB instances (
docker run surrealdb/surrealdb:v3)
- SDK of choice -- JavaScript, Python, Go, Rust, Java, .NET, C, PHP, or Dart
Security note: This skill's documentation references package manager installs
(brew, pip, cargo, npm, Docker) as the recommended install method. If you
encounter curl | sh examples in the rules files, prefer your OS package
manager or download-and-review workflow instead.
Quick Start
Credential warning: Examples below use root/root for local development
only. Never use default credentials against production or shared instances.
Create scoped, least-privilege users for non-local environments.
surreal start memory --user root --pass root --bind 127.0.0.1:8000
surreal start rocksdb://data/mydb.db --user root --pass root
surreal start surrealkv://data/mydb --user root --pass root
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql
surreal version
uv run {baseDir}/scripts/doctor.py
Environment Variables
| Variable | Description | Default |
|---|
SURREAL_ENDPOINT | SurrealDB server URL | http://localhost:8000 |
SURREAL_USER | Root or namespace username | root |
SURREAL_PASS | Root or namespace password | root |
SURREAL_NS | Default namespace | test |
SURREAL_DB | Default database | test |
These map directly to the surreal sql CLI flags (--endpoint, --user, --pass, --ns, --db) and are recognized by official SurrealDB SDKs.
Core Capabilities
SurrealQL Mastery
Full coverage of the SurrealQL query language: CREATE, SELECT, UPDATE, UPSERT, DELETE, RELATE, INSERT, LIVE SELECT, DEFINE, REMOVE, INFO, subqueries, transactions, futures, and all built-in functions (array, crypto, duration, geo, math, meta, object, parse, rand, string, time, type, vector).
See: rules/surrealql.md
Multi-Model Data Modeling
Design schemas that leverage SurrealDB's multi-model capabilities -- document collections, graph edges, relational references, vector embeddings, time-series data, and geospatial coordinates -- all in a single database with a single query language.
See: rules/data-modeling.md
Graph Queries
First-class graph traversal without JOINs. RELATE creates typed edges between records. Traverse with -> (outgoing), <- (incoming), and <-> (bidirectional) operators. Filter, aggregate, and recurse at any depth.
See: rules/graph-queries.md
Vector Search
Built-in vector similarity search using HNSW and brute-force indexes. Define vector fields, create indexes with configurable distance metrics (cosine, euclidean, manhattan, minkowski), and query with vector::similarity::* functions. Build RAG pipelines and semantic search directly in SurrealQL.
See: rules/vector-search.md
Security and Permissions
Row-level security via DEFINE TABLE ... PERMISSIONS, namespace/database/record-level access control, DEFINE ACCESS for JWT/token-based auth, DEFINE USER for system users, and $auth/$session runtime variables for permission predicates.
See: rules/security.md
Deployment and Operations
Single-binary deployment, Docker, Kubernetes (Helm charts), storage engine selection (memory, RocksDB, SurrealKV, TiKV for distributed), backup/restore, monitoring, and production hardening.
See: rules/deployment.md
Performance Tuning
Index strategies (unique, search, vector HNSW, MTree), query optimization with EXPLAIN, connection pooling, storage engine trade-offs, batch operations, and resource limits.
See: rules/performance.md
SDK Integration
Official SDKs for JavaScript/TypeScript (Node.js, Deno, Bun, browser), Python, Go, Rust, Java, .NET, C, PHP, and Dart. Connection protocols (HTTP, WebSocket), authentication flows, live query subscriptions, and typed record handling.
See: rules/sdks.md
Surrealism WASM Extensions
New in SurrealDB 3: extend the database with custom functions, analyzers, and logic written in Rust and compiled to WASM. Define, deploy, and manage Surrealism modules.
See: rules/surrealism.md
Ecosystem Tools
- Surrealist -- Official IDE and GUI for SurrealDB (schema designer, query editor, graph visualizer)
- Surreal-Sync -- Change Data Capture (CDC) for migrations from other databases
- SurrealFS -- AI agent filesystem built on SurrealDB
- SurrealML -- Machine learning model management and inference within SurrealDB
See: rules/surrealist.md, rules/surreal-sync.md, rules/surrealfs.md
Doctor / Health Check
uv run {baseDir}/scripts/doctor.py
uv run {baseDir}/scripts/doctor.py --check
uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000
The doctor script verifies: surreal CLI installed and on PATH, server reachable, authentication succeeds, namespace and database exist, version compatibility, and storage engine status.
Schema Introspection
uv run {baseDir}/scripts/schema.py introspect
uv run {baseDir}/scripts/schema.py tables
uv run {baseDir}/scripts/schema.py table <table_name>
uv run {baseDir}/scripts/schema.py export --format surql
uv run {baseDir}/scripts/schema.py export --format json
Introspection uses INFO FOR DB, INFO FOR TABLE, and INFO FOR NS to reconstruct the full schema.
Rules Reference
| Rule File | Coverage |
|---|
rules/surrealql.md | SurrealQL syntax, statements, functions, operators, idioms |
rules/data-modeling.md | Schema design, record IDs, field types, relations, normalization |
rules/graph-queries.md | RELATE, graph traversal operators, path expressions, recursive queries |
rules/vector-search.md | Vector fields, HNSW/brute-force indexes, similarity functions, RAG patterns |
rules/security.md | Permissions, access control, authentication, JWT, row-level security |
rules/deployment.md | Installation, storage engines, Docker, Kubernetes, production config |
rules/performance.md | Indexes, EXPLAIN, query optimization, batch ops, resource tuning |
rules/sdks.md | JavaScript, Python, Go, Rust SDK usage, connection patterns, live queries |
rules/surrealism.md | WASM extensions, custom functions, Surrealism module authoring |
rules/surrealist.md | Surrealist IDE/GUI usage, schema designer, query editor |
rules/surreal-sync.md | CDC migration tool, source/target connectors, migration workflows |
rules/surrealfs.md | AI agent filesystem, file storage, metadata, retrieval patterns |
Workflow Examples
New Project Setup
uv run {baseDir}/scripts/doctor.py
surreal start rocksdb://data/myproject.db --user root --pass root
surreal import --endpoint http://localhost:8000 --user root --pass root \
--ns myapp --db production schema.surql
uv run {baseDir}/scripts/schema.py introspect
Migration from SurrealDB v2
surreal export --endpoint http://old-server:8000 --user root --pass root \
--ns myapp --db production v2-backup.surql
surreal import --endpoint http://localhost:8000 --user root --pass root \
--ns myapp --db production v2-backup.surql
uv run {baseDir}/scripts/schema.py introspect
Data Modeling for a New Domain
surreal import --endpoint http://localhost:8000 --user root --pass root \
--ns dev --db test schema.surql
uv run {baseDir}/scripts/schema.py introspect
Deploying to Production
uv run {baseDir}/scripts/doctor.py --endpoint https://prod-surreal:8000
uv run {baseDir}/scripts/schema.py introspect --endpoint https://prod-surreal:8000
Upstream Source Check
uv run {baseDir}/scripts/check_upstream.py
uv run {baseDir}/scripts/check_upstream.py --json
uv run {baseDir}/scripts/check_upstream.py --stale
Compares current HEAD SHAs and release tags of all tracked repos against the
baselines in SOURCES.json. Use this to plan incremental skill updates.
Source Provenance
This skill was built on 2026-02-19 from these upstream sources:
Documentation: surrealdb.com/docs snapshot 2026-02-22.
Machine-readable provenance: SOURCES.json.
Output Convention
All Python scripts in this skill follow a dual-output pattern:
- stderr: Rich-formatted human-readable output (tables, panels, status indicators)
- stdout: Machine-readable JSON for programmatic consumption by AI agents
This means 2>/dev/null hides the human output, and piping stdout gives clean JSON for downstream processing.
