.. toctree::
   :maxdepth: 1

Version 2.1 of the DataStax Python driver for Apache Cassandra adds support for Cassandra 2.1 and version 3 of the native protocol.

Cassandra 1.2, 2.0, and 2.1 are all supported. However, 1.2 only supports protocol version 1, and 2.0 only supports versions 1 and 2, so some features may not be available.

By default, the driver will attempt to use version 2 of the native protocol. To use version 3, you must explicitly set the :attr:`~.Cluster.protocol_version`:

from cassandra.cluster import Cluster

cluster = Cluster(protocol_version=3)

Note that protocol version 3 is only supported by Cassandra 2.1+.

In future releases, the driver may default to using protocol version 3.

Cassandra 2.1 introduced the ability to define new types:

USE KEYSPACE mykeyspace;

CREATE TYPE address (street text, city text, zip int);

The driver generally expects you to use instances of a specific class to represent column values of this type. You can let the driver know what class to use with :meth:`.Cluster.register_user_type`:

cluster = Cluster()

class Address(object):

    def __init__(self, street, city, zipcode):
        self.street = street
        self.city = text
        self.zipcode = zipcode

cluster.register_user_type('mykeyspace', 'address', Address)

When inserting data for address columns, you should pass in instances of Address. When querying data, address column values will be instances of Address.

If no class is registered for a user-defined type, query results will use a namedtuple class and data may only be inserted though prepared statements.

See :ref:`udts` for more details.

Starting with version 2.1 of the driver, it is possible to customize how Python types are converted to CQL literals when working with non-prepared statements. This is done on a per-:class:`~.Session` basis through :attr:`.Session.encoder`:

cluster = Cluster()
session = cluster.connect()
session.encoder.mapping[tuple] = session.encoder.cql_encode_tuple

See :ref:`type-conversions` for the table of default CQL literal conversions.

With version 3 of the native protocol, timestamps may be supplied by the client at the protocol level. (Normally, if they are not specified within the CQL query itself, a timestamp is generated server-side.)

When :attr:`~.Cluster.protocol_version` is set to 3 or higher, the driver will automatically use client-side timestamps with microsecond precision unless :attr:`.Session.use_client_timestamp` is changed to :const:`False`. If a timestamp is specified within the CQL query, it will override the timestamp generated by the driver.

Version 2.0 of the DataStax Python driver for Apache Cassandra includes some notable improvements over version 1.x. This version of the driver supports Cassandra 1.2, 2.0, and 2.1. However, not all features may be used with Cassandra 1.2, and some new features in 2.1 are not yet supported.

By default, the driver will attempt to use version 2 of Cassandra's native protocol. You can explicitly set the protocol version to 2, though:

from cassandra.cluster import Cluster

cluster = Cluster(protocol_version=2)

When working with Cassandra 1.2, you will need to explicitly set the :attr:`~.Cluster.protocol_version` to 1:

from cassandra.cluster import Cluster

cluster = Cluster(protocol_version=1)

Version 2 of the native protocol adds support for automatic query paging, which can make dealing with large result sets much simpler.

See :ref:`query-paging` for full details.

With version 1 of the native protocol, batching of statements required using a BATCH cql query. With version 2 of the native protocol, you can now batch statements at the protocol level. This allows you to use many different prepared statements within a single batch.

See :class:`~.query.BatchStatement` for details and usage examples.

Also new in version 2 of the native protocol is SASL-based authentication. See the section on :ref:`security` for details and examples.

Lightweight transactions are another new feature. To use lightweight transactions, add IF clauses to your CQL queries and set the :attr:`~.Statement.serial_consistency_level` on your statements.

In order to fix some issues around garbage collection and unclean interpreter shutdowns, version 2.0 of the driver requires you to call :meth:`.Cluster.shutdown()` on your :class:`~.Cluster` objects when you are through with them. This helps to guarantee a clean shutdown.

The following functions have moved from cassandra.decoder to cassandra.query. The original functions have been left in place with a :exc:`DeprecationWarning` for now:

• :attr:`cassandra.decoder.tuple_factory` has moved to :attr:`cassandra.query.tuple_factory`
• :attr:`cassandra.decoder.named_tuple_factory` has moved to :attr:`cassandra.query.named_tuple_factory`
• :attr:`cassandra.decoder.dict_factory` has moved to :attr:`cassandra.query.dict_factory`
• :attr:`cassandra.decoder.ordered_dict_factory` has moved to :attr:`cassandra.query.ordered_dict_factory`

The following dependencies have officially been made optional:

• scales
• blist

And one new dependency has been added (to enable Python 3 support):

• six