24601/surrealkit

SurrealKit -- Schema Management for SurrealDB Apps

SurrealKit manages SurrealDB application schemas as desired-state .surql files, with separate paths for disposable development databases and shared or production rollouts.

Tracked upstream snapshot: v0.6.0 pre-release (28f5a1c9d20c, 2026-05-03). v0.6.0 introduces a procedural macro publish workflow on top of the v0.5.x sync/rollout/seed/test pipeline; the public CLI surface below remains stable between v0.5 and v0.6.

Quick Start

# Install
cargo install surrealkit

# Scaffold project structure
surrealkit init

# Reconcile local/disposable database to local schema files
surrealkit sync

# Generate and apply a reviewed rollout for shared/prod
surrealkit rollout plan --name add_customer_indexes
surrealkit rollout start 20260410120000__add_customer_indexes
surrealkit rollout complete 20260410120000__add_customer_indexes

Core Commands

| Command | Use | |---------|-----| | surrealkit sync | Desired-state reconciliation for local, preview, or disposable DBs | | surrealkit sync --watch | Local development loop with file watching | | surrealkit rollout baseline | Establish rollout tracking on an existing shared DB | | surrealkit rollout plan --name <name> | Create a reviewed manifest from current schema diff | | surrealkit rollout start <id> | Apply the expansion phase | | surrealkit rollout complete <id> | Apply the contract/destructive phase after cutover | | surrealkit rollout rollback <id> | Roll back an in-flight rollout | | surrealkit rollout lint <id> | Validate a rollout without mutating the DB | | surrealkit rollout status | Inspect rollout state stored in the DB | | surrealkit seed | Apply seed data | | surrealkit test | Run declarative schema, permission, and API tests |

When to Use It

• Use sync when the database should mirror local files immediately.
• Use rollout when changes need staging, review, rollback, or controlled cutover.
• Use seed for deterministic fixture data.
• Use test in CI to validate permissions, schema behavior, and API contracts.

Environment

SurrealKit reads these variables:

• DATABASE_HOST or PUBLIC_DATABASE_HOST
• DATABASE_NAME or PUBLIC_DATABASE_NAME
• DATABASE_NAMESPACE or PUBLIC_DATABASE_NAMESPACE
• DATABASE_USER
• DATABASE_PASSWORD

Testing

Declarative suites in database/tests/suites/*.toml support:

• sql_expect
• permissions_matrix
• schema_metadata
• schema_behavior
• api_request

Example:

surrealkit test --fail-fast --json-out artifacts/surrealkit-tests.json

Full Documentation

See the main skill rule for full operating guidance:

• rules/surrealkit.md -- sync vs rollout strategy, env vars, seeds, declarative tests, and CI patterns
• surrealdb/surrealkit -- upstream repository