surrealdb

What this skill does

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