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 (although the protocol spec is in the DSE codebase if you’re curious); 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:

  DSE: 3.2 4.0 to 4.6 4.7 to 4.8 5.0
Driver: 1.x v1 v2 v3 v4

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 using protocol v3, which 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