forked from apache/cassandra-python-driver
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathupgrade_guide.html
More file actions
316 lines (302 loc) · 20.7 KB
/
Copy pathupgrade_guide.html
File metadata and controls
316 lines (302 loc) · 20.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Upgrade Guide — Cassandra Driver 2.7.1 documentation</title>
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.7.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Cassandra Driver 2.7.1 documentation" href="../index.html" />
<link rel="up" title="Object Mapper" href="../object_mapper.html" />
<link rel="next" title="Models" href="models.html" />
<link rel="prev" title="Object Mapper" href="../object_mapper.html" />
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="models.html" title="Models"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../object_mapper.html" title="Object Mapper"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Cassandra Driver 2.7.1 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../object_mapper.html" accesskey="U">Object Mapper</a> »</li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Upgrade Guide</a><ul>
<li><a class="reference internal" href="#functional-changes">Functional Changes</a><ul>
<li><a class="reference internal" href="#list-prepend-reversing">List Prepend Reversing</a></li>
<li><a class="reference internal" href="#date-column-type">Date Column Type</a></li>
</ul>
</li>
<li><a class="reference internal" href="#remove-cqlengine">Remove cqlengine</a></li>
<li><a class="reference internal" href="#organization">Organization</a><ul>
<li><a class="reference internal" href="#imports">Imports</a></li>
<li><a class="reference internal" href="#package-level-aliases">Package-Level Aliases</a></li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
<li><a class="reference internal" href="#unicodemixin-consolidation">UnicodeMixin Consolidation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#api-deprecations">API Deprecations</a><ul>
<li><a class="reference internal" href="#float-double-overload">Float/Double Overload</a></li>
<li><a class="reference internal" href="#schema-management">Schema Management</a></li>
<li><a class="reference internal" href="#model-inheritance">Model Inheritance</a></li>
<li><a class="reference internal" href="#timeuuid-from-datetime">TimeUUID.from_datetime</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../object_mapper.html"
title="previous chapter">Object Mapper</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="models.html"
title="next chapter">Models</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/cqlengine/upgrade_guide.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="upgrade-guide">
<h1>Upgrade Guide<a class="headerlink" href="#upgrade-guide" title="Permalink to this headline">¶</a></h1>
<p>This is an overview of things that changed as the cqlengine project was merged into
cassandra-driver. While efforts were taken to preserve the API and most functionality exactly,
conversion to this package will still require certain minimal updates (namely, imports).</p>
<p><strong>THERE IS ONE FUNCTIONAL CHANGE</strong>, described in the first section below.</p>
<div class="section" id="functional-changes">
<h2>Functional Changes<a class="headerlink" href="#functional-changes" title="Permalink to this headline">¶</a></h2>
<div class="section" id="list-prepend-reversing">
<h3>List Prepend Reversing<a class="headerlink" href="#list-prepend-reversing" title="Permalink to this headline">¶</a></h3>
<p>Legacy cqlengine included a workaround for a Cassandra bug in which prepended list segments were
reversed (<a class="reference external" href="https://issues.apache.org/jira/browse/CASSANDRA-8733">CASSANDRA-8733</a>). As of
this integration, this workaround is removed. The first released integrated version emits
a warning when prepend is used. Subsequent versions will have this warning removed.</p>
</div>
<div class="section" id="date-column-type">
<h3>Date Column Type<a class="headerlink" href="#date-column-type" title="Permalink to this headline">¶</a></h3>
<p>The Date column type in legacy cqlengine used a <code class="docutils literal"><span class="pre">timestamp</span></code> CQL type and truncated the time.
Going forward, the <a class="reference internal" href="../api/cassandra/cqlengine/columns.html#cassandra.cqlengine.columns.Date" title="cassandra.cqlengine.columns.Date"><code class="xref py py-class docutils literal"><span class="pre">Date</span></code></a> type represents a <code class="docutils literal"><span class="pre">date</span></code> for Cassandra 2.2+
(<a class="reference external" href="https://datastax-oss.atlassian.net/browse/PYTHON-245">PYTHON-245</a>).
Users of the legacy functionality should convert models to use <a class="reference internal" href="../api/cassandra/cqlengine/columns.html#cassandra.cqlengine.columns.DateTime" title="cassandra.cqlengine.columns.DateTime"><code class="xref py py-class docutils literal"><span class="pre">DateTime</span></code></a> (which
uses <code class="docutils literal"><span class="pre">timestamp</span></code> internally), and use the build-in <code class="docutils literal"><span class="pre">datetime.date</span></code> for input values.</p>
</div>
</div>
<div class="section" id="remove-cqlengine">
<h2>Remove cqlengine<a class="headerlink" href="#remove-cqlengine" title="Permalink to this headline">¶</a></h2>
<p>To avoid confusion or mistakes using the legacy package in your application, it
is prudent to remove the cqlengine package when upgrading to the integrated version.</p>
<p>The driver setup script will warn if the legacy package is detected during install,
but it will not prevent side-by-side installation.</p>
</div>
<div class="section" id="organization">
<h2>Organization<a class="headerlink" href="#organization" title="Permalink to this headline">¶</a></h2>
<div class="section" id="imports">
<h3>Imports<a class="headerlink" href="#imports" title="Permalink to this headline">¶</a></h3>
<p>cqlengine is now integrated as a sub-package of the driver base package ‘cassandra’.
Upgrading will require adjusting imports to cqlengine. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">cqlengine</span> <span class="kn">import</span> <span class="n">columns</span>
</pre></div>
</div>
<p>is now:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">cassandra.cqlengine</span> <span class="kn">import</span> <span class="n">columns</span>
</pre></div>
</div>
</div>
<div class="section" id="package-level-aliases">
<h3>Package-Level Aliases<a class="headerlink" href="#package-level-aliases" title="Permalink to this headline">¶</a></h3>
<p>Legacy cqlengine defined a number of aliases at the package level, which became redundant
when the package was integrated for a driver. These have been removed in favor of absolute
imports, and referring to cannonical definitions. For example, <code class="docutils literal"><span class="pre">cqlengine.ONE</span></code> was an alias
of <code class="docutils literal"><span class="pre">cassandra.ConsistencyLevel.ONE</span></code>. In the integrated package, only the
<a class="reference internal" href="../api/cassandra.html#cassandra.ConsistencyLevel" title="cassandra.ConsistencyLevel"><code class="xref py py-class docutils literal"><span class="pre">cassandra.ConsistencyLevel</span></code></a> remains.</p>
<p>Additionally, submodule aliases are removed from cqlengine in favor of absolute imports.</p>
<p>These aliases are removed, and not deprecated because they should be straightforward to iron out
at module load time.</p>
</div>
<div class="section" id="exceptions">
<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
<p>The legacy cqlengine.exceptions module had a number of Exception classes that were variously
common to the package, or only used in specific modules. Common exceptions were relocated to
cqlengine, and specialized exceptions were placed in the module that raises them. Below is a
listing of updated locations:</p>
<table border="1" class="docutils">
<colgroup>
<col width="48%" />
<col width="52%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Exception class</th>
<th class="head">New module</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>CQLEngineException</td>
<td>cassandra.cqlengine</td>
</tr>
<tr class="row-odd"><td>ModelException</td>
<td>cassandra.cqlengine.models</td>
</tr>
<tr class="row-even"><td>ValidationError</td>
<td>cassandra.cqlengine</td>
</tr>
<tr class="row-odd"><td>UndefinedKeyspaceException</td>
<td>cassandra.cqlengine.connection</td>
</tr>
<tr class="row-even"><td>LWTException</td>
<td>cassandra.cqlengine.query</td>
</tr>
<tr class="row-odd"><td>IfNotExistsWithCounterColumn</td>
<td>cassandra.cqlengine.query</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="unicodemixin-consolidation">
<h3>UnicodeMixin Consolidation<a class="headerlink" href="#unicodemixin-consolidation" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">class</span> <span class="pre">UnicodeMixin</span></code> was defined in several cqlengine modules. This has been consolidated
to a single definition in the cqlengine package init file. This is not technically part of
the API, but noted here for completeness.</p>
</div>
</div>
<div class="section" id="api-deprecations">
<h2>API Deprecations<a class="headerlink" href="#api-deprecations" title="Permalink to this headline">¶</a></h2>
<p>This upgrade served as a good juncture to deprecate certain API features and invite users to upgrade
to new ones. The first released version does not change functionality – only introduces deprecation
warnings. Future releases will remove these features in favor of the alternatives.</p>
<div class="section" id="float-double-overload">
<h3>Float/Double Overload<a class="headerlink" href="#float-double-overload" title="Permalink to this headline">¶</a></h3>
<p>Previously there was no <code class="docutils literal"><span class="pre">Double</span></code> column type. Doubles were modeled by specifying <code class="docutils literal"><span class="pre">Float(double_precision=True)</span></code>.
This inititializer parameter is now deprecated. Applications should use <a class="reference internal" href="../api/cassandra/cqlengine/columns.html#cassandra.cqlengine.columns.Double" title="cassandra.cqlengine.columns.Double"><code class="xref py py-class docutils literal"><span class="pre">Double</span></code></a> for CQL <code class="docutils literal"><span class="pre">double</span></code>, and <a class="reference internal" href="../api/cassandra/cqlengine/columns.html#cassandra.cqlengine.columns.Float" title="cassandra.cqlengine.columns.Float"><code class="xref py py-class docutils literal"><span class="pre">Float</span></code></a>
for CQL <code class="docutils literal"><span class="pre">float</span></code>.</p>
</div>
<div class="section" id="schema-management">
<h3>Schema Management<a class="headerlink" href="#schema-management" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">cassandra.cqlengine.management.create_keyspace</span></code> is deprecated. Instead, use the new replication-strategy-specific
functions that accept explicit options for known strategies:</p>
<ul class="simple">
<li><a class="reference internal" href="../api/cassandra/cqlengine/management.html#cassandra.cqlengine.management.create_keyspace_simple" title="cassandra.cqlengine.management.create_keyspace_simple"><code class="xref py py-func docutils literal"><span class="pre">create_keyspace_simple()</span></code></a></li>
<li><a class="reference internal" href="../api/cassandra/cqlengine/management.html#cassandra.cqlengine.management.create_keyspace_network_topology" title="cassandra.cqlengine.management.create_keyspace_network_topology"><code class="xref py py-func docutils literal"><span class="pre">create_keyspace_network_topology()</span></code></a></li>
</ul>
<p><code class="docutils literal"><span class="pre">cassandra.cqlengine.management.delete_keyspace</span></code> is deprecated in favor of a new function, <a class="reference internal" href="../api/cassandra/cqlengine/management.html#cassandra.cqlengine.management.drop_keyspace" title="cassandra.cqlengine.management.drop_keyspace"><code class="xref py py-func docutils literal"><span class="pre">drop_keyspace()</span></code></a>. The
intent is simply to make the function match the CQL verb it invokes.</p>
</div>
<div class="section" id="model-inheritance">
<h3>Model Inheritance<a class="headerlink" href="#model-inheritance" title="Permalink to this headline">¶</a></h3>
<p>The names for class attributes controlling model inheritance are changing. Changes are as follows:</p>
<ul class="simple">
<li>Replace ‘polymorphic_key’ in the base class Column definition with <a class="reference internal" href="../api/cassandra/cqlengine/columns.html#cassandra.cqlengine.columns.Column.discriminator_column" title="cassandra.cqlengine.columns.Column.discriminator_column"><code class="xref py py-attr docutils literal"><span class="pre">discriminator_column</span></code></a></li>
<li>Replace the ‘__polymorphic_key__’ class attribute the derived classes with <a class="reference internal" href="../api/cassandra/cqlengine/models.html#cassandra.cqlengine.models.Model.__discriminator_value__" title="cassandra.cqlengine.models.Model.__discriminator_value__"><code class="xref py py-attr docutils literal"><span class="pre">__discriminator_value__</span></code></a></li>
</ul>
<p>The functionality is unchanged – the intent here is to make the names and language around these attributes more precise.
For now, the old names are just deprecated, and the mapper will emit warnings if they are used. The old names
will be removed in a future version.</p>
<p>The example below shows a simple translation:</p>
<p>Before:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Pet</span><span class="p">(</span><span class="n">Model</span><span class="p">):</span>
<span class="n">__table_name__</span> <span class="o">=</span> <span class="s">'pet'</span>
<span class="n">owner_id</span> <span class="o">=</span> <span class="n">UUID</span><span class="p">(</span><span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">pet_id</span> <span class="o">=</span> <span class="n">UUID</span><span class="p">(</span><span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">pet_type</span> <span class="o">=</span> <span class="n">Text</span><span class="p">(</span><span class="n">polymorphic_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">Text</span><span class="p">()</span>
<span class="k">class</span> <span class="nc">Cat</span><span class="p">(</span><span class="n">Pet</span><span class="p">):</span>
<span class="n">__polymorphic_key__</span> <span class="o">=</span> <span class="s">'cat'</span>
<span class="k">class</span> <span class="nc">Dog</span><span class="p">(</span><span class="n">Pet</span><span class="p">):</span>
<span class="n">__polymorphic_key__</span> <span class="o">=</span> <span class="s">'dog'</span>
</pre></div>
</div>
<p>After:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Pet</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
<span class="n">__table_name__</span> <span class="o">=</span> <span class="s">'pet'</span>
<span class="n">owner_id</span> <span class="o">=</span> <span class="n">UUID</span><span class="p">(</span><span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">pet_id</span> <span class="o">=</span> <span class="n">UUID</span><span class="p">(</span><span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">pet_type</span> <span class="o">=</span> <span class="n">Text</span><span class="p">(</span><span class="n">discriminator_column</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">Text</span><span class="p">()</span>
<span class="k">class</span> <span class="nc">Cat</span><span class="p">(</span><span class="n">Pet</span><span class="p">):</span>
<span class="n">__discriminator_value__</span> <span class="o">=</span> <span class="s">'cat'</span>
<span class="k">class</span> <span class="nc">Dog</span><span class="p">(</span><span class="n">Pet</span><span class="p">):</span>
<span class="n">__discriminator_value__</span> <span class="o">=</span> <span class="s">'dog'</span>
</pre></div>
</div>
</div>
<div class="section" id="timeuuid-from-datetime">
<h3>TimeUUID.from_datetime<a class="headerlink" href="#timeuuid-from-datetime" title="Permalink to this headline">¶</a></h3>
<p>This function is deprecated in favor of the core utility function <code class="xref py py-func docutils literal"><span class="pre">uuid_from_time()</span></code>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="models.html" title="Models"
>next</a> |</li>
<li class="right" >
<a href="../object_mapper.html" title="Object Mapper"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Cassandra Driver 2.7.1 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../object_mapper.html" >Object Mapper</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2014, DataStax.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.1.
</div>
</body>
</html>