Oliver Michallat

<p>The latest version of the DataStax Java driver brings support for version 3 of the native CQL protocol. This post explores what that means from an end-user perspective.</p>

<h2>Native protocol overview</h2>

<p>The native protocol defines the format of the messages exchanged between the driver and Cassandra over TCP. It was&nbsp;<a href="https://www.datastax.com/dev/blog/binary-protocol" target="_blank" title="Blog post introducing the binary protocol">introduced in Cassandra 1.2</a>&nbsp;as an alternative to Thrift, and has since undergone three revisions:</p>

<table border="1">
	<tbody>
		<tr>
			<th>Cassandra version</th>
			<th>Supported protocol versions</th>
			<th>Java driver version</th>
		</tr>
		<tr>
			<td>1.2</td>
			<td>1</td>
			<td>1.0.x</td>
		</tr>
		<tr>
			<td>2.0</td>
			<td>1, 2</td>
			<td>2.0.x, 2.1.0, 2.1.1</td>
		</tr>
		<tr>
			<td>2.1</td>
			<td>1, 2, 3</td>
			<td>2.1.2</td>
		</tr>
	</tbody>
</table>

<p>Both Cassandra and the Java driver are backward-compatible with older versions of the protocol; for example, you can connect to Cassandra 1.2 from the driver 2.1.2 over protocol v1. If not specified at configuration time (see below), the best version for a given client and server will be negotiated on the first connection.</p>

<p>For interested readers, the full specification of the native protocol can be found&nbsp;<a href="https://git-wip-us.apache.org/repos/asf?p=cassandra.git;a=tree;f=doc;hb=HEAD" target="_blank" title="Directory containing native protocol specifications in the Cassandra git repo">in the Cassandra codebase</a>.</p>

<h2>Protocol version as a Java enum</h2>

<p>The first change introduced by 2.1.2 is to model protocol versions as a Java enum. Typical use cases include forcing a specific version at startup, or manually deserializing a&nbsp;<code>ByteBuffer</code>&nbsp;to a given datatype:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>

			<p>4</p>

			<p>5</p>
			</td>
			<td>
			<p><code>Cluster.builder().addContactPoint(</code><code>"127.0.0.1"</code><code>)</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.withProtocolVersion(ProtocolVersion.V2)</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.build();</code></p>

			<p>&nbsp;</p>

			<p><code>String text = (String) DataType.deserialize(buffer, ProtocolVersion.V3);</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>An enum brings obvious type safety benefits: you can't reference an unsupported version. For backward compatibility, we've kept the methods that take an&nbsp;<code>int</code>, but you should use the newer ones whenever possible.</p>

<h2>More streams per connection</h2>

<p>The native protocol is asynchronous, in that each connection handles more than one request at the same time. Requests and responses are matched by a common&nbsp;<em>stream id</em>. Here's how three requests might get interleaved on a single connection:</p>
<img alt="Stream IDs" data-align="center" data-entity-type="file" data-entity-uuid="a76c2ad2-9413-41a2-bc96-91741461a69a" src="https://www.datastax.com/sites/default/files/inline-images/stream_ids.png" />
<p>In version 2 of the native protocol, there were at most 128 stream ids per connection. The driver maintained a pool of connections to each node to handle higher throughputs.</p>

<p>In version 3, this number gets bumped to 32,768. The driver now only opens&nbsp;<strong>a single connection to each host</strong>. Most&nbsp;<a href="https://www.datastax.com/drivers/java/2.1/com/datastax/driver/core/Cluster.Builder.html#withPoolingOptions(com.datastax.driver.core.PoolingOptions)" target="_blank" title="Javadoc for Cluster.Builder.withPoolingOptions">pooling options</a>&nbsp;are no longer relevant and will be ignored if v3 is in use. However, we've added new options to limit the total number of requests per host. This is useful to enforce client-side throttling:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>

			<p>4</p>

			<p>5</p>
			</td>
			<td>
			<p><code>Cluster.builder().addContactPoint(</code><code>"127.0.0.1"</code><code>)</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.withPoolingOptions(</code><code>new</code> <code>PoolingOptions()</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.setMaxSimultaneousRequestsPerHostThreshold(HostDistance.LOCAL, </code><code>16384</code><code>)</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.setMaxSimultaneousRequestsPerHostThreshold(HostDistance.REMOTE, </code><code>2048</code><code>))</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.build();</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>These options default to 1024 for local hosts and 256 for remote hosts, which gives you roughly the same load as the v2 pool with the default options.</p>

<h2>Client-side timestamps</h2>

<p>In Cassandra, each write has a microsecond-precision timestamp associated with it. Until now, there were two ways to assign it:</p>

