← Back to branch summary

~ubuntu-branches/debian/jessie/sqlalchemy/jessie

« back to all changes in this revision

Viewing changes to doc/orm/tutorial.html

  • Committer: Package Import Robot
  • Author(s): Piotr Ożarowski, Jakub Wilk, Piotr Ożarowski
  • Date: 2013-07-06 20:53:52 UTC
  • mfrom: (1.4.23) (16.1.17 experimental)
  • Revision ID: package-import@ubuntu.com-20130706205352-ryppl1eto3illd79
Tags: 0.8.2-1
[ Jakub Wilk ]
* Use canonical URIs for Vcs-* fields.

[ Piotr Ożarowski ]
* New upstream release
* Upload to unstable
* Build depend on python3-all instead of -dev, extensions are not built for
  Python 3.X 

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/orm/tutorial.html
10
10
    
11
11
                Object Relational Tutorial
12
12
             — 
13
 
    SQLAlchemy 0.7 Documentation
 
13
    SQLAlchemy 0.8 Documentation
14
14
 
15
15
        </title>
16
16
        
20
20
    <script type="text/javascript">
21
21
      var DOCUMENTATION_OPTIONS = {
22
22
          URL_ROOT:    '../',
23
 
          VERSION:     '0.7.9',
 
23
          VERSION:     '0.8.2',
24
24
          COLLAPSE_MODINDEX: false,
25
25
          FILE_SUFFIX: '.html'
26
26
      };
32
32
    <link rel="index" title="Index" href="../genindex.html" />
33
33
    <link rel="search" title="Search" href="../search.html" />
34
34
        <link rel="copyright" title="Copyright" href="../copyright.html" />
35
 
    <link rel="top" title="SQLAlchemy 0.7 Documentation" href="../index.html" />
 
35
    <link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
36
36
        <link rel="up" title="SQLAlchemy ORM" href="index.html" />
37
37
        <link rel="next" title="Mapper Configuration" href="mapper_config.html" />
38
38
        <link rel="prev" title="SQLAlchemy ORM" href="index.html" />
55
55
 
56
56
 
57
57
<div id="docs-header">
58
 
    <h1>SQLAlchemy 0.7 Documentation</h1>
 
58
    <h1>SQLAlchemy 0.8 Documentation</h1>
59
59
 
60
60
    <div id="docs-search">
61
61
    Search:
67
67
    </div>
68
68
 
69
69
    <div id="docs-version-header">
70
 
        Release: <span class="version-num">0.7.9</span> | Release Date: October 1, 2012
 
70
        Release: <span class="version-num">0.8.2</span> | Release Date: July 3, 2013
71
71
 
72
72
 
73
73
    </div>
93
93
    </div>
94
94
 
95
95
    <div id="docs-navigation-banner">
96
 
        <a href="../index.html">SQLAlchemy 0.7 Documentation</a>
 
96
        <a href="../index.html">SQLAlchemy 0.8 Documentation</a>
97
97
                » <a href="index.html" title="SQLAlchemy ORM">SQLAlchemy ORM</a>
98
98
        » 
99
99
                Object Relational Tutorial
210
210
following text represents the expected return value.</p>
211
211
<div class="section" id="version-check">
212
212
<h2>Version Check<a class="headerlink" href="#version-check" title="Permalink to this headline">¶</a></h2>
213
 
<p>A quick check to verify that we are on at least <strong>version 0.7</strong> of SQLAlchemy:</p>
 
213
<p>A quick check to verify that we are on at least <strong>version 0.8</strong> of SQLAlchemy:</p>
214
214
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">sqlalchemy</span>
215
215
<span class="gp">&gt;&gt;&gt; </span><span class="n">sqlalchemy</span><span class="o">.</span><span class="n">__version__</span> 
216
 
<span class="go">0.7.0</span></pre></div>
 
216
<span class="go">0.8.0</span></pre></div>
217
217
</div>
218
218
</div>
219
219
<div class="section" id="connecting">
229
229
and want less output generated, set it to <tt class="docutils literal"><span class="pre">False</span></tt>. This tutorial will format
230
230
the SQL behind a popup window so it doesn&#8217;t get in our way; just click the
231
231
&#8220;SQL&#8221; links to see what&#8217;s being generated.</p>
232
 
<p>The return value of <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal"><span class="pre">create_engine()</span></tt></a> is an instance of <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, and it represents
 
232
<p>The return value of <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal"><span class="pre">create_engine()</span></tt></a> is an instance of <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, and it represents
233
233
the core interface to the database, adapted through a <strong>dialect</strong> that handles the details
234
234
of the database and DBAPI in use.  In this case the SQLite dialect will interpret instructions
235
235
to the Python built-in <tt class="docutils literal"><span class="pre">sqlite3</span></tt> module.</p>
236
 
<p>The <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> has not actually tried to connect to the database yet; that happens
 
