surrealdb

SurrealDB 3 技能

SurrealDB 3 架构、开发与运维专家级指南。涵盖 SurrealQL、多模型数据建模、图遍历、向量搜索、安全、部署、性能调优、SDK 集成以及更广泛的 SurrealDB 生态，包括 SurrealKit、SurrealMCP、n8n、CodeMirror 和 Agent 技能界面。

面向 AI Agent

获取完整的功能清单、决策树和输出约定：

uv run {baseDir}/scripts/onboard.py --agent

完整的结构化说明请参阅 AGENTS.md。

命令	功能
uv run {baseDir}/scripts/doctor.py	健康检查：验证 surreal CLI、连接状态和版本
uv run {baseDir}/scripts/doctor.py --check	快速检查通过或失败（仅返回退出代码）
uv run {baseDir}/scripts/schema.py introspect	导出正在运行的 SurrealDB 实例的完整架构
uv run {baseDir}/scripts/schema.py tables	列出所有表及其字段数和索引
uv run {baseDir}/scripts/onboard.py --agent	用于 Agent 集成的 JSON 功能清单

先决条件

• surreal CLI -- brew install surrealdb/tap/surreal（macOS），或参阅安装文档
• Python 3.10+ -- 技能脚本所需
• uv -- brew install uv（macOS）、pip install uv，或参阅 uv 文档

可选：

• Docker -- 用于容器化的 SurrealDB 实例（docker run surrealdb/surrealdb:v3）
• 首选的 SDK -- JavaScript、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift 或 Ruby

安全提示：本技能仅介绍通过包管理器和容器进行安装。 建议通过 Homebrew、apt/dnf、Cargo、npm 或 Docker 进行可审计的安装，而不要使用远程的一行式 Shell 安装脚本。

快速开始

凭据警告：以下示例使用 root/root，仅限本地开发使用。切勿使用默认凭据访问生产环境或共享实例。 对于非本地环境，请创建权限范围受限且遵循最小权限原则的用户。

# Start SurrealDB in-memory for LOCAL DEVELOPMENT ONLY
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# Start with persistent RocksDB storage (local dev)
surreal start rocksdb://data/mydb.db --user root --pass root

# Start with SurrealKV (time-travel queries supported, local dev)
surreal start surrealkv://data/mydb --user root --pass root

# Connect via CLI REPL (local dev)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

# Import a SurrealQL file
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql

# Export the database
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql

# Check version
surreal version

# Run the skill health check
uv run {baseDir}/scripts/doctor.py

环境变量

变量	描述	默认值
SURREAL_ENDPOINT	SurrealDB 服务 URL	http://localhost:8000
SURREAL_USER	Root 或命名空间用户名	root
SURREAL_PASS	Root 或命名空间密码	root
SURREAL_NS	默认命名空间	test
SURREAL_DB	默认数据库	test

这些变量直接对应 surreal sql CLI 标志（--endpoint、--user、--pass、--ns、--db），并可被官方 SurrealDB SDK 识别。

核心功能

精通 SurrealQL

全面涵盖 SurrealQL 查询语言：CREATE、SELECT、UPDATE、UPSERT、DELETE、RELATE、INSERT、LIVE SELECT、DEFINE、REMOVE、INFO、子查询、事务、futures 以及所有内置函数（array、crypto、duration、geo、math、meta、object、parse、rand、string、time、type、vector）。

参见：rules/surrealql.md

多模型数据建模

设计能够充分利用 SurrealDB 多模型能力的架构——文档集合、图边、关系引用、向量嵌入、时间序列数据和地理空间坐标——所有数据均可存储在单个数据库中，并使用同一种查询语言。

参见：rules/data-modeling.md

图查询

无需 JOIN 即可进行一流的图遍历。RELATE 可在记录之间创建有类型的边。使用 ->（出向）、<-（入向）和 <->（双向）运算符进行遍历。可在任意深度进行筛选、聚合和递归。

参见：rules/graph-queries.md

向量搜索

使用 HNSW 索引进行内置向量相似度搜索（v3 向量索引类型；在索引构建或重建期间，可回退到暴力搜索）。定义向量字段，创建可配置距离度量（cosine、euclidean、manhattan、minkowski）的索引，并使用 vector::similarity::* 函数进行查询。直接在 SurrealQL 中构建 RAG 流水线和语义搜索。

