SurrealKit -- SurrealDB 应用的模式管理
SurrealKit 将 SurrealDB 应用程序模式作为期望状态的 .surql 文件进行管理，并为可丢弃的开发数据库以及共享或生产环境提供独立的路径。
跟踪的上游快照：v0.6.3 预发布版本（7771b93ea563，2026-05-13）。
v0.6.1 -> v0.6.3 补丁系列增加了库锁修复、模板变量、注释剥离清理、DROP ... IF EXISTS 处理，以及针对 BUCKET、SEQUENCE 和 CONFIG 的 DEFINE 覆盖。
快速开始
# 安装
cargo binstall surrealkit
# 或：cargo install surrealkit
# 搭建项目结构
surrealkit init
# 将本地/可丢弃数据库与本地模式文件同步
surrealkit sync
# 生成并应用一个经过审查的共享/生产迁移
surrealkit rollout plan --name add_customer_indexes
surrealkit rollout start 20260410120000__add_customer_indexes
surrealkit rollout complete 20260410120000__add_customer_indexes
核心命令
| 命令 | 用途 |
|---|---|
surrealkit sync | 本地、预览或可丢弃数据库的期望状态协调 |
surrealkit sync --watch | 带文件监听的本地开发循环 |
surrealkit rollout baseline | 在现有共享数据库上建立迁移追踪 |
surrealkit rollout plan --name <名称> | 从当前模式差异创建审查清单 |
surrealkit rollout start <ID> | 应用扩展阶段 |
surrealkit rollout complete <ID> | 在切换后应用收缩/破坏阶段 |
surrealkit rollout rollback <ID> | 回滚进行中的迁移 |
surrealkit rollout lint <ID> | 验证迁移而不修改数据库 |
surrealkit rollout status | 检查存储在数据库中的迁移状态 |
surrealkit seed | 应用种子数据 |
surrealkit test | 运行声明式模式、权限和 API 测试 |
何时使用
- 当数据库应即时镜像本地文件时，使用
sync。 - 当变更需要暂存、审查、回滚或受控切换时，使用
rollout。 - 对于确定性测试数据，使用
seed。 - 在 CI 中用于验证权限、模式行为和 API 契约时，使用
test。
环境变量
SurrealKit 读取以下变量：
SURREALDB_HOST（回退：DATABASE_HOST）SURREALDB_NAME（回退：DATABASE_NAME）SURREALDB_NAMESPACE（回退：DATABASE_NAMESPACE）SURREALDB_USER（回退：DATABASE_USER）SURREALDB_PASSWORD（回退：DATABASE_PASSWORD）SURREALDB_AUTH_LEVEL（回退：DATABASE_AUTH_LEVEL）
测试
database/tests/suites/*.toml 中的声明式测试套件支持：
sql_expectpermissions_matrixschema_metadataschema_behaviorapi_request
示例：
surrealkit test --fail-fast --json-out artifacts/surrealkit-tests.json
完整文档
有关完整的操作指南，请参阅主要技能规则：
- rules/surrealkit.md -- sync vs rollout 策略、环境变量、种子数据、声明式测试和 CI 模式
- surrealdb/surrealkit -- 上游仓库