236
<p>The <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> has not actually tried to connect to the database yet; that happens
237
237
only the first time it is asked to perform a task against the database.   We can illustrate
238
238
this by asking it to perform a simple SELECT statement:</p>
239
239
<div class="highlight-python+sql"><div class="highlight"><pre><a href='#' class='sql_link'>sql</a><span class="o">&gt;&gt;&gt;</span> <span class="n">engine</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;select 1&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
240
240
<div class='popup_sql'>select 1
241
241
()</div><span class="mi">1</span></pre></div>
242
242
</div>
243
 
<p>As the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine.execute" title="sqlalchemy.engine.base.Engine.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Engine.execute()</span></tt></a> method is called, the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> establishes a connection to the
 
243
<p>As the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine.execute" title="sqlalchemy.engine.Engine.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Engine.execute()</span></tt></a> method is called, the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> establishes a connection to the
244
244
SQLite database, which is then used to emit the SQL.   The connection is then returned to an internal
245
245
connection pool where it will be reused on subsequent statement executions.  While we illustrate direct usage of the
246
 
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> here, this isn&#8217;t typically necessary when using the ORM, where the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>,
 
246
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> here, this isn&#8217;t typically necessary when using the ORM, where the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>,
247
247
once created, is used behind the scenes by the ORM as we&#8217;ll see shortly.</p>
248
248
</div>
249
249
<div class="section" id="declare-a-mapping">
342
342
new tables that have yet to be created in our SQLite database, so one helpful feature
343
343
the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> object offers is the ability to issue CREATE TABLE statements
344
344
to the database for all tables that don&#8217;t yet exist.   We illustrate this
345
 
by calling the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.MetaData.create_all" title="sqlalchemy.schema.MetaData.create_all"><tt class="xref py py-meth docutils literal"><span class="pre">MetaData.create_all()</span></tt></a> method, passing in our <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>
 
345
by calling the <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.MetaData.create_all" title="sqlalchemy.schema.MetaData.create_all"><tt class="xref py py-meth docutils literal"><span class="pre">MetaData.create_all()</span></tt></a> method, passing in our <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>
346
346
as a source of database connectivity.  We will see that special commands are
347
347
first emitted to check for the presence of the <tt class="docutils literal"><span class="pre">users</span></tt> table, and following that
348
348
the actual <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt> statement:</p>
418
418
column we declared in our mapping.  By
419
419
default, the ORM creates class attributes for all columns present
420
420
in the table being mapped.   These class attributes exist as
421
 
<a class="reference external" href="http://docs.python.org/howto/descriptor.html">Python descriptors</a>, and
 
421
<a class="reference internal" href="../glossary.html#term-descriptors"><em class="xref std std-term">descriptors</em></a>, and
422
422
define <strong>instrumentation</strong> for the mapped class. The
423
423
functionality of this instrumentation includes the ability to fire on change
424
424
events, track modifications, and to automatically load new data from the database when
459
459
<span class="gp">&gt;&gt;&gt; </span><span class="n">Session</span> <span class="o">=</span> <span class="n">sessionmaker</span><span class="p">(</span><span class="n">bind</span><span class="o">=</span><span class="n">engine</span><span class="p">)</span></pre></div>
460
460
</div>
461
461
<p>In the case where your application does not yet have an
462
 
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> when you define your module-level
 
462
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> when you define your module-level
463
463
objects, just set it up like this:</p>
464
464
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Session</span> <span class="o">=</span> <span class="n">sessionmaker</span><span class="p">()</span></pre></div>
465
465
</div>
466
466
<p>Later, when you create your engine with <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal"><span class="pre">create_engine()</span></tt></a>,
467
467
connect it to the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> using
468
 
<tt class="xref py py-meth docutils literal"><span class="pre">configure()</span></tt>:</p>
 
468
<a class="reference internal" href="session.html#sqlalchemy.orm.session.sessionmaker.configure" title="sqlalchemy.orm.session.sessionmaker.configure"><tt class="xref py py-meth docutils literal"><span class="pre">configure()</span></tt></a>:</p>
469
469
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Session</span><span class="o">.</span><span class="n">configure</span><span class="p">(</span><span class="n">bind</span><span class="o">=</span><span class="n">engine</span><span class="p">)</span>  <span class="c"># once engine is available</span></pre></div>
470
470
</div>
471
471
<p>This custom-made <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> class will create
472
472
new <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> objects which are bound to our
473
473
database. Other transactional characteristics may be defined when calling
474
 
<a class="reference internal" href="session.html#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal"><span class="pre">sessionmaker()</span></tt></a> as well; these are described in a later
 
474
<tt class="xref py py-func docutils literal"><span class="pre">sessionmaker()</span></tt> as well; these are described in a later
475
475
chapter. Then, whenever you need to have a conversation with the database, you
476
476
instantiate a <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>:</p>
477
477
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">session</span> <span class="o">=</span> <span class="n">Session</span><span class="p">()</span></pre></div>
478
478
</div>
479
479
<p>The above <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> is associated with our
480
 
