aibot88 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
.surqlfiles - 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 13 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 |
| 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/rootfor 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.