Sync Gateway’s primary purpose isn’t just moving data; it’s about creating a managed, offline-first synchronization experience for mobile apps, acting as a crucial intermediary between your Couchbase Lite mobile databases and your central Couchbase Server.
Let’s see it in action. Imagine a simple to-do list app.
Mobile Client (Couchbase Lite):
{
"doc_type": "task",
"title": "Buy groceries",
"completed": false,
"_id": "task_123",
"_rev": "3-abc..."
}
Sync Gateway Configuration (Simplified sync-gateway-config.json):
{
"databases": {
"todos": {
"users": {
"GUEST": {
"admin_channels": ["public"]
}
},
"sync": "sync/sync.js"
}
}
}
Sync Function (sync/sync.js):
function (doc, oldDoc) {
if (!doc.title) {
channel(null); // Revoke access if no title
return;
}
if (doc.completed) {
channel('completed'); // Assign to 'completed' channel if done
} else {
channel('open'); // Assign to 'open' channel if not completed
}
}
When a user adds a task, Couchbase Lite writes it locally. Sync Gateway, configured with the todos database and the sync.js function, polls Couchbase Lite for changes. It then applies the sync.js logic. If the task is not completed, it’s assigned to the open channel. This means any device subscribed to the open channel will receive this task. If the user marks it as complete, the sync.js function re-evaluates, assigns it to the completed channel, and other devices subscribed to completed will get the update.
The core problem Sync Gateway solves is managing distributed data consistency and conflict resolution in a mobile-first world where devices are intermittently connected. It abstracts away the complexities of network latency, offline work, and ensuring data eventually converges across all clients and the server. It allows you to define fine-grained access control and data routing using "channels."
Internally, Sync Gateway maintains a persistent connection (or polls) to Couchbase Server, acting as a proxy. When a mobile client syncs, it communicates its local revision history to Sync Gateway. Sync Gateway then determines what changes the mobile client needs based on its channel subscriptions and the data in Couchbase Server, pushing those changes down. Conversely, it receives changes from the mobile client, validates them against the sync function, and writes them to Couchbase Server.
The sync function is the heart of the data governance. It’s a JavaScript function executed by Sync Gateway for every document change. It determines which "channels" a document belongs to. Channels are essentially tags that control data visibility and replication. A user is granted access to specific channels, and only documents belonging to those channels will be replicated to their devices. This provides a powerful mechanism for data partitioning and security.
A key detail most developers overlook is how Sync Gateway handles document revisions and conflicts. When two clients modify the same document offline, Couchbase Lite creates a revision history. Sync Gateway, upon receiving conflicting revisions, doesn’t arbitrarily pick one. Instead, it relies on the _rev ID, which is a string incorporating the revision number and a hash. The revision with the higher revision number is generally considered the "winner" for a given branch of the history. If revisions are at the same level but have different histories (meaning they diverged offline), Sync Gateway will flag this as a conflict. Your mobile app (Couchbase Lite) then needs to be programmed to detect and resolve these conflicts, often by presenting the user with options or applying a predefined resolution strategy.
The next hurdle you’ll encounter is implementing robust conflict resolution strategies in your Couchbase Lite mobile application.