Existing databases

If your project already has a running SurrealDB database, you can adopt SurrealKit without disrupting it. A baseline snapshot records the current schema state so SurrealKit can compute diffs from there.

1. Install and initialise

Install SurrealKit and initialise the project directory if you have not already done so:

cargo binstall surrealkit
surrealkit init

2. Mirror your existing schema into files

Before taking a baseline, write your existing schema definitions into .surql files under database/schema/. These files should reflect what is currently in the database, as SurrealKit treats them as the target state going forward.

You can use INFO FOR DB and INFO FOR TABLE in SurrealQL to inspect what is currently defined:

INFO FOR DB;
INFO FOR TABLE my_table;

The following code can be used to return all the define statements in a database as an array of strings.

LET $db = INFO FOR DB;
  $db.tables.values() +
  $db.users.values() + 
  $db.tables.keys().map(|$t| {
    LET $i = INFO FOR TABLE $t;
    $i.fields.?.values() + $i.indexes.?.values()
  }).flatten().filter(|$v| !!$v);

Copy the returned DEFINE statements into appropriately named files in database/schema/.

3. Take a baseline snapshot

Once your schema files mirror the live database, run:

surrealkit rollout baseline --user root --pass secret

This connects to the database, captures its current schema state, and writes two snapshot files:

database/snapshots/schema_snapshot.json
database/snapshots/catalog_snapshot.json

These snapshots tell SurrealKit what the database looked like before any SurrealKit-managed rollout. Future rollout plan commands diff against this baseline to produce migration manifests.

4. Plan and apply future changes

With a baseline in place, use the standard Rollouts workflow for all subsequent schema changes:

# Edit files in database/schema/, then:

surrealkit rollout plan --name describe_your_change
surrealkit rollout start <rollout-id>

# Deploy your application changes
surrealkit rollout complete <rollout-id>

See the Rollouts page for the full reference.

Using Sync on existing databases

You can also use surrealkit sync against an existing database, but be aware that Sync will remove definitions from the database that are not present in your schema files (pruning). If your schema files are not yet complete, this could delete definitions you did not intend to remove.

To prevent accidental pruning on a shared database, Sync requires an explicit flag:

surrealkit sync --allow-shared-prune

For production and shared databases, use the Rollouts workflow to keep full control over what changes are applied and when.

Next steps

• Rollouts: full reference for the phased migration workflow

• Sync vs Rollouts: a side-by-side comparison