Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

New In 4.1

    Couchbase Sync Gateway — What’s new in the latest release
    This content covers the new features introduced in Sync Gateway 4.1

    Sync Gateway 4.0 introduces some breaking changes. If you’re upgrading from 3.x, see Upgrading Sync Gateway.

    Overview 4.1

    Sync Gateway 4.1 focuses on operational reliability and scalability for production deployments. This release introduces non-disruptive rolling upgrades with a safe rollback path, distributed resync for large datasets, channel history management APIs, and an opt-in migration to isolate Sync Gateway internal metadata from user application data, and document channel history management APIs.

    Non-Disruptive Rolling Upgrades

    Sync Gateway 4.1 introduces cluster compatibility version, which transforms rolling upgrades into a low-risk, routine operational task.

    • Upgrade a cluster node by node without downtime and without reducing cluster capacity or throughput.

    • Freeze the cluster compatibility version before starting an upgrade to preserve a safe rollback path throughout the upgrade window. A freeze persists across node restarts and is cluster-wide.

    • Roll back any upgraded node to the previous version at any point before starting an upgrade, without data loss or invasive operations such as bucket flushing or backup and restore.

    • Unfreeze when all nodes are on the new version to start an upgrade and activate new cluster-wide features.

    Three new Admin REST API endpoints support this workflow: GET /_cluster_compat_version, POST /_cluster_compat_version/freeze, and POST /_cluster_compat_version/unfreeze.

    For more information, see Cluster Compatibility Version.

    Distributed Resync

    Sync Gateway 4.1 redesigns the resync mechanism to distribute work in parallel across all nodes in the cluster.

    In previous versions, resync ran sequentially on a single node, making it impractical for large datasets. In Sync Gateway 4.1, resync distributes the workload automatically across all available nodes without any configuration changes. Resync runs alongside live application traffic with bounded resource usage, and adding nodes to the cluster increases resync throughput.

    The GET /{db}/_resync response adds two new fields: docs_targeted for tracking estimated total documents to process across the cluster, and docs_errored for per-node error counts. Two new Prometheus metrics, sgw_database_resync_docs_targeted and sgw_database_resync_errors_total, support monitoring distributed resync runs.

    For more information, see Resync.

    Channel History Management

    Sync Gateway 4.1 introduces Admin REST API endpoints for managing channel history in both user and document metadata.

    In deployments with high channel grant and revocation frequency, channel history grows without bound. This causes two operational problems: metadata bloat on documents and user records, and unnecessary revocation messages sent to clients during zero-checkpoint replications such as after an app reinstall or checkpoint rollback.

    • User channel history: Two new endpoints let administrators retrieve a user’s channel access history and selectively remove specific channel entries, preventing Sync Gateway from re-sending old revocations during future zero-checkpoint replications.

    • Document channel history: Two new endpoints let administrators retrieve inactive channel history for specific documents and remove entries older than a specified sequence number. Using the current head sequence performs a deep clean of all historical channel metadata for the targeted documents without affecting document content.

    Both operations are non-destructive to user data and do not interrupt active continuous replications.

    For more information, see Channel History Management.

    Metadata Isolation: Migrate to System Collection

    Sync Gateway 4.1 introduces an opt-in migration that moves Sync Gateway internal metadata from the default collection (_default._default) to the system collection (_system._mobile).

    • Sync Gateway metadata is isolated from user application data in its own collection.

    • Internal Sync Gateway documents no longer appear alongside user-modifiable documents in the Capella UI.

    • Eventing functions and SQL++ queries against the default collection no longer process Sync Gateway system documents.

    The migration is opt-in at both the cluster level and per database, and is never applied automatically at upgrade. Databases remain fully available for reads and writes throughout the migration. The migration is a one-way operation and cannot be reversed.

    A new Admin REST API endpoint GET|POST /{db}/_metadata_migration lets operators monitor migration status and manually start, stop, or retry the operation. Seven new Prometheus metrics track migration progress per database under the sgw_metadata_migration subsystem.

    For more information, see Migrate Metadata to System Collection.

    Compatibility

    • You must use Couchbase Server 7.6.0 or later. Use 7.6.6 or later for bi-directional XDCR features.

    • See the Compatibility Matrix for full version compatibility details.

    See Also

    What’s new in the previous version 4.0.

    Sync Gateway Release Notes

    Read the full 4.1 release notes here.

    Upgrading

    Upgrade Sync Gateway.

    Downgrading from Sync Gateway 4.1 to an earlier version is not supported after the full cluster has been upgraded. Use Cluster Compatibility Version to preserve a rollback path during the upgrade window.

    Related Content

    Learn more …​
    Reference material …​
    Community

    Mobile Forum | Blog | Blog (Mobile) | Tutorials