SurrealDB 3 Expert 技能
适用于 GitHub Copilot 的 SurrealDB 3 专家级架构、开发与运维技能。
当 Copilot 应使用此技能
当用户出现以下情况时自动激活：
- 编写或询问 SurrealQL 查询
- 处理
.surql文件 - 为 SurrealDB 设计数据库模式
- 配置 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 | 设计模式、选择字段类型、记录 ID 时 | 多模型模式设计模式 |
| 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 功能和模式设计器 |
| surreal-sync.md | 从其他数据库迁移时 | 从 Postgres、Mongo 等 CDC 同步 |
| surrealfs.md | AI 代理文件系统操作时 | 由 SurrealDB 支持的虚拟文件系统 |
| surrealkit.md | 模式同步、发布、种子数据和声明式测试时 | SurrealDB 应用的期望状态模式管理 |
快速参考
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
# 模式自省
uv run scripts/schema.py introspect
# 检查上游更新
uv run scripts/check_upstream.py
安全说明
- 示例中仅本地开发使用
root/root。生产环境请使用作用域凭据。 - 脚本仅连接到用户指定的端点。无第三方网络调用。
- 在查询插值前，表名会通过
[a-zA-Z_][a-zA-Z0-9_]*验证。 - 优先使用包管理器或容器安装，而不是远程 shell 安装程序。