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.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

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