Skip to content

Docs

Sign In

SurrealKit

SurrealKit schema migration

Note

Examples on these pages assume a SurrealDB Cloud instance with the namespace main, the database main, and a root user named root with the password secret. Set the endpoint once so that each example stays short:

Find the endpoint for an instance with surrealctl instance endpoint. Namespace main and database main are the defaults, so only --user root --pass secret is shown alongside each command.

SurrealKit is the official schema management and migration CLI for SurrealDB. You define your database schema as plain .surql files, commit them alongside your application code, and SurrealKit keeps every environment in sync with those definitions.

It has two modes for getting schema into a database:

  • Sync: immediately pushes your schema files to the connected database. Best for local development and ephemeral environments where fast iteration matters and losing data is acceptable.

  • Rollouts: generates a reviewed, phased migration manifest and applies changes in non-destructive then destructive passes, with rollback support. Best for shared, staging, and production databases.

Most teams use Sync day-to-day and switch to Rollouts when promoting changes to shared environments.

SurrealKit also provides:

  • Templates: scaffold a new project from a template with selectable features (surrealkit init).

  • Schema modules and targets: split a project into independently tracked schemas and apply them across several databases.

  • Seeding: apply .surql seed data, tracked so that each file runs once.

  • Type generation: introspect a database to emit JSON and TypeScript types for your application.

  • Testing: a declarative framework for validating schema, permissions, and API endpoints.

Important

These pages document SurrealKit 1.0.0-beta.1. Anything added in the 1.0 line is marked with a badge: Available since: v1.0. Upgrading from 0.7 needs a few deliberate changes, two of which are silent: see Upgrading to SurrealKit 1.0.

Installation

1.0 is a prerelease, so it has to be requested by version. Without one, Cargo installs the latest stable release, which is still 0.7.

cargo binstall (recommended, no compilation required once cargo binstall is installed):

cargo binstall surrealkit --version 1.0.0-beta.1

Cargo from source:

cargo install surrealkit --version 1.0.0-beta.1

Docker:

docker pull ghcr.io/surrealdb/surrealkit:1.0.0-beta.1

The latest tag also points at the newest stable release rather than the beta. See Configuration for mounting a project into the container.

Prebuilt binaries for Linux (x86_64 / aarch64), macOS (x86_64 / aarch64), and Windows (x86_64) are available on the GitHub releases page.

Initialise a project

surrealkit init

This scaffolds a project from a template, letting you pick which optional features to include. It always writes the base layout:

database/
├── schema/        # .surql schema definition files
├── rollouts/      # rollout manifests (generated)
├── snapshots/     # schema and catalog snapshots
├── seed/          # optional seed data
├── tests/         # test suites and config
└── setup.surql    # runs before sync
surrealkit.toml    # project configuration

See Project templates for the feature checklist, non-interactive flags, and custom templates, and Configuration for what surrealkit.toml holds.

Connection configuration

SurrealKit resolves connection details in the following order (first match wins):

  1. CLI arguments (--host, --ns, --db, --user, --pass, --auth-level)

  2. SURREALDB_* environment variables

  3. .env or .env.local in the working directory

Environment variableCLI equivalentPurpose
SURREALDB_HOST--hostDatabase endpoint URL
SURREALDB_NAMESPACE--nsNamespace
SURREALDB_NAME--dbDatabase name
SURREALDB_USER--userUsername
SURREALDB_PASSWORD--passPassword
SURREALDB_AUTH_LEVEL--auth-levelroot, namespace/ns, database/db, or none
SURREALDB_FOLDER--folderProject root, holding schema/, rollouts/, snapshots/, seed/ and tests/. Defaults to ./database
Warning

The DATABASE_* aliases were removed in 1.0. One set without its SURREALDB_* replacement is an error rather than being ignored, because ignoring it would fall back to the defaults and connect to the wrong database. See Upgrading.

Example connecting via CLI flags:

surrealkit --user root --pass secret sync

To apply schema to more than one database from one project, declare targets instead of switching these values between runs.

Embedded databases

Available since: v1.0

SurrealKit can manage an in-process SurrealDB by pointing --host at an embedded endpoint. Authentication is skipped automatically, because a fresh embedded datastore has no users:

surrealkit --host surrealkv://./data --ns main --db main sync

The recognised schemes are mem://, surrealkv://, surrealkv+versioned://, rocksdb://, speedb://, file://, tikv:// and indxdb://. Pass --auth-level none to force the same no-signin path on any endpoint.

The prebuilt CLI bundles the in-memory engine only, to keep the binary small. Build with the matching feature for an on-disk engine:

cargo install surrealkit --version 1.0.0-beta.1 --features kv-surrealkv

kv-rocksdb is available on the same basis, and embedded enables every engine that ships a feature.

Note

speedb://, tikv:// and indxdb:// are recognised as embedded endpoints but have no corresponding cargo feature in 1.0.0-beta.1, so they fail when the connection is opened. Embedded engines are also single-process: the CLI holds an exclusive lock on the datastore, so run it while your application is stopped. To manage schema inside your application at startup, use the library instead.

Next steps

Was this page helpful?

Next

Configuration