> ## Documentation Index
> Fetch the complete documentation index at: https://boutiquedb.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Synchronization Overview

> How BoutiqueDB keeps local data authoritative while optionally synchronizing through CloudKit.

# Sync possibilities

BoutiqueDB separates persistence from sync. The local database is always authoritative while the app is offline; sync adapters move changes to and from a remote store when connectivity is available.

## CloudKit sync (default)

`TursoCKSync` maps CDC change records from the local database to CloudKit records. It uses `CKSyncEngine` and is designed for private-database, per-user sync.

What it provides:

* One local row maps to one CloudKit record.
* Inserts, updates, and deletes are captured from `turso_cdc`.
* Conflict resolution is delegated to CloudKit with configurable policies.
* Account switches preserve local rows and reset sync metadata.

Requirements:

* iCloud + CloudKit entitlements.
* Push Notifications + `remote-notification` background mode.
* An explicit `CKContainer` or container identifier.
* `BoutiqueDBSyncEngine.attach(to:automaticallyDrain: true)` after opening the database.

See [CloudKit sync guide](https://boutiquedb.mintlify.site/guides/cloudkit-sync.md) and the [CloudKit QA checklist](https://boutiquedb.mintlify.site/contributors/spi-checklist.md).

## Turso Cloud sync (future adapter)

The engine includes a sync protocol (`sync/engine` and `sync/sdk-kit`) that can pull and push WAL changes over HTTP. BoutiqueDB exposes a `SyncAdapter` protocol so a future adapter can plug into the same `BoutiqueDB` container without changing the local schema or query APIs.

The sync protocol supports:

* Push of local CDC operations to a remote endpoint.
* Pull of remote page updates or logical MVCC changes.
* Partial bootstrap with prefix or query-based lazy page loading.
* Remote encryption keys for cloud-encrypted databases.

At this time, the framework ships with `CloudKitSyncAdapter` only. A Turso Cloud adapter is not included in the current beta.

## Custom sync adapters

You can implement `SyncAdapter` to connect BoutiqueDB to any backend:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
public protocol SyncAdapter {
  func applyRemoteChanges(_ changes: SyncChangeSet) async throws
  func fetchRemoteChanges(since: SyncToken) async throws -> SyncChangeSet
}
```

Attach an adapter with `BoutiqueDB.attachSyncAdapter(_:)`.

## CDC and sync safety

CDC (`PRAGMA capture_data_changes_conn`) writes every local change to `turso_cdc`. The sync engine drains that table, maps rows, and clears successfully applied operations. If sync falls behind, the CDC table grows; checkpointing and retention are handled by the engine.

> **Note:** CDC and MVCC are mutually exclusive on the same connection. BoutiqueDB uses MVCC on a separate concurrent writer and CDC on the primary handle, or falls back to immediate transactions if that combination is rejected by the engine build.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.