^^&&^^

Edit File: autogenerate.html

<!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>Autogeneration &mdash; Alembic 0.8.3 documentation</title>
 
 <link rel="stylesheet" href="../_static/nature_override.css" type="text/css" />
 <link rel="stylesheet" href="../_static/pygments.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" />
 
 <script type="text/javascript">
 var DOCUMENTATION_OPTIONS = {
 URL_ROOT: '../',
 VERSION: '0.8.3',
 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="Alembic 0.8.3 documentation" href="../index.html" />
 <link rel="up" title="API Details" href="index.html" />
 <link rel="next" title="Script Directory" href="script.html" />
 <link rel="prev" title="Operation Directives" href="operations.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="script.html" title="Script Directory"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="operations.html" title="Operation Directives"
 accesskey="P">previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="../index.html">Alembic 0.8.3 documentation</a> &raquo;</li>
 <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">API Details</a> &raquo;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <div class="section" id="autogeneration">
<h1>Autogeneration<a class="headerlink" href="#autogeneration" title="Permalink to this headline">¶</a></h1>
<div class="admonition note">
Note
this section discusses the internal API of Alembic
as regards the autogeneration feature of the <code class="docutils literal">alembic revision</code>
command.
This section is only useful for developers who wish to extend the
capabilities of Alembic. For general documentation on the autogenerate
feature, please see <a class="reference internal" href="../autogenerate.html">Auto Generating Migrations</a>.
</div>
The autogeneration system has a wide degree of public API, including
the following areas:
<ol class="arabic simple">
<li>The ability to do a &#8220;diff&#8221; of a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a> object against
a database, and receive a data structure back. This structure
is available either as a rudimentary list of changes, or as
a <a class="reference internal" href="../ops.html#alembic.operations.MigrateOperation" title="alembic.operations.MigrateOperation"><code class="xref py py-class docutils literal">MigrateOperation</code></a> structure.</li>
<li>The ability to alter how the <code class="docutils literal">alembic revision</code> command generates
revision scripts, including support for multiple revision scripts
generated in one pass.</li>
<li>The ability to add new operation directives to autogeneration, including
custom schema/model comparison functions and revision script rendering.</li>
</ol>
<div class="section" id="getting-diffs">
<h2>Getting Diffs<a class="headerlink" href="#getting-diffs" title="Permalink to this headline">¶</a></h2>
The simplest API autogenerate provides is the &#8220;schema comparison&#8221; API;
these are simple functions that will run all registered &#8220;comparison&#8221; functions
between a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a> object and a database
backend to produce a structure showing how they differ. The two
functions provided are <a class="reference internal" href="#alembic.autogenerate.compare_metadata" title="alembic.autogenerate.compare_metadata"><code class="xref py py-func docutils literal">compare_metadata()</code></a>, which is more of the
&#8220;legacy&#8221; function that produces diff tuples, and <a class="reference internal" href="#alembic.autogenerate.produce_migrations" title="alembic.autogenerate.produce_migrations"><code class="xref py py-func docutils literal">produce_migrations()</code></a>,
which produces a structure consisting of operation directives detailed in
<a class="reference internal" href="operations.html#alembic-operations-toplevel">Operation Directives</a>.
<dl class="function">
<dt id="alembic.autogenerate.compare_metadata">
<code class="descclassname">alembic.autogenerate.</code><code class="descname">compare_metadata</code>(context, metadata)<a class="headerlink" href="#alembic.autogenerate.compare_metadata" title="Permalink to this definition">¶</a></dt>
<dd>Compare a database schema to that given in a
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a> instance.
The database connection is presented in the context
of a <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> object, which
provides database connectivity as well as optional
comparison functions to use for datatypes and
server defaults - see the &#8220;autogenerate&#8221; arguments
at <a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">EnvironmentContext.configure()</code></a>
for details on these.
The return format is a list of &#8220;diff&#8221; directives,
each representing individual differences:
<div class="highlight-python"><div class="highlight"><pre>from alembic.migration import MigrationContext
from alembic.autogenerate import compare_metadata
from sqlalchemy.schema import SchemaItem
from sqlalchemy.types import TypeEngine
from sqlalchemy import (create_engine, MetaData, Column,
 Integer, String, Table)
import pprint

engine = create_engine(&quot;sqlite://&quot;)

engine.execute(&#39;&#39;&#39;
 create table foo (
 id integer not null primary key,
 old_data varchar,
 x integer
 )&#39;&#39;&#39;)

engine.execute(&#39;&#39;&#39;
 create table bar (
 data varchar
 )&#39;&#39;&#39;)

metadata = MetaData()
Table(&#39;foo&#39;, metadata,
 Column(&#39;id&#39;, Integer, primary_key=True),
 Column(&#39;data&#39;, Integer),
 Column(&#39;x&#39;, Integer, nullable=False)
)
Table(&#39;bat&#39;, metadata,
 Column(&#39;info&#39;, String)
)

mc = MigrationContext.configure(engine.connect())

diff = compare_metadata(mc, metadata)
pprint.pprint(diff, indent=2, width=20)
</pre></div>
</div>
Output:
<div class="highlight-python"><div class="highlight"><pre>[ ( &#39;add_table&#39;,
 Table(&#39;bat&#39;, MetaData(bind=None),
 Column(&#39;info&#39;, String(), table=&lt;bat&gt;), schema=None)),
 ( &#39;remove_table&#39;,
 Table(u&#39;bar&#39;, MetaData(bind=None),
 Column(u&#39;data&#39;, VARCHAR(), table=&lt;bar&gt;), schema=None)),
 ( &#39;add_column&#39;,
 None,
 &#39;foo&#39;,
 Column(&#39;data&#39;, Integer(), table=&lt;foo&gt;)),
 ( &#39;remove_column&#39;,
 None,
 &#39;foo&#39;,
 Column(u&#39;old_data&#39;, VARCHAR(), table=None)),
 [ ( &#39;modify_nullable&#39;,
 None,
 &#39;foo&#39;,
 u&#39;x&#39;,
 { &#39;existing_server_default&#39;: None,
 &#39;existing_type&#39;: INTEGER()},
 True,
 False)]]
</pre></div>
</div>
<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>context<a class="paramlink headerlink reference internal" href="#alembic.autogenerate.compare_metadata.params.context">¶</a> &#8211; a <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
instance.</li>
<li>metadata<a class="paramlink headerlink reference internal" href="#alembic.autogenerate.compare_metadata.params.metadata">¶</a> &#8211; a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a>
instance.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
See also
<a class="reference internal" href="#alembic.autogenerate.produce_migrations" title="alembic.autogenerate.produce_migrations"><code class="xref py py-func docutils literal">produce_migrations()</code></a> - produces a <a class="reference internal" href="operations.html#alembic.operations.ops.MigrationScript" title="alembic.operations.ops.MigrationScript"><code class="xref py py-class docutils literal">MigrationScript</code></a>
structure based on metadata comparison.
</div>
</dd></dl>

<dl class="function">
<dt id="alembic.autogenerate.produce_migrations">
<code class="descclassname">alembic.autogenerate.</code><code class="descname">produce_migrations</code>(context, metadata)<a class="headerlink" href="#alembic.autogenerate.produce_migrations" title="Permalink to this definition">¶</a></dt>
<dd>Produce a <a class="reference internal" href="operations.html#alembic.operations.ops.MigrationScript" title="alembic.operations.ops.MigrationScript"><code class="xref py py-class docutils literal">MigrationScript</code></a> structure based on schema
comparison.
This function does essentially what <a class="reference internal" href="#alembic.autogenerate.compare_metadata" title="alembic.autogenerate.compare_metadata"><code class="xref py py-func docutils literal">compare_metadata()</code></a> does,
but then runs the resulting list of diffs to produce the full
<a class="reference internal" href="operations.html#alembic.operations.ops.MigrationScript" title="alembic.operations.ops.MigrationScript"><code class="xref py py-class docutils literal">MigrationScript</code></a> object. For an example of what this looks like,
see the example in <a class="reference internal" href="#customizing-revision">Customizing Revision Generation</a>.
<div class="versionadded">
New in version 0.8.0.
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="#alembic.autogenerate.compare_metadata" title="alembic.autogenerate.compare_metadata"><code class="xref py py-func docutils literal">compare_metadata()</code></a> - returns more fundamental &#8220;diff&#8221;
data from comparing a schema.
</div>
</dd></dl>

</div>
<div class="section" id="customizing-revision-generation">
<h2>Customizing Revision Generation<a class="headerlink" href="#customizing-revision-generation" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
New in version 0.8.0: - the <code class="docutils literal">alembic revision</code> system is now customizable.
</div>
The <code class="docutils literal">alembic revision</code> command, also available programmatically
via <a class="reference internal" href="commands.html#alembic.command.revision" title="alembic.command.revision"><code class="xref py py-func docutils literal">command.revision()</code></a>, essentially produces a single migration
script after being run. Whether or not the <code class="docutils literal">--autogenerate</code> option
was specified basically determines if this script is a blank revision
script with empty <code class="docutils literal">upgrade()</code> and <code class="docutils literal">downgrade()</code> functions, or was
produced with alembic operation directives as the result of autogenerate.
In either case, the system creates a full plan of what is to be done
in the form of a <a class="reference internal" href="../ops.html#alembic.operations.MigrateOperation" title="alembic.operations.MigrateOperation"><code class="xref py py-class docutils literal">MigrateOperation</code></a> structure, which is then
used to produce the script.
For example, suppose we ran <code class="docutils literal">alembic revision --autogenerate</code>, and the
end result was that it produced a new revision <code class="docutils literal">'eced083f5df'</code>
with the following contents:
<div class="highlight-python"><div class="highlight"><pre>&quot;&quot;&quot;create the organization table.&quot;&quot;&quot;

# revision identifiers, used by Alembic.
revision = &#39;eced083f5df&#39;
down_revision = &#39;beafc7d709f&#39;

from alembic import op
import sqlalchemy as sa

def upgrade():
 op.create_table(
 &#39;organization&#39;,
 sa.Column(&#39;id&#39;, sa.Integer(), primary_key=True),
 sa.Column(&#39;name&#39;, sa.String(50), nullable=False)
 )
 op.add_column(
 &#39;user&#39;,
 sa.Column(&#39;organization_id&#39;, sa.Integer())
 )
 op.create_foreign_key(
 &#39;org_fk&#39;, &#39;user&#39;, &#39;organization&#39;, [&#39;organization_id&#39;], [&#39;id&#39;]
 )

def downgrade():
 op.drop_constraint(&#39;org_fk&#39;, &#39;user&#39;)
 op.drop_column(&#39;user&#39;, &#39;organization_id&#39;)
 op.drop_table(&#39;organization&#39;)
</pre></div>
</div>
The above script is generated by a <a class="reference internal" href="../ops.html#alembic.operations.MigrateOperation" title="alembic.operations.MigrateOperation"><code class="xref py py-class docutils literal">MigrateOperation</code></a> structure
that looks like this:
<div class="highlight-python"><div class="highlight"><pre>from alembic.operations import ops
import sqlalchemy as sa

migration_script = ops.MigrationScript(
 &#39;eced083f5df&#39;,
 ops.UpgradeOps(
 ops=[
 ops.CreateTableOp(
 &#39;organization&#39;,
 [
 sa.Column(&#39;id&#39;, sa.Integer(), primary_key=True),
 sa.Column(&#39;name&#39;, sa.String(50), nullable=False)
 ]
 ),
 ops.ModifyTableOps(
 &#39;user&#39;,
 ops=[
 ops.AddColumnOp(
 &#39;user&#39;,
 sa.Column(&#39;organization_id&#39;, sa.Integer())
 ),
 ops.CreateForeignKeyOp(
 &#39;org_fk&#39;, &#39;user&#39;, &#39;organization&#39;,
 [&#39;organization_id&#39;], [&#39;id&#39;]
 )
 ]
 )
 ]
 ),
 ops.DowngradeOps(
 ops=[
 ops.ModifyTableOps(
 &#39;user&#39;,
 ops=[
 ops.DropConstraintOp(&#39;org_fk&#39;, &#39;user&#39;),
 ops.DropColumnOp(&#39;user&#39;, &#39;organization_id&#39;)
 ]
 ),
 ops.DropTableOp(&#39;organization&#39;)
 ]
 ),
 message=&#39;create the organization table.&#39;
)
</pre></div>
</div>
When we deal with a <a class="reference internal" href="operations.html#alembic.operations.ops.MigrationScript" title="alembic.operations.ops.MigrationScript"><code class="xref py py-class docutils literal">MigrationScript</code></a> structure, we can render
the upgrade/downgrade sections into strings for debugging purposes
using the <a class="reference internal" href="#alembic.autogenerate.render_python_code" title="alembic.autogenerate.render_python_code"><code class="xref py py-func docutils literal">render_python_code()</code></a> helper function:
<div class="highlight-python"><div class="highlight"><pre>from alembic.autogenerate import render_python_code
print(render_python_code(migration_script.upgrade_ops))
</pre></div>
</div>
Renders:
<div class="highlight-python"><div class="highlight"><pre>### commands auto generated by Alembic - please adjust! ###
 op.create_table(&#39;organization&#39;,
 sa.Column(&#39;id&#39;, sa.Integer(), nullable=False),
 sa.Column(&#39;name&#39;, sa.String(length=50), nullable=False),
 sa.PrimaryKeyConstraint(&#39;id&#39;)
 )
 op.add_column(&#39;user&#39;, sa.Column(&#39;organization_id&#39;, sa.Integer(), nullable=True))
 op.create_foreign_key(&#39;org_fk&#39;, &#39;user&#39;, &#39;organization&#39;, [&#39;organization_id&#39;], [&#39;id&#39;])
 ### end Alembic commands ###
</pre></div>
</div>
Given that structures like the above are used to generate new revision
files, and that we&#8217;d like to be able to alter these as they are created,
we then need a system to access this structure when the
<a class="reference internal" href="commands.html#alembic.command.revision" title="alembic.command.revision"><code class="xref py py-func docutils literal">command.revision()</code></a> command is used. The
<a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.process_revision_directives" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.process_revision_directives</code></a>
parameter gives us a way to alter this. This is a function that
is passed the above structure as generated by Alembic, giving us a chance
to alter it.
For example, if we wanted to put all the &#8220;upgrade&#8221; operations into
a certain branch, and we wanted our script to not have any &#8220;downgrade&#8221;
operations at all, we could build an extension as follows, illustrated
within an <code class="docutils literal">env.py</code> script:
<div class="highlight-python"><div class="highlight"><pre>def process_revision_directives(context, revision, directives):
 script = directives[0]

# set specific branch
 script.head = &quot;mybranch@head&quot;

# erase downgrade operations
 script.downgrade_ops.ops[:] = []

# ...

def run_migrations_online():

# ...
 with engine.connect() as connection:

context.configure(
 connection=connection,
 target_metadata=target_metadata,
 process_revision_directives=process_revision_directives)

<div class="section" id="fine-grained-autogenerate-generation-with-rewriters">
<h3>Fine-Grained Autogenerate Generation with Rewriters<a class="headerlink" href="#fine-grained-autogenerate-generation-with-rewriters" title="Permalink to this headline">¶</a></h3>
The preceding example illustrated how we can make a simple change to the
structure of the operation directives to produce new autogenerate output.
For the case where we want to affect very specific parts of the autogenerate
stream, we can make a function for
<a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.process_revision_directives" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.process_revision_directives</code></a>
which traverses through the whole <a class="reference internal" href="operations.html#alembic.operations.ops.MigrationScript" title="alembic.operations.ops.MigrationScript"><code class="xref py py-class docutils literal">MigrationScript</code></a> structure, locates
the elements we care about and modifies them in-place as needed. However,
to reduce the boilerplate associated with this task, we can use the
<a class="reference internal" href="#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> object to make this easier. <a class="reference internal" href="#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> gives
us an object that we can pass directly to
<a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.process_revision_directives" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.process_revision_directives</code></a> which
we can also attach handler functions onto, keyed to specific types of
constructs.
Below is an example where we rewrite <a class="reference internal" href="operations.html#alembic.operations.ops.AddColumnOp" title="alembic.operations.ops.AddColumnOp"><code class="xref py py-class docutils literal">ops.AddColumnOp</code></a> directives;
based on whether or not the new column is &#8220;nullable&#8221;, we either return
the existing directive, or we return the existing directive with
the nullable flag changed, inside of a list with a second directive
to alter the nullable flag in a second step:
<div class="highlight-python"><div class="highlight"><pre># ... fragmented env.py script ....

from alembic.autogenerate import rewriter
from alembic.operations import ops

writer = rewriter.Rewriter()

@writer.rewrites(ops.AddColumnOp)
def add_column(context, revision, op):
 if op.column.nullable:
 return op
 else:
 op.column.nullable = True
 return [
 op,
 ops.AlterColumnOp(
 op.table_name,
 op.column.name,
 modify_nullable=False,
 existing_type=op.column.type,
 )
 ]

# ... later ...

def run_migrations_online():
 # ...

with connectable.connect() as connection:
 context.configure(
 connection=connection,
 target_metadata=target_metadata,
 process_revision_directives=writer
 )

with context.begin_transaction():
 context.run_migrations()
</pre></div>
</div>
Above, in a full <a class="reference internal" href="operations.html#alembic.operations.ops.MigrationScript" title="alembic.operations.ops.MigrationScript"><code class="xref py py-class docutils literal">ops.MigrationScript</code></a> structure, the
<a class="reference internal" href="ddl.html#alembic.ddl.base.AddColumn" title="alembic.ddl.base.AddColumn"><code class="xref py py-class docutils literal">AddColumn</code></a> directives would be present within
the paths <code class="docutils literal">MigrationScript-&gt;UpgradeOps-&gt;ModifyTableOps</code>
and <code class="docutils literal">MigrationScript-&gt;DowngradeOps-&gt;ModifyTableOps</code>. The
<a class="reference internal" href="#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> handles traversing into these structures as well
as rewriting them as needed so that we only need to code for the specific
object we care about.
<dl class="class">
<dt id="alembic.autogenerate.rewriter.Rewriter">
class <code class="descclassname">alembic.autogenerate.rewriter.</code><code class="descname">Rewriter</code><a class="headerlink" href="#alembic.autogenerate.rewriter.Rewriter" title="Permalink to this definition">¶</a></dt>
<dd>A helper object that allows easy &#8216;rewriting&#8217; of ops streams.
The <a class="reference internal" href="#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> object is intended to be passed along
to the
<a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.process_revision_directives" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.process_revision_directives</code></a>
parameter in an <code class="docutils literal">env.py</code> script. Once constructed, any number
of &#8220;rewrites&#8221; functions can be associated with it, which will be given
the opportunity to modify the structure without having to have explicit
knowledge of the overall structure.
The function is passed the <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> object and
<code class="docutils literal">revision</code> tuple that are passed to the <code class="xref py py-paramref docutils literal">Environment
Context.configure.process_revision_directives</code> function normally,
and the third argument is an individual directive of the type
noted in the decorator. The function has the choice of returning
a single op directive, which normally can be the directive that
was actually passed, or a new directive to replace it, or a list
of zero or more directives to replace it.
<div class="admonition seealso">
See also
<a class="reference internal" href="#autogen-rewriter">Fine-Grained Autogenerate Generation with Rewriters</a> - usage example
</div>
<div class="versionadded">
New in version 0.8.
</div>
<dl class="method">
<dt id="alembic.autogenerate.rewriter.Rewriter.chain">
<code class="descname">chain</code>(other)<a class="headerlink" href="#alembic.autogenerate.rewriter.Rewriter.chain" title="Permalink to this definition">¶</a></dt>
<dd>Produce a &#8220;chain&#8221; of this <a class="reference internal" href="#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> to another.
This allows two rewriters to operate serially on a stream,
e.g.:
<div class="highlight-python"><div class="highlight"><pre>writer1 = autogenerate.Rewriter()
writer2 = autogenerate.Rewriter()

@writer1.rewrites(ops.AddColumnOp)
def add_column_nullable(context, revision, op):
 op.column.nullable = True
 return op

@writer2.rewrites(ops.AddColumnOp)
def add_column_idx(context, revision, op):
 idx_op = ops.CreateIndexOp(
 &#39;ixc&#39;, op.table_name, [op.column.name])
 return [
 op,
 idx_op
 ]

writer = writer1.chain(writer2)
</pre></div>
</div>
<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">other<a class="paramlink headerlink reference internal" href="#alembic.autogenerate.rewriter.Rewriter.chain.params.other">¶</a> &#8211; a <a class="reference internal" href="#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> instance</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">a new <a class="reference internal" href="#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> that will run the operations
of this writer, then the &#8220;other&#8221; writer, in succession.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="alembic.autogenerate.rewriter.Rewriter.rewrites">
<code class="descname">rewrites</code>(operator)<a class="headerlink" href="#alembic.autogenerate.rewriter.Rewriter.rewrites" title="Permalink to this definition">¶</a></dt>
<dd>Register a function as rewriter for a given type.
The function should receive three arguments, which are
the <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>, a <code class="docutils literal">revision</code> tuple, and
an op directive of the type indicated. E.g.:
<div class="highlight-python"><div class="highlight"><pre>@writer1.rewrites(ops.AddColumnOp)
def add_column_nullable(context, revision, op):
 op.column.nullable = True
 return op
</pre></div>
</div>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="revision-generation-with-multiple-engines-run-migrations-calls">
<h3>Revision Generation with Multiple Engines / <code class="docutils literal">run_migrations()</code> calls<a class="headerlink" href="#revision-generation-with-multiple-engines-run-migrations-calls" title="Permalink to this headline">¶</a></h3>
A lesser-used technique which allows autogenerated migrations to run
against multiple databse backends at once, generating changes into
a single migration script, is illustrated in the
provided <code class="docutils literal">multidb</code> template. This template features a special <code class="docutils literal">env.py</code>
which iterates through multiple <a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Engine" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Engine</code></a> instances
and calls upon <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext.run_migrations" title="alembic.runtime.migration.MigrationContext.run_migrations"><code class="xref py py-meth docutils literal">MigrationContext.run_migrations()</code></a> for each:
<div class="highlight-python"><div class="highlight"><pre>for name, rec in engines.items():
 logger.info(&quot;Migrating database %s&quot; % name)
 context.configure(
 connection=rec[&#39;connection&#39;],
 upgrade_token=&quot;%s_upgrades&quot; % name,
 downgrade_token=&quot;%s_downgrades&quot; % name,
 target_metadata=target_metadata.get(name)
 )
 context.run_migrations(engine_name=name)
</pre></div>
</div>
Above, <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext.run_migrations" title="alembic.runtime.migration.MigrationContext.run_migrations"><code class="xref py py-meth docutils literal">MigrationContext.run_migrations()</code></a> is run multiple times,
once for each engine. Within the context of autogeneration, each time
the method is called the <a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.upgrade_token" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">upgrade_token</code></a>
and <a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.downgrade_token" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">downgrade_token</code></a> parameters
are changed, so that the collection of template variables gains distinct
entries for each engine, which are then referred to explicitly
within <code class="docutils literal">script.py.mako</code>.
In terms of the
<a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.process_revision_directives" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.process_revision_directives</code></a> hook,
the behavior here is that the <code class="docutils literal">process_revision_directives</code> hook
is invoked multiple times, once for each call to
context.run_migrations(). This means that if
a multi-<code class="docutils literal">run_migrations()</code> approach is to be combined with the
<code class="docutils literal">process_revision_directives</code> hook, care must be taken to use the
hook appropriately.
The first point to note is that when a second call to
<code class="docutils literal">run_migrations()</code> occurs, the <code class="docutils literal">.upgrade_ops</code> and <code class="docutils literal">.downgrade_ops</code>
attributes are converted into Python lists, and new
<a class="reference internal" href="operations.html#alembic.operations.ops.UpgradeOps" title="alembic.operations.ops.UpgradeOps"><code class="xref py py-class docutils literal">UpgradeOps</code></a> and <a class="reference internal" href="operations.html#alembic.operations.ops.DowngradeOps" title="alembic.operations.ops.DowngradeOps"><code class="xref py py-class docutils literal">DowngradeOps</code></a> objects are appended
to these lists. Each <a class="reference internal" href="operations.html#alembic.operations.ops.UpgradeOps" title="alembic.operations.ops.UpgradeOps"><code class="xref py py-class docutils literal">UpgradeOps</code></a> and <a class="reference internal" href="operations.html#alembic.operations.ops.DowngradeOps" title="alembic.operations.ops.DowngradeOps"><code class="xref py py-class docutils literal">DowngradeOps</code></a>
object maintains an <code class="docutils literal">.upgrade_token</code> and a <code class="docutils literal">.downgrade_token</code> attribute
respectively, which serves to render their contents into the appropriate
template token.
For example, a multi-engine run that has the engine names <code class="docutils literal">engine1</code>
and <code class="docutils literal">engine2</code> will generate tokens of <code class="docutils literal">engine1_upgrades</code>,
<code class="docutils literal">engine1_downgrades</code>, <code class="docutils literal">engine2_upgrades</code> and <code class="docutils literal">engine2_downgrades</code> as
it runs. The resulting migration structure would look like this:
<div class="highlight-python"><div class="highlight"><pre>from alembic.operations import ops
import sqlalchemy as sa

migration_script = ops.MigrationScript(
 &#39;eced083f5df&#39;,
 [
 ops.UpgradeOps(
 ops=[
 # upgrade operations for &quot;engine1&quot;
 ],
 upgrade_token=&quot;engine1_upgrades&quot;
 ),
 ops.UpgradeOps(
 ops=[
 # upgrade operations for &quot;engine2&quot;
 ],
 upgrade_token=&quot;engine2_upgrades&quot;
 ),
 ],
 [
 ops.DowngradeOps(
 ops=[
 # downgrade operations for &quot;engine1&quot;
 ],
 downgrade_token=&quot;engine1_downgrades&quot;
 ),
 ops.DowngradeOps(
 ops=[
 # downgrade operations for &quot;engine2&quot;
 ],
 downgrade_token=&quot;engine2_downgrades&quot;
 )
 ],
 message=&#39;migration message&#39;
)
</pre></div>
</div>
Given the above, the following guidelines should be considered when
the <code class="docutils literal">env.py</code> script calls upon <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext.run_migrations" title="alembic.runtime.migration.MigrationContext.run_migrations"><code class="xref py py-meth docutils literal">MigrationContext.run_migrations()</code></a>
mutiple times when running autogenerate:
<ul class="simple">
<li>If the <code class="docutils literal">process_revision_directives</code> hook aims to add elements
based on inspection of the current database /
connection, it should do its operation on each iteration. This is
so that each time the hook runs, the database is available.</li>
<li>Alternatively, if the <code class="docutils literal">process_revision_directives</code> hook aims to
modify the list of migration directives in place, this should
be called only on the last iteration. This is so that the hook
isn&#8217;t being given an ever-growing structure each time which it has already
modified previously.</li>
<li>The <a class="reference internal" href="#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> object, if used, should be called only on the
last iteration, because it will always deliver all directives every time,
so again to avoid double/triple/etc. processing of directives it should
be called only when the structure is complete.</li>
<li>The <a class="reference internal" href="operations.html#alembic.operations.ops.MigrationScript.upgrade_ops_list" title="alembic.operations.ops.MigrationScript.upgrade_ops_list"><code class="xref py py-attr docutils literal">MigrationScript.upgrade_ops_list</code></a> and
<a class="reference internal" href="operations.html#alembic.operations.ops.MigrationScript.downgrade_ops_list" title="alembic.operations.ops.MigrationScript.downgrade_ops_list"><code class="xref py py-attr docutils literal">MigrationScript.downgrade_ops_list</code></a> attributes should be consulted
when referring to the collection of <a class="reference internal" href="operations.html#alembic.operations.ops.UpgradeOps" title="alembic.operations.ops.UpgradeOps"><code class="xref py py-class docutils literal">UpgradeOps</code></a> and
<a class="reference internal" href="operations.html#alembic.operations.ops.DowngradeOps" title="alembic.operations.ops.DowngradeOps"><code class="xref py py-class docutils literal">DowngradeOps</code></a> objects.</li>
</ul>
<div class="versionchanged">
Changed in version 0.8.1: - multiple calls to
<a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext.run_migrations" title="alembic.runtime.migration.MigrationContext.run_migrations"><code class="xref py py-meth docutils literal">MigrationContext.run_migrations()</code></a> within an autogenerate operation,
such as that proposed within the <code class="docutils literal">multidb</code> script template,
are now accommodated by the new extensible migration system
introduced in 0.8.0.
</div>
</div>
</div>
<div class="section" id="autogenerating-custom-operation-directives">
<h2>Autogenerating Custom Operation Directives<a class="headerlink" href="#autogenerating-custom-operation-directives" title="Permalink to this headline">¶</a></h2>
In the section <a class="reference internal" href="operations.html#operation-plugins">Operation Plugins</a>, we talked about adding new
subclasses of <a class="reference internal" href="../ops.html#alembic.operations.MigrateOperation" title="alembic.operations.MigrateOperation"><code class="xref py py-class docutils literal">MigrateOperation</code></a> in order to add new <code class="docutils literal">op.</code>
directives. In the preceding section <a class="reference internal" href="#customizing-revision">Customizing Revision Generation</a>, we
also learned that these same <a class="reference internal" href="../ops.html#alembic.operations.MigrateOperation" title="alembic.operations.MigrateOperation"><code class="xref py py-class docutils literal">MigrateOperation</code></a> structures are at
the base of how the autogenerate system knows what Python code to render.
Using this knowledge, we can create additional functions that plug into
the autogenerate system so that our new operations can be generated
into migration scripts when <code class="docutils literal">alembic revision --autogenerate</code> is run.
The following sections will detail an example of this using the
the <code class="docutils literal">CreateSequenceOp</code> and <code class="docutils literal">DropSequenceOp</code> directives
we created in <a class="reference internal" href="operations.html#operation-plugins">Operation Plugins</a>, which correspond to the
SQLAlchemy <a class="reference external" href="http://www.sqlalchemy.org/docs/core/defaults.html#sqlalchemy.schema.Sequence" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Sequence</code></a> construct.
<div class="versionadded">
New in version 0.8.0: - custom operations can be added to the
autogenerate system to support new kinds of database objects.
</div>
<div class="section" id="tracking-our-object-with-the-model">
<h3>Tracking our Object with the Model<a class="headerlink" href="#tracking-our-object-with-the-model" title="Permalink to this headline">¶</a></h3>
The basic job of an autogenerate comparison function is to inspect
a series of objects in the database and compare them against a series
of objects defined in our model. By &#8220;in our model&#8221;, we mean anything
defined in Python code that we want to track, however most commonly
we&#8217;re talking about a series of <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.Table" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Table</code></a>
objects present in a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a> collection.
Let&#8217;s propose a simple way of seeing what <a class="reference external" href="http://www.sqlalchemy.org/docs/core/defaults.html#sqlalchemy.schema.Sequence" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Sequence</code></a>
objects we want to ensure exist in the database when autogenerate
runs. While these objects do have some integrations with
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.Table" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Table</code></a> and <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a>
already, let&#8217;s assume they don&#8217;t, as the example here intends to illustrate
how we would do this for most any kind of custom construct. We
associate the object with the <code class="xref py py-attr docutils literal">info</code>
collection of <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a>, which is a dictionary
we can use for anything, which we also know will be passed to the autogenerate
process:
<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.schema import Sequence

def add_sequence_to_model(sequence, metadata):
 metadata.info.setdefault(&quot;sequences&quot;, set()).add(
 (sequence.schema, sequence.name)
 )

my_seq = Sequence(&quot;my_sequence&quot;)
add_sequence_to_model(my_seq, model_metadata)
</pre></div>
</div>
The <code class="xref py py-attr docutils literal">info</code>
dictionary is a good place to put things that we want our autogeneration
routines to be able to locate, which can include any object such as
custom DDL objects representing views, triggers, special constraints,
or anything else we want to support.
</div>
<div class="section" id="registering-a-comparison-function">
<h3>Registering a Comparison Function<a class="headerlink" href="#registering-a-comparison-function" title="Permalink to this headline">¶</a></h3>
We now need to register a comparison hook, which will be used
to compare the database to our model and produce <code class="docutils literal">CreateSequenceOp</code>
and <code class="docutils literal">DropSequenceOp</code> directives to be included in our migration
script. Note that we are assuming a
Postgresql backend:
<div class="highlight-python"><div class="highlight"><pre>from alembic.autogenerate import comparators

@comparators.dispatch_for(&quot;schema&quot;)
def compare_sequences(autogen_context, upgrade_ops, schemas):
 all_conn_sequences = set()

for sch in schemas:

all_conn_sequences.update([
 (sch, row[0]) for row in
 autogen_context.connection.execute(
 &quot;SELECT relname FROM pg_class c join &quot;
 &quot;pg_namespace n on n.oid=c.relnamespace where &quot;
 &quot;relkind=&#39;S&#39; and n.nspname=%(nspname)s&quot;,

# note that we consider a schema of &#39;None&#39; in our
 # model to be the &quot;default&quot; name in the PG database;
 # this usually is the name &#39;public&#39;
 nspname=autogen_context.dialect.default_schema_name
 if sch is None else sch
 )
 ])

# get the collection of Sequence objects we&#39;re storing with
 # our MetaData
 metadata_sequences = autogen_context.metadata.info.setdefault(
 &quot;sequences&quot;, set())

# for new names, produce CreateSequenceOp directives
 for sch, name in metadata_sequences.difference(all_conn_sequences):
 upgrade_ops.ops.append(
 CreateSequenceOp(name, schema=sch)
 )

# for names that are going away, produce DropSequenceOp
 # directives
 for sch, name in all_conn_sequences.difference(metadata_sequences):
 upgrade_ops.ops.append(
 DropSequenceOp(name, schema=sch)
 )
</pre></div>
</div>
Above, we&#8217;ve built a new function <code class="docutils literal">compare_sequences()</code> and registered
it as a &#8220;schema&#8221; level comparison function with autogenerate. The
job that it performs is that it compares the list of sequence names
present in each database schema with that of a list of sequence names
that we are maintaining in our <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a> object.
When autogenerate completes, it will have a series of
<code class="docutils literal">CreateSequenceOp</code> and <code class="docutils literal">DropSequenceOp</code> directives in the list of
&#8220;upgrade&#8221; operations; the list of &#8220;downgrade&#8221; operations is generated
directly from these using the
<code class="docutils literal">CreateSequenceOp.reverse()</code> and <code class="docutils literal">DropSequenceOp.reverse()</code> methods
that we&#8217;ve implemented on these objects.
The registration of our function at the scope of &#8220;schema&#8221; means our
autogenerate comparison function is called outside of the context
of any specific table or column. The three available scopes
are &#8220;schema&#8221;, &#8220;table&#8221;, and &#8220;column&#8221;, summarized as follows:
<ul>
<li>Schema level - these hooks are passed a <a class="reference internal" href="#alembic.autogenerate.api.AutogenContext" title="alembic.autogenerate.api.AutogenContext"><code class="xref py py-class docutils literal">AutogenContext</code></a>,
an <a class="reference internal" href="operations.html#alembic.operations.ops.UpgradeOps" title="alembic.operations.ops.UpgradeOps"><code class="xref py py-class docutils literal">UpgradeOps</code></a> collection, and a collection of string schema
names to be operated upon. If the
<a class="reference internal" href="operations.html#alembic.operations.ops.UpgradeOps" title="alembic.operations.ops.UpgradeOps"><code class="xref py py-class docutils literal">UpgradeOps</code></a> collection contains changes after all
hooks are run, it is included in the migration script:
<div class="highlight-python"><div class="highlight"><pre>@comparators.dispatch_for(&quot;schema&quot;)
def compare_schema_level(autogen_context, upgrade_ops, schemas):
 pass
</pre></div>
</div>
</li>
<li>Table level - these hooks are passed a <a class="reference internal" href="#alembic.autogenerate.api.AutogenContext" title="alembic.autogenerate.api.AutogenContext"><code class="xref py py-class docutils literal">AutogenContext</code></a>,
a <a class="reference internal" href="operations.html#alembic.operations.ops.ModifyTableOps" title="alembic.operations.ops.ModifyTableOps"><code class="xref py py-class docutils literal">ModifyTableOps</code></a> collection, a schema name, table name,
a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.Table" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Table</code></a> reflected from the database if any
or <code class="docutils literal">None</code>, and a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.Table" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Table</code></a> present in the
local <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a>. If the
<a class="reference internal" href="operations.html#alembic.operations.ops.ModifyTableOps" title="alembic.operations.ops.ModifyTableOps"><code class="xref py py-class docutils literal">ModifyTableOps</code></a> collection contains changes after all
hooks are run, it is included in the migration script:
<div class="highlight-python"><div class="highlight"><pre>@comparators.dispatch_for(&quot;table&quot;)
def compare_table_level(autogen_context, modify_ops,
 schemaname, tablename, conn_table, metadata_table):
 pass
</pre></div>
</div>
</li>
<li>Column level - these hooks are passed a <a class="reference internal" href="#alembic.autogenerate.api.AutogenContext" title="alembic.autogenerate.api.AutogenContext"><code class="xref py py-class docutils literal">AutogenContext</code></a>,
an <a class="reference internal" href="operations.html#alembic.operations.ops.AlterColumnOp" title="alembic.operations.ops.AlterColumnOp"><code class="xref py py-class docutils literal">AlterColumnOp</code></a> object, a schema name, table name,
column name, a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.Column" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Column</code></a> reflected from the
database and a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.Column" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Column</code></a> present in the
local table. If the <a class="reference internal" href="operations.html#alembic.operations.ops.AlterColumnOp" title="alembic.operations.ops.AlterColumnOp"><code class="xref py py-class docutils literal">AlterColumnOp</code></a> contains changes after
all hooks are run, it is included in the migration script;
a &#8220;change&#8221; is considered to be present if any of the <code class="docutils literal">modify_</code> attributes
are set to a non-default value, or there are any keys
in the <code class="docutils literal">.kw</code> collection with the prefix <code class="docutils literal">&quot;modify_&quot;</code>:
<div class="highlight-python"><div class="highlight"><pre>@comparators.dispatch_for(&quot;column&quot;)
def compare_column_level(autogen_context, alter_column_op,
 schemaname, tname, cname, conn_col, metadata_col):
 pass
</pre></div>
</div>
</li>
</ul>
The <a class="reference internal" href="#alembic.autogenerate.api.AutogenContext" title="alembic.autogenerate.api.AutogenContext"><code class="xref py py-class docutils literal">AutogenContext</code></a> passed to these hooks is documented below.
<dl class="class">
<dt id="alembic.autogenerate.api.AutogenContext">
class <code class="descclassname">alembic.autogenerate.api.</code><code class="descname">AutogenContext</code>(migration_context, metadata=None, opts=None, autogenerate=True)<a class="headerlink" href="#alembic.autogenerate.api.AutogenContext" title="Permalink to this definition">¶</a></dt>
<dd>Maintains configuration and state that&#8217;s specific to an
autogenerate operation.
<dl class="attribute">
<dt id="alembic.autogenerate.api.AutogenContext.connection">
<code class="descname">connection</code> = None<a class="headerlink" href="#alembic.autogenerate.api.AutogenContext.connection" title="Permalink to this definition">¶</a></dt>
<dd>The <code class="xref py py-class docutils literal">Connection</code> object currently
connected to the database backend being compared.
This is obtained from the <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext.bind" title="alembic.runtime.migration.MigrationContext.bind"><code class="xref py py-attr docutils literal">MigrationContext.bind</code></a> and is
utimately set up in the <code class="docutils literal">env.py</code> script.
</dd></dl>

<dl class="attribute">
<dt id="alembic.autogenerate.api.AutogenContext.dialect">
<code class="descname">dialect</code> = None<a class="headerlink" href="#alembic.autogenerate.api.AutogenContext.dialect" title="Permalink to this definition">¶</a></dt>
<dd>The <code class="xref py py-class docutils literal">Dialect</code> object currently in use.
This is normally obtained from the
<code class="xref py py-attr docutils literal">dialect</code> attribute.
</dd></dl>

<dl class="attribute">
<dt id="alembic.autogenerate.api.AutogenContext.imports">
<code class="descname">imports</code> = None<a class="headerlink" href="#alembic.autogenerate.api.AutogenContext.imports" title="Permalink to this definition">¶</a></dt>
<dd>A <code class="docutils literal">set()</code> which contains string Python import directives.
The directives are to be rendered into the <code class="docutils literal">${imports}</code> section
of a script template. The set is normally empty and can be modified
within hooks such as the <a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.render_item" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.render_item</code></a>
hook.
<div class="versionadded">
New in version 0.8.3.
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="../autogenerate.html#autogen-render-types">Affecting the Rendering of Types Themselves</a>
</div>
</dd></dl>

<dl class="attribute">
<dt id="alembic.autogenerate.api.AutogenContext.metadata">
<code class="descname">metadata</code> = None<a class="headerlink" href="#alembic.autogenerate.api.AutogenContext.metadata" title="Permalink to this definition">¶</a></dt>
<dd>The <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a> object
representing the destination.
This object is the one that is passed within <code class="docutils literal">env.py</code>
to the <a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.target_metadata" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.target_metadata</code></a>
parameter. It represents the structure of <code class="xref py py-class docutils literal">Table</code> and other
objects as stated in the current database model, and represents the
destination structure for the database being examined.
While the <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">MetaData</code></a> object is primarily
known as a collection of <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.Table" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Table</code></a> objects,
it also has an <code class="xref py py-attr docutils literal">info</code> dictionary
that may be used by end-user schemes to store additional schema-level
objects that are to be compared in custom autogeneration schemes.
</dd></dl>

<dl class="attribute">
<dt id="alembic.autogenerate.api.AutogenContext.migration_context">
<code class="descname">migration_context</code> = None<a class="headerlink" href="#alembic.autogenerate.api.AutogenContext.migration_context" title="Permalink to this definition">¶</a></dt>
<dd>The <a class="reference internal" href="runtime.html#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> established by the <code class="docutils literal">env.py</code> script.
</dd></dl>

<dl class="method">
<dt id="alembic.autogenerate.api.AutogenContext.run_filters">
<code class="descname">run_filters</code>(object_, name, type_, reflected, compare_to)<a class="headerlink" href="#alembic.autogenerate.api.AutogenContext.run_filters" title="Permalink to this definition">¶</a></dt>
<dd>Run the context&#8217;s object filters and return True if the targets
should be part of the autogenerate operation.
This method should be run for every kind of object encountered within
an autogenerate operation, giving the environment the chance
to filter what objects should be included in the comparison.
The filters here are produced directly via the
<a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.include_object" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.include_object</code></a>
and <a class="reference internal" href="runtime.html#alembic.runtime.environment.EnvironmentContext.configure.params.include_symbol" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.include_symbol</code></a>
functions, if present.
</dd></dl>

</dd></dl>

</div>
<div class="section" id="creating-a-render-function">
<h3>Creating a Render Function<a class="headerlink" href="#creating-a-render-function" title="Permalink to this headline">¶</a></h3>
The second autogenerate integration hook is to provide a &#8220;render&#8221; function;
since the autogenerate
system renders Python code, we need to build a function that renders
the correct &#8220;op&#8221; instructions for our directive:
<div class="highlight-python"><div class="highlight"><pre>from alembic.autogenerate import renderers

@renderers.dispatch_for(CreateSequenceOp)
def render_create_sequence(autogen_context, op):
 return &quot;op.create_sequence(%r, **%r)&quot; % (
 op.sequence_name,
 {&quot;schema&quot;: op.schema}
 )

@renderers.dispatch_for(DropSequenceOp)
def render_drop_sequence(autogen_context, op):
 return &quot;op.drop_sequence(%r, **%r)&quot; % (
 op.sequence_name,
 {&quot;schema&quot;: op.schema}
 )
</pre></div>
</div>
The above functions will render Python code corresponding to the
presence of <code class="docutils literal">CreateSequenceOp</code> and <code class="docutils literal">DropSequenceOp</code> instructions
in the list that our comparison function generates.
</div>
<div class="section" id="running-it">
<h3>Running It<a class="headerlink" href="#running-it" title="Permalink to this headline">¶</a></h3>
All the above code can be organized however the developer sees fit;
the only thing that needs to make it work is that when the
Alembic environment <code class="docutils literal">env.py</code> is invoked, it either imports modules
which contain all the above routines, or they are locally present,
or some combination thereof.
If we then have code in our model (which of course also needs to be invoked
when <code class="docutils literal">env.py</code> runs!) like this:
<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.schema import Sequence

my_seq_1 = Sequence(&quot;my_sequence_1&quot;)
add_sequence_to_model(my_seq_1, target_metadata)
</pre></div>
</div>
When we first run <code class="docutils literal">alembic revision --autogenerate</code>, we&#8217;ll see this
in our migration file:
<div class="highlight-python"><div class="highlight"><pre>def upgrade():
 ### commands auto generated by Alembic - please adjust! ###
 op.create_sequence(&#39;my_sequence_1&#39;, **{&#39;schema&#39;: None})
 ### end Alembic commands ###

def downgrade():
 ### commands auto generated by Alembic - please adjust! ###
 op.drop_sequence(&#39;my_sequence_1&#39;, **{&#39;schema&#39;: None})
 ### end Alembic commands ###
</pre></div>
</div>
These are our custom directives that will invoke when <code class="docutils literal">alembic upgrade</code>
or <code class="docutils literal">alembic downgrade</code> is run.
</div>
</div>
</div>

</div>
 </div>
 </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="#">Autogeneration</a><ul>
<li><a class="reference internal" href="#getting-diffs">Getting Diffs</a></li>
<li><a class="reference internal" href="#customizing-revision-generation">Customizing Revision Generation</a><ul>
<li><a class="reference internal" href="#fine-grained-autogenerate-generation-with-rewriters">Fine-Grained Autogenerate Generation with Rewriters</a></li>
<li><a class="reference internal" href="#revision-generation-with-multiple-engines-run-migrations-calls">Revision Generation with Multiple Engines / <code class="docutils literal">run_migrations()</code> calls</a></li>
</ul>
</li>
<li><a class="reference internal" href="#autogenerating-custom-operation-directives">Autogenerating Custom Operation Directives</a><ul>
<li><a class="reference internal" href="#tracking-our-object-with-the-model">Tracking our Object with the Model</a></li>
<li><a class="reference internal" href="#registering-a-comparison-function">Registering a Comparison Function</a></li>
<li><a class="reference internal" href="#creating-a-render-function">Creating a Render Function</a></li>
<li><a class="reference internal" href="#running-it">Running It</a></li>
</ul>
</li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="operations.html"
 title="previous chapter">Operation Directives</a>
 <h4>Next topic</h4>
 <a href="script.html"
 title="next chapter">Script Directory</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../_sources/api/autogenerate.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>
 
 Enter search terms or a module, class or function name.
 
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
 </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="script.html" title="Script Directory"
 >next</a> |</li>
 <li class="right" >
 <a href="operations.html" title="Operation Directives"
 >previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="../index.html">Alembic 0.8.3 documentation</a> &raquo;</li>
 <li class="nav-item nav-item-1"><a href="index.html" >API Details</a> &raquo;</li> 
 </ul>
 </div>
 <div class="footer" role="contentinfo">
 &copy; Copyright 2010-2015, Mike Bayer.
 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.1.
 </div>
 </body>
</html>