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.3 pre-release (7771b93ea563, 2026-05-13). The v0.6.1 -> v0.6.3 patch line added library-lock fixes, template variables, comment-stripping cleanup, DROP ... IF EXISTS handling, and DEFINE coverage for BUCKET, SEQUENCE, and CONFIG.

Quick Start

# Install
cargo binstall surrealkit
# or: 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:

• SURREALDB_HOST (fallback: DATABASE_HOST)
• SURREALDB_NAME (fallback: DATABASE_NAME)
• SURREALDB_NAMESPACE (fallback: DATABASE_NAMESPACE)
• SURREALDB_USER (fallback: DATABASE_USER)
• SURREALDB_PASSWORD (fallback: DATABASE_PASSWORD)
• SURREALDB_AUTH_LEVEL (fallback: DATABASE_AUTH_LEVEL)

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