<ul>
	<li>automatically on the server-side. This can sometimes be a problem when the order of the writes matter: with unlucky timing (different coordinators, network latency, etc.), two successive requests from the same client might be processed in a different order server-side, and end up with out-of-order timestamps;</li>
	<li>explicitly in the CQL query string (with&nbsp;<code>USING TIMESTAMP</code>). This solves the previous problem, but puts the burden of generating timestamps on client code.</li>
</ul>

<p>With the native protocol version 3, a&nbsp;<em>default timestamp</em>&nbsp;can now be sent with each query. The driver will do it automatically if it's configured with an instance of&nbsp;<code>TimestampGenerator</code>:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>
			</td>
			<td>
			<p><code>Cluster.builder().addContactPoint(</code><code>"127.0.0.1"</code><code>)</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.withTimestampGenerator(</code><code>new</code> <code>AtomicMonotonicTimestampGenerator())</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.build();&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>In 2.1.2, the default is still server-side generation. So unless you explicitly provide a generator, you get the same behavior as previous driver versions.</p>

<p>In addition, you can also override the default timestamp on a per-statement basis:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>
			</td>
			<td>
			<p><code>Statement statement = </code><code>new</code> <code>SimpleStatement(</code><code>"UPDATE users SET email = 'x@y.com' where id = 1"</code><code>);</code></p>

			<p><code>statement.setDefaultTimestamp(</code><code>1234567890</code><code>);</code></p>

			<p><code>session.execute(statement);</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>As you can see, there are multiple ways to provide a timestamp, some of which overlap. The order of precedence is the following:</p>

<ol>
	<li>if there is a "<code>USING TIMESTAMP</code>" clause in the CQL string, use that over anything else;</li>
	<li>otherwise, if a default timestamp was set on the statement&nbsp;<em>and is different from&nbsp;<code>Long.MIN_VALUE</code></em>, use it;</li>
	<li>otherwise, if a generator is specified, invoke it and use its result&nbsp;<em>if it is different from&nbsp;<code>Long.MIN_VALUE</code></em>;</li>
	<li>otherwise, let the server assign the timestamp.</li>
</ol>

<h2>Serial consistency level on batch statements</h2>

<p>The serial consistency level is used in lightweight transactions. It applies to the "Paxos" phase — where the nodes reach a consensus on the proposal to proceed with — and can take one of two values:&nbsp;<code>SERIAL</code>&nbsp;and&nbsp;<code>LOCAL_SERIAL</code>&nbsp;(to understand the motivation for&nbsp;<code>LOCAL_SERIAL</code>, see&nbsp;<a href="https://issues.apache.org/jira/browse/CASSANDRA-5797" target="_blank" title="CASSANDRA-5797">CASSANDRA-5797</a>). In contrast, the "regular" consistency level in a lightweight transaction applies to the standard write that happens once Paxos has unfolded.</p>

<p>In the Java driver, you set the serial consistency level through the aptly-named Statement#setSerialConsistencyLevel method. But in earlier versions, this method would throw an exception when called on a&nbsp;<code>BatchStatement</code>, because the operation was not supported at the protocol level. This is now possible in 2.1.2 with protocol v3. Here it is, with an example from an earlier blog post:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>

			<p>4</p>

			<p>5</p>

			<p>6</p>

			<p>7</p>
			</td>
			<td>
			<p><code>BatchStatement batch = </code><code>new</code> <code>BatchStatement();</code></p>

			<p><code>batch.add(</code><code>new</code> <code>SimpleStatement(</code><code>"UPDATE bills SET balance=-200 WHERE user='user1' IF balance=-208"</code><code>));</code></p>

			<p><code>batch.add(</code><code>new</code> <code>SimpleStatement(</code><code>"UPDATE bills SET paid=true"</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>+ </code><code>"WHERE user='user1' AND expense_id=1"</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>+ </code><code>"IF paid=false"</code><code>));</code></p>

			<p><code>batch.setSerialConsistencyLevel(ConsistencyLevel.LOCAL_SERIAL);</code></p>

			<p><code>session.execute(batch);</code></p>
			</td>
		</tr>
	</tbody>
</table>

<h2>Other improvements in 2.1.2</h2>

<p>2.1.2's main focus was protocol v3 support, but it also comes with a handful of other improvements and fixes. As always, refer to the&nbsp;<a href="https://github.com/datastax/java-driver/blob/2.1/driver-core/CHANGELOG.rst#212" target="_blank" title="2.1.2 changelog on GitHub">changelog</a>&nbsp;for the full list.</p>


Build and scale cloud native apps

Discover the benefits of DBaaS and why your apps deserve an upgrade.

Learn about NoSQL Databases

Learn about NoSQL databases with Apache Cassandra and Astra DB.

2022 Recap: A Year for Customers, Community, and Real-Time Data

Highlights from 2022 and a glimpse into the year ahead.

ViewingTechnical How To’s

New in Java driver 2.1.2: native protocol v3 support

Sign up for our Developer Newsletter