# Surrealdb

> Expert SurrealDB 3 skill. Use when working with SurrealDB, SurrealQL queries, multi-model data modeling (document, graph, vector, time-series, geospatial), schema design, graph traversal, vector search, security and permissions, deployment and operations, performance tuning, SDK integration (JavaScript, Python, Go, Rust, Java, .NET), Surrealism WASM extensions, Surrealist IDE, Surreal-Sync migrations, or SurrealFS.

- Skill: `jsgforever/surrealdb` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jsgforever/surrealdb`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsgforever/surrealdb/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jsgforever (https://skillmd.com/u/jsgforever)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jsgforever/surrealdb

---


# SurrealDB 3 Expert Skill

Expert-level SurrealDB 3 architecture, development, and operations for GitHub Copilot.

## When Copilot Should Use This Skill

Activate automatically when the user:
- Writes or asks about SurrealQL queries
- Works with `.surql` files
- Designs database schemas for SurrealDB
- Configures SurrealDB deployment or Docker
- Uses SurrealDB SDKs (JavaScript, Python, Go, Rust, Java, .NET)
- Works with graph relationships (RELATE, traversal)
- Implements vector search or RAG patterns
- Configures security, permissions, or access control
- Builds Surrealism WASM extensions
- Migrates data to SurrealDB from other databases

## Rules Reference

This skill contains 12 detailed rule files. Read the relevant rule file when
the user's request matches its domain:

| Rule File | When to Load | Domain |
|-----------|-------------|--------|
| [surrealql.md](../../../rules/surrealql.md) | Writing or debugging SurrealQL queries | Full SurrealQL language reference |
| [data-modeling.md](../../../rules/data-modeling.md) | Designing schemas, choosing field types, record IDs | Multi-model schema design patterns |
| [graph-queries.md](../../../rules/graph-queries.md) | RELATE, graph traversal, path expressions | Graph edge and traversal patterns |
| [vector-search.md](../../../rules/vector-search.md) | HNSW indexes, similarity search, embeddings | Vector search and RAG pipelines |
| [security.md](../../../rules/security.md) | Permissions, auth, JWT, access control | Row-level security and auth flows |
| [deployment.md](../../../rules/deployment.md) | Installing, configuring, running SurrealDB | Storage engines, Docker, Kubernetes |
| [performance.md](../../../rules/performance.md) | Slow queries, index strategy, EXPLAIN | Performance tuning and optimization |
| [sdks.md](../../../rules/sdks.md) | Using SurrealDB from application code | JS, Python, Go, Rust SDK patterns |
| [surrealism.md](../../../rules/surrealism.md) | Writing WASM extensions | Rust to WASM extension development |
| [surrealist.md](../../../rules/surrealist.md) | Using the Surrealist IDE/GUI | IDE features and schema designer |
| [surreal-sync.md](../../../rules/surreal-sync.md) | Migrating from other databases | CDC sync from Postgres, Mongo, etc. |
| [surrealfs.md](../../../rules/surrealfs.md) | AI agent filesystem operations | Virtual FS backed by SurrealDB |

## Quick Reference

### SurrealQL Essentials

```surql
-- Create records
CREATE person:alice SET name = 'Alice', age = 30;

-- Graph edges
RELATE person:alice->follows->person:bob SET since = time::now();

-- Traverse graph
SELECT ->follows->person.name AS following FROM person:alice;

-- Vector search (HNSW)
DEFINE INDEX idx_embed ON document FIELDS embedding HNSW DIMENSION 1536 DIST COSINE;
SELECT * FROM document WHERE embedding <|10,40|> $query_vector;

-- Row-level permissions
DEFINE TABLE post SCHEMALESS PERMISSIONS
  FOR select WHERE published = true OR user = $auth.id
  FOR create, update WHERE user = $auth.id;

-- Live queries
LIVE SELECT * FROM person WHERE age > 25;
```

### Key Concepts

- **Record IDs**: `table:id` (e.g., `person:alice`) -- first-class citizens, no JOINs needed
- **Multi-model**: Document + Graph + Vector + Time-series + Geospatial in one DB
- **Graph operators**: `->` (outgoing), `<-` (incoming), `<->` (bidirectional)
- **KNN operator**: `<|K,EF|>` where K=neighbors, EF=search parameter (NOT distance metric)
- **Storage engines**: memory, RocksDB, SurrealKV (time-travel), TiKV (distributed)
- **WASM extensions**: New in v3 -- write Rust, compile to WASM, register with DEFINE MODULE

### Scripts

```bash
# Health check
uv run scripts/doctor.py

# Schema introspection
uv run scripts/schema.py introspect

# Check upstream for updates
uv run scripts/check_upstream.py
```

## Security Notes

- Examples use `root/root` for local development only. Use scoped credentials in production.
- Scripts connect to user-specified endpoints only. No third-party network calls.
- Table names are validated against `[a-zA-Z_][a-zA-Z0-9_]*` before query interpolation.
- Prefer `brew install` over `curl | sh` for installing prerequisites.