A newer version of this documentation is available.

View Latest

Release Notes

      Release Note from Previous Releases

      Release 2.7 | Release 2.6 | Release 2.5 | Release 2.1 | Release 2.0

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

      Release 2.8.2 (March 2021)

      Users of 2.8.1 should upgrade to this release at the earliest opportunity.

      Issues and Resolutions

      Release 2.8.2 fixes an issue that could result in Sync Gateway entering an infinite loop when creating a mobile tombstone, if a Couchbase Server tombstone already exists for that key.

      Release 2.8.1 (February 2021)

      Release 2.8.1 has now been superseded by Release 2.8.2 (March 2021). Users of 2.8.1 should upgrade to 2.8.2 as soon as practicable.

      New Features

      Metrics REST API

      Release 2.8.1 sees the transition to general availability of Couchbase Sync Gateway’s Metrics REST API, which was introduced as a developer preview in release 2.8.0.

      This feature exposes Sync Gateway’s extensive stats in both JSON and Prometheus-compatible format. For more on how to enable the integration of Sync Gateway’s metrics with one of the most popular monitoring and alerting solutions — see: Prometheus Integration and Metrics REST API.


      Configuration Changes

      Custom Response Headers

      It is now possible to remove product versions from Sync Gateway responses using the hide_product_versions setting in the Config file. This customization of responses avoids revealing the version of the Sync Gateway to HTTP requests to the root path — see: Hide Product Version in Headers and CBG-1235

      Connection String Overrides

      It is now possible to use the server connection string to override the current heuristic-driven behavior for selecting internal/external networking matches — see: Couchbase Server Connection String and CBG-1276

      Release 2.8.0 (October 2020)

      New Features

      Inter-Sync Gateway Replication

      Couchbase Sync Gateway’s Inter-Sync Gateway Replicationglossary icon feature supports cloud-to-edgeglossary icon synchronization use cases, where data changes must be synchronized between a centralized cloud cluster and a large number of edge clusters whilst still enforcing fine grained access control. This is an increasingly important enterprise-level requirement.

      Prometheus Monitoring Support (Developer Preview)

      This release gives developers the chance to try-out Couchbase Sync Gateway’s new metrics API, which exposes stats in a Prometheus compatible format. This enables the integration of Sync Gateway’s metrics with one of the most popular monitoring and alerting solutions, without resorting to external data transformation.

      Read More . . . Metrics REST API


      Configuration Changes

      Sync Gateway 2.8 introduces a number of configuration file changes made to accommodate the Inter-sync-gateway replication feature.


      The database property has a new sub-property replications, which is used to associate an inter-Sync Gateway replication with a 'local' database.

      The top level replications configuration property and its sub-properties is deprecated. Instead, use the database.replication property (as above) to define replications, unless you specifically need to use the pre-2.8 version with SG Replicate.

      Note that any given database can still have multiple replications configured. Also, that inter-Sync Gateway replication does not support replication between two remote hosts via a third Sync Gateway; at least one database must be local.

      API Changes

      This release introduces two new endpoints to the Admin Rest API.

      • _replication - used to initialize Inter-Sync Gateway Replication

      • _replicationStatus - used to set or query the status of a replication

      The _replicate and _active_tasks endpoints are both deprecated, as they are replaced by the above.

      Other Enhancements

      • CBG-1022 — Require replication to be stopped prior to upsert

      • CBG-921 — Ignore transaction ATR documents during DCP processing

      • CBG-905 — Support using custom OIDC claim as Sync Gateway username

      • CBG-880 — Python 3 support for sgcollect

      • CBG-877 — Remove inappropriate logging warning related JSON parsing from ReadJSONFromMIME when request body is empty

      • CBG-876 — Include Bearer prefix when sending token base authentication request in OIDC E2E tests

      • CBG-864 — Improve addJSON-related error handling

      • CBG-821 — Limit on channel queries triggered by 2.x replication

      • CBG-820 — Add state for OIDC auth code authentication

      • CBG-803 — Support for OIDC provider config refresh

      • CBG-802 — Being able to configure OIDC Test Provider with HTTPS

      • CBG-801 — Auto-generated OIDC callback URL should include provider when non-default

      • CBG-800 — OnDemandImportForWrite bypasses migrate handling

      • CBG-752 — sgcollect: Re-gzip rotated logfiles post-redaction, clean up intermediate extracted files

      • CBG-751 — Improve REST-based sgcollect_info options validation

      • CBG-719 — Update OIDC library

      • CBG-714 — Log warning on ignored, invalid channel data

      • CBG-709 — Inter-Sync Gateway Replication

      • CBG-697 — SGW startup routine could use more retry logic while CBS warms up

      • CBG-688 — Improve logging for x.509 connection errors

      • CBG-673 — Include USE INDEX hint with channel queries

      • CBG-665 — Make trace level logging a typical file logger

      • CBG-664 — Enhance trace logging for blip messages

      • CBG-658 — Optimize LogKey string lookup

      • CBG-653 — Add 'norev' BLIP handler to log detailed error information

      • CBG-640 — Wrong content type for _user and _role

      • CBG-633 — Clean up duplicate db definitions in blipHandler/blipSyncContext

      • CBG-630 — Validate whether multiple databases connect to the same bucket

      • CBG-624 — Add database config option for HttpOnly cookies

      • CBG-622 — Use secure cookies when SG is configured to listen over TLS

      • CBG-600 — sgcollect_info TMPDIR setting should be a real argument

      • CBG-585 — Avoid log redaction cost via UD/MD/SD when log-level disabled

      • CBG-581 — Write simple JSON HTTP responses directly as raw bytes

      • CBG-437 — Return error when receiving deltas for deltaSrc revisions which are tombstoned

      Issues and Resolutions

      Known Issues

      • CBG-1127 —  Treat resurrected tombstones as non-conflict when no shared history

      • CBG-798 — Sync Gateway requires Couchbase Server nodes to use the same SSL memcached port

      Fixed Issues

      • CBG-1072 — CAS race can result in unordered recentSequences

      • CBG-983 — _all_docs with keys parameter not returning revID

      • CBG-951 — Deleted documents should set _deleted:true for import filter function

      • CBG-946 — Repeated change entries on access grant to doc’s previous channel

      • CBG-926 — User name not being logged for initial HTTP request

      • CBG-819 — Generate empty delta as {} instead of null

      • CBG-812 — Running compact when UseViews=true causes an infinite loop

      • CBG-744 — OldDoc body in sync function for tombstone resurrections does not contain _deleted=true

      • CBG-743 — Doc body in sync function contains _deleted=false

      • CBG-741 — 403 Attachment’s doc not being synced during CBL replication

      • CBG-731 — Channels query performance degradation when using limit

      • CBG-727 — Panic when connecting to non-standard memcached port using couchbase(s):// scheme

      • CBG-695 — Alternate addresses are always used if defined instead of applying heuristic

      • CBG-661 — Errors from REST API produce invalid JSON

      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.

      SG Replicate replication protocol

      SG Replicate is deprecated in Sync Gateway version 2.8. You should plan your transition to inter-Sync Gateway replication now to avoid potential issues when this functionality is removed — see CBG-904

      The functionality of SG Replicate remains unchanged, unless explicitly stated in these release notes and-or in the appropriate documentation section. Refer to Upgrade Sync Gateway for more information on upgrading from SG Replicate to Inter-Sync Gateway replication.

      Configuration deprecations

      CBG-904 — The SG Replicate configuration method is deprecated at version 2.8.

      Replications configured at the configuration file’s root level will continue to function, but you should configure new replications under the appropriate database using the databases.{dbname}.replications.{replication_id} property.

      REST API Deprecations

      CBG-904 These SG Replicate REST endpoints are deprecated:

      • _active_tasks — superseded by new monitoring endpoint

      • _replicate — superseded by the _replication endpoint

      Operating Systems

      Support for Microsoft Windows 2012 (64-bit) is deprecated

      Other Notices

      Minimum Version for Inter-Sync Gateway Replication

      In order to support inter-Sync Gateway replication’s new features (2.8), all nodes in the active cluster must be running Sync Gateway 2.8+.

      Replication between two remote databases

      Replication between two remote databases is no longer supported. However, root level replications (which by definition, use SG Replicate) will continue to support remote replications, albeit in the now deprecated feature.

      Pushing to pre-2.8 targets
      • Push replications do not support a pre-2.8 target with "allow_conflicts": false set; the target must use "allow_conflicts": true for a replication to work.

      • Push replications do not use Delta Sync when pushing to a pre-2.8 target

      Support is added for:
      • Red Hat Enterprise Linux 8

      • CentOS 8


      In order to support inter-Sync Gateway replication’s new features (2.8), all nodes in the active cluster must be running Sync Gateway 2.8+.

      The version of inter-Sync Gateway replication useable depends on the combination of Sync Gateway versions running on the active and passive nodes — see: Example 1.

      Example 1. Availability of Inter-Sync Gateway replication versions
      Available for use on an active node
      • Pre-Sync Gateway 2.8 — only SG Replicate is available

      • Sync Gateway 2.8+ — you may run inter-Sync Gateway (2.8+), or the pre-2.8 SG Replicate (deprecated)

      SG versions compatible as a passive node
      • Pre-2.8 (SG Replicate) can target any inter-Sync Gateway replication version

      • 2.8+ inter-Sync Gateway replications can only target other inter-Sync Gateway replications

      For more on upgrading — see: Upgrade Sync Gateway