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 older Sync Gateway versions that do not write import XATTRs, Eventing functions will encounter 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 older version during an upgrade and a new Eventing/Sync Gateway function is deployed. |
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 also use Eventing to generate vector embeddings from document fields, see Vector Search for more details about Vector Search with Couchbase Lite.
When using Server versions 7.6.3 and later, users should set Sync Gateway Aware to true in the on prem Eventing Service UI on their Eventing functions.
This will avoid duplicated event hits for documents being imported by Sync Gateway.
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.
|
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.
But when an update originates outside of Couchbase mobile then multiple mutations are generated. That is 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 is 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