SQLite-enabled <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, but it hasn&#8217;t opened any connections yet. When it&#8217;s first
 
480
SQLite-enabled <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, but it hasn&#8217;t opened any connections yet. When it&#8217;s first
481
481
used, it retrieves a connection from a pool of connections maintained by the
482
 
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, and holds onto it until we commit all changes and/or close the
 
482
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, and holds onto it until we commit all changes and/or close the
483
483
session object.</p>
484
484
<div class="topic">
485
485
<p class="topic-title first">Session Creational Patterns</p>
701
701
<span class="n">fred</span> <span class="n">Fred</span> <span class="n">Flinstone</span></pre></div>
702
702
</div>
703
703
<p>The tuples returned by <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> are <em>named</em>
704
 
tuples, and can be treated much like an ordinary Python object. The names are
 
704
tuples, supplied by the <a class="reference internal" href="query.html#sqlalchemy.util.KeyedTuple" title="sqlalchemy.util.KeyedTuple"><tt class="xref py py-class docutils literal"><span class="pre">KeyedTuple</span></tt></a> class, and can be treated much like an
 
705
ordinary Python object. The names are
705
706
the same as the attribute&#8217;s name for an attribute, and the class name for a
706
707
class:</p>
707
708
<div class="highlight-python+sql"><div class="highlight"><pre><a href='#' class='sql_link'>sql</a><span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">():</span> 
717
718
<span class="o">&lt;</span><span class="n">User</span><span class="p">(</span><span class="s">&#39;fred&#39;</span><span class="p">,</span><span class="s">&#39;Fred Flinstone&#39;</span><span class="p">,</span> <span class="s">&#39;blah&#39;</span><span class="p">)</span><span class="o">&gt;</span> <span class="n">fred</span></pre></div>
718
719
</div>
719
720
<p>You can control the names of individual column expressions using the
720
 
<a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression._CompareMixin.label" title="sqlalchemy.sql.expression._CompareMixin.label"><tt class="xref py py-meth docutils literal"><span class="pre">label()</span></tt></a> construct, which is available from
 
721
<tt class="xref py py-meth docutils literal"><span class="pre">label()</span></tt> construct, which is available from
721
722
any <a class="reference internal" href="../core/expression_api.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>-derived object, as well as any class attribute which
722
723
is mapped to one (such as <tt class="docutils literal"><span class="pre">User.name</span></tt>):</p>
723
724
<div class="highlight-python+sql"><div class="highlight"><pre><a href='#' class='sql_link'>sql</a><span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">label</span><span class="p">(</span><span class="s">&#39;name_label&#39;</span><span class="p">))</span><span class="o">.</span><span class="n">all</span><span class="p">():</span> 
731
732
</div>
732
733
<p>The name given to a full entity such as <tt class="docutils literal"><span class="pre">User</span></tt>, assuming that multiple
733
734
entities are present in the call to <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><tt class="xref py py-meth docutils literal"><span class="pre">query()</span></tt></a>, can be controlled using
734
 
<a class="reference internal" href="query.html#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><tt class="xref py py-class docutils literal"><span class="pre">aliased</span></tt></a> :</p>
 
735
<tt class="xref py py-class docutils literal"><span class="pre">aliased</span></tt> :</p>
735
736
<div class="highlight-python+sql"><div class="highlight"><pre><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">aliased</span>
736
737
<span class="o">&gt;&gt;&gt;</span> <span class="n">user_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">&#39;user_alias&#39;</span><span class="p">)</span>
737
738
 
1689
1690
deleted. SQLAlchemy doesn&#8217;t assume that deletes cascade, you have to tell it
1690
1691
to do so.</p>
1691
1692
<div class="section" id="configuring-delete-delete-orphan-cascade">
1692
 
<h3>Configuring delete/delete-orphan Cascade<a class="headerlink" href="#configuring-delete-delete-orphan-cascade" title="Permalink to this headline">¶</a></h3>
 
1693
<span id="tutorial-delete-cascade"></span><h3>Configuring delete/delete-orphan Cascade<a class="headerlink" href="#configuring-delete-delete-orphan-cascade" title="Permalink to this headline">¶</a></h3>
1693
1694
<p>We will configure <strong>cascade</strong> options on the <tt class="docutils literal"><span class="pre">User.addresses</span></tt> relationship
1694
1695
to change the behavior. While SQLAlchemy allows you to add new attributes and
1695
1696
relationships to mappings at any point in time, in this case the existing
2009
2010
        <a href="mapper_config.html" title="next chapter">Mapper Configuration</a>
2010
2011
 
2011
2012
    <div id="docs-copyright">
2012
 
        &copy; <a href="../copyright.html">Copyright</a> 2007-2012, the SQLAlchemy authors and contributors.
 
2013
        &copy; <a href="../copyright.html">Copyright</a> 2007-2013, the SQLAlchemy authors and contributors.
2013
2014
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
2014
2015
    </div>
2015
2016
</div>