Native protocol

The native protocol defines the format of the binary messages exchanged between the driver and DSE over TCP. As a driver user, you don’t need to know the fine details; the most visible aspect is that some features are only available with specific protocol versions.

Compatibility matrix

By default, the protocol version is negotiated between the driver and DSE when the first connection is established. Both sides are backward-compatible with older versions:

Driver Version DSE: 3.2 4.0 to 4.6 4.7 to 4.8 5.0 5.1 6.0 to 6.8
1.0 to 1.1 v1 v2 v3 v4 v4 v4
1.2 to 1.5 v1 v2 v3 v4 DSE_V1 DSE_V1
1.6 to 1.9 v1 v2 v3 v4 DSE_V1 DSE_V2

Controlling the protocol version

To find out which version you’re currently using, use ProtocolOptions#getProtocolVersion():

ProtocolVersion myCurrentVersion = cluster.getConfiguration()
    .getProtocolOptions()
    .getProtocolVersion();

The protocol version can not be changed at runtime. However, you can force a given version at initialization:

DseCluster cluster = DseCluster.builder()
    .addContactPoint("127.0.0.1")
    .withProtocolVersion(ProtocolVersion.V2)
    .build();

If you specify a version that is not compatible with your current driver/DSE combination, you’ll get an error:

Exception in thread "main" com.datastax.driver.core.exceptions.NoHostAvailableException:
All host(s) tried for query failed
(tried: /127.0.0.1:9042 (com.datastax.driver.core.UnsupportedProtocolVersionException:
  [/127.0.0.1:9042] Host /127.0.0.1:9042 does not support protocol version V3 but V2))

Protocol version with mixed clusters

If you have a cluster with mixed versions (for example, while doing a rolling upgrade of DSE), note that the protocol version will be negotiated with the first host the driver connects to.

This could lead to the following situation (assuming you use driver 1.x):

  • the first contact point is a DSE 5 host, so the driver negotiates protocol v4;
  • while connecting to the rest of the cluster, the driver contacts a 4.8 host (that is using protocol v3), so request fails; an error is logged and this host will be permanently ignored.

To avoid this issue, you can use one the following workarounds:

  • always force a protocol version at startup. You keep it at v3 while the rolling upgrade is happening, and only switch to v4 when the whole cluster has switched to DSE 5;
  • ensure that the list of initial contact points only contains hosts with the oldest version (4.8 in this example).

New features by protocol version

v1 to v2

v2 to v3

v3 to v4

v4 to DSE_V1

DSE_V1 to DSE_V2

  • Continuous Paging backpressure support