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:

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 brew install over curl | sh for installing prerequisites.