SurrealKit has two modes for applying schema changes. Which one you use depends on the environment.
At a glance
| - | Sync | Rollouts |
|---|---|---|
| Philosophy | Desired state: your files are truth | Phased migration via reviewed manifests |
| Speed | Immediate | Planned and staged |
| Destructive changes | Automatic (pruning) | Explicit, in a separate phase |
| Rollback | Restore previous files and re-sync | rollout rollback command |
| Concurrency safety | Not guaranteed | Blocked by in-progress rollout |
| Best for | Local dev, ephemeral, disposable DBs | Shared, staging, production |
When to use Sync
Sync is the right choice when:
You are working on a local or personal development database
The database is ephemeral or disposable (a Docker container, a CI job, a preview environment)
Losing and recreating data is acceptable
You want fast iteration without planning each change explicitly
Sync gives you an instant feedback loop: edit a .surql file, save it, and the database reflects the change within seconds (especially with --watch mode).
When to use Rollouts
Rollouts are the right choice when:
You are modifying a database shared with other developers or services
You are promoting changes to staging or production
The migration involves both non-destructive additions and destructive removals that must happen in separate phases, with your application deployed in between
You need a record of what was changed and when, with the ability to roll back
The phased approach (expand first, then contract after the application is updated) means schema changes and application code can be deployed independently, with no downtime or data loss.
How teams typically combine both
A common pattern is:
Local development: every developer runs
surrealkit sync --watchagainst their own local SurrealDB instance. Schema changes are iterated freely.Pull request / CI: a
surrealkit teststep validates the schema and permissions against an ephemeral database. Sync is used here too, since the CI database is disposable.Staging / production: when changes are ready to promote, a developer runs
surrealkit rollout planto generate a migration manifest, commits it, and the deployment pipeline runsrollout startandrollout completeat the right points around the application release.
Prune behaviour on shared databases
Sync's automatic pruning (removing definitions no longer in your files) is safe on a personal database but dangerous on a shared one. If a colleague has added a definition not yet in your local files, Sync will delete it.
SurrealKit protects against this: running surrealkit sync against a database that already contains SurrealKit metadata (the __entity table) will require you to pass --allow-shared-prune explicitly before it will prune anything. This flag is a deliberate speed bump, not a routine option.