SurrealDB 3 專家技能
專為 GitHub Copilot 提供的 SurrealDB 3 架構、開發與運維專家級技能。
何時 Copilot 應使用此技能
當使用者有下列行為時自動啟用：
- 撰寫或詢問 SurrealQL 查詢
- 處理
.surql檔案 - 設計 SurrealDB 的資料庫 Schema
- 設定 SurrealDB 部署或 Docker
- 使用 SurrealDB SDK（JavaScript、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift、Ruby）
- 處理圖形關聯（RELATE、遍歷）
- 實作向量搜尋或 RAG 模式
- 設定安全性、權限或存取控制
- 建構 Surrealism WASM 擴充
- 從其他資料庫遷移至 SurrealDB
- 將 SurrealDB 連接到 MCP 主機、n8n、AI 框架或自訂編輯器
規則參考
此技能包含 18 個詳細規則檔案。當使用者的請求符合其領域時，請讀取對應的規則檔案：
| 規則檔案 | 何時載入 | 領域 |
|---|---|---|
| surrealql.md | 撰寫或除錯 SurrealQL 查詢 | 完整 SurrealQL 語言參考 |
| data-modeling.md | 設計 Schema、選擇欄位類型、記錄 ID | 多模型 Schema 設計模式 |
| graph-queries.md | RELATE、圖形遍歷、路徑表達式 | 圖形邊與遍歷模式 |
| vector-search.md | HNSW 索引、相似度搜尋、嵌入 | 向量搜尋與 RAG 管線 |
| security.md | 權限、認證、JWT、存取控制 | 列層級安全性與認證流程 |
| deployment.md | 安裝、設定、執行 SurrealDB | 儲存引擎、Docker、Kubernetes |
| performance.md | 慢查詢、索引策略、EXPLAIN | 效能調校與最佳化 |
| sdks.md | 從應用程式程式碼使用 SurrealDB | JS、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift、Ruby 模式 |
| surrealism.md | 撰寫 WASM 擴充 | Rust 到 WASM 擴充開發 |
| surrealml.md | 使用 SurrealML 相關功能 | 預覽 .surml 邊界與原生相依性警告 |
| surrealmcp.md | 連接 AI 主機 | MCP 工具目錄與部署 |
| editor-tooling.md | 編輯器 / IDE 支援 | LSP、tree-sitter、CodeMirror、編輯器擴充 |
| langchain.md | LangChain RAG | Python 向量儲存 API |
| ecosystem-integrations.md | n8n / 框架參考 | n8n、AI 框架文件、Spectron 邊界、Agent 技能 |
| surrealist.md | 使用 Surrealist IDE/GUI | IDE 功能與 Schema 設計器 |
| surreal-sync.md | 從其他資料庫遷移 | 從 Postgres、Mongo 等進行 CDC 同步 |
| surrealfs.md | AI 代理檔案系統操作 | 基於 SurrealDB 的虛擬檔案系統 |
| surrealkit.md | Schema 同步、發佈、種子資料與宣告式測試 | SurrealDB 應用的期望狀態 Schema 管理 |
快速參考
SurrealQL 要點
-- 建立記錄
CREATE person:alice SET name = 'Alice', age = 30;
-- 圖形邊
RELATE person:alice->follows->person:bob SET since = time::now();
-- 遍歷圖形
SELECT ->follows->person.name AS following FROM person:alice;
-- 向量搜尋 (HNSW)
DEFINE INDEX idx_embed ON document FIELDS embedding HNSW DIMENSION 1536 DIST COSINE;
SELECT * FROM document WHERE embedding <|10,40|> $query_vector;
-- 列層級權限
DEFINE TABLE post SCHEMALESS PERMISSIONS
FOR select WHERE published = true OR user = $auth.id
FOR create, update WHERE user = $auth.id;
-- 即時查詢
LIVE SELECT * FROM person WHERE age > 25;
關鍵概念
- 記錄 ID：
table:id（例如person:alice）—— 一級公民，無需 JOIN - 多模型：文件 + 圖形 + 向量 + 時間序列 + 地理空間，單一資料庫
- 圖形運算子：
->（傳出）、<-（傳入）、<->（雙向） - KNN 運算子：
<|K,EF|>其中 K=鄰居數，EF=搜尋參數（非距離度量） - 儲存引擎：memory、RocksDB、SurrealKV（時光旅行）、TiKV（分散式）
- WASM 擴充：v3 新功能——撰寫 Rust，編譯為 WASM，使用 DEFINE MODULE 註冊
腳本
# 健康檢查
uv run scripts/doctor.py
# Schema 內省
uv run scripts/schema.py introspect
# 檢查上游更新
uv run scripts/check_upstream.py
安全注意事項
- 範例使用
root/root僅限於本機開發。生產環境請使用限域憑證。 - 腳本僅連線到使用者指定的端點。不進行第三方網路呼叫。
- 在查詢插值前，資料表名稱會以
[a-zA-Z_][a-zA-Z0-9_]*進行驗證。 - 建議使用套件管理器或容器安裝，而非遠端 shell 安裝程式。