Eventing — Server Compatibility
How Sync Gateway works with Couchbase Server’s Eventing feature
Related topics: XDCR | Eventing | Transactions | Collections
Other Topics: Compatibility Matrix
| This content relates only to ENTERPRISE EDITION |
Introduction
Couchbase Server provides the backing data store for Sync Gateway.
| See: Compatibility Matrix for version compatibility information. |
Couchbase Server’s Couchbase Eventing Service feature provides a framework to operate on changes to data in real time.
Here we provide details on how Couchbase Eventing Service relates to data changes in the Couchbase Mobile ecosystem.
Using Eventing - Server 7.6.3+
|
Do not deploy Eventing/Sync Gateway until all SGW nodes are at version 3.2. For earlier Sync Gateway versions that do not write import XATTRs, Eventing functions experience infinite recursions and duplicate mutations if deployed in a mixed mode SGW environment. This can only happen during a mixed mode of SGW with a 3.2 version and an earlier version during an upgrade and you deploy a new Eventing/Sync Gateway function. |
Sync Gateway 3.2.0 now supports interoperability with Eventing from Couchbase Server version 7.6.3+. You can use Eventing to handle data changes that happen when applications interact and to integrate with other Couchbase services such as Data, Query and Full Text Search.
You can now create Eventing functions with read-write bindings with the source bucket associated with a Sync Gateway database.
You can also use Eventing to generate vector embeddings from document fields, see Vector Search for more details about Vector Search with Couchbase Lite.
Eventing now skips all documents with IDs prefixed with _sync.
For Sync Gateway versions that write import XATTRs:
-
Eventing now prevents infinite recursion.
-
Eventing now prevents duplicate mutations with the opt-in
import_mutation_awareboolean flag.
If the import_mutation_aware flag is set to true, the performance of the Eventing function will drop because every mutation processed by Eventing will require a subdocument operation to maintain a cursor or progress for any Function that is sharing a Sync Gateway endpoint.
|
The procedure to enable Sync Gateway support for an Eventing function is as follows:
-
On Couchbase Server, pause the function.
-
Using the Eventing REST API, set the
allow_sync_documentssetting for the function to false.You must also include the deployment_statusandprocessing_statussettings in the request body.For example, for a global function with a scope of
.:curl -XPOST -d '{ "deployment_status": true, "processing_status": false, "allow_sync_documents": false }' "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"For a scoped function:
curl -XPOST -d '{ "deployment_status": true, "processing_status": false, "allow_sync_documents": false }' "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data"Where:
-
$HOSTis the hostname or IP address of a node running the Eventing service. -
$ADMINis the user name of an administrator. -
$USERis the user name of any authorized user . -
$PASSWORDis the password to connect to Couchbase Server.
-
-
On Couchbase Server, resume the function.
For more details, see Eventing REST API.
Using Eventing (Pre-Server 7.6.3)
You can use Eventing and Sync Gateway connected to the same bucket when Eventing operates on server buckets in read only mode — see Bucket Bindings for how to do this.
You should write your Eventing function to be idempotent; to behave correctly when the same mutation is seen more than once. This is necessary because:
-
When a single document update is made directly by Sync Gateway, such as those replicated from Couchbase Lite, it generates a single server mutation that writes both the document body and the metadata.
When an update originates outside of Couchbase mobile then multiple mutations are generated because Sync Gateway must update both the document’s body and its _sync metadata (XATTRs).
-
Eventing detects these mutations and invokes its
OnUpdatefor each; whether it’s for the modified body of the document, Sync Gateway metadata, or both. It is here that you need to code the function to apply the same update once only. One way to do this is to use the crc64 function call to identify when an update is to the Sync Gateway metadata only — see: Eventing — crc64() for more on how to do this.
Eventing prevents inadvertent use of its functions on Sync Gateway read-write buckets.
You will see the following warning if you try to do this:
SyncGateway is enabled on: <bucket-name>, deployment of source bucket mutating handler will cause Intra Bucket Recursion