--- name: surrealdb description: "Expert SurrealDB 3 architect and developer skill. SurrealQL mastery, multi-model data modeling (document, graph, vector, time-series, geospatial), schema design, security, deployment, performance tuning, SDK integration (JS, Python, Go, Rust), Surrealism WASM extensions, and full ecosystem (Surrealist, Surreal-Sync, SurrealFS). Universal skill for 30+ AI agents." license: MIT metadata: version: "1.2.1" author: "24601" snapshot_date: "2026-03-13" repository: "https://github.com/24601/surreal-skills" 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: true 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: false no_curl_pipe_sh_note: "Documentation mentions curl|sh as ONE install option alongside safer alternatives (brew, Docker, package managers). The skill itself never executes curl|sh." ---

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.

# 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 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

...