---
title: "Sync vs Rollouts"
description: "Understand when to use SurrealKit's Sync mode for development and Rollouts mode for production, and how teams typically combine both."
canonical_url: "https://surrealdb.com/docs/operate/schema-migration/getting-started/sync-vs-rollouts"
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

# Sync vs Rollouts

Understand when to use SurrealKit's Sync mode for development and Rollouts mode for production, and how teams typically combine both.

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:

1. **Local development**: every developer runs `surrealkit sync --watch` against their own local SurrealDB instance. Schema changes are iterated freely.
2. **Pull request / CI**: a `surrealkit test` step validates the schema and permissions against an ephemeral database. Sync is used here too, since the CI database is disposable.
3. **Staging / production**: when changes are ready to promote, a developer runs `surrealkit rollout plan` to generate a migration manifest, commits it, and the deployment pipeline runs `rollout up` before the application release and `rollout up --complete` after it. A CI step can run `surrealkit rollout lint`, which needs no database, to check every manifest on each pull request.

## 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. The flag exists to make you stop and confirm, so do not pass it routinely.

## Next steps

- [Sync](/docs/operate/schema-migration/sync.md): full Sync reference
- [Rollouts](/docs/operate/schema-migration/rollouts.md): full Rollouts reference

## Learn more about this topic

- [3: Migrations](https://surrealdb.com/learn/schemas/page-03#when-to-reach-for-surrealkit) (SurrealDB University, section "When to reach for SurrealKit")
- [10: Sync vs rollouts](https://surrealdb.com/learn/schemas/page-10) (SurrealDB University)
- [6: SurrealKit and the first table](https://surrealdb.com/learn/schemas/page-06#why-files-instead-of-the-shell) (SurrealDB University, section "Why files instead of the shell?")
