What's new in 1.5

What's new in 1.5

Edit on GitHub

Beta 2

SSL and Multi-URL support

In Sync Gateway 1.5 you have the ability to define multiple server URLs in the Sync Gateway configuration, and full support for SSL between Sync Gateway and Couchbase Server.

Mobile Convergence

The core functionality provided by convergence is the ability for mobile and server applications to read from and write to the same bucket. It is an opt-in feature that can be enabled through the databases.foo_db.unsupported.enable_extended_attributes property in the configuration file.

The feature was made opt-in primarily out of consideration for existing customers upgrading from Sync Gateway 1.4. It ensures that their existing configs will continue to work as-is, and supports upgrade without bringing down the entire Sync Gateway cluster.

Revs Limit lower limit

The databases.foo_db.revs_limit property now has a minimal value. See the API reference for more detail.

Compatibility matrix

Sync Gateway - Couchbase Server

The table below shows the versions of Sync Gateway compatible with Couchbase Server.

CB Server/Sync Gateway SG 1.5 SG 1.5 (XATTRs)
CB 4.0
CB 4.1
CB 4.5
CB 4.6
CB 5.0

For all of the above, the bucket type must be Couchbase. Usage of Ephemeral and Memcached buckets with Couchbase Mobile is not supported.

Couchbase Lite - Sync Gateway

CB Lite/Sync Gateway SG 1.5 SG 1.5 (XATTRs)
CBL 1.3
CBL 1.4
CBL 2.0

Sample App

The following tutorial demonstrates the extended attributes support introduced in Sync Gateway 1.5.

Getting Started

  1. Download the latest Developer Build of Couchbase Server 5.0.
  2. Download Sync Gateway.
  3. Create a new bucket in the Couchbase Server Admin Console.
  4. Create a Couchbase Server user for Sync Gateway to use (Security/Add User in the Couchbase Server Admin Console), and grant that user the 'Bucket Full Access' role for your new bucket from step 3.
  5. Start Sync Gateway with the following configuration file.

        "databases": {
            "db": {
                "bucket": "my-bucket",
                "username": "my-user",
                "password": "my-password",
                "server": "http://localhost:8091",
                "enable_shared_bucket_access": true,
                "import_docs": "continuous"
  6. On start-up, Sync Gateway will generate the mobile-specific metadata for all the pre-existing documents in the Couchbase Server bucket. From then on, documents can be inserted on the Server directly (SDKs) or through the Sync Gateway REST API.


To upgrade Sync Gateway to 1.5, you will need to stop all Sync Gateway instances. This means that mobile applications will not be able to push or pull data to the server during that time. Run the following steps to upgrade an existing Couchbase Mobile deployment.

  1. Stop all Sync Gateway nodes.
  2. Upgrade all Sync Gateway nodes to 1.5.
  3. Upgrade all Couchbase Server nodes to 5.0 or higher.
  4. If you wish to use Sync Gateway 1.5 with the convergence feature, update the configuration file as shown above.
  5. Start Sync Gateway instances. Note that starting Sync Gateway 1.5 instances with convergence enabled in the configuration file will trigger all existing documents to be re-processed. So it may take a while before Sync Gateway appears online. You may monitor the logs to track the progress of this operation.
  6. Replications with clients (i.e Couchbase Lite) should now resume.

Note: Enabling convergence on your existing deployment (i.e XATTRs) is not reversible. It is recommended to test the upgrade on a staging environment before upgrading the production environment.

Migrating from Bucket Shadowing

As of Sync Gateway 1.5, the Bucket Shadowing feature is deprecated and no longer supported. The following steps outline a recommended method for migrating from Bucket Shadowing to the latest version with interoperability between Couchbase Server SDKs and Couchbase Mobile.

  1. Follow the recommendations in the Couchbase Server documentation to upgrade all instances to 5.0.
  2. Update Couchbase Server SDK applications to read/write documents to the mobile bucket.
  3. Make sure that all documents are present in the mobile bucket, the Sync Function may have rejected some documents based on the access control rules for example. If you are not using a Sync Function you can ignore this verification step.
  4. Delete the shadow bucket from Couchbase Server.
  5. Perform an upgrade of Sync Gateway instances as detailed above. This upgrade will incur some application downtime.
  6. Monitor the Sync Gateway logs upon start-up.
  7. Replications with mobile clients (i.e Couchbase Lite) should now resume.