Resync
Recalculating routing and data access following Sync Function changes
This content explains the resync feature
Related sync topics: Admin REST API | Database Configuration | database.sync | Legacy Pre-3.0 Configuration
Introduction
The Sync Function computes both the document routing to channels and the user access to channels at document write time.
If you change the Sync Function, Sync Gateway needs to reprocess all existing documents in the bucket to recalculate the routing and access assignments. A resync operation does this reprocessing.
When to Use Resync
You need to run a resync operation when:
-
You have modified the Sync Function in a way that affects document routing to channels.
-
You have changed access control rules in the Sync Function.
-
You want the changes to apply to all existing documents in the database.
You’ll not need to run the resync operation if either:
-
The modifications to the Sync Function only impact write security, and not routing/access.
-
You only want changes to channel/access rules to apply to documents written after you made the change.
Resync API
The Admin REST API provides a POST /{db}/_resync endpoint that enables you to start or stop a resync operation. Starting the resync initiates the reprocessing of every document in the database.
The resync operation runs asynchronously. Use GET /{db}/_resync to monitor the current status of a resync operation.
| When using nonpersistent (legacy) configuration, the resync action is carried out only on the node that the POST is made to. It is not cross-node aware. In a multi-node cluster, the resync must only run on 1 node. Starting resync on more than 1 node results in multiple instances running, with undefined system behavior. When using persistent configuration (default since Sync Gateway 3.0), resync operations work across all nodes automatically. |
| There’s also a 'support-only' option to regenerate sequences while resyncing. |
Update Sync Function and Resync
This section describes how to update your Sync Function and perform a full resync of your database.
| This is an expensive operation because the new function must process every document in the database. The database cannot accept requests until resync is complete because Sync Gateway cannot determine any user’s full access privileges until it scans all documents. Therefore, the Sync Function update results in application downtime while the database is offline. |
-
Persistent Configuration
-
Non-Persistent Configuration
Use this method when Couchbase Server stores your Sync Gateway configuration (default since Sync Gateway 3.0).
-
The database is online.
Procedure-
Update the configuration file of the Sync Gateway instance.
-
Restart Sync Gateway.
-
Take the database offline using
PUT /{db}/_configwith{"offline": true}(can use Load Balancer).This updates the database configuration persisted in the bucket, and all nodes will go offline.
-
Run resync using POST /{db}/_resync (you can call this on any node or through Load Balancer).
-
Monitor resync status using GET /{db}/_resync.
The message body of the response contains the number of changes that resync made.
-
Bring the database back online using
PUT /{db}/_configwith{"offline": false}(can use Load Balancer).This updates the database configuration persisted in the bucket, and all nodes go online.
-
Use this method when local config files store your Sync Gateway configuration (legacy mode).
-
The database is online.
Procedure-
Update the configuration file on all nodes.
-
Restart Sync Gateway.
-
Take the database offline by calling
POST /{db}/_offlineon each node individually (do not use Load Balancer).This modifies the state on the current node only.
-
Run resync using POST /{db}/_resync on a single node only (do not use Load Balancer).
-
Monitor resync status using GET /{db}/_resync.
The message body of the response contains the number of changes that resync made.
-
Bring the database back online by calling
POST /{db}/_onlineon each node individually (do not use Load Balancer).This modifies the state on the current node only.
-
Resync Considerations
This section covers important considerations when running a resync operation.
Resync Context
When running a resync operation, the context in the Sync Function is the admin user.
For that reason, calling the methods requireUser, requireAccess, and requireRole always succeeds.
You may use those functions in production to govern write operations.
But in a resync operation, all the documents are already written to the database.
For that reason, it’s recommended to use resync for changing the assignment to channels only (i.e. reads).
Revoking Access
If you change the sync function to revoke a user’s access to a document, the access only takes effect once you save a new revision to that document on Sync Gateway. Running a resync operation does not revoke access to that document.
Maintaining Availability During Resync
If you need to verify access to the database during a Sync function update and resync, you can create a read-only backup of the Sync Gateway’s bucket beforehand, then run a secondary Sync Gateway on the backup bucket in read-only mode. Once you detect the resync is complete, switch back to the main Sync Gateway and bucket.