surrealkit

SurrealKit

用于操作 SurrealKit 的技能。SurrealKit 是 SurrealDB 的架构管理和迁移 CLI。本文基于 SurrealKit 1.0 编写（当前版本为 1.0.0-beta.3）。

SurrealKit 可让 SurrealDB 数据库与 .surql 架构文件保持同步。它提供两种互补的工作流——用于开发的快速声明式 sync，以及用于共享数据库和生产数据库的受控分阶段 rollouts——还支持数据填充、静态分析、类型生成和声明式测试框架。

何时使用此技能

在以下场景中，请参考这些指南：

• 搭建新的 SurrealDB 项目（surrealkit init）或编写模板
• 在开发环境中应用架构变更（surrealkit sync）
• 规划、执行或回滚生产迁移（surrealkit rollout）
• 在现有数据库上采用 SurrealKit（surrealkit rollout baseline）
• 将架构拆分为独立跟踪的模块，或将其应用到多个数据库
• 无需连接数据库即可对照架构静态检查 SurrealQL（surrealkit check）
• 根据实时架构生成 JSON 或 TypeScript 类型（surrealkit typegen）
• 为架构、权限或 API 端点编写或运行声明式测试（surrealkit test）

此技能介绍 SurrealKit 工具本身。若要编写 .surql 文件中的实际架构、数据填充和查询语句，请使用 surrealql 技能。

安装

方法	命令
cargo binstall（推荐）	cargo binstall surrealkit
Cargo（从源代码安装）	cargo install surrealkit
Docker	docker pull ghcr.io/surrealdb/surrealkit:latest
预编译 tarball	GitHub Releases

从源代码构建需要 C 编译器和 cmake。静态分析默认启用，会添加 tree-sitter（约 7.5 MiB，构建时间约 100 秒）；使用 cargo install surrealkit --no-default-features --features kv-mem,cli 可将其移除——该二进制不包含 check、generate 或 watch。预编译二进制和 cargo binstall 始终包含分析功能。

Docker 镜像采用 distroless（约 25 MB，uid 65532），并会在执行完成后退出，适合在 Docker Compose 中与 SurrealDB 一起运行“应用架构后再运行测试”的流水线。

命令一览

命令	用途	参考
surrealkit init	从模板搭建项目，并选择可选功能	init-templates.md
surrealkit sync	以声明式方式将数据库与架构文件同步（开发环境）	sync-rollouts.md
surrealkit rollout <sub>	规划、暂存、完成、回滚和修复迁移（共享环境／生产环境）	sync-rollouts.md
surrealkit seed [--force]	运行 database/seed/ 中的数据填充文件（幂等，按哈希跟踪）	sync-rollouts.md
surrealkit check	对项目的 SurrealQL 进行静态分析——不连接数据库	static-analysis.md
surrealkit generate / watch	为嵌入式查询生成／持续刷新类型化客户端	static-analysis.md
surrealkit typegen	检查实时数据库并生成 JSON／TypeScript 类型	typegen.md
surrealkit test	运行声明式 TOML 测试套件	testing.md
surrealkit apply <path>	直接应用单个 .surql 文件	—
surrealkit setup	运行 database/setup.surql（SurrealKit 自身的元数据表）	—
surrealkit status	显示同步／发布状态	—

运行 surrealkit <command> --help，确认已安装版本支持的标志。

连接与配置

全局标志适用于每条命令，并按以下顺序解析（优先级从高到低）： surrealkit.toml 中的 [target.<name>] > CLI 标志 > 系统环境变量 > .env 文件 > 默认值。

surrealkit --host http://localhost:8000 --ns my_ns --db my_db \
  --user root --pass root --auth-level root sync

标志	环境变量	默认值
--host	SURREALDB_HOST	http://localhost:8000
--ns	SURREALDB_NAMESPACE	db
--db	SURREALDB_NAME	test
--user	SURREALDB_USER	root
--pass	SURREALDB_PASSWORD	root
--auth-level	SURREALDB_AUTH_LEVEL	root（root / namespace|ns / database|db / none）
--folder	SURREALDB_FOLDER	./database
--connect-timeout-secs	SURREALDB_CONNECT_TIMEOUT_SECS	30（0 表示无限等待）
--query-timeout-secs	SURREALDB_QUERY_TIMEOUT_SECS	未设置（rollout 步骤的 SQL 将无限等待）

DATABASE_* 别名已在 1.0 中移除。 如果只设置该别名，而未设置对应的 SURREALDB_* 替代项，将直接报错，不会静默回退。升级时请更新 .env 文件和 CI。

选择标志也是全局标志：-s/--schema <name>、-t/--target <name>、--all、--keep-going、--no-deps ——参见 modules-targets.md。

项目根目录下有 surrealkit.toml，其中包含 [variables]、[typegen]、[analyze]、[schema.*] 和 [target.*] 部分。

嵌入式数据库

将 --host 指向嵌入式端点，即可管理进程内数据存储；系统会自动跳过身份验证。

surrealkit --host surrealkv://./data --ns my_ns --db my_db sync

