A newer version of this documentation is available.

View Latest

Release Notes


      Couchbase Sync Gateway
      This content describes the key features and changes implemented by release 3.0.0 of Couchbase Sync Gateway

      One Way Upgrade

      The migration to 3.0 configuration is a ONE WAY process — see: Upgrading for more.

      3.0.8 — June 2023

      Release 3.0.0 — February 2022

      Replaced by v3.0.3

      Version 3.0.3 includes fixes for several critical issues found in 3.0.0. Therefore v3.0.0 is replaced by v3.0.3. We strongly encourage upgrading to v3.0.3.

      New Features

      Centralized Persistent Modular Configuration

      Centralized Persistent Modular Configuration is a core enhancement that makes it simpler for administrators to configure and manage the Sync Gateway.

      This enhancement removes reliance on monolithic JSON configuration files whilst providing a modular and cluster-aware approach to Sync Gateway node configuration.

      Basic startup configuration settings bootstrap your Sync Gateway nodes and securely connect them to a Couchbase Server. Configuration of cluster-wide Sync Gateway databases, access control policies and inter-Sync Gateway replications is then provided using the Admin REST API.

      Secure Administration

      This major enhancement complements the introduction of the centralized persistent configuration by introducing secure administration of a cluster through the Admin REST API.

      The Admin REST API now enforces authentication and role-based access control by default.

      TLS Encryption Enabled by Default

      The default enabling of secure TLS connections for all Couchbase Server,side communication ensures that all such communication is encrypted; enforcing and encouraging security best practices.

      User Defined Extended Attributes(XAttrs) for Access Control

      Use extended attributes (metadata) to avoid the need to embed sensitive access grant information such as channels and roles within document bodies.

      This key architectural enhancement enforces separation of concerns by providing you the option to use Extended Attributes (XATTRs) to specify channel access grants outside of your document bodies.

      Auto-Purge on Channel Access Revocation in Inter-Sync Gateway Replication

      This enhancement to inter-Sync Gateway replication technology helps with the enforcement of data privacy and governance in complex workflows.

      Use Environment Variables in Configuration File

      Sync Gateway configuration is extended to allow the use of defined environment variables as substitution values inside the configuration file. This allows users to determine, pick-up and substitute appropriate values during Sync Gateway start-up.



      Attachments added post 3.0 are automatically removed from the bucket upon reference removal, document delete or document purge.
      The {db}/_compact API includes an option to remove any redundant pre-3.0 attachments — see: Revisions — Compacting.


      The _resync process has been enhanced to better handle large datasets, minimizing timeout and out-of-memory issues. The process now runs asynchronously, uses query pagination and supports sequence regeneration.

      Other Enhancements

      Issues and Resolutions

      API and Configuration Changes

      This release introduces significant configuration and persistent API changes; some of which may be breaking changes if they impact a feature you rely on — see the items identified in:attribute: value Table 1 | Table 2 | Table 3.

      Breaks compatibility

      Table 1. Breaks compatibility
      Feature Link

      enable_shared_bucket_access — enabled by default

      The change ought to be transparent to the user, if:

      • Doc metadata is smaller than 1MB

      • There is no reliance on inspecting doc metadata using the _sync property in a document on the server side

      Old documents are automatically migrated to the xattr metadata format.

      Enforce TLS by default


      Table 2. Deprecated
      Feature Link

      allow_conflicts confg

      enable_shared_bucket_access — disabled option

      Facebook User Auth Config

      Google User Auth Config

      Logging API

      Dropped or removed

      Table 3. Dropped or removed
      Feature Link

      admin UI

      configServer property



      logging.default config section







      old cache config values: databases.this_db.rev_cache_size


      walrus mode

      Support Notices

      This section documents any support-related notes, constraints and changes

      Deprecation Notices

      Items (features and-or functionality) are marked as deprecated when a more current, and usually enhanced, alternative is available.

      Whilst the deprecated item will remain usable, it is no longer supported, and will be removed in a future release. You should plan to move to an alternative, supported, solution as soon as practical.


      For more on upgrading — see: Upgrading