Terminal
Terminal/Skill
Schema and migration CLI for SurrealDB: scaffolds projects, syncs schema in development, runs production rollouts, and runs schema tests.
By SurrealDB
Works with
npx skills add surrealdb/agent-skills --skill surrealkitA skill for driving SurrealKit, SurrealDB's schema-management and migration CLI. Written against SurrealKit 1.0 (currently 1.0.0-beta.3).
SurrealKit keeps a SurrealDB database in sync with .surql schema files. It provides two complementary workflows — a fast declarative sync for development and controlled, phased rollouts for shared and production databases — plus seeding, static analysis, type generation, and a declarative testing framework.
Reference these guidelines when:
surrealkit init) or authoring templatessurrealkit sync)surrealkit rollout)surrealkit rollout baseline)surrealkit check)surrealkit typegen)surrealkit test)This skill covers the SurrealKit tool itself. To write the actual schema, seed, and query statements that go in .surql files, use the surrealql skill.
| Method | Command |
|---|---|
cargo binstall (recommended) | cargo binstall surrealkit |
| Cargo (from source) | cargo install surrealkit |
| Docker | docker pull ghcr.io/surrealdb/surrealkit:latest |
| Prebuilt tarball | GitHub Releases |
Building from source needs a C compiler and cmake. Static analysis is on by default and adds tree-sitter (~7.5 MiB, ~100s of build time); drop it with cargo install surrealkit --no-default-features --features kv-mem,cli — that binary has no check, generate, or watch. Prebuilt binaries and cargo binstall always include analysis.
The Docker image is distroless (~25 MB, uid 65532) and exits on completion, which suits "apply schema then run tests" pipelines in Docker Compose alongside SurrealDB.
| Command | Purpose | Reference |
|---|---|---|
surrealkit init | Scaffold a project from a template, selecting optional features | init-templates.md |
surrealkit sync | Declaratively reconcile the database to your schema files (dev) | sync-rollouts.md |
surrealkit rollout <sub> | Plan, stage, complete, roll back, and repair migrations (shared/prod) | sync-rollouts.md |
surrealkit seed [--force] | Run seeding files in database/seed/ (idempotent, hash-tracked) | sync-rollouts.md |
surrealkit check | Statically analyse the project's SurrealQL — no database contacted | static-analysis.md |
surrealkit generate / watch | Emit / continuously refresh a typed client for embedded queries | static-analysis.md |
surrealkit typegen | Introspect a live DB and emit JSON / TypeScript types | typegen.md |
surrealkit test | Run declarative TOML test suites | testing.md |
surrealkit apply <path> | Apply a single .surql file directly | — |
surrealkit setup | Run database/setup.surql (SurrealKit's own metadata tables) | — |
surrealkit status | Show sync/rollout state | — |
Run surrealkit <command> --help to confirm available flags for an installed version.
Global flags work on every command and resolve in this order (highest wins):
[target.<name>] in surrealkit.toml > CLI flags > system env vars > .env file > defaults.
surrealkit --host http://localhost:8000 --ns my_ns --db my_db \
--user root --pass root --auth-level root sync
| Flag | Env var | Default |
|---|---|---|
--host | SURREALDB_HOST | http://localhost:8000 |
--ns | SURREALDB_NAMESPACE | db |
--db | SURREALDB_NAME | test |
--user | SURREALDB_USER | root |
--pass | SURREALDB_PASSWORD | root |
--auth-level | SURREALDB_AUTH_LEVEL | root (root / namespace|ns / database|db / none) |
--folder | SURREALDB_FOLDER | ./database |
--connect-timeout-secs | SURREALDB_CONNECT_TIMEOUT_SECS | 30 (0 waits indefinitely) |
--query-timeout-secs | SURREALDB_QUERY_TIMEOUT_SECS | unset (a rollout step's SQL waits indefinitely) |
The
DATABASE_*aliases were removed in 1.0. Setting one without itsSURREALDB_*replacement is a hard error, not a silent fallback. Update.envfiles and CI when upgrading.
Selection flags are also global: -s/--schema <name>, -t/--target <name>, --all, --keep-going, --no-deps — see modules-targets.md.
The project root holds surrealkit.toml with [variables], [typegen], [analyze], [schema.*], and [target.*] sections.
Point --host at an embedded endpoint to manage an in-process datastore; authentication is skipped automatically.
surrealkit --host surrealkv://./data --ns my_ns --db my_db sync
Schemes: surrealkv://, rocksdb://, speedb://, mem://, file://, tikv://. --auth-level none forces the no-signin path on any endpoint. The prebuilt CLI bundles only the in-memory engine — for on-disk engines build with --features kv-surrealkv (or kv-rocksdb, or embedded). Embedded engines take an exclusive lock, so stop the application before running the CLI against one; to manage schema from inside an application at startup, use the library instead.
Use ${VAR_NAME} tokens in any .surql file (schema, seed, or rollout SQL). Names are case-insensitive. Values resolve in order (highest wins):
--var KEY=VALUE CLI flag (repeatable)SURREALKIT_VAR_<KEY> environment variable[variables] section in surrealkit.toml# surrealkit.toml
[variables]
schema_prefix = "myapp"
talent_username = "talent_rw"
surrealkit sync --var schema_prefix=acme --var talent_username=talent_rw
${...} by doubling the dollar sign: $${literal}.${VAR} inside a SurrealQL string literal is also replaced.sync, seed, apply, and rollout start/complete/rollback. It does not run on rollout plan/baseline/status/lint (no user SQL executes there).surrealkit init creates a database/ directory (override the root with --folder / SURREALDB_FOLDER):
database/
├── schema/ # Schema definitions (.surql) — the default module, the source of truth
├── modules/<name>/schema/ # Additional schema modules, when declared in surrealkit.toml
├── rollouts/ # Generated rollout manifests (.toml)
├── snapshots/ # Drift tracking — what `rollout plan` diffs against
│ ├── schema_snapshot.json
│ └── catalog_snapshot.json
├── seed/ # Seeding files (.surql)
├── tests/
│ ├── suites/ # Test suites (.toml)
│ ├── fixtures/ # Test fixture data (.surql)
│ └── config.toml # Global test config
└── setup.surql # One-time setup script (SurrealKit's own metadata tables)
surrealkit.toml # Project config
SurrealKit tracks its own state in three metadata tables on your database: __entity (file hashes and per-definition records), __rollout (rollout run state), and __seed (seed-file hashes).
sync for local, preview, and other disposable databases where it is safe to match files immediately; use rollout for shared/production databases that need review, staged execution, rollback, or operator-controlled cutover.sync creates, updates, and prunes SurrealKit-managed objects to match the schema directory.DEFINE/REMOVE statements. Allow other statements (INSERT, UPDATE, CREATE) only with --allow-all-statements, which disables catalog entity tracking.rollout plan diffs against database/snapshots/, not the live database, and sync never writes snapshots. Adopting rollouts after a period of sync-only work needs a rollout baseline first, or the first plan proposes every file you have..surql extension. Validate and format generated SurrealQL with the tools described in the surrealql skill (surreal validate, npx @surrealdb/surql-fmt), and gate it in CI with surrealkit check.surrealkit --help and the README.The surrealkit crate runs sync, seed, and rollouts from inside an application — useful for applying schema at startup, or for embedded engines the CLI cannot hold a lock on.
[dependencies]
surrealkit = { version = "1.0.0-beta.3", default-features = false, features = ["kv-mem"] }
default = ["kv-mem", "cli"]; library consumers drop cli to shed clap, inquire, rustls, and tempfile.embed_schema! and embed_seed! compile the schema and seed files into the binary, so no filesystem is needed at runtime.Sync is a builder for runtime control; Rollout no longer writes to disk as of 1.0.log facade; without a logger the library is silent.Full API reference: crates/surrealkit/README.md. Upgrade notes: MIGRATING.md.
check / generate / watch) — references/static-analysis.md