<!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>
Column Insert/Update Defaults
—
SQLAlchemy 0.8 Documentation
</title>
<!-- begin iterate through SQLA + sphinx environment css_files -->
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
<link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
<!-- end iterate through SQLA + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.7',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<!-- begin iterate through sphinx environment script_files -->
<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>
<!-- end iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/detectmobile.js"></script>
<script type="text/javascript" src="../_static/init.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
<link rel="up" title="Schema Definition Language" href="schema.html" />
<link rel="next" title="Defining Constraints and Indexes" href="constraints.html" />
<link rel="prev" title="Reflecting Database Objects" href="reflection.html" />
<!-- end layout.mako headers -->
</head>
<body>
<div id="docs-container">
<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
<div id="docs-version-header">
Release: <span class="version-num">0.8.7</span> | Release Date: July 22, 2014
</div>
<h1>SQLAlchemy 0.8 Documentation</h1>
</div>
</div>
<div id="docs-body-container">
<div id="fixed-sidebar" class="withsidebar">
<div id="docs-sidebar-popout">
<h3><a href="../index.html">SQLAlchemy 0.8 Documentation</a></h3>
<p id="sidebar-paginate">
<a href="schema.html" title="Schema Definition Language">Up</a> |
<a href="reflection.html" title="Reflecting Database Objects">Prev</a> |
<a href="constraints.html" title="Defining Constraints and Indexes">Next</a>
</p>
<p id="sidebar-topnav">
<a href="../index.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="12" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<h3><a href="#">
Column Insert/Update Defaults
</a></h3>
<ul>
<li><a class="reference internal" href="#">Column Insert/Update Defaults</a><ul>
<li><a class="reference internal" href="#scalar-defaults">Scalar Defaults</a></li>
<li><a class="reference internal" href="#python-executed-functions">Python-Executed Functions</a><ul>
<li><a class="reference internal" href="#context-sensitive-default-functions">Context-Sensitive Default Functions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#sql-expressions">SQL Expressions</a></li>
<li><a class="reference internal" href="#server-side-defaults">Server Side Defaults</a></li>
<li><a class="reference internal" href="#triggered-columns">Triggered Columns</a></li>
<li><a class="reference internal" href="#defining-sequences">Defining Sequences</a></li>
<li><a class="reference internal" href="#default-objects-api">Default Objects API</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<span class="target" id="module-sqlalchemy.schema"><span id="metadata-defaults"></span><span id="metadata-defaults-toplevel"></span></span><div class="section" id="column-insert-update-defaults">
<h1>Column Insert/Update Defaults<a class="headerlink" href="#column-insert-update-defaults" title="Permalink to this headline">¶</a></h1>
<p>SQLAlchemy provides a very rich featureset regarding column level events which
take place during INSERT and UPDATE statements. Options include:</p>
<ul class="simple">
<li>Scalar values used as defaults during INSERT and UPDATE operations</li>
<li>Python functions which execute upon INSERT and UPDATE operations</li>
<li>SQL expressions which are embedded in INSERT statements (or in some cases execute beforehand)</li>
<li>SQL expressions which are embedded in UPDATE statements</li>
<li>Server side default values used during INSERT</li>
<li>Markers for server-side triggers used during UPDATE</li>
</ul>
<p>The general rule for all insert/update defaults is that they only take effect
if no value for a particular column is passed as an <tt class="docutils literal"><span class="pre">execute()</span></tt> parameter;
otherwise, the given value is used.</p>
<div class="section" id="scalar-defaults">
<h2>Scalar Defaults<a class="headerlink" href="#scalar-defaults" title="Permalink to this headline">¶</a></h2>
<p>The simplest kind of default is a scalar value used as the default value of a column:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Table</span><span class="p">(</span><span class="s">"mytable"</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">"somecolumn"</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">12</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Above, the value “12” will be bound as the column value during an INSERT if no
other value is supplied.</p>
<p>A scalar value may also be associated with an UPDATE statement, though this is
not very common (as UPDATE statements are usually looking for dynamic
defaults):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Table</span><span class="p">(</span><span class="s">"mytable"</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">"somecolumn"</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">onupdate</span><span class="o">=</span><span class="mi">25</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="python-executed-functions">
<h2>Python-Executed Functions<a class="headerlink" href="#python-executed-functions" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">default</span></tt> and <tt class="docutils literal"><span class="pre">onupdate</span></tt> keyword arguments also accept Python
functions. These functions are invoked at the time of insert or update if no
other value for that column is supplied, and the value returned is used for
the column’s value. Below illustrates a crude “sequence” that assigns an
incrementing counter to a primary key column:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># a function which counts upwards</span>
<span class="n">i</span> <span class="o">=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">mydefault</span><span class="p">():</span>
<span class="k">global</span> <span class="n">i</span>
<span class="n">i</span> <span class="o">+=</span> <span class="mi">1</span>
<span class="k">return</span> <span class="n">i</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">"mytable"</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'id'</span><span class="p">,</span> <span class="n">Integer</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">default</span><span class="o">=</span><span class="n">mydefault</span><span class="p">),</span>
<span class="p">)</span></pre></div>
</div>
<p>It should be noted that for real “incrementing sequence” behavior, the
built-in capabilities of the database should normally be used, which may
include sequence objects or other autoincrementing capabilities. For primary
key columns, SQLAlchemy will in most cases use these capabilities
automatically. See the API documentation for
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> including the <tt class="docutils literal"><span class="pre">autoincrement</span></tt> flag, as
well as the section on <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> later in this
chapter for background on standard primary key generation techniques.</p>
<p>To illustrate onupdate, we assign the Python <tt class="docutils literal"><span class="pre">datetime</span></tt> function <tt class="docutils literal"><span class="pre">now</span></tt> to
the <tt class="docutils literal"><span class="pre">onupdate</span></tt> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">"mytable"</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'id'</span><span class="p">,</span> <span class="n">Integer</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="c"># define 'last_updated' to be populated with datetime.now()</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'last_updated'</span><span class="p">,</span> <span class="n">DateTime</span><span class="p">,</span> <span class="n">onupdate</span><span class="o">=</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">),</span>
<span class="p">)</span></pre></div>
</div>
<p>When an update statement executes and no value is passed for <tt class="docutils literal"><span class="pre">last_updated</span></tt>,
the <tt class="docutils literal"><span class="pre">datetime.datetime.now()</span></tt> Python function is executed and its return
value used as the value for <tt class="docutils literal"><span class="pre">last_updated</span></tt>. Notice that we provide <tt class="docutils literal"><span class="pre">now</span></tt>
as the function itself without calling it (i.e. there are no parenthesis
following) - SQLAlchemy will execute the function at the time the statement
executes.</p>
<div class="section" id="context-sensitive-default-functions">
<h3>Context-Sensitive Default Functions<a class="headerlink" href="#context-sensitive-default-functions" title="Permalink to this headline">¶</a></h3>
<p>The Python functions used by <tt class="docutils literal"><span class="pre">default</span></tt> and <tt class="docutils literal"><span class="pre">onupdate</span></tt> may also make use of
the current statement’s context in order to determine a value. The <cite>context</cite>
of a statement is an internal SQLAlchemy object which contains all information
about the statement being executed, including its source expression, the
parameters associated with it and the cursor. The typical use case for this
context with regards to default generation is to have access to the other
values being inserted or updated on the row. To access the context, provide a
function that accepts a single <tt class="docutils literal"><span class="pre">context</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">mydefault</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="k">return</span> <span class="n">context</span><span class="o">.</span><span class="n">current_parameters</span><span class="p">[</span><span class="s">'counter'</span><span class="p">]</span> <span class="o">+</span> <span class="mi">12</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'mytable'</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'counter'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'counter_plus_twelve'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">mydefault</span><span class="p">,</span> <span class="n">onupdate</span><span class="o">=</span><span class="n">mydefault</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Above we illustrate a default function which will execute for all INSERT and
UPDATE statements where a value for <tt class="docutils literal"><span class="pre">counter_plus_twelve</span></tt> was otherwise not
provided, and the value will be that of whatever value is present in the
execution for the <tt class="docutils literal"><span class="pre">counter</span></tt> column, plus the number 12.</p>
<p>While the context object passed to the default function has many attributes,
the <tt class="docutils literal"><span class="pre">current_parameters</span></tt> member is a special member provided only during the
execution of a default function for the purposes of deriving defaults from its
existing values. For a single statement that is executing many sets of bind
parameters, the user-defined function is called for each set of parameters,
and <tt class="docutils literal"><span class="pre">current_parameters</span></tt> will be provided with each individual parameter set
for each execution.</p>
</div>
</div>
<div class="section" id="sql-expressions">
<h2>SQL Expressions<a class="headerlink" href="#sql-expressions" title="Permalink to this headline">¶</a></h2>
<p>The “default” and “onupdate” keywords may also be passed SQL expressions,
including select statements or direct function calls:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">"mytable"</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'id'</span><span class="p">,</span> <span class="n">Integer</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="c"># define 'create_date' to default to now()</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'create_date'</span><span class="p">,</span> <span class="n">DateTime</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">func</span><span class="o">.</span><span class="n">now</span><span class="p">()),</span>
<span class="c"># define 'key' to pull its default from the 'keyvalues' table</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'key'</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">20</span><span class="p">),</span> <span class="n">default</span><span class="o">=</span><span class="n">keyvalues</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="n">keyvalues</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">type</span><span class="o">=</span><span class="s">'type1'</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="mi">1</span><span class="p">)),</span>
<span class="c"># define 'last_modified' to use the current_timestamp SQL function on update</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'last_modified'</span><span class="p">,</span> <span class="n">DateTime</span><span class="p">,</span> <span class="n">onupdate</span><span class="o">=</span><span class="n">func</span><span class="o">.</span><span class="n">utc_timestamp</span><span class="p">())</span>
<span class="p">)</span></pre></div>
</div>
<p>Above, the <tt class="docutils literal"><span class="pre">create_date</span></tt> column will be populated with the result of the
<tt class="docutils literal"><span class="pre">now()</span></tt> SQL function (which, depending on backend, compiles into <tt class="docutils literal"><span class="pre">NOW()</span></tt>
or <tt class="docutils literal"><span class="pre">CURRENT_TIMESTAMP</span></tt> in most cases) during an INSERT statement, and the
<tt class="docutils literal"><span class="pre">key</span></tt> column with the result of a SELECT subquery from another table. The
<tt class="docutils literal"><span class="pre">last_modified</span></tt> column will be populated with the value of
<tt class="docutils literal"><span class="pre">UTC_TIMESTAMP()</span></tt>, a function specific to MySQL, when an UPDATE statement is
emitted for this table.</p>
<p>Note that when using <tt class="docutils literal"><span class="pre">func</span></tt> functions, unlike when using Python <cite>datetime</cite>
functions we <em>do</em> call the function, i.e. with parenthesis “()” - this is
because what we want in this case is the return value of the function, which
is the SQL expression construct that will be rendered into the INSERT or
UPDATE statement.</p>
<p>The above SQL functions are usually executed “inline” with the INSERT or
UPDATE statement being executed, meaning, a single statement is executed which
embeds the given expressions or subqueries within the VALUES or SET clause of
the statement. Although in some cases, the function is “pre-executed” in a
SELECT statement of its own beforehand. This happens when all of the following
is true:</p>
<ul class="simple">
<li>the column is a primary key column</li>
<li>the database dialect does not support a usable <tt class="docutils literal"><span class="pre">cursor.lastrowid</span></tt> accessor
(or equivalent); this currently includes PostgreSQL, Oracle, and Firebird, as
well as some MySQL dialects.</li>
<li>the dialect does not support the “RETURNING” clause or similar, or the
<tt class="docutils literal"><span class="pre">implicit_returning</span></tt> flag is set to <tt class="docutils literal"><span class="pre">False</span></tt> for the dialect. Dialects
which support RETURNING currently include Postgresql, Oracle, Firebird, and
MS-SQL.</li>
<li>the statement is a single execution, i.e. only supplies one set of
parameters and doesn’t use “executemany” behavior</li>
<li>the <tt class="docutils literal"><span class="pre">inline=True</span></tt> flag is not set on the
<a class="reference internal" href="dml.html#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert()</span></tt></a> or
<a class="reference internal" href="dml.html#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update()</span></tt></a> construct, and the statement has
not defined an explicit <cite>returning()</cite> clause.</li>
</ul>
<p>Whether or not the default generation clause “pre-executes” is not something
that normally needs to be considered, unless it is being addressed for
performance reasons.</p>
<p>When the statement is executed with a single set of parameters (that is, it is
not an “executemany” style execution), the returned
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a> will contain a collection
accessible via <tt class="docutils literal"><span class="pre">result.postfetch_cols()</span></tt> which contains a list of all
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> objects which had an inline-executed
default. Similarly, all parameters which were bound to the statement,
including all Python and SQL expressions which were pre-executed, are present
in the <tt class="docutils literal"><span class="pre">last_inserted_params()</span></tt> or <tt class="docutils literal"><span class="pre">last_updated_params()</span></tt> collections on
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a>. The <tt class="docutils literal"><span class="pre">inserted_primary_key</span></tt>
collection contains a list of primary key values for the row inserted (a list
so that single-column and composite-column primary keys are represented in the
same format).</p>
</div>
<div class="section" id="server-side-defaults">
<h2>Server Side Defaults<a class="headerlink" href="#server-side-defaults" title="Permalink to this headline">¶</a></h2>
<p>A variant on the SQL expression default is the <tt class="docutils literal"><span class="pre">server_default</span></tt>, which gets
placed in the CREATE TABLE statement during a <tt class="docutils literal"><span class="pre">create()</span></tt> operation:</p>
<div class="highlight-python+sql"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'test'</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'abc'</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">20</span><span class="p">),</span> <span class="n">server_default</span><span class="o">=</span><span class="s">'abc'</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'created_at'</span><span class="p">,</span> <span class="n">DateTime</span><span class="p">,</span> <span class="n">server_default</span><span class="o">=</span><span class="n">text</span><span class="p">(</span><span class="s">"sysdate"</span><span class="p">))</span>
<span class="p">)</span></pre></div>
</div>
<p>A create call for the above table will produce:</p>
<div class="highlight-python"><pre>CREATE TABLE test (
abc varchar(20) default 'abc',
created_at datetime default sysdate
)</pre>
</div>
<p>The behavior of <tt class="docutils literal"><span class="pre">server_default</span></tt> is similar to that of a regular SQL
default; if it’s placed on a primary key column for a database which doesn’t
have a way to “postfetch” the ID, and the statement is not “inlined”, the SQL
expression is pre-executed; otherwise, SQLAlchemy lets the default fire off on
the database side normally.</p>
</div>
<div class="section" id="triggered-columns">
<span id="id1"></span><h2>Triggered Columns<a class="headerlink" href="#triggered-columns" title="Permalink to this headline">¶</a></h2>
<p>Columns with values set by a database trigger or other external process may be
called out using <a class="reference internal" href="#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><tt class="xref py py-class docutils literal"><span class="pre">FetchedValue</span></tt></a> as a marker:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'test'</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'abc'</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">20</span><span class="p">),</span> <span class="n">server_default</span><span class="o">=</span><span class="n">FetchedValue</span><span class="p">()),</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'def'</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">20</span><span class="p">),</span> <span class="n">server_onupdate</span><span class="o">=</span><span class="n">FetchedValue</span><span class="p">())</span>
<span class="p">)</span></pre></div>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.8.0b2,0.7.10: </span>The <tt class="docutils literal"><span class="pre">for_update</span></tt> argument on <a class="reference internal" href="#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><tt class="xref py py-class docutils literal"><span class="pre">FetchedValue</span></tt></a> is set automatically
when specified as the <tt class="docutils literal"><span class="pre">server_onupdate</span></tt> argument. If using an older version,
specify the onupdate above as <tt class="docutils literal"><span class="pre">server_onupdate=FetchedValue(for_update=True)</span></tt>.</p>
</div>
<p>These markers do not emit a “default” clause when the table is created,
however they do set the same internal flags as a static <tt class="docutils literal"><span class="pre">server_default</span></tt>
clause, providing hints to higher-level tools that a “post-fetch” of these
rows should be performed after an insert or update.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>It’s generally not appropriate to use <a class="reference internal" href="#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><tt class="xref py py-class docutils literal"><span class="pre">FetchedValue</span></tt></a> in
conjunction with a primary key column, particularly when using the
ORM or any other scenario where the <a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.inserted_primary_key" title="sqlalchemy.engine.ResultProxy.inserted_primary_key"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.inserted_primary_key</span></tt></a>
attribute is required. This is becaue the “post-fetch” operation requires
that the primary key value already be available, so that the
row can be selected on its primary key.</p>
<p>For a server-generated primary key value, all databases provide special
accessors or other techniques in order to acquire the “last inserted
primary key” column of a table. These mechanisms aren’t affected by the presence
of <a class="reference internal" href="#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><tt class="xref py py-class docutils literal"><span class="pre">FetchedValue</span></tt></a>. For special situations where triggers are
used to generate primary key values, and the database in use does not
support the <tt class="docutils literal"><span class="pre">RETURNING</span></tt> clause, it may be necessary to forego the usage
of the trigger and instead apply the SQL expression or function as a
“pre execute” expression:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'test'</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'abc'</span><span class="p">,</span> <span class="n">MyType</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">func</span><span class="o">.</span><span class="n">generate_new_value</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="p">)</span></pre></div>
</div>
<p class="last">Where above, when <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.insert" title="sqlalchemy.schema.Table.insert"><tt class="xref py py-meth docutils literal"><span class="pre">Table.insert()</span></tt></a> is used,
the <tt class="docutils literal"><span class="pre">func.generate_new_value()</span></tt> expression will be pre-executed
in the context of a scalar <tt class="docutils literal"><span class="pre">SELECT</span></tt> statement, and the new value will
be applied to the subsequent <tt class="docutils literal"><span class="pre">INSERT</span></tt>, while at the same time being
made available to the <a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.inserted_primary_key" title="sqlalchemy.engine.ResultProxy.inserted_primary_key"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.inserted_primary_key</span></tt></a>
attribute.</p>
</div>
</div>
<div class="section" id="defining-sequences">
<h2>Defining Sequences<a class="headerlink" href="#defining-sequences" title="Permalink to this headline">¶</a></h2>
<p>SQLAlchemy represents database sequences using the
<a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> object, which is considered to be a
special case of “column default”. It only has an effect on databases which
have explicit support for sequences, which currently includes Postgresql,
Oracle, and Firebird. The <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> object is
otherwise ignored.</p>
<p>The <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> may be placed on any column as a
“default” generator to be used during INSERT operations, and can also be
configured to fire off during UPDATE operations if desired. It is most
commonly used in conjunction with a single integer primary key column:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">"cartitems"</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">"cart_id"</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">Sequence</span><span class="p">(</span><span class="s">'cart_id_seq'</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">Column</span><span class="p">(</span><span class="s">"description"</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">40</span><span class="p">)),</span>
<span class="n">Column</span><span class="p">(</span><span class="s">"createdate"</span><span class="p">,</span> <span class="n">DateTime</span><span class="p">())</span>
<span class="p">)</span></pre></div>
</div>
<p>Where above, the table “cartitems” is associated with a sequence named
“cart_id_seq”. When INSERT statements take place for “cartitems”, and no value
is passed for the “cart_id” column, the “cart_id_seq” sequence will be used to
generate a value.</p>
<p>When the <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> is associated with a table,
CREATE and DROP statements issued for that table will also issue CREATE/DROP
for the sequence object as well, thus “bundling” the sequence object with its
parent table.</p>
<p>The <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> object also implements special
functionality to accommodate Postgresql’s SERIAL datatype. The SERIAL type in
PG automatically generates a sequence that is used implicitly during inserts.
This means that if a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> object defines a
<a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> on its primary key column so that it
works with Oracle and Firebird, the <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> would
get in the way of the “implicit” sequence that PG would normally use. For this
use case, add the flag <tt class="docutils literal"><span class="pre">optional=True</span></tt> to the
<a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> object - this indicates that the
<a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> should only be used if the database
provides no other option for generating primary key identifiers.</p>
<p>The <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> object also has the ability to be
executed standalone like a SQL expression, which has the effect of calling its
“next value” function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">seq</span> <span class="o">=</span> <span class="n">Sequence</span><span class="p">(</span><span class="s">'some_sequence'</span><span class="p">)</span>
<span class="n">nextid</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">seq</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="default-objects-api">
<h2>Default Objects API<a class="headerlink" href="#default-objects-api" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.schema.ColumnDefault">
<em class="property">class </em><tt class="descclassname">sqlalchemy.schema.</tt><tt class="descname">ColumnDefault</tt><big>(</big><em>arg</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.ColumnDefault" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.schema.DefaultGenerator" title="sqlalchemy.schema.DefaultGenerator"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.schema.DefaultGenerator</span></tt></a></p>
<p>A plain default value on a column.</p>
<p>This could correspond to a constant, a callable function,
or a SQL clause.</p>
<p><a class="reference internal" href="#sqlalchemy.schema.ColumnDefault" title="sqlalchemy.schema.ColumnDefault"><tt class="xref py py-class docutils literal"><span class="pre">ColumnDefault</span></tt></a> is generated automatically
whenever the <tt class="docutils literal"><span class="pre">default</span></tt>, <tt class="docutils literal"><span class="pre">onupdate</span></tt> arguments of
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> are used. A <a class="reference internal" href="#sqlalchemy.schema.ColumnDefault" title="sqlalchemy.schema.ColumnDefault"><tt class="xref py py-class docutils literal"><span class="pre">ColumnDefault</span></tt></a>
can be passed positionally as well.</p>
<p>For example, the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Column</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span></pre></div>
</div>
<p>Is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Column</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">ColumnDefault</span><span class="p">(</span><span class="mi">50</span><span class="p">))</span></pre></div>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.schema.DefaultClause">
<em class="property">class </em><tt class="descclassname">sqlalchemy.schema.</tt><tt class="descname">DefaultClause</tt><big>(</big><em>arg</em>, <em>for_update=False</em>, <em>_reflected=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.DefaultClause" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.schema.FetchedValue</span></tt></a></p>
<p>A DDL-specified DEFAULT column value.</p>
<p><a class="reference internal" href="#sqlalchemy.schema.DefaultClause" title="sqlalchemy.schema.DefaultClause"><tt class="xref py py-class docutils literal"><span class="pre">DefaultClause</span></tt></a> is a <a class="reference internal" href="#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><tt class="xref py py-class docutils literal"><span class="pre">FetchedValue</span></tt></a>
that also generates a “DEFAULT” clause when
“CREATE TABLE” is emitted.</p>
<p><a class="reference internal" href="#sqlalchemy.schema.DefaultClause" title="sqlalchemy.schema.DefaultClause"><tt class="xref py py-class docutils literal"><span class="pre">DefaultClause</span></tt></a> is generated automatically
whenever the <tt class="docutils literal"><span class="pre">server_default</span></tt>, <tt class="docutils literal"><span class="pre">server_onupdate</span></tt> arguments of
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> are used. A <a class="reference internal" href="#sqlalchemy.schema.DefaultClause" title="sqlalchemy.schema.DefaultClause"><tt class="xref py py-class docutils literal"><span class="pre">DefaultClause</span></tt></a>
can be passed positionally as well.</p>
<p>For example, the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Column</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">server_default</span><span class="o">=</span><span class="s">"50"</span><span class="p">)</span></pre></div>
</div>
<p>Is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Column</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">DefaultClause</span><span class="p">(</span><span class="s">"50"</span><span class="p">))</span></pre></div>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.schema.DefaultGenerator">
<em class="property">class </em><tt class="descclassname">sqlalchemy.schema.</tt><tt class="descname">DefaultGenerator</tt><big>(</big><em>for_update=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.DefaultGenerator" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.schema._NotAColumnExpr</span></tt>, <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.schema.SchemaItem</span></tt></a></p>
<p>Base class for column <em>default</em> values.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.schema.FetchedValue">
<em class="property">class </em><tt class="descclassname">sqlalchemy.schema.</tt><tt class="descname">FetchedValue</tt><big>(</big><em>for_update=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.FetchedValue" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.schema._NotAColumnExpr</span></tt>, <a class="reference internal" href="events.html#sqlalchemy.events.SchemaEventTarget" title="sqlalchemy.events.SchemaEventTarget"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.events.SchemaEventTarget</span></tt></a></p>
<p>A marker for a transparent database-side default.</p>
<p>Use <a class="reference internal" href="#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><tt class="xref py py-class docutils literal"><span class="pre">FetchedValue</span></tt></a> when the database is configured
to provide some automatic default for a column.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Column</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">FetchedValue</span><span class="p">())</span></pre></div>
</div>
<p>Would indicate that some trigger or default generator
will create a new value for the <tt class="docutils literal"><span class="pre">foo</span></tt> column during an
INSERT.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#triggered-columns"><em>Triggered Columns</em></a></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.schema.PassiveDefault">
<em class="property">class </em><tt class="descclassname">sqlalchemy.schema.</tt><tt class="descname">PassiveDefault</tt><big>(</big><em>*arg</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.PassiveDefault" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.schema.DefaultClause" title="sqlalchemy.schema.DefaultClause"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.schema.DefaultClause</span></tt></a></p>
<p>A DDL-specified DEFAULT column value.</p>
<div class="deprecated">
<p><span>Deprecated since version 0.6: </span><a class="reference internal" href="#sqlalchemy.schema.PassiveDefault" title="sqlalchemy.schema.PassiveDefault"><tt class="xref py py-class docutils literal"><span class="pre">PassiveDefault</span></tt></a> is deprecated.
Use <a class="reference internal" href="#sqlalchemy.schema.DefaultClause" title="sqlalchemy.schema.DefaultClause"><tt class="xref py py-class docutils literal"><span class="pre">DefaultClause</span></tt></a>.</p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.schema.Sequence">
<em class="property">class </em><tt class="descclassname">sqlalchemy.schema.</tt><tt class="descname">Sequence</tt><big>(</big><em>name</em>, <em>start=None</em>, <em>increment=None</em>, <em>schema=None</em>, <em>optional=False</em>, <em>quote=None</em>, <em>metadata=None</em>, <em>quote_schema=None</em>, <em>for_update=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.Sequence" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.schema.DefaultGenerator" title="sqlalchemy.schema.DefaultGenerator"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.schema.DefaultGenerator</span></tt></a></p>
<p>Represents a named database sequence.</p>
<p>The <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> object represents the name and configurational
parameters of a database sequence. It also represents
a construct that can be “executed” by a SQLAlchemy <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>
or <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>, rendering the appropriate “next value” function
for the target database and returning a result.</p>
<p>The <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> is typically associated with a primary key column:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">some_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'some_table'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">Sequence</span><span class="p">(</span><span class="s">'some_table_seq'</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="p">)</span></pre></div>
</div>
<p>When CREATE TABLE is emitted for the above <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>, if the
target platform supports sequences, a CREATE SEQUENCE statement will
be emitted as well. For platforms that don’t support sequences,
the <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> construct is ignored.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="ddl.html#sqlalchemy.schema.CreateSequence" title="sqlalchemy.schema.CreateSequence"><tt class="xref py py-class docutils literal"><span class="pre">CreateSequence</span></tt></a></p>
<p class="last"><a class="reference internal" href="ddl.html#sqlalchemy.schema.DropSequence" title="sqlalchemy.schema.DropSequence"><tt class="xref py py-class docutils literal"><span class="pre">DropSequence</span></tt></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.schema.Sequence.__init__">
<tt class="descname">__init__</tt><big>(</big><em>name</em>, <em>start=None</em>, <em>increment=None</em>, <em>schema=None</em>, <em>optional=False</em>, <em>quote=None</em>, <em>metadata=None</em>, <em>quote_schema=None</em>, <em>for_update=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.Sequence.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.schema.Sequence.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.schema.Sequence.params.name">¶</a> – The name of the sequence.</li>
<li><span class="target" id="sqlalchemy.schema.Sequence.params.start"></span><strong>start</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.schema.Sequence.params.start">¶</a> – the starting index of the sequence. This value is
used when the CREATE SEQUENCE command is emitted to the database
as the value of the “START WITH” clause. If <tt class="docutils literal"><span class="pre">None</span></tt>, the
clause is omitted, which on most platforms indicates a starting
value of 1.</li>
<li><span class="target" id="sqlalchemy.schema.Sequence.params.increment"></span><strong>increment</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.schema.Sequence.params.increment">¶</a> – the increment value of the sequence. This
value is used when the CREATE SEQUENCE command is emitted to
the database as the value of the “INCREMENT BY” clause. If <tt class="docutils literal"><span class="pre">None</span></tt>,
the clause is omitted, which on most platforms indicates an
increment of 1.</li>
<li><span class="target" id="sqlalchemy.schema.Sequence.params.schema"></span><strong>schema</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.schema.Sequence.params.schema">¶</a> – Optional schema name for the sequence, if located
in a schema other than the default.</li>
<li><span class="target" id="sqlalchemy.schema.Sequence.params.optional"></span><strong>optional</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.schema.Sequence.params.optional">¶</a> – boolean value, when <tt class="docutils literal"><span class="pre">True</span></tt>, indicates that this
<a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> object only needs to be explicitly generated
on backends that don’t provide another way to generate primary
key identifiers. Currently, it essentially means, “don’t create
this sequence on the Postgresql backend, where the SERIAL keyword
creates a sequence for us automatically”.</li>
<li><span class="target" id="sqlalchemy.schema.Sequence.params.quote"></span><strong>quote</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.schema.Sequence.params.quote">¶</a> – boolean value, when <tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt>, explicitly
forces quoting of the schema name on or off. When left at its
default of <tt class="docutils literal"><span class="pre">None</span></tt>, normal quoting rules based on casing and reserved
words take place.</li>
<li><span class="target" id="sqlalchemy.schema.Sequence.params.metadata"></span><strong>metadata</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.schema.Sequence.params.metadata">¶</a> – <p>optional <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> object which will be
associated with this <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a>. A <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a>
that is associated with a <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> gains access to the
<tt class="docutils literal"><span class="pre">bind</span></tt> of that <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a>, meaning the
<a class="reference internal" href="#sqlalchemy.schema.Sequence.create" title="sqlalchemy.schema.Sequence.create"><tt class="xref py py-meth docutils literal"><span class="pre">Sequence.create()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.schema.Sequence.drop" title="sqlalchemy.schema.Sequence.drop"><tt class="xref py py-meth docutils literal"><span class="pre">Sequence.drop()</span></tt></a> methods will
make usage of that engine automatically.</p>
<div class="versionchanged">
<p><span>Changed in version 0.7: </span>Additionally, the appropriate CREATE SEQUENCE/
DROP SEQUENCE DDL commands will be emitted corresponding to this
<a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> when <a class="reference internal" href="metadata.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> and
<a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData.drop_all" title="sqlalchemy.schema.MetaData.drop_all"><tt class="xref py py-meth docutils literal"><span class="pre">MetaData.drop_all()</span></tt></a> are invoked.</p>
</div>
<p>Note that when a <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> is applied to a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>,
the <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> is automatically associated with the
<a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> object of that column’s parent <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>,
when that association is made. The <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> will then
be subject to automatic CREATE SEQUENCE/DROP SEQUENCE corresponding
to when the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> object itself is created or dropped,
rather than that of the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> object overall.</p>
</li>
<li><span class="target" id="sqlalchemy.schema.Sequence.params.for_update"></span><strong>for_update</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.schema.Sequence.params.for_update">¶</a> – Indicates this <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a>, when associated
with a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>, should be invoked for UPDATE statements
on that column’s table, rather than for INSERT statements, when
no value is otherwise present for that column in the statement.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.schema.Sequence.create">
<tt class="descname">create</tt><big>(</big><em>bind=None</em>, <em>checkfirst=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.Sequence.create" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates this sequence in the database.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.schema.Sequence.drop">
<tt class="descname">drop</tt><big>(</big><em>bind=None</em>, <em>checkfirst=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.schema.Sequence.drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Drops this sequence from the database.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.schema.Sequence.next_value">
<tt class="descname">next_value</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.schema.Sequence.next_value" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="functions.html#sqlalchemy.sql.functions.next_value" title="sqlalchemy.sql.functions.next_value"><tt class="xref py py-class docutils literal"><span class="pre">next_value</span></tt></a> function element
which will render the appropriate increment function
for this <a class="reference internal" href="#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><tt class="xref py py-class docutils literal"><span class="pre">Sequence</span></tt></a> within any SQL expression.</p>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links">
Previous:
<a href="reflection.html" title="previous chapter">Reflecting Database Objects</a>
Next:
<a href="constraints.html" title="next chapter">Defining Constraints and Indexes</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
</div>
</div>
</div>
</body>
</html>
