Upgrade
This page documents various implementation details and functionalities to consider when performing an upgrade to Sync Gateway 2.6.
Views to GSI
Prior to 2.1, Sync Gateway used system views for a variety of internal operations, including authentication and replication. Starting in 2.1, Sync Gateway will use GSI and N1QL to perform those tasks.
The upgrade, from using views to using Global Secondary Indexes and N1QL, happens automatically when starting a Sync Gateway 2.1 or above node in a cluster that was previously using views.
Use of GSI requires Couchbase Server 5.5, with at least one node running the Query and Index Services.
Users wanting to run Sync Gateway 2.1 or above with an older version of Couchbase Server will need to continue to use views, by setting the use_views
property.
Configuration Changes
Before |
After |
Sync Gateway 1.5 or above
|
Sync Gateway 1.5 or above
|
After restarting Sync Gateway with the updated configuration file, the mobile metadata for existing documents is automatically migrated.
To enable shared bucket on incoming documents, one Sync Gateway node in the cluster must also have the Enabling shared bucket access on your existing deployment is not reversible. It is recommended to test the upgrade on a staging environment before upgrading the production environment. Known issue: enabling shared bucket access on your existing deployment if it’s already running with GSI indexing will require downtime (known issues CBG-394). |
|
Sync Gateway 2.1 or above
|
Sync Gateway 2.1 or above
|
After restarting Sync Gateway with the updated configuration file, the number of Index Replicas in the Couchbase Server cluster is automatically updated. |
Upgrade
A rolling upgrade is the recommended method to upgrade a Sync Gateway cluster. At a high level, a rolling upgrade consists of the following steps:
-
The load balancer configuration is updated to stop any HTTP traffic going to the node that will be upgraded.
-
The upgrade is performed on the given node
-
The load balancer configuration is updated to re-balance the HTTP traffic across all nodes.
Those steps are then repeated for each node in the Sync Gateway cluster.
The tables below provide more detail for distinct upgrade scenarios.
From |
To |
Sync Gateway 1.x, 2.0 |
Sync Gateway 2.1+ ( |
No downtime in a rolling upgrade. |
|
The upgrade, from using views to using Global Secondary Indexes and N1QL, happens automatically when starting a Sync Gateway 2.1 or above node in a cluster that was previously using views.
By default, Sync Gateway requires the Couchbase Server cluster to be running Couchbase Server 5.5, with at least two nodes running the Index and Query Services.
If this is not the case, users must configure the Installation follows the same general approach used in 2.0. On startup, Sync Gateway will check for the existence of the required indexes, and only attempt to create them if they do not already exist. Then, Sync Gateway will wait until indexes are available before starting to serve requests. Sync Gateway 2.1 or above will not automatically remove the previously used design documents.
Removal of the obsolete design documents is done via a call to the /_post_upgrade endpoint in Sync Gateway’s Admin REST API.
This endpoint can be run in preview mode (
|
From |
To |
Sync Gateway 1.x |
Sync Gateway 2.0, 2.1+ ( |
No downtime in a rolling upgrade. |
|
In 2.0, Sync Gateway’s design documents include the version number in the design document name.
In this release for example, the design documents are named On startup, Sync Gateway will check for the existence of these design documents, and only attempt to create them if they do not already exist.
Then, Sync Gateway will wait until views are available and indexed before starting to serve requests.
To evaluate this, Sync Gateway will issue a If the view request exceeds the default timeout of 75s (which would be expected when indexing large buckets), Sync Gateway will log additional messages and retry. The logging output will look like this:
Sync Gateway 2.0 will not automatically remove the previous design documents.
Removal of the obsolete design documents is done via a call to the new
|
From |
To |
Sync Gateway 1.1, 1.2, 1.3, 1.4 |
Sync Gateway 1.5 |
Possible downtime in a rolling upgrade. Follow the steps below to avoid any downtime. |
|
In this upgrade path, the upgrade process will trigger views in Couchbase Server to be re-indexed. During the re-indexing, operations that are dependent on those views will not be available. The main operations relying on views to be indexed are:
The unavailability of those operations may result in some requests not being processed. The duration of the downtime will depend on the data set and frequency of replications with mobile clients. To avoid this downtime, it is possible to pre-build the view index before directing traffic to the upgraded node. Sync Gateway uses Couchbase Server views to index and query documents. When Sync Gateway starts, it will publish a Design Document which contains the View definitions (map/reduce functions). For example, the Design Document for Sync Gateway is the following:
Following the Design Document creation, it must run against all the documents in the Couchbase Server bucket to build the index which may result in downtime. During a Sync Gateway upgrade, the index may also have to be re-built if the Design Document definition has changed. To avoid this downtime, you can publish the Design Document and build the index before starting Sync Gateway by using the Couchbase Server REST API. The following curl commands refer to a Sync Gateway 1.3 → Sync Gateway 1.4 upgrade but they apply to any upgrade of Sync Gateway or Accelerator.
|
Couchbase Server
All of the different upgrade paths mentioned above assume that Couchbase Server is running a compatible version for Sync Gateway. There are 3 commonly used upgrade paths for Couchbase Server. Depending on the one you choose, there may be additional consideration to keep in mind when using Sync Gateway:
Upgrade Strategy | Downtime | Additional Machine Requirements | Impact when using Sync Gateway |
---|---|---|---|
Rolling Online Upgrade |
None |
Low |
Potential transient connection errors: The Couchbase Server re-balance operations can result in transient connection errors between Couchbase Server and Sync Gateway, which could result in Sync Gateway performance degradation. Potential for unexpected server errors during re-balance: There is an increased potential to lose in-flight ops during a fail-over. |
Upgrade Using Inter-cluster Replication |
Small amount during switchover |
High - duplicate entire cluster |
Using an XDCR (Cross Data Center Replication) approach will have incur some Sync Gateway downtime, but less downtime than other approaches where Sync Gateway is shutdown during the entire Couchbase Server upgrade. It’s important to note that the XDCR replication must be a one way replication from the existing (source) Couchbase Server cluster to the new (target) Couchbase Server cluster, and that no other writes can happen on the new (target) Couchbase Server cluster other than the writes from the XDCR replication, and no Sync Gateway instances should be configured to use the new (target) Couchbase Server cluster until the last step in the process.
Caveats:
|
Offline Upgrade |
During entire upgrade |
None |
|