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 the Sync Function is changed, Sync Gateway needs to reprocess all existing documents in the bucket to recalculate the routing and access assignments.
Resync API
The Admin REST API provides a /{db}/resync endpoint that enables you to start or stop a resync operation. Starting the resync will initiate the reprocessing of every document in the database again.
There is also a 'support-only' option to regenerate sequences whilst resyncing.
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 be only run on one node. Users should take other nodes offline before initiating this action. Starting resync on more than one node will result in multiple instances running, with undefined system behavior.
The resync operation is run asynchronously. Use /{db}/resync to establish the current status of a resync operation.
Updating the Sync Function
To update the Sync Function and fully resync, you are recommended to follow the steps in Steps to Update and Resync.
| This is an expensive operation because it requires every document in the database to be processed by the new function. |
The database can accept no requests until resync is complete because no user’s full access privileges are known until all documents have been scanned.
Therefore, the Sync Function update will result in application downtime whilst the database is offline (that is, between the call to the /{db}/_offline and /{db}/_online endpoints in Steps to Update and Resync.
You won’t need to run the resync operation, if either:
-
The modifications to the Sync Function only impact write security (and not routing/access), or,
-
You only want changes to channel/access rules to apply to documents written after the change was made.
Running Resync
Resync is run asynchronously. Its status can be monitored using /{db}/resync.
Be sure to take the database offline using /{db}/_offline
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 will always succeed.
It is very likely that you are using 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 is 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 will only take effect once a new revision to that document is saved on Sync Gateway. Running a resync operation does not revoke access to that document.
Availability
If you need to ensure 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.
Updating Clusters
In a clustered environment with multiple Sync Gateway instances sharing the load, all the instances need to share the same configuration. To ensure this happens, you must taken all instances offline using the /{db}/_offline endpoint.
After the configuration is updated, one instance should be brought up so it can update the database—if more than one is running at this time, they’ll conflict with each other. After the first instance finishes opening the database, the others can be started.