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
- bound variables in simple statements (Session#execute(String, Object…))
- batch statements
- query paging
v2 to v3
- the number of stream ids per connection goes from 128 to 32768 (see Connection pooling)
- serial consistency on batch statements
- client-side timestamps
v3 to v4
- query warnings
- allowed unset values in bound statements
- Custom payloads
v4 to DSE_V1
DSE_V1 to DSE_V2
- Continuous Paging backpressure support