参见：rules/vector-search.md

安全与权限

通过 DEFINE TABLE ... PERMISSIONS 实现行级安全，支持命名空间／数据库／记录级访问控制；通过 DEFINE ACCESS 实现基于 JWT／令牌的身份验证；通过 DEFINE USER 定义系统用户；并使用 $auth／$session 运行时变量编写权限谓词。

参见：rules/security.md

部署与运维

支持单二进制部署、Docker、Kubernetes（Helm charts）、存储引擎选择（memory、RocksDB、SurrealKV、用于分布式场景的 TiKV）、备份／恢复、监控以及生产环境加固。

参见：rules/deployment.md

性能调优

涵盖索引策略（唯一索引、搜索索引、向量 HNSW）、使用 EXPLAIN 优化查询、连接池、存储引擎权衡、批量操作以及资源限制。

参见：rules/performance.md

SDK 集成

提供适用于 JavaScript/TypeScript（Node.js、Deno、Bun、浏览器）、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift（iOS/macOS/visionOS）和 Ruby 的官方 SDK。内容包括仅提供源码的 C 绑定、Python v3 尚未发布的 API 边界、.NET v0.10.2 beta 接口、连接协议、身份验证流程、实时查询订阅以及类型化记录处理。

参见：rules/sdks.md

Surrealism WASM 扩展

SurrealDB 3 新增：使用 Rust 编写并编译为 WASM 的自定义函数、分析器和逻辑，扩展数据库功能。定义、部署和管理 Surrealism 模块。

参见：rules/surrealism.md

SurrealML 数据库内推理（预览／不稳定）

surrealml 在 GitHub 上发布了 v0.1.2，但截至此快照，PyPI 上最新的 surrealml 软件包仍为 0.0.4。.surml 工件格式以及 [sklearn]、[torch]、[tensorflow] 附加项是稳定文档所述的边界。v1.4.0 文档中的 DEFINE MODEL、INFO FOR MODEL、REMOVE MODEL、ml::name<version>(...)、surreal ml import、db.upload_ml(...) 和 SurMlFile.from_<framework>(...) 工厂方法已在 v1.4.1 中撤回。目前，除非设置 LOCAL_BUILD=TRUE，否则 Python 安装流程会从 GitHub Releases 下载原生库，因此生产环境使用前请锁定版本并进行审核。

参见：rules/surrealml.md

SurrealMCP —— Model Context Protocol 服务

官方 MCP 服务（surrealdb/surrealmcp）让兼容 MCP 的 AI 主机（Claude Desktop、Cursor、VS Code 中的 GitHub Copilot、Zed、n8n）通过一个配置条目读写 SurrealDB。可从源码安装（cargo install --path .）或使用 Docker；不在 crates.io 或 npm 上发布。二进制文件需要 start 子命令。工具的线协议名称采用 snake_case：query、select、insert、create、upsert、update、delete、relate、connect_endpoint、use_namespace、use_database、list_namespaces、list_databases、disconnect_endpoint，以及云工具。

参见：rules/surrealmcp.md、skills/surrealmcp/SKILL.md

编辑器工具

surrealql-language-server v0.1.3 是第一方 LSP 基线；surql-lsp v0.1.1 仍是独立的社区 crate。该规则还涵盖 tree-sitter、第一方编辑器扩展，以及用于自定义 Web 编辑器的 @surrealdb/codemirror／@surrealdb/lezer v1.0.5。各扩展的命令面板和设置仍需以对应扩展的 README 为准。

参见：rules/editor-tooling.md

LangChain 集成（仅限 Python）

langchain-surrealdb 0.2.1（Python；langchain-core ~= 1.1.0、surrealdb ~= 1.0.8 v1 SDK）通过构造函数 SurrealDBVectorStore(embeddings, conn) 将 SurrealDB 作为向量存储使用。v1.4.0 中的 JS 软件包、异步类、聊天历史和混合检索器已在 v1.4.1 中撤回。

参见：rules/langchain.md

生态系统集成

