24601/surreal-skills

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:

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, Java, Kotlin, .NET, C, PHP, Swift, Ruby patterns
surrealism.md	Writing WASM extensions	Rust to WASM extension development
surrealml.md	Working near SurrealML	Preview .surml boundary and native dependency warning
surrealmcp.md	Connecting AI hosts	MCP tool catalog and deployment
editor-tooling.md	Editor / IDE support	LSP, tree-sitter, CodeMirror, editor extensions
langchain.md	LangChain RAG	Python vector store API
ecosystem-integrations.md	n8n / framework pointers	n8n, AI framework docs, Spectron boundary, Agent Skills
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
surrealkit.md	Schema sync, rollouts, seeds, and declarative tests	Desired-state schema management for SurrealDB apps

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.