Shared Bucket Access

Starting in Sync Gateway 1.5, you can seamlessly extend an existing Couchbase Server deployment to connect with remote edge devices that are occasionally disconnected or connected.

In previous releases, you either had to ensure all writes happened through Sync Gateway, or had to set up bucket shadowing to ensure that the security and replication metadata needed by mobile applications was preserved.

In this release, the metadata created by the Sync Gateway is abstracted from applications reading and writing data directly to Couchbase Server. Sync Gateway 1.5 utilizes a new feature of Couchbase Server 5.0 called XATTRs (eXtended ATTRibutes) to store that metadata into an external document fragment. Mobile, web and desktop applications can therefore write to the same bucket in a Couchbase cluster.

How to enable it

This new 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.

The getting started page includes step-by-step instructions to:

  1. Install Couchbase Server 5.0 or above.

  2. Configure Couchbase Server with RBAC.

  3. Install Sync Gateway with a configuration file that enables Mobile-Web data synchronization. Another example is presented below.

        "databases": {
            "db": {
                "bucket": "my-bucket",
                "username": "my-user",
                "password": "my-password",
                "server": "http://localhost:8091",
                "enable_shared_bucket_access": true, (1)
                "import_docs": true (2)
    1 The enable_shared_bucket_access property is used to enable Web-Mobile data sync.
    2 The import_docs property is used to specify that this Sync Gateway node should perform import processing of incoming documents. Note that in a clustered environment, only 1 node should use the import_docs property. 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. The mobile metadata is no longer kept in the document, but in a system extended attribute in Couchbase Server.


The reference to the configuration properties can be found below.

Metadata Purge Interval

When this feature is enabled, mobile tombstones are not retained indefinitely. They will be purged based on the server’s metadata purge interval. To ensure tombstones are replicated to clients, you should set the server’s metadata purge interval based on your expected replication frequency (see the $dbname.enable_shared_bucket_access reference).

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. Create a new bucket on Couchbase Server (bucket 2).

  3. Install Sync Gateway 1.5 on a separate node with shared access enabled and connect it to the new bucket (bucket 2).

  4. Setup a push replication from the Sync Gateway instance used for Bucket Shadowing to the Sync Gateway 1.5 instance.

  5. Once the replication has completed, test your application is performing as expected.

  6. Update the load balancer to direct incoming traffic to the Sync Gateway 1.5 instance when you are ready to upgrade.

  7. Delete the first bucket (bucket 1).

bucket shadowing migration