deb-python-cassandra-driver/docs/upgrading.rst

Upgrading

Upgrading to 2.1 from 2.0

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.

Using the v3 Native Protocol

By default, the driver will attempt to use version 2 of the native protocol. To use version 3, you must explicitly set the ~.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.

Working with User-Defined Types

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 .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 udts for more details.

Customizing Encoders for Non-prepared Statements

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-~.Session basis through .Session.encoder:

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

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

Using Client-Side Protocol-Level Timestamps

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 ~.Cluster.protocol_version is set to 3 or higher, the driver will automatically use client-side timestamps with microsecond precision unless .Session.use_client_timestamp is changed to False. If a timestamp is specified within the CQL query, it will override the timestamp generated by the driver.

Upgrading to 2.0 from 1.x

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.

Using the v2 Native Protocol

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 ~.Cluster.protocol_version to 1:

from cassandra.cluster import Cluster

cluster = Cluster(protocol_version=1)

Automatic Query Paging

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

See query-paging for full details.

Protocol-Level Batch Statements

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 ~.query.BatchStatement for details and usage examples.

SASL-based Authentication

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

Lightweight Transactions

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

Calling Cluster.shutdown()

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

Deprecations

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

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

Dependency Changes

The following dependencies have officially been made optional:

• scales
• blist

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

• six