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, Kotlin, .NET, C, PHP, Swift, Ruby)
• 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
• Connects SurrealDB to MCP hosts, n8n, AI frameworks, or custom editors

Rules Reference

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

Quick Reference

SurrealQL Essentials

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

# 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 package-manager or container installs over remote shell installers.