12 KiB
Upgrading
Upgrading to 3.0
Version 3.0 of the DataStax Python driver for Apache Cassandra adds support for Cassandra 3.0 while maintaining support for previously supported versions. In addition to substantial internal rework, there are several updates to the API that integrators will need to consider:
Default consistency is now
LOCAL_ONE
Previous value was ONE
. The new value is introduced to
mesh with the default DC-aware load balancing policy and to match other
drivers.
Execution API Updates
Result return normalization
Previously results would be returned as a list
of rows
for result rows up to fetch_size
, and
PagedResult
afterward. This could break application code
that assumed one type and got another.
Now, all results are returned as an iterable ~.ResultSet
.
The preferred way to consume results of unknown size is to iterate through them, letting automatic paging occur as they are consumed.
= session.execute("SELECT * FROM system.local")
results for row in results:
process(row)
If the expected size of the results is known, it is still possible to materialize a list using the iterator:
= session.execute("SELECT * FROM system.local")
results = list(results) row_list
For backward compatability, ~.ResultSet
supports indexing. If the result is
paged, all pages will be materialized. A warning will be logged if a
paged query is implicitly materialized.
Trace information is not attached to executed Statements
Previously trace data was attached to Statements if tracing was enabled. This could lead to confusion if the same statement was used for multiple executions.
Now, trace data is associated with the ResponseFuture
and ResultSet
returned for each query:
.ResponseFuture.get_query_trace()
.ResponseFuture.get_all_query_traces()
.ResultSet.get_query_trace()
.ResultSet.get_all_query_traces()
Binding named parameters now ignores extra names
Previously, .BoundStatement.bind()
would raise if a mapping was
passed with extra names not found in the prepared statement.
Behavior in 3.0+ is to ignore extra names.
blist removed as soft dependency
Previously the driver had a soft dependency on
blist sortedset
, using that where available and using an
internal fallback where possible.
Now, the driver never chooses the blist
variant, instead
returning the internal .util.SortedSet
for all set
results.
The class implements all standard set operations, so no integration code
should need to change unless it explicitly checks for
sortedset
type.
Metadata API Updates
PYTHON-276, PYTHON-408, PYTHON-400, PYTHON-422
Cassandra 3.0 brought a substantial overhaul to the internal schema metadata representation. This version of the driver supports that metadata in addition to the legacy version. Doing so also brought some changes to the metadata model.
The present API is documented: cassandra.metadata
. Changes highlighted below:
- All types are now exposed as CQL types instead of types derived from the internal server implementation
- Some metadata attributes have changed names to match current
nomenclature (for example,
.Index.kind
in place ofIndex.type
). - Some metadata attributes removed
TableMetadata.keyspace
reference replaced with.TableMetadata.keyspace_name
ColumnMetadata.index
is removed table- and keyspace-level mappings are still maintained
Several deprecated features are removed
ResponseFuture.result
timeout parameter is removed, useSession.execute
timeout instead (031ebb0)Cluster.refresh_schema
removed, useCluster.refresh_*_metadata
instead (419fcdf)Cluster.submit_schema_refresh
removed (574266d)cqltypes
time/date functions removed, useutil
entry points instead (bb984ee)decoder
module removed (e16a073)TableMetadata.keyspace
attribute replaced withkeyspace_name
(cc94073)cqlengine.columns.TimeUUID.from_datetime
removed, useutil
variant instead (96489cc)cqlengine.columns.Float(double_precision)
parameter removed, usecolumns.Double
instead (a2d3a98)cqlengine
keyspace management functions are removed in favor of the strategy-specific entry points (4bd5909)cqlengine.Model.__polymorphic_*__
attributes removed, use__discriminator*
attributes instead (9d98c8e)cqlengine.statements
will no longer warn about list list prepend behavior (79efe97)
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(protocol_version=3) cluster
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
'mykeyspace', 'address', Address) cluster.register_user_type(
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 = cluster.connect()
session tuple] = session.encoder.cql_encode_tuple session.encoder.mapping[
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(protocol_version=2) cluster
When working with Cassandra 1.2, you will need to explicitly set the
~.Cluster.protocol_version
to 1:
from cassandra.cluster import Cluster
= Cluster(protocol_version=1) cluster
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 tocassandra.query.tuple_factory
cassandra.decoder.named_tuple_factory
has moved tocassandra.query.named_tuple_factory
cassandra.decoder.dict_factory
has moved tocassandra.query.dict_factory
cassandra.decoder.ordered_dict_factory
has moved tocassandra.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