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

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.