Sync Gateway Overview

Sync Gateway Overview

Sync Gateway mobile-enables your Couchbase Server cluster. It also facilitates synchronizing Couchbase Lite databases on users’ mobile devices with Couchbase Server databases.

Using Sync Gateway can address a major problem of synchronization—the disparity between the volume of user data and limited storage space on mobile devices.

The following diagram illustrates the place of Sync Gateway in a Couchbase Mobile deployment:

Sync Gateway

You can scale out Sync Gateway just like you would any web application: by adding more nodes behind a load balancer.

Sync Gateway:

  • Maintains up-to-date copies of documents where users need them: on mobile devices for instant access and on servers in data centers for reasons such as synchronizing documents, sharing documents, and loss-protection. Mobile apps create, update, and delete files locally. Sync Gateway takes care of the rest.
  • Provides access control, ensuring that users can only access documents to which they should have access.
  • Ensures that only relevant documents are synced. Sync Gateway accomplishes this by examining documents and by applying business logic to decide whether to assign the documents to channels.

Access control and ensuring that only relevant documents are synced are achieved through use of channels and the sync function.


Channels are logical groupings of documents. A channel might contain documents for a specific user, for a specific group of users (identified by their role, for example, the Software Engineering department), or about a specific topic (for example, photography).

Channels provide users read access to documents. There are three parts to this:

  1. Each user is authorized to access specific channels. Both the Sync Gateway Admin API and the sync function can grant users access to channels.
  2. The sync function examines each new, revised, and deleted document and assigns it to one or more channels. Evaluations and resulting assignments can consider access privileges, business logic, and the contents of documents. Document deletion is a kind of revision, so deleted documents can be assigned to channels.
  3. During synchronization, only documents in specific channels are replicated. When starting a replication, Couchbase Lite can request specific channels. If no specific channels are requested, all channels to which the user has access are synced.

Sync function

The sync function is JavaScript code that resides in the Sync Gateway’s configuration file for a database. The sync function implements business logic and considers the contents of documents, giving fine-grained control over which documents should be replicated.

For example, the sync function could give a user access to:

  • Documents that s/he has created
  • Documents in channels assigned a role to which the user belongs
  • Documents deemed “relevant” (that is, of interest) by the sync function
Note:The sync function is central to the security of your app data. It is responsible for data validation and for authorizing both read and write access to documents.

Every time a document is created, revised, or deleted, the sync function is called to examine the document. The sync function:

  • Validates the document: If the contents of the document are not valid, then the sync function can reject the revision. Of course, clients should avoid creating invalid documents. This feature of the Sync Gateway is a fail-safe and a guard against malicious access.
  • Authorizes the document revision: The sync function can specify which users are allowed to modify the document (both directly and through roles). If the user making the change isn't in the list of authorized users, the sync function can reject the revision. Similarly, the sync function can require that the user making the change have access to any of specific listed channels.
  • Assigns the document to channels: Based on the contents of the document, the sync function can add the document to one or more channels. This makes the document accessible to users who have access to those channels, and will cause the document to be pulled by clients that subscribe to those channels.
  • Grants users and roles access to channels: Based on an evaluation of the contents of a document, the sync function can grant users and roles access to channels. This allows documents to act as membership lists or access-control lists.


Following is an example of a sync function:

function (doc, oldDoc) {
    if (oldDoc == null) {
        // Only editors can create documents:
    } else {
        // Only users in the writers property of the previous
        // revision of the document’s can change a document:
    // Assign the document to the channels in the document’s
    // channels property:

For more information about the sync function, see Sync Function API.

Next steps

To learn more about Sync Gateway, see the Sync Gateway Guide in our documentation. There are also sample applications which show these Sync Gateway concepts in both the GrocerySync iOS and GrocerySync Android sample applications. For more information about Couchbase Lite replication, see Replication.