openstack/deb-python-cassandra-driver
Code Issues Proposed changes
Files
8f847245fa244a2e23de34a6a29ba0e6e121eb0c
deb-python-cassandra-driver/docs/upgrading.rst
Tyler Hobbs 66a5cca5ab Mention Cluster.shutdown() in the upgrading guide
2014-05-28 14:53:52 -05:00

3.2 KiB
Raw Blame History

Upgrading

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