Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu

Caution

You're viewing documentation for a previous version of Scylla Java Driver. Switch to the latest stable version.

Scylla Java Driver Manual Native protocol

Native protocol¶

The native protocol defines the format of the binary messages exchanged between the driver and Cassandra over TCP. As a driver user, you don’t need to know the fine details (although the protocol spec is in the Cassandra 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 Cassandra when the first connection is established. Both sides are backward-compatible with older versions:

Driver VersionCassandra: 1.2.x
(DSE 3.2)
2.0.x
(DSE 4.0 to 4.6)
2.1.x
(DSE 4.7)
2.2.x3.0.x & 3.x
(DSE 5.0+)
1.0.x v1 v1 v1 v1 Unsupported (1)
2.0.x to 2.1.1 v1 v2 v2 v2 Unsupported (1)
2.1.2 to 2.1.x v1 v2 v3 v3 Unsupported (2)
3.x v1 v2 v3 v4 v4

(1) Cassandra 3.0 does not support protocol versions v1 and v2

(2) There is a matching protocol version (v3), but the driver 2.1.x can’t read the new system table format of Cassandra 3.0

For example, if you use version 2.1.5 of the driver to connect to Cassandra 2.0.9, the maximum version you can use (and the one you’ll get by default) is protocol v2 (third row, second column). If you use the same version to connect to Cassandra 2.1.4, you can use protocol v3.

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:

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

If you specify a version that is not compatible with your current driver/Cassandra 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 Cassandra), 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 2.1.2+):

  • the first contact point is a 2.1 host, so the driver negotiates protocol v3;

  • while connecting to the rest of the cluster, the driver contacts a 2.0 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 v2 while the rolling upgrade is happening, and only switch to v3 when the whole cluster has switched to Cassandra 2.1;

  • ensure that the list of initial contact points only contains hosts with the oldest version (2.0 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

PREVIOUS
Metrics
NEXT
Object Mapper
  • 3.11.0.x
    • 4.13.0.x
    • 4.12.0.x
    • 4.11.1.x
    • 4.10.0.x
    • 4.7.2.x
    • 3.11.2.x
    • 3.11.0.x
    • 3.10.2.x
    • 3.7.2.x
  • Scylla Java Driver for Scylla and Apache Cassandra®
  • API Documentation
  • Manual
    • Address resolution
    • Asynchronous programming
    • Authentication
    • Compression
    • Control connection
    • Custom Codecs
    • Custom Payloads
    • Query idempotence
    • Load balancing
    • Logging
    • Metadata
    • Metrics
    • Native protocol
    • Object Mapper
      • Definition of mapped classes
      • Using custom codecs
      • Using the mapper
    • OSGi
    • Paging
    • Connection pooling
    • Query timestamps
    • Reconnection
    • Retries
    • Using the shaded JAR
    • Socket options
    • Speculative query execution
    • SSL
    • Statements
      • Simple statements
      • Prepared statements
      • Built statements
      • Batch statements
    • Using Tuples with the Java driver
    • User-defined types
  • Upgrade guide
    • Migrating from Astyanax
      • Configuration
      • Language change : from Thrift to CQL
      • Queries and Results
  • Frequently Asked Questions
  • Changelog
  • Create an issue
  • Edit this page

On this page

  • Native protocol
    • Compatibility matrix
    • Controlling the protocol version
      • Protocol version with mixed clusters
    • New features by protocol version
      • v1 to v2
      • v2 to v3
      • v3 to v4
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© 2022, ScyllaDB. All rights reserved.
Last updated on 25 May 2022.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2