SurrealKit schema migration

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.

• •

  MCP server: surrealkit mcp gives an AI coding agent SurrealKit's commands as typed tools over the Model Context Protocol.

Requirements

SurrealKit 1.0.0-rc.1 works with SurrealDB 4.0 and later. It checks the server version on every command and refuses an older server before it changes anything:

error: SurrealKit 1.0.0-rc.1 needs SurrealDB 4.0 or later, and this server is 3.3.5.

Keep SurrealKit 1.0.0-beta.8 while your servers run SurrealDB 3.x, and upgrade SurrealKit after the servers move to 4.0. SurrealKit's own records come through the database upgrade unchanged, and a rollout that started on 3.x can finish on 4.0.

Installation

1.0 is a prerelease, so Cargo needs the 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-rc.1

Cargo from source:

cargo install surrealkit --version 1.0.0-rc.1

The surreal CLI: SurrealKit is also the kit component of the SurrealDB CLI. surreal install kit installs the newest release, which is 1.0.0-rc.1 until 1.0 is stable, and surreal kit runs it:

surreal install kit
surreal kit sync

surreal kit is the same program as surrealkit, so every command and flag on these pages works in either form.

Docker:

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

The latest tag still points at the newest stable release, 0.7. 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. 1.

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

2. 2.

   SURREALDB_* environment variables

3. 3.

   .env or .env.local in the working directory

An endpoint that accepts the connection and never completes the handshake fails after the connect time limit, with a message naming the endpoint. Rollout steps have no time limit unless you set one, but each step logs when it starts and every 15 seconds while it runs, so a slow step is distinguishable from a stuck one.

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

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 embedded engine is SurrealDB 4.0, and it opens mem:// and surrealkv:// endpoints. For a versioned SurrealKV store, add ?versioned=true to the endpoint. 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 kv-surrealkv feature for an on-disk engine:

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

The embedded feature enables both kv-surrealkv and kv-mem.

Output for scripts

SurrealKit reports its version and its failures the same way as the other components of the surreal CLI:

• •

  -v, -V and --version print <version> for <os> on <arch>. Use --verbose for more detailed logs.

• •

  -j or --json, or SURREAL_KIT_JSON=1, keeps standard output for JSON alone. typegen writes its schema document there and test writes its report. Other commands write nothing to standard output, and their progress goes to standard error. --version --json prints {"arch", "os", "version"}.

• •

  A failure prints error: <message> on standard error and exits with code 1, or with code 2 for a usage error. With --json, the failure is one JSON object on standard error instead, with kind, message, hint, command and exit_code among its keys.

surrealkit --json typegen > schema.json
surrealkit --json test > report.json

MCP server

surrealkit mcp serves SurrealKit's commands to an AI coding agent over the Model Context Protocol, on standard input and output. The agent gets typed tools and structured results instead of parsing the CLI's output, and reads the project's own files as MCP resources. The prebuilt binaries and the Docker image include the server; from source, build with --features mcp.

The server works on the project it starts in, so set cwd in your editor's MCP configuration:

{
    "mcpServers": {
        "surrealkit": {
            "command": "surrealkit",
            "args": ["mcp"],
            "cwd": "/path/to/your/project"
        }
    }
}

With the surreal CLI, use "command": "surreal" and "args": ["kit", "mcp"]. The server takes its connection from the same SURREALDB_* variables, .env file and flags as the CLI, and each tool call acts on one database, named by target when the project declares more than one.

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

• •

  Configuration: everything surrealkit.toml accepts, and where it has to live

• •

  Schema modules and targets: several schemas across several databases

• •

  Project templates: scaffold a project with selectable features

• •

  Type generation: generate JSON and TypeScript types from your schema

• •

  Migrating existing records: change fields on tables that already hold records