Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu

Caution

You're viewing documentation for a previous version of Scylla Python Driver. Switch to the latest stable version.

Scylla Python Driver Upgrading

Upgrading¶

Upgrading from dse-driver¶

Since 3.21.0, scylla-driver fully supports DataStax products. dse-driver and dse-graph users should now migrate to scylla-driver to benefit from latest bug fixes and new features. The upgrade to this new unified driver version is straightforward with no major API changes.

Installation¶

Only the scylla-driver package should be installed. dse-driver and dse-graph are not required anymore:

pip install scylla-driver

If you need the Graph Fluent API (features provided by dse-graph):

pip install scylla-driver[graph]

See Installation for more details.

Import from the cassandra module¶

There is no dse module, so you should import from the cassandra module. You need to change only the first module of your import statements, not the submodules.

from dse.cluster import Cluster, EXEC_PROFILE_GRAPH_DEFAULT
from dse.auth import PlainTextAuthProvider
from dse.policies import WhiteListRoundRobinPolicy

# becomes

from cassandra.cluster import Cluster, EXEC_PROFILE_GRAPH_DEFAULT
from cassandra.auth import PlainTextAuthProvider
from cassandra.policies import WhiteListRoundRobinPolicy

Also note that the cassandra.hosts module doesn’t exist in scylla-driver. This module is named cassandra.pool.

dse-graph¶

dse-graph features are now built into scylla-driver. The only change you need to do is your import statements:

from dse_graph import ..
from dse_graph.query import ..

# becomes

from cassandra.datastax.graph.fluent import ..
from cassandra.datastax.graph.fluent.query import ..

See fluent.

Session.execute and Session.execute_async API¶

Although it is not common to use this API with positional arguments, it is important to be aware that the host and execute_as parameters have had their positional order swapped. This is only because execute_as was added in dse-driver before host.

See Session.execute().

Deprecations¶

These changes are optional, but recommended:

  • Importing from cassandra.graph is deprecated. Consider importing from cassandra.datastax.graph.

  • Use DefaultLoadBalancingPolicy instead of DSELoadBalancingPolicy.

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¶

PYTHON-368

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.

results = session.execute("SELECT * FROM system.local")
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:

results = session.execute("SELECT * FROM system.local")
row_list = list(results)

For backward compatibility, ResultSet supports indexing. When accessed at an index, a ~.ResultSet object will materialize all its pages:

results = session.execute("SELECT * FROM system.local")
first_result = results[0]  # materializes results, fetching all pages

This can send requests and load (possibly large) results into memory, so ~.ResultSet will log a warning on implicit materialization.

Trace information is not attached to executed Statements¶

PYTHON-318

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¶

PYTHON-178

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¶

PYTHON-385

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 of Index.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¶

PYTHON-292

  • ResponseFuture.result timeout parameter is removed, use Session.execute timeout instead (031ebb0)

  • Cluster.refresh_schema removed, use Cluster.refresh_*_metadata instead (419fcdf)

  • Cluster.submit_schema_refresh removed (574266d)

  • cqltypes time/date functions removed, use util entry points instead (bb984ee)

  • decoder module removed (e16a073)

  • TableMetadata.keyspace attribute replaced with keyspace_name (cc94073)

  • cqlengine.columns.TimeUUID.from_datetime removed, use util variant instead (96489cc)

  • cqlengine.columns.Float(double_precision) parameter removed, use columns.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 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 User Defined Types 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 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 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 Paging Large Queries 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 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 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

PREVIOUS
Scylla Specific Features
NEXT
Execution Profiles
  • 3.24.8
    • 3.25.4
    • 3.24.8
    • 3.22.3
    • 3.21.0
  • API Documentation
    • cassandra - Exceptions and Enums
    • cassandra.cluster - Clusters and Sessions
    • cassandra.policies - Load balancing and Failure Handling Policies
    • cassandra.auth - Authentication
    • cassandra.graph - Graph Statements, Options, and Row Factories
    • cassandra.metadata - Schema and Ring Topology
    • cassandra.metrics - Performance Metrics
    • cassandra.query - Prepared Statements, Batch Statements, Tracing, and Row Factories
    • cassandra.pool - Hosts and Connection Pools
    • cassandra.protocol - Protocol Features
    • cassandra.encoder - Encoders for non-prepared Statements
    • cassandra.decoder - Data Return Formats
    • cassandra.concurrent - Utilities for Concurrent Statement Execution
    • cassandra.connection - Low Level Connection Info
    • cassandra.util - Utilities
    • cassandra.timestamps - Timestamp Generation
    • cassandra.io.asyncioreactor - asyncio Event Loop
    • cassandra.io.asyncorereactor - asyncore Event Loop
    • cassandra.io.eventletreactor - eventlet-compatible Connection
    • cassandra.io.libevreactor - libev Event Loop
    • cassandra.io.geventreactor - gevent-compatible Event Loop
    • cassandra.io.twistedreactor - Twisted Event Loop
    • cassandra.cqlengine.models - Table models for object mapping
    • cassandra.cqlengine.columns - Column types for object mapping models
    • cassandra.cqlengine.query - Query and filter model objects
    • cassandra.cqlengine.connection - Connection management for cqlengine
    • cassandra.cqlengine.management - Schema management for cqlengine
    • cassandra.cqlengine.usertype - Model classes for User Defined Types
    • cassandra.datastax.graph - Graph Statements, Options, and Row Factories
    • cassandra.datastax.graph.fluent
    • cassandra.datastax.graph.fluent.query
    • cassandra.datastax.graph.fluent.predicates
  • Installation
  • Getting Started
  • Scylla Specific Features
  • Upgrading
  • Execution Profiles
  • Performance Notes
  • Paging Large Queries
  • Lightweight Transactions (Compare-and-set)
  • Security
  • User Defined Types
  • Object Mapper
    • Upgrade Guide
    • Models
    • Making Queries
    • Batch Queries
    • Connections
    • Third party integrations
    • Frequently Asked Questions
  • Working with Dates and Times
  • Scylla Cloud
  • Frequently Asked Questions
  • Create an issue
  • Edit this page

On this page

  • Upgrading
    • Upgrading from dse-driver
      • Installation
      • Import from the cassandra module
      • dse-graph
      • Session.execute and Session.execute_async API
      • Deprecations
    • Upgrading to 3.0
      • Default consistency is now LOCAL_ONE
      • Execution API Updates
        • Result return normalization
        • Trace information is not attached to executed Statements
        • Binding named parameters now ignores extra names
      • blist removed as soft dependency
      • Metadata API Updates
      • Several deprecated features are removed
    • Upgrading to 2.1 from 2.0
      • Using the v3 Native Protocol
      • Working with User-Defined Types
      • Customizing Encoders for Non-prepared Statements
      • Using Client-Side Protocol-Level Timestamps
    • Upgrading to 2.0 from 1.x
      • Using the v2 Native Protocol
      • Automatic Query Paging
      • Protocol-Level Batch Statements
      • SASL-based Authentication
      • Lightweight Transactions
      • Calling Cluster.shutdown()
      • Deprecations
      • Dependency Changes
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© ScyllaDB 2021 and © DataStax 2013-2017
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2