尚未设立专门规则的官方文档及与第一方相邻的内容：面向可自托管 n8n 的 @surrealdb/n8n-nodes-surrealdb v0.6.0、官方 AI 框架文档索引、仅列入路线图的 Spectron／Agent Memory Context、CodeMirror 软件包，以及官方 surrealdb/agent-skills 仓库。请使用此规则，避免将路线图或指引页面误述为生产 API。

参见：rules/ecosystem-integrations.md

生态系统工具

• Surrealist -- SurrealDB 官方 IDE 和 GUI（架构设计器、查询编辑器、图可视化工具）
• Surreal-Sync -- 用于从其他数据库迁移的变更数据捕获（CDC）
• SurrealFS -- 基于 SurrealDB 构建的 AI Agent 文件系统
• SurrealKit -- 期望状态架构同步、基于发布的迁移、数据填充和声明式测试
• SurrealML -- 预览阶段的 .surml 工件工具；服务端调用接口仍不稳定
• SurrealMCP -- 面向 AI Agent 的模型上下文协议服务
• n8n -- 面向可自托管 n8n 工作流的官方限定范围社区软件包
• CodeMirror -- 面向自定义编辑器的官方 SurrealQL 语法软件包
• setup-surreal -- 官方 GitHub Action（surrealdb/setup-surreal@v2），用于在 CI 工作流中运行 SurrealDB。它不是命令行引导工具（v1.4.0 中将其描述为此类工具的文档已在 v1.4.2 中撤回）

参见：rules/surrealist.md、rules/surreal-sync.md、rules/surrealfs.md、rules/surrealkit.md、rules/surrealml.md、rules/surrealmcp.md、rules/ecosystem-integrations.md、rules/deployment.md（setup-surreal 部分）

Doctor / 健康检查

# Full diagnostic (Rich output on stderr, JSON on stdout)
uv run {baseDir}/scripts/doctor.py

# Quick check (exit code 0 = healthy, 1 = issues found)
uv run {baseDir}/scripts/doctor.py --check

# Check a specific endpoint
uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000

doctor 脚本会验证：是否已安装 surreal CLI 且位于 PATH 中、服务是否可访问、身份验证是否成功、命名空间和数据库是否存在、版本是否兼容，以及存储引擎状态。

架构内省

# Full schema dump (all tables, fields, indexes, events, accesses)
uv run {baseDir}/scripts/schema.py introspect

# List tables with summary
uv run {baseDir}/scripts/schema.py tables

# Inspect a specific table
uv run {baseDir}/scripts/schema.py table <table_name>

# Export schema as SurrealQL (reproducible DEFINE statements)
uv run {baseDir}/scripts/schema.py export --format surql

# Export schema as JSON
uv run {baseDir}/scripts/schema.py export --format json

内省使用 INFO FOR DB、INFO FOR TABLE 和 INFO FOR NS 重建完整架构。

规则参考

规则文件	涵盖内容
rules/surrealql.md	SurrealQL 语法、语句、函数、运算符、惯用写法
rules/data-modeling.md	架构设计、记录 ID、字段类型、关系、规范化
rules/graph-queries.md	RELATE、图遍历运算符、路径表达式、递归查询
rules/vector-search.md	向量字段、HNSW 索引（v3 向量索引类型）、相似度函数、RAG 模式
rules/security.md	权限、访问控制、身份验证、JWT、行级安全
rules/deployment.md	安装、存储引擎、Docker、Kubernetes、生产环境配置；surrealdb/setup-surreal@v2 GitHub Action（仅限 CI；不是命令行引导工具）
rules/performance.md	索引、EXPLAIN、查询优化、批量操作、资源调优
rules/sdks.md	JS/TS、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift、Ruby SDK 的用法、连接模式、实时查询
rules/surrealism.md	WASM 扩展、自定义函数、Surrealism 模块编写
rules/surrealml.md	SurrealML 预览范围、.surml 工件、软件包/发布边界、原生依赖警告
rules/surrealmcp.md	模型上下文协议服务：工具目录、宿主配置、传输方式、部署
rules/editor-tooling.md	LSP、tree-sitter 语法、CodeMirror、VS Code / JetBrains / Neovim / Helix / Sublime / Zed 扩展
rules/langchain.md	LangChain Python 集成：向量存储、构造函数 API、custom_filter 边界
rules/ecosystem-integrations.md	n8n、AI 框架文档索引、Spectron 路线图边界、CodeMirror、官方 Agent Skills 仓库
rules/surrealist.md	Surrealist IDE/GUI 用法、架构设计器、查询编辑器
rules/surreal-sync.md	CDC 迁移工具、源/目标连接器、迁移工作流
rules/surrealfs.md	AI Agent 文件系统、文件存储、元数据、检索模式
rules/surrealkit.md	期望状态架构同步、基于发布的迁移、数据填充和声明式数据库测试
rules/gotchas.md	跨领域边缘情况和易错点：升级、图、向量、安全、MCP、SDK（v3.1.4+）

