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 have an 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 Server maintenance.

If you create your own Couchbase client, you can also create a wrapper on this protocol to provide replica reads.

If you use replica read, it will introduce the possibility that a client gets inconsistent data from the cluster; for this reason we generally recommend you have your application logic handle shorts periods of unavailability. For example if a user cannot get their user profile within 30 seconds, you can handle it with an error message and request that they try later. Replica read will get replicated data from the functioning node; but this does not ensure that the document is the most current document. For instance, if you update a document then immediately perform replica read, the data might not yet be replicated to the other node and you will get an older version back. If it is very important that you always have the most current version of a document, you may not satisfy this with a replica read. One thing you can do to help mitigate this problem is to keep the CAS value for an item when you set or update it and compare this with the CAS value returned by replica read. For more information, see Check and set (CAS)

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 ENGINE_NOT_MY_VBUCKET message 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 replica read.

Couchbase Server will return ENGINE_EWOULDBLOCK 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.