As of Couchbase Server 2.1.0, we have a binary protocol to retrieve replicated data for a given key. The command is similar to the existing binary get command, however it returns data from a vBucket that is in a replica state as opposed to an active state.
In case of node failure you can have an application retry the server and wait until replicated data is available on another node. Couchbase Server takes 30 seconds to detect a node has failed, automatically failover the node, and then elevate replicated data to an active state on another node. If you do not have automatic failover enabled, it may take even longer for human intervention and manual failover. Although clients can wait and retry a read, you may have a scenario where you cannot wait 30 seconds to detect node failure, perform failover and activate replicated data. For instance if you a SLA that requires you to get data within 30 seconds of a request or less, you may need replica read functionality. In this case you can use replica read at the binary protocol level or as it is available in Couchbase SDKs. For more information about node failure and failover, see Couchbase Server Manual, Failing Over Nodes.
If you create your own Couchbase client, you can also create a wrapper on this protocol to provide replica reads.
The request is identical to a get request with the exception of the Opcode of 0x83:
Field (offset) (value) Magic (0) : 0x80 Opcode (1) : 0x83 Key length (2,3) : 0x0005 Extra length (4) : 0x00 Data type (5) : 0x00 VBucket (6,7) : 0x0000 Total body (8-11) : 0x00000005 Opaque (12-15): 0x00000000 CAS (16-23): 0x0000000000000000 Extras : None Key (24-29): The textual string: "Hello" Value : None
The response is also identical to a get response except for the Opcode of 0x83:
Field (offset) (value) Magic (0) : 0x81 Opcode (1) : 0x83 Key length (2,3) : 0x0000 Extra length (4) : 0x04 Data type (5) : 0x00 Status (6,7) :0x0000 Total body (8-11) : 0x00000009 Opaque (12-15): 0x00000000 CAS (16-23): 0x0000000000000001 Key (24-29): The textual string: "Hello" Value : The textual string: "World"
Possible errors from the server include the following:
ENGINE_NOT_MY_VBUCKET = 0x0c ENGINE_EWOULDBLOCK = 0x07
You will get the
if the server cannot find the vBucket with this key. You may also
get this message if the vBucket with this key is not in replica
state. This means you will get this error if the server has
already performed automatic failover and has already elevated the
replicated data into an active state when it got the request. In
this case, the key is available as a get operation and not as a
Couchbase Server will return
if the vBucket with replicated data is still undergoing rebalance.
In this case you may want to provide logic in your client to retry
as a get operation once the rebalance completes.