SurrealKit schema migration

SurrealKit is the official schema management and migration CLI for SurrealDB. Define your schema in .surql files and keep databases in sync across every environment.

Note

All of the example commands in this tutorial assume a database running at http://localhost:8000, a root user named root with the password secret, a namespace main and a database main. As host http://localhost:8000, namespace main and database main are default values, only the necessary --user root and --pass secret will be shown alongside each command. To test these commands without --user root and --pass secret, authentication can be disabled by passing in the --unauthenticated flag when starting the SurrealDB server.

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:

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.

Installation

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

cargo binstall surrealkit

Cargo from source:

cargo install surrealkit

Docker:

docker pull ghcr.io/surrealdb/surrealkit:latest

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 database/ directory with the expected layout:

database/
├── schema/       # .surql schema definition files
├── seed/         # optional seed data
├── tests/        # test suites and config
└── rollouts/     # rollout manifests (generated)

Connection configuration

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

CLI arguments (--host, --ns, --db, --user, --pass, --auth-level)
SURREALDB_* environment variables
.env file in the working directory
Fallback DATABASE_* environment variables

Environment variable	CLI equivalent	Purpose
`SURREALDB_HOST`	`--host`	Database endpoint URL
`SURREALDB_NAMESPACE`	`--ns`	Namespace
`SURREALDB_NAME`	`--db`	Database name
`SURREALDB_USER`	`--user`	Username
`SURREALDB_PASSWORD`	`--pass`	Password
`SURREALDB_AUTH_LEVEL`	`--auth-level`	`root`, `namespace`/`ns`, or `database`/`db`

Example connecting via CLI flags:

surrealkit --user root --pass secret sync

Next steps

New databases: start a fresh project with SurrealKit from the beginning
Existing databases: adopt SurrealKit in a project that already has a database
Sync vs Rollouts: choose the right mode for each environment