184 lines
6.2 KiB
ReStructuredText
184 lines
6.2 KiB
ReStructuredText
Upgrading
|
|
=========
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
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 :attr:`~.Cluster.protocol_version`:
|
|
|
|
.. code-block:: python
|
|
|
|
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 :meth:`.Cluster.register_user_type`:
|
|
|
|
.. code-block:: python
|
|
|
|
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.
|
|
|
|
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-:class:`~.Session`
|
|
basis through :attr:`.Session.encoder`:
|
|
|
|
.. code-block:: python
|
|
|
|
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.
|
|
|
|
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 :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.
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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 :ref:`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 <http://cassandra.apache.org/doc/cql3/CQL.html#batchStmt>`_.
|
|
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.
|
|
|
|
SASL-based Authentication
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
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
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
`Lightweight transactions <http://www.datastax.com/dev/blog/lightweight-transactions-in-cassandra-2-0>`_ 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.
|
|
|
|
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 :meth:`.Cluster.shutdown()`
|
|
on your :class:`~.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 :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`
|
|
|
|
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``
|