--- 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: ```bash uv run {baseDir}/scripts/onboard.py --agent ``` See [AGENTS.md]({baseDir}/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](https://surrealdb.com/docs/surrealdb/installation) - **Python 3.10+** -- Required for skill scripts - **uv** -- `brew install uv` (macOS) or `pip install uv` or see [uv docs](https://docs.astral.sh/uv/getting-started/installation/) 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. ```bash # 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(...)`, `surreal ml import`, `db.upload_ml(...)`, and the `SurMlFile.from_(...)` 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.4.1. See: `rules/langchain.md` ### Ecosystem Integrations Official-docs and first-party-adjacent surfaces that are not full dedicated rules yet: `@surrealdb/n8n-nodes-surrealdb` v0.6.0 for self-hosted n8n, the official AI framework docs index, Spectron / Agent Memory Context as roadmap-only, CodeMirror packages, and the official `surrealdb/agent-skills` repo. Use this rule to avoid presenting roadmap or pointer pages as production APIs. See: `rules/ecosystem-integrations.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 - **SurrealKit** -- Desired-state schema sync, rollout-based migrations, seeding, and declarative tests - **SurrealML** -- Preview-stage `.surml` artifact tooling; server invocation surface still unstable - **SurrealMCP** -- Model Context Protocol server for AI agents - **n8n** -- Official scoped community package for self-hosted n8n workflows - **CodeMirror** -- Official SurrealQL syntax packages for custom editors - **setup-surreal** -- Official GitHub Action (`surrealdb/setup-surreal@v2`) for running SurrealDB in CI workflows. Not a CLI bootstrap (the v1.4.0 documentation that described it as one was retracted in v1.4.2) See: `rules/surrealist.md`, `rules/surreal-sync.md`, `rules/surrealfs.md`, `rules/surrealkit.md`, `rules/surrealml.md`, `rules/surrealmcp.md`, `rules/ecosystem-integrations.md`, `rules/deployment.md` (setup-surreal section) ## Doctor / Health Check ```bash # Full diagnostic (Rich output on stderr, JSON on stdout) uv run {baseDir}/scripts/doctor.py # Quick check (exit code 0 = healthy, 1 = issues found) uv run {baseDir}/scripts/doctor.py --check # Check a specific endpoint 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 ```bash # Full schema dump (all tables, fields, indexes, events, accesses) uv run {baseDir}/scripts/schema.py introspect # List tables with summary uv run {baseDir}/scripts/schema.py tables # Inspect a specific table uv run {baseDir}/scripts/schema.py table # Export schema as SurrealQL (reproducible DEFINE statements) uv run {baseDir}/scripts/schema.py export --format surql # Export schema as JSON 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 indexes (the v3 vector index type), 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; `surrealdb/setup-surreal@v2` GitHub Action (CI-only; not a CLI bootstrap) | | `rules/performance.md` | Indexes, EXPLAIN, query optimization, batch ops, resource tuning | | `rules/sdks.md` | JS/TS, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby SDK usage, connection patterns, live queries | | `rules/surrealism.md` | WASM extensions, custom functions, Surrealism module authoring | | `rules/surrealml.md` | SurrealML preview scope, .surml artifacts, package/release boundaries, native dependency warning | | `rules/surrealmcp.md` | Model Context Protocol server: tool catalog, host configuration, transports, deployment | | `rules/editor-tooling.md` | LSP, tree-sitter grammar, CodeMirror, VS Code / JetBrains / Neovim / Helix / Sublime / Zed extensions | | `rules/langchain.md` | LangChain Python integration: vector store, constructor API, custom_filter boundary | | `rules/ecosystem-integrations.md` | n8n, AI framework docs index, Spectron roadmap boundary, CodeMirror, official Agent Skills repo | | `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 | | `rules/surrealkit.md` | Desired-state schema sync, rollout-based migrations, seeding, and declarative DB testing | | `rules/gotchas.md` | Cross-domain edge cases and footguns: upgrade, graph, vector, security, MCP, SDKs (v3.1.4+) | ## Workflow Examples > **All workflow examples use `root/root` for local development only.** > For production, use `DEFINE USER` with scoped, least-privilege credentials. ### New Project Setup ```bash # 1. Verify environment uv run {baseDir}/scripts/doctor.py # 2. Start SurrealDB surreal start rocksdb://data/myproject.db --user root --pass root # 3. Design schema (use rules/data-modeling.md for guidance) # 4. Import initial schema surreal import --endpoint http://localhost:8000 --user root --pass root \ --ns myapp --db production schema.surql # 5. Introspect to verify uv run {baseDir}/scripts/schema.py introspect ``` ### Migration from SurrealDB v2 ```bash # 1. Export v2 data surreal export --endpoint http://old-server:8000 --user root --pass root \ --ns myapp --db production v2-backup.surql # 2. Review breaking changes (see rules/surrealql.md v2->v3 migration section) # Key changes: range syntax 1..4 is now exclusive of end, new WASM extension system # 3. Import into v3 surreal import --endpoint http://localhost:8000 --user root --pass root \ --ns myapp --db production v2-backup.surql # 4. Verify schema uv run {baseDir}/scripts/schema.py introspect ``` ### Data Modeling for a New Domain ```bash # 1. Read rules/data-modeling.md for schema design patterns # 2. Read rules/graph-queries.md if your domain has relationships # 3. Read rules/vector-search.md if you need semantic search # 4. Draft schema.surql with DEFINE TABLE, DEFINE FIELD, DEFINE INDEX # 5. Import and test 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 ```bash # 1. Read rules/deployment.md for storage engine selection and hardening # 2. Read rules/security.md for access control setup # 3. Read rules/performance.md for index strategy # 4. Run doctor against production endpoint uv run {baseDir}/scripts/doctor.py --endpoint https://prod-surreal:8000 # 5. Verify schema matches expectations uv run {baseDir}/scripts/schema.py introspect --endpoint https://prod-surreal:8000 ``` ## Upstream Source Check ```bash # Check if upstream SurrealDB repos have changed since this skill was built uv run {baseDir}/scripts/check_upstream.py # JSON-only output for agents uv run {baseDir}/scripts/check_upstream.py --json # Only show repos that have new commits 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 refreshed on **2026-06-17** from these upstream sources: | Repository | Release | Snapshot Date | |------------|---------|---------------| | [surrealdb/surrealdb](https://github.com/surrealdb/surrealdb) | v3.1.4 | 2026-06-10 | | [surrealdb/surrealist](https://github.com/surrealdb/surrealist) | surrealist-v3.9.0 | 2026-06-16 | | [surrealdb/surrealdb.js](https://github.com/surrealdb/surrealdb.js) | v2.0.3 | 2026-06-17 | | [surrealdb/surrealdb.py](https://github.com/surrealdb/surrealdb.py) | v2.0.0 (PyPI); main 3.0.0 unreleased | 2026-06-17 | | [surrealdb/surrealkit](https://github.com/surrealdb/surrealkit) | v0.7.0 | 2026-06-11 | | [surrealdb/surrealmcp](https://github.com/surrealdb/surrealmcp) | v0.4.0 standalone; built-in MCP in 3.1+ | 2026-06-17 | Documentation: [surrealdb.com/docs](https://surrealdb.com/docs) snapshot 2026-06-17. 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.