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.

    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