---

name: surrealdb description: "Expert SurrealDB 3 architect and developer skill (tracks v3.1.4+). SurrealQL mastery, multi-model data modeling (document, graph, vector, time-series, geospatial), schema design, security, deployment, performance tuning, SDK integration (JS, Python, Go, Rust, Java, .NET, C, PHP, Swift, Kotlin, Ruby), Surrealism WASM extensions, SurrealML scope coverage (preview), built-in MCP (v3.1+) and standalone SurrealMCP, LangChain Python integration, editor tooling (LSP v0.1.6, tree-sitter, CodeMirror v1.0.6, VS Code/JetBrains/Neovim/Zed), and ecosystem integrations (Surrealist v3.9, Surreal-Sync, SurrealFS, SurrealKit v0.7, n8n, Agent Skills, setup-surreal). Universal skill for 30+ AI agents." version: "1.7.1" license: MIT metadata: version: "1.7.1" author: "24601" snapshot_date: "2026-06-17" repository: "https://github.com/24601/surreal-skills" openclaw: requires: env: - SURREAL_ENDPOINT - SURREAL_USER - SURREAL_PASS - SURREAL_NS - SURREAL_DB bins: - surreal - python3 - uv primaryEnv: SURREAL_PASS homepage: "https://github.com/24601/surreal-skills" always: false install: - kind: brew formula: surrealdb/tap/surreal bins: [surreal] - kind: brew formula: uv bins: [uv] requires: binaries: - name: surreal install: "brew install surrealdb/tap/surreal" purpose: "SurrealDB CLI for server management, SQL REPL, import/export" optional: false - name: python3 version: ">=3.10" purpose: "Required for skill scripts (doctor.py, schema.py, onboard.py)" optional: false - name: uv install: "brew install uv" purpose: "PEP 723 script runner -- installs script deps automatically" optional: false - name: docker purpose: "Containerized SurrealDB instances" optional: true - name: gh install: "brew install gh" purpose: "GitHub CLI -- used only by check_upstream.py for comparing upstream repo SHAs" optional: true env_vars: - name: SURREAL_ENDPOINT purpose: "SurrealDB server URL" default: "http://localhost:8000" sensitive: false - name: SURREAL_USER purpose: "Authentication username" default: "root" sensitive: true - name: SURREAL_PASS purpose: "Authentication password" default: "root" sensitive: true - name: SURREAL_NS purpose: "Default namespace" default: "test" sensitive: false - name: SURREAL_DB purpose: "Default database" default: "test" sensitive: false security: no_network: false no_network_note: "doctor.py and schema.py connect to a user-specified SurrealDB endpoint (WebSocket) for health checks and schema introspection. check_upstream.py calls GitHub API via gh CLI to compare upstream repo SHAs. No other third-party network calls." no_credentials: false no_credentials_note: "Scripts accept SURREAL_USER/SURREAL_PASS for DB authentication. No credentials are stored in the skill itself." no_env_write: true no_file_write: false no_file_write_note: "schema.py can write exported schema files when --output-dir is set. onboard.py can write a local .env file during interactive setup if the user explicitly confirms." no_shell_exec: false no_shell_exec_note: "Scripts invoke surreal CLI and gh for health checks." scripts_auditable: true scripts_use_pep723: true no_obfuscated_code: true no_binary_blobs: true no_minified_scripts: true no_curl_pipe_sh: true

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 wider SurrealDB ecosystem, including SurrealKit, SurrealMCP, n8n, CodeMirror, and agent-skill surfaces.

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, Kotlin, .NET, C, PHP, Swift, or Ruby

Security note: This skill documents package-manager and container installs only. Prefer auditable installs through Homebrew, apt/dnf, Cargo, npm, or Docker rather than remote one-line shell installers.

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.

# Start SurrealDB in-memory for LOCAL DEVELOPMENT ONLY
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# Start with persistent RocksDB storage (local dev)
surreal start rocksdb://data/mydb.db --user root --pass root

# Start with SurrealKV (time-travel queries supported, local dev)
surreal start surrealkv://data/mydb --user root --pass root

# Connect via CLI REPL (local dev)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

# Import a SurrealQL file
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql

# Export the database
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql

# Check version
surreal version

# Run the skill health check
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 indexes (the v3 vector index type; brute-force is available as a fallback during index build/rebuild). 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), 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, Kotlin, .NET, C, PHP, Swift (iOS/macOS/visionOS), and Ruby. Includes the source-only C binding, Python v3 unreleased API boundary, .NET v0.10.2 beta surface, connection protocols, 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

SurrealML In-Database Inference (preview / unstable)

surrealml has a GitHub v0.1.2 release, but PyPI still exposes surrealml 0.0.4 as the latest package as of this snapshot. The .surml artifact format and [sklearn], [torch], [tensorflow] extras are the stable documented boundary. The v1.4.0 documentation for DEFINE MODEL, INFO FOR MODEL, REMOVE MODEL, ml::name<version>(...), surreal ml import, db.upload_ml(...), and the SurMlFile.from_<framework>(...) factory methods was retracted in v1.4.1. The current Python setup path downloads native libraries from GitHub Releases unless LOCAL_BUILD=TRUE, so pin and audit before production use.

See: rules/surrealml.md

SurrealMCP -- Model Context Protocol Server

The official MCP server (surrealdb/surrealmcp) lets MCP-compatible AI hosts (Claude Desktop, Cursor, GitHub Copilot in VS Code, Zed, n8n) read and write SurrealDB through one configuration entry. Install from source (cargo install --path .) or Docker; not on crates.io or npm. Binary requires start subcommand. Tool wire-names are snake_case: query, select, insert, create, upsert, update, delete, relate, connect_endpoint, use_namespace, use_database, list_namespaces, list_databases, disconnect_endpoint, plus cloud tools.

See: rules/surrealmcp.md, skills/surrealmcp/SKILL.md

Editor Tooling

surrealql-language-server v0.1.3 is the first-party LSP baseline; surql-lsp v0.1.1 remains a separate community crate. The rule tracks tree-sitter, first-party editor extensions, and @surrealdb/codemirror / @surrealdb/lezer v1.0.5 for custom web editors. Per-extension command palettes and settings still need each extension README as source of truth.

See: rules/editor-tooling.md

LangChain Integration (Python only)

langchain-surrealdb 0.2.1 (Python; langchain-core ~= 1.1.0, surrealdb ~= 1.0.8 v1 SDK) exposes SurrealDB as a vector store via constructor SurrealDBVectorStore(embeddings, conn). JS package, async class, chat history, and hybrid retriever from v1.4.0 were retracted in v1