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.

Rolling Upgrade

    Step-by-step procedures for performing a rolling upgrade of a Sync Gateway cluster for each supported version.

    Related Application Deployment topics: Prepare | Release Notes

    About Rolling Upgrades

    A rolling upgrade is the recommended method to upgrade a Sync Gateway cluster. You upgrade nodes one at a time while the cluster continues serving traffic, avoiding downtime.

    At a high level, a rolling upgrade consists of the following steps:

    1. Remove the node from the load balancer or stop HTTP traffic to the node.

    2. Run the upgrade on that node.

    3. Re-add the node to the load balancer or resume traffic to the node.

    Repeat these steps for each node in the Sync Gateway cluster.

    Sync Gateway 4.1 introduces cluster compatibility version, which lets you perform a rolling upgrade with a safe rollback path and without reducing cluster capacity. See Cluster Compatibility Version.

    Upgrade to Sync Gateway 4.1

    Prerequisites

    1. Verify your Couchbase Server cluster is running 7.6.0 or later. Bi-directional XDCR features require 7.6.6 or later.

    2. Verify all Couchbase Server nodes are operational before starting the Sync Gateway upgrade.

    3. Check your existing Sync Gateway configuration files and remove any unsupported settings:

      • shared_bucket_access=false

      • allow_conflicts=true

      • enable_star_channel=false

      Databases configured with these settings do not start on Sync Gateway 4.1.

    Procedure

    For each node in the cluster, repeat the following steps:

    1. Remove the node from the load balancer or stop HTTP traffic to the node.

    2. Install Sync Gateway 4.1 on the node.

    3. Start the Sync Gateway service.

    4. Verify the node is healthy using the GET / endpoint on the Admin REST API.

    5. Verify all databases on the node are online.

    6. Re-add the node to the load balancer or resume HTTP traffic to the node.

    Downgrading from Sync Gateway 4.1 to an earlier version is not supported after the full cluster has been upgraded. If you require a rollback path during the upgrade window, use Cluster Compatibility Version before starting.

    Upgrade to Sync Gateway 4.0

    Prerequisites

    1. Verify your Couchbase Server cluster is running 7.6.0 or later. Bi-directional XDCR features require 7.6.6 or later.

    2. Verify all Couchbase Server nodes are operational before starting the Sync Gateway upgrade.

    3. Check your existing Sync Gateway configuration files and remove any unsupported settings:

      • shared_bucket_access=false

      • allow_conflicts=true

      • enable_star_channel=false

      Databases configured with these settings do not start on Sync Gateway 4.0.

    Procedure

    For each node in the cluster, repeat the following steps:

    1. Remove the node from the load balancer or stop HTTP traffic to the node.

    2. Update the configuration file if it contains any unsupported settings listed in the prerequisites.

    3. Install Sync Gateway 4.0 on the node.

    4. Start the Sync Gateway service.

    5. Verify the node is healthy using the GET / endpoint on the Admin REST API.

    6. Verify all databases on the node are online.

    7. Re-add the node to the load balancer or resume HTTP traffic to the node.

    Downgrading from Sync Gateway 4.0 to earlier versions is not supported.

    Upgrade to Sync Gateway 3.1

    About Persistent Configuration

    Sync Gateway 3.1 uses Persistent Configuration as its default operational mode. When you start a Sync Gateway 3.1 node with an existing configuration file, Sync Gateway automatically converts the configuration to the persistent format.

    Migration to the 3.x Persistent Configuration is a one-way process. You cannot downgrade to a previous version after upgrading to 3.1.

    Before starting the upgrade, confirm the following:

    • Sync Gateway has write access to the directory containing the existing configuration file. Sync Gateway creates a backup of the existing configuration before writing the upgraded version.

    • If your configuration file contains multiple databases, all server fields used to connect to Couchbase Server must match. Sync Gateway uses the first set of credentials for the bootstrap configuration.

      Sync Gateway cannot automatically upgrade configurations with multiple distinct server fields. You must create the bootstrap configuration manually in this case.

    Consider the following before starting:

    • Configuration groups: most deployments use the default group. If you require custom node groupings, add the bootstrap_group_id value to your configuration file before startup. See bootstrap.group_id.

    • TLS: Sync Gateway 3.0 and later enables secure TLS connections to Couchbase Server by default. To use a non-secure connection in a test environment, set bootstrap.use_tls_server to false. See Secure Sync Gateway Access.

    • Admin API authentication: Secure Administration requires Couchbase Server RBAC users for Admin and Metrics API access. Configure the appropriate users before upgrading. See REST API Access.

    Procedure

    1. Start a Sync Gateway 3.1 node using your existing configuration properties file.

      Sync Gateway takes the appropriate upgrade path based on the current configuration state:

      Configuration status Inference Outcome

      No configuration exists

      This is the first node in the default group, or with this group ID, to start.

      Sync Gateway uses the configuration file to derive and persist a configuration for this node.

      Configuration exists in the server bucket

      A node in the default group, or with this group ID, has already started.

      Sync Gateway ignores the configuration file and uses the configuration associated with the default group or group ID provided.

    2. Verify the node is healthy using the GET / endpoint on the Admin REST API.

    3. Re-add the node to the load balancer or resume traffic to the node.

    4. Repeat for each remaining node in the cluster.

    Related Content

    Getting Started
    Product Information
    Community

    Mobile Forum | Blog | Blog (Mobile) | Tutorials