# 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 start` and `rollout complete` at 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.

## Next steps

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