Skip to content

Commit 2bbe76e

Browse files
aholmbergaholmberg
committed
Add an upgrade guide for cqlengine
1 parent e1dbefc commit 2bbe76e

File tree

2 files changed

+140
-0
lines changed

2 files changed

+140
-0
lines changed

‎docs/cqlengine/upgrade_guide.rst‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
========================
2+
Upgrade Guide
3+
========================
4+
5+
This is an overview of things that changed as the cqlengine project was merged into
6+
cassandra-driver. While efforts were taken to preserve the API and most functionality exactly,
7+
conversion to this package will still require certain minimal updates (namely, imports).
8+
9+
**THERE IS ONE FUNCTIONAL CHANGE**, described in the first section below.
10+
11+
Functional Change
12+
=================
13+
Legacy cqlengine included a workaround for a Cassandra bug in which prepended list segments were
14+
reversed (`CASSANDRA-8733 <https://issues.apache.org/jira/browse/CASSANDRA-8733>`_). As of
15+
this integration, this workaround is removed. The first released integrated version emits
16+
a warning when prepend is used. Subsequent versions will have this warning removed.
17+
18+
Remove cqlengine
19+
================
20+
To avoid confusion or mistakes using the legacy package in your application, it
21+
is prudent to remove the cqlengine package when upgrading to the integrated version.
22+
23+
The driver setup script will warn if the legacy package is detected during install,
24+
but it will not prevent side-by-side installation.
25+
26+
Organization
27+
============
28+
Imports
29+
-------
30+
cqlengine is now integrated as a sub-package of the driver base package 'cassandra'.
31+
Upgrading will require adjusting imports to cqlengine. For example::
32+
33+
from cqlengine import columns
34+
35+
is now::
36+
37+
from cassandra.cqlengine import columns
38+
39+
Package-Level Aliases
40+
---------------------
41+
Legacy cqlengine defined a number of aliases at the package level, which became redundant
42+
when the package was integrated for a driver. These have been removed in favor of absolute
43+
imports, and referring to cannonical definitions. For example, ``cqlengine.ONE`` was an alias
44+
of ``cassandra.ConsistencyLevel.ONE``. In the integrated package, only the
45+
:class:`cassandra.ConsistencyLevel` remains.
46+
47+
Additionally, submodule aliases are removed from cqlengine in favor of absolute imports.
48+
49+
These aliases are removed, and not deprecated because they should be straightforward to iron out
50+
at module load time.
51+
52+
Exceptions
53+
----------
54+
The legacy cqlengine.exceptions module had a number of Exception classes that were variously
55+
common to the package, or only used in specific modules. Common exceptions were relocated to
56+
cqlengine, and specialized exceptions were placed in the module that raises them. Below is a
57+
listing of updated locations:
58+
59+
============================ ==========
60+
Exception class New module
61+
============================ ==========
62+
CQLEngineException cassandra.cqlengine
63+
ModelException cassandra.cqlengine.models
64+
ValidationError cassandra.cqlengine
65+
UndefinedKeyspaceException cassandra.cqlengine.connection
66+
LWTException cassandra.cqlengine.query
67+
IfNotExistsWithCounterColumn cassandra.cqlengine.query
68+
============================ ==========
69+
70+
UnicodeMixin Consolidation
71+
--------------------------
72+
``class UnicodeMixin`` was defined in several cqlengine modules. This has been consolidated
73+
to a single definition in the cqlengine package init file. This is not technically part of
74+
the API, but noted here for completeness.
75+
76+
API Deprecations
77+
================
78+
This upgrade served as a good juncture to deprecate certain API features and invite users to upgrade
79+
to new ones. The first released version does not change functionality -- only introduces deprecation
80+
warnings. Future releases will remove these features in favor of the alternatives.
81+
82+
Schema Management
83+
-----------------
84+
``cassandra.cqlengine.management.create_keyspace`` is deprecated. Instead, use the new replication-strategy-specific
85+
functions that accept explicit options for known strategies:
86+
87+
- :func:`~.create_keyspace_simple`
88+
- :func:`~.create_keyspace_network_topology`
89+
90+
``cassandra.cqlengine.management.delete_keyspace`` is deprecated in favor of a new function, :func:`~.drop_keyspace`. The
91+
intent is simply to make the function match the CQL verb it invokes.
92+
93+
Model Inheritance
94+
-----------------
95+
The names for class attributes controlling model inheritance are changing. Changes are as follows:
96+
97+
- Replace 'polymorphic_key' in the base class Column definition with :attr:`~.discriminator_column`
98+
- Replace the '__polymporphic_key__' class attribute the derived classes with :attr:`~.__discriminator_value__`
99+
100+
The functionality is unchanged -- the intent here is to make the names and language around these attributes more precise.
101+
For now, the old names are just deprecated, and the mapper will emit warnings if they are used. The old names
102+
will be removed in a future version.
103+
104+
The example below shows a simple translation:
105+
106+
Before::
107+
108+
class Pet(Model):
109+
__table_name__ = 'pet'
110+
owner_id = UUID(primary_key=True)
111+
pet_id = UUID(primary_key=True)
112+
pet_type = Text(polymorphic_key=True)
113+
name = Text()
114+
115+
class Cat(Pet):
116+
__polymorphic_key__ = 'cat'
117+
118+
class Dog(Pet):
119+
__polymorphic_key__ = 'dog'
120+
121+
After::
122+
123+
class Pet(models.Model):
124+
__table_name__ = 'pet'
125+
owner_id = UUID(primary_key=True)
126+
pet_id = UUID(primary_key=True)
127+
pet_type = Text(discriminator_column=True)
128+
name = Text()
129+
130+
class Cat(Pet):
131+
__discriminator_value__ = 'cat'
132+
133+
class Dog(Pet):
134+
__discriminator_value__ = 'dog'
135+
136+

‎docs/object_mapper.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ cqlengine is the Cassandra CQL 3 Object Mapper packaged with this driver
77

88
Contents
99
--------
10+
:doc:`cqlengine/upgrade_guide`
11+
For migrating projects from legacy cqlengine, to the integrated product
12+
1013
:doc:`cqlengine/models`
1114
Examples defining models, and mapping them to tables
1215

@@ -27,6 +30,7 @@ Contents
2730
.. toctree::
2831
:hidden:
2932

33+
cqlengine/upgrade_guide
3034
cqlengine/models
3135
cqlengine/queryset
3236
cqlengine/batches

0 commit comments

Comments
 (0)