SurrealKit -- SurrealDB 應用程式的 Schema 管理
SurrealKit 將 SurrealDB 應用程式的 schema 管理為期望狀態的 .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
# 將本地/可拋棄資料庫與本地 schema 檔案同步
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 <name> | 從目前 schema 差異建立審查清單 |
surrealkit rollout start <id> | 套用力擴充階段 |
surrealkit rollout complete <id> | 在切換後套用收縮/破壞階段 |
surrealkit rollout rollback <id> | 回復進行中的發佈 |
surrealkit rollout lint <id> | 驗證發佈，但不修改資料庫 |
surrealkit rollout status | 檢查儲存在資料庫中的發佈狀態 |
surrealkit seed | 套用種子資料 |
surrealkit test | 執行宣告式 schema、權限與 API 測試 |
使用時機
- 當資料庫應立即反映本地檔案時，使用
sync。 - 當變更需要分階段、審查、回復或受控切換時，使用
rollout。 - 使用
seed進行確定性的測試固定資料。 - 在 CI 中使用
test驗證權限、schema 行為與 API 合約。
環境變數
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 與 rollout 策略、環境變數、種子資料、宣告式測試與 CI 模式
- surrealdb/surrealkit -- 上游倉庫