支持的 scheme：surrealkv://、rocksdb://、speedb://、mem://、file://、tikv://。--auth-level none 会在任何端点强制使用免登录路径。预构建的 CLI 仅包含内存引擎——如需使用磁盘引擎，请使用 --features kv-surrealkv（或 kv-rocksdb，或 embedded）进行构建。嵌入式引擎会获取独占锁，因此使用 CLI 操作前请先停止应用程序；如需在应用程序启动时于其内部管理 schema，请改用库。

模板变量

在任何 .surql 文件（schema、seed 或 rollout SQL）中使用 ${VAR_NAME} 标记。名称不区分大小写。变量值按以下顺序解析（优先级从高到低）：

1. --var KEY=VALUE CLI 标志（可重复使用）
2. SURREALKIT_VAR_<KEY> 环境变量
3. surrealkit.toml 中的 [variables] 部分

# surrealkit.toml
[variables]
schema_prefix = "myapp"
talent_username = "talent_rw"

surrealkit sync --var schema_prefix=acme --var talent_username=talent_rw

• 未定义的变量会直接报错——SurrealKit 绝不会静默跳过变量，也不会将标记保留在 SQL 中。
• 如需保留字面量 ${...}，请将美元符号加倍：$${literal}。
• 替换以文本方式进行，因此 SurrealQL 字符串字面量中的 ${VAR} 也会被替换。
• 替换会在 sync、seed、apply 和 rollout start/complete/rollback 中运行。在 rollout plan/baseline/status/lint 中不会运行（这些命令不会执行用户 SQL）。

项目结构

surrealkit init 会创建一个 database/ 目录（使用 --folder / SURREALDB_FOLDER 可更改根目录）：

database/
├── schema/                     # Schema definitions (.surql) — the default module, the source of truth
├── modules/<name>/schema/      # Additional schema modules, when declared in surrealkit.toml
├── rollouts/                   # Generated rollout manifests (.toml)
├── snapshots/                  # Drift tracking — what `rollout plan` diffs against
│   ├── schema_snapshot.json
│   └── catalog_snapshot.json
├── seed/                       # Seeding files (.surql)
├── tests/
│   ├── suites/                 # Test suites (.toml)
│   ├── fixtures/               # Test fixture data (.surql)
│   └── config.toml             # Global test config
└── setup.surql                 # One-time setup script (SurrealKit's own metadata tables)
surrealkit.toml                 # Project config

SurrealKit 会在数据库的三个元数据表中跟踪自身状态：__entity（文件哈希和每个定义的记录）、__rollout（rollout 运行状态）和 __seed（seed 文件哈希）。

规则与约定

• 同步与发布： 对于本地、预览及其他可随时丢弃的数据库，在安全的情况下可立即匹配文件，请使用 sync；对于需要审核、分阶段执行、回滚或由操作员控制切换的共享／生产数据库，请使用 rollout。
• 架构文件是唯一事实来源。sync 会创建、更新和清理 SurrealKit 管理的对象，使其与架构目录保持一致。
• 架构文件应包含 DEFINE／REMOVE 语句。只有使用 --allow-all-statements 时才允许其他语句（INSERT、UPDATE、CREATE）；该选项会停用目录实体跟踪。
• rollout plan 会与 database/snapshots/ 中的内容比较，而不是与实时数据库比较；sync 从不写入快照。 如果此前一段时间只使用 sync，之后要采用 rollout，必须先执行 rollout baseline，否则第一个计划会提议包含你所有文件的变更。
• 将生成的清单和更新后的快照一起提交；要撤销计划，必须同时撤销二者。
• 将 SurrealQL 存储在扩展名为 .surql 的文件中。使用 surrealql 技能中介绍的工具验证和格式化生成的 SurrealQL（surreal validate、npx @surrealdb/surql-fmt），并在 CI 中通过 surrealkit check 进行检查。
• SurrealKit 仍处于早期阶段，且在持续演进；请通过 surrealkit --help 和 README 确认命令用法。

将 SurrealKit 用作 Rust 库

surrealkit crate 可在应用内部运行同步、数据填充和 rollout，适用于在启动时应用架构，或用于 CLI 无法锁定的嵌入式引擎。

[dependencies]
surrealkit = { version = "1.0.0-beta.3", default-features = false, features = ["kv-mem"] }

• default = ["kv-mem", "cli"]；库的使用者可移除 cli，以免引入 clap、inquire、rustls 和 tempfile。
• embed_schema! 和 embed_seed! 会将架构文件和数据填充文件编译进二进制文件，因此运行时不需要文件系统。
• Sync 是用于控制运行时行为的构建器；从 1.0 开始，Rollout 不再写入磁盘。
• 进度通过 log 门面输出；如果没有日志记录器，库将保持静默。

完整 API 参考：crates/surrealkit/README.md。升级说明：MIGRATING.md。

参考资料

• 项目脚手架与模板 — references/init-templates.md
• 开发同步、生产环境 rollout 与数据填充 — references/sync-rollouts.md
• 架构模块与数据库目标 — references/modules-targets.md
• 静态分析（check / generate / watch）— references/static-analysis.md
• 类型生成（JSON 和 TypeScript）— references/typegen.md
• 声明式测试框架 — references/testing.md