---
title: "SurrealKit schema migration"
description: "SurrealKit is the official schema migration CLI for SurrealDB. Define your schema in .surql files and keep databases in sync across every environment."
canonical_url: "https://surrealdb.com/docs/operate/schema-migration"
section: "SurrealKit schema migration"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# SurrealKit schema migration

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

> [!NOTE]
> Examples on these pages assume a [SurrealDB Cloud](/docs/operate/instances.md) 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:
> ```bash
> export SURREALDB_HOST=wss://production-6xk2.aws-euw1.surreal.cloud
> ```
> Find the endpoint for an instance with [`surreal cloud instance endpoint`](/docs/reference/cli/cloud/commands/instance.md). 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.
- **MCP server:** `surrealkit mcp` gives an AI coding agent SurrealKit's commands as typed tools over the [Model Context Protocol](https://modelcontextprotocol.io).

> [!IMPORTANT]
> These pages document SurrealKit `1.0.0-rc.1`, which needs SurrealDB 4.0 or later. Anything added in the 1.0 line is marked with a badge: _(since v1.0)_. Upgrading from 0.7 or an earlier 1.0 beta needs a few deliberate changes, some of them silent: see [Upgrading to SurrealKit 1.0](/docs/operate/schema-migration/upgrading.md).

## 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:

```text title="Error output"
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](https://github.com/cargo-bins/cargo-binstall#installation)):

```bash
cargo binstall surrealkit --version 1.0.0-rc.1
```

**Cargo from source:**

```bash
cargo install surrealkit --version 1.0.0-rc.1
```

**The `surreal` CLI:** SurrealKit is also the `kit` component of the [SurrealDB CLI](/docs/reference/cli/guides.md). `surreal install kit` installs the newest release, which is `1.0.0-rc.1` until 1.0 is stable, and `surreal kit` runs it:

```bash
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:**

```bash
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](/docs/operate/schema-migration/configuration.md#inside-a-container) 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](https://github.com/surrealdb/surrealkit/releases).

## Initialise a project

```bash
surrealkit init
```

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

```text
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](/docs/operate/schema-migration/templates.md) for the feature checklist, non-interactive flags, and custom templates, and [Configuration](/docs/operate/schema-migration/configuration.md) 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 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`, `database`/`db`, or `none` |
| `SURREALDB_FOLDER` | `--folder` | Project root, holding `schema/`, `rollouts/`, `snapshots/`, `seed/` and `tests/`. Defaults to `./database` |
| `SURREALDB_CONNECT_TIMEOUT_SECS` | `--connect-timeout-secs` | Time limit for connecting and signing in. Defaults to `30`; `0` waits indefinitely |
| `SURREALDB_QUERY_TIMEOUT_SECS` | `--query-timeout-secs` | Time limit for the SQL of one rollout step. Unset by default, so a long index build is not cut off |

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.

> [!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](/docs/operate/schema-migration/upgrading.md#rename-the-database-variables).

Example connecting via CLI flags:

```bash
surrealkit --user root --pass secret sync
```

To apply schema to more than one database from one project, declare [targets](/docs/operate/schema-migration/modules-and-targets.md) instead of switching these values between runs.

## Embedded databases

_(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:

```bash
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:

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

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

> [!NOTE]
> SurrealDB 4.0 has no RocksDB engine, so the `kv-rocksdb` feature is gone. `surrealkv+versioned://`, `rocksdb://`, `speedb://`, `file://`, `tikv://` and `indxdb://` are still recognised as embedded endpoints, so they skip the sign-in, but SurrealKit cannot open them, and 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](/docs/operate/schema-migration/library.md) instead.

## Output for scripts

_(since v1.0)_

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.

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

## MCP server

_(since v1.0)_

`surrealkit mcp` serves SurrealKit's commands to an AI coding agent over the [Model Context Protocol](https://modelcontextprotocol.io), 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:

```json title=".mcp.json"
{
    "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](/docs/operate/schema-migration/getting-started/new-databases.md): start a fresh project with SurrealKit from the beginning
- [Existing databases](/docs/operate/schema-migration/getting-started/existing-databases.md): adopt SurrealKit in a project that already has a database
- [Sync vs Rollouts](/docs/operate/schema-migration/getting-started/sync-vs-rollouts.md): choose the right mode for each environment
- [Configuration](/docs/operate/schema-migration/configuration.md): everything `surrealkit.toml` accepts, and where it has to live
- [Schema modules and targets](/docs/operate/schema-migration/modules-and-targets.md): several schemas across several databases
- [Project templates](/docs/operate/schema-migration/templates.md): scaffold a project with selectable features
- [Type generation](/docs/operate/schema-migration/typegen.md): generate JSON and TypeScript types from your schema
- [Migrating existing records](/docs/operate/schema-migration/existing-records.md): change fields on tables that already hold records
