Important notice for upgrades from 2.2.X to 3.Y

[Sylvain Lebresne <sy...@datastax.com>]

The native protocol is the name we give to the protocol used between CQL
drivers and the server. That protocol is versioned and a new version,
version
4, was introduced in Cassandra 2.2.0. We recently uncovered a compatibility
bug
in that 4th version (https://issues.apache.org/jira/browse/CASSANDRA-10880)
that made said version of the protocol not fully compatible between 2.2.X
and
3.Y. As a consequence, you _must_ ensure that your clients use the protocol
version 3 if you plan an upgrade from any 2.2.X version to any 3.Y version.
Ensuring that might requires forcing the protocol version in the client
driver
used. For instance, in the DataStax Java driver, you can do so by calling
`.withProtocolVersion(ProtocolVersion.V3)` on your `Cluster.Builder` object.

The bug in question affects the automatic paging of result sets that the
protocol provides: the first page or results is always sent correctly, but
requesting the next pages might result in a failure. This mean that in
theory
you can disregard this problem if you know that you are not using said
paging,
but we still strongly encourage sticking to the protocol v3 for upgrade as
the
downsides are very minor (see below) and not worth taking risk.

The changes in the protocol v4 are relatively minor, and so forcing the use
of
v3 are relatively minor downsides, namely:
- the use of the recently added CQL type `date`, `time`, `tinyint` and
  `smallint` involves sending slightly bigger metadata in v3 that in v4. The
  resulting performance difference is unlikely to be noticeable.
- schema changes related to User Defined Functions are notified to clients
as a
  "keyspace change" in v3 which, being imprecise, might require a client
driver
  to request more schema metadata to update its own copy of said metadata.
This
  is again a very minor inefficiently.
- The protocol v4 has a feature that allows the server to send warnings to
the
  clients. This is as of yet little used by the server and in which case
where
  it is, the warning is also logged server side.

Note that using the protocol v4 is fine once you have finished with your
upgrade and all your nodes are on 3.Y. The problem is only with cluster
mixing
2.2.X and 3.Y nodes.

--
The Cassandra dev team