工作流示例

所有工作流示例仅在本地开发中使用 root/root。 生产环境请使用 DEFINE USER，并配置限定范围、遵循最小权限原则的凭据。

新项目设置

# 1. Verify environment
uv run {baseDir}/scripts/doctor.py

# 2. Start SurrealDB
surreal start rocksdb://data/myproject.db --user root --pass root

# 3. Design schema (use rules/data-modeling.md for guidance)
# 4. Import initial schema
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns myapp --db production schema.surql

# 5. Introspect to verify
uv run {baseDir}/scripts/schema.py introspect

从 SurrealDB v2 迁移

# 1. Export v2 data
surreal export --endpoint http://old-server:8000 --user root --pass root \
  --ns myapp --db production v2-backup.surql

# 2. Review breaking changes (see rules/surrealql.md v2->v3 migration section)
# Key changes: range syntax 1..4 is now exclusive of end, new WASM extension system

# 3. Import into v3
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns myapp --db production v2-backup.surql

# 4. Verify schema
uv run {baseDir}/scripts/schema.py introspect

新领域的数据建模

# 1. Read rules/data-modeling.md for schema design patterns
# 2. Read rules/graph-queries.md if your domain has relationships
# 3. Read rules/vector-search.md if you need semantic search
# 4. Draft schema.surql with DEFINE TABLE, DEFINE FIELD, DEFINE INDEX
# 5. Import and test
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns dev --db test schema.surql
uv run {baseDir}/scripts/schema.py introspect

部署到生产环境

# 1. Read rules/deployment.md for storage engine selection and hardening
# 2. Read rules/security.md for access control setup
# 3. Read rules/performance.md for index strategy
# 4. Run doctor against production endpoint
uv run {baseDir}/scripts/doctor.py --endpoint https://prod-surreal:8000
# 5. Verify schema matches expectations
uv run {baseDir}/scripts/schema.py introspect --endpoint https://prod-surreal:8000

上游源检查

# Check if upstream SurrealDB repos have changed since this skill was built
uv run {baseDir}/scripts/check_upstream.py

# JSON-only output for agents
uv run {baseDir}/scripts/check_upstream.py --json

# Only show repos that have new commits
uv run {baseDir}/scripts/check_upstream.py --stale

将所有受跟踪仓库当前 HEAD 的 SHA 和发布标签与 SOURCES.json 中的基线进行比较。使用此功能规划增量技能更新。

源代码来源

此技能于 2026-06-17 根据以下上游来源更新：

仓库	发布版本	快照日期
surrealdb/surrealdb	v3.1.4	2026-06-10
surrealdb/surrealist	surrealist-v3.9.0	2026-06-16
surrealdb/surrealdb.js	v2.0.3	2026-06-17
surrealdb/surrealdb.py	v2.0.0（PyPI）；main 3.0.0 尚未发布	2026-06-17
surrealdb/surrealkit	v0.7.0	2026-06-11
surrealdb/surrealmcp	v0.4.0 独立版；3.1+ 内置 MCP	2026-06-17

文档：surrealdb.com/docs，快照日期为 2026-06-17。

机器可读的来源信息：SOURCES.json。

输出约定

此技能中的所有 Python 脚本都采用双重输出模式：

• stderr：以 Rich 格式呈现的易读输出（表格、面板、状态指示器）
• stdout：供 AI Agent 程序化使用的机器可读 JSON

这意味着 2>/dev/null 会隐藏人类可读的输出，而通过管道传递 stdout 则可获得干净的 JSON，供下游处理。