^^&&^^

Edit File: runtime.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>Runtime Objects &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="Configuration" href="config.html" />
 <link rel="prev" title="Overview" href="overview.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="config.html" title="Configuration"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="overview.html" title="Overview"
 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="runtime-objects">
<h1>Runtime Objects<a class="headerlink" href="#runtime-objects" title="Permalink to this headline">¶</a></h1>
The &#8220;runtime&#8221; of Alembic involves the <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a>
and <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> objects. These are the objects that are
in play once the <code class="docutils literal">env.py</code> script is loaded up by a command and
a migration operation proceeds.
<div class="section" id="the-environment-context">
<h2>The Environment Context<a class="headerlink" href="#the-environment-context" title="Permalink to this headline">¶</a></h2>
The <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> class provides most of the
API used within an <code class="docutils literal">env.py</code> script. Within <code class="docutils literal">env.py</code>,
the instantated <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> is made available
via a special proxy module called <code class="docutils literal">alembic.context</code>. That is,
you can import <code class="docutils literal">alembic.context</code> like a regular Python module,
and each name you call upon it is ultimately routed towards the
current <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> in use.
In particular, the key method used within <code class="docutils literal">env.py</code> is <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">EnvironmentContext.configure()</code></a>,
which establishes all the details about how the database will be accessed.
<dl class="class">
<dt id="alembic.runtime.environment.EnvironmentContext">
class <code class="descclassname">alembic.runtime.environment.</code><code class="descname">EnvironmentContext</code>(config, script, **kw)<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext" title="Permalink to this definition">¶</a></dt>
<dd>A configurational facade made available in an <code class="docutils literal">env.py</code> script.
The <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> acts as a facade to the more
nuts-and-bolts objects of <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> as well as certain
aspects of <a class="reference internal" href="config.html#alembic.config.Config" title="alembic.config.Config"><code class="xref py py-class docutils literal">Config</code></a>,
within the context of the <code class="docutils literal">env.py</code> script that is invoked by
most Alembic commands.
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> is normally instantiated
when a command in <a class="reference internal" href="commands.html#module-alembic.command" title="alembic.command"><code class="xref py py-mod docutils literal">alembic.command</code></a> is run. It then makes
itself available in the <code class="docutils literal">alembic.context</code> module for the scope
of the command. From within an <code class="docutils literal">env.py</code> script, the current
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> is available by importing this module.
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> also supports programmatic usage.
At this level, it acts as a Python context manager, that is, is
intended to be used using the
<code class="docutils literal">with:</code> statement. A typical use of <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a>:
<div class="highlight-python"><div class="highlight"><pre>from alembic.config import Config
from alembic.script import ScriptDirectory

config = Config()
config.set_main_option(&quot;script_location&quot;, &quot;myapp:migrations&quot;)
script = ScriptDirectory.from_config(config)

def my_function(rev, context):
 &#39;&#39;&#39;do something with revision &quot;rev&quot;, which
 will be the current database revision,
 and &quot;context&quot;, which is the MigrationContext
 that the env.py will create&#39;&#39;&#39;

with EnvironmentContext(
 config,
 script,
 fn = my_function,
 as_sql = False,
 starting_rev = &#39;base&#39;,
 destination_rev = &#39;head&#39;,
 tag = &quot;sometag&quot;
):
 script.run_env()
</pre></div>
</div>
The above script will invoke the <code class="docutils literal">env.py</code> script
within the migration environment. If and when <code class="docutils literal">env.py</code>
calls <a class="reference internal" href="#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>, the
<code class="docutils literal">my_function()</code> function above will be called
by the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>, given the context
itself as well as the current revision in the database.
<div class="admonition note">
Note
For most API usages other than full blown
invocation of migration scripts, the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
and <a class="reference internal" href="script.html#alembic.script.ScriptDirectory" title="alembic.script.ScriptDirectory"><code class="xref py py-class docutils literal">ScriptDirectory</code></a> objects can be created and
used directly. The <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> object
is only needed when you need to actually invoke the
<code class="docutils literal">env.py</code> module present in the migration environment.
</div>
Construct a new <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a>.
<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>config<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.params.config">¶</a> &#8211; a <a class="reference internal" href="config.html#alembic.config.Config" title="alembic.config.Config"><code class="xref py py-class docutils literal">Config</code></a> instance.</li>
<li>script<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.params.script">¶</a> &#8211; a <a class="reference internal" href="script.html#alembic.script.ScriptDirectory" title="alembic.script.ScriptDirectory"><code class="xref py py-class docutils literal">ScriptDirectory</code></a> instance.</li>
<li>**kw<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.params.**kw">¶</a> &#8211; keyword options that will be ultimately
passed along to the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> when
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">EnvironmentContext.configure()</code></a> is called.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.begin_transaction">
<code class="descname">begin_transaction</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.begin_transaction" title="Permalink to this definition">¶</a></dt>
<dd>Return a context manager that will
enclose an operation within a &#8220;transaction&#8221;,
as defined by the environment&#8217;s offline
and transactional DDL settings.
e.g.:
<div class="highlight-python"><div class="highlight"><pre>with context.begin_transaction():
 context.run_migrations()
</pre></div>
</div>
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.begin_transaction" title="alembic.runtime.environment.EnvironmentContext.begin_transaction"><code class="xref py py-meth docutils literal">begin_transaction()</code></a> is intended to
&#8220;do the right thing&#8221; regardless of
calling context:
<ul class="simple">
<li>If <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.is_transactional_ddl" title="alembic.runtime.environment.EnvironmentContext.is_transactional_ddl"><code class="xref py py-meth docutils literal">is_transactional_ddl()</code></a> is <code class="docutils literal">False</code>,
returns a &#8220;do nothing&#8221; context manager
which otherwise produces no transactional
state or directives.</li>
<li>If <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.is_offline_mode" title="alembic.runtime.environment.EnvironmentContext.is_offline_mode"><code class="xref py py-meth docutils literal">is_offline_mode()</code></a> is <code class="docutils literal">True</code>,
returns a context manager that will
invoke the <a class="reference internal" href="ddl.html#alembic.ddl.impl.DefaultImpl.emit_begin" title="alembic.ddl.impl.DefaultImpl.emit_begin"><code class="xref py py-meth docutils literal">DefaultImpl.emit_begin()</code></a>
and <a class="reference internal" href="ddl.html#alembic.ddl.impl.DefaultImpl.emit_commit" title="alembic.ddl.impl.DefaultImpl.emit_commit"><code class="xref py py-meth docutils literal">DefaultImpl.emit_commit()</code></a>
methods, which will produce the string
directives <code class="docutils literal">BEGIN</code> and <code class="docutils literal">COMMIT</code> on
the output stream, as rendered by the
target backend (e.g. SQL Server would
emit <code class="docutils literal">BEGIN TRANSACTION</code>).</li>
<li>Otherwise, calls <a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection.begin" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal">sqlalchemy.engine.Connection.begin()</code></a>
on the current online connection, which
returns a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Transaction" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">sqlalchemy.engine.Transaction</code></a>
object. This object demarcates a real
transaction and is itself a context manager,
which will roll back if an exception
is raised.</li>
</ul>
Note that a custom <code class="docutils literal">env.py</code> script which
has more specific transactional needs can of course
manipulate the <a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Connection</code></a>
directly to produce transactional state in &#8220;online&#8221;
mode.
</dd></dl>

<dl class="attribute">
<dt id="alembic.runtime.environment.EnvironmentContext.config">
<code class="descname">config</code> = None<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.config" title="Permalink to this definition">¶</a></dt>
<dd>An instance of <a class="reference internal" href="config.html#alembic.config.Config" title="alembic.config.Config"><code class="xref py py-class docutils literal">Config</code></a> representing the
configuration file contents as well as other variables
set programmatically within it.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.configure">
<code class="descname">configure</code>(connection=None, url=None, dialect_name=None, transactional_ddl=None, transaction_per_migration=False, output_buffer=None, starting_rev=None, tag=None, template_args=None, render_as_batch=False, target_metadata=None, include_symbol=None, include_object=None, include_schemas=False, process_revision_directives=None, compare_type=False, compare_server_default=False, render_item=None, literal_binds=False, upgrade_token='upgrades', downgrade_token='downgrades', alembic_module_prefix='op.', sqlalchemy_module_prefix='sa.', user_module_prefix=None, **kw)<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.configure" title="Permalink to this definition">¶</a></dt>
<dd>Configure a <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> within this
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> which will provide database
connectivity and other configuration to a series of
migration scripts.
Many methods on <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext" title="alembic.runtime.environment.EnvironmentContext"><code class="xref py py-class docutils literal">EnvironmentContext</code></a> require that
this method has been called in order to function, as they
ultimately need to have database access or at least access
to the dialect in use. Those which do are documented as such.
The important thing needed by <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">configure()</code></a> is a
means to determine what kind of database dialect is in use.
An actual connection to that database is needed only if
the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> is to be used in
&#8220;online&#8221; mode.
If the <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.is_offline_mode" title="alembic.runtime.environment.EnvironmentContext.is_offline_mode"><code class="xref py py-meth docutils literal">is_offline_mode()</code></a> function returns <code class="docutils literal">True</code>,
then no connection is needed here. Otherwise, the
<code class="docutils literal">connection</code> parameter should be present as an
instance of <a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">sqlalchemy.engine.Connection</code></a>.
This function is typically called from the <code class="docutils literal">env.py</code>
script within a migration environment. It can be called
multiple times for an invocation. The most recent
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Connection</code></a>
for which it was called is the one that will be operated upon
by the next call to <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.run_migrations" title="alembic.runtime.environment.EnvironmentContext.run_migrations"><code class="xref py py-meth docutils literal">run_migrations()</code></a>.
General parameters:
<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>connection<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.connection">¶</a> &#8211; a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Connection</code></a>
to use
for SQL execution in &#8220;online&#8221; mode. When present, is also
used to determine the type of dialect in use.</li>
<li>url<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.url">¶</a> &#8211; a string database url, or a
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/engines.html#sqlalchemy.engine.url.URL" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">sqlalchemy.engine.url.URL</code></a> object.
The type of dialect to be used will be derived from this if
<code class="docutils literal">connection</code> is not passed.</li>
<li>dialect_name<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.dialect_name">¶</a> &#8211; string name of a dialect, such as
&#8220;postgresql&#8221;, &#8220;mssql&#8221;, etc.
The type of dialect to be used will be derived from this if
<code class="docutils literal">connection</code> and <code class="docutils literal">url</code> are not passed.</li>
<li>transactional_ddl<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.transactional_ddl">¶</a> &#8211; Force the usage of &#8220;transactional&#8221;
DDL on or off;
this otherwise defaults to whether or not the dialect in
use supports it.</li>
<li>transaction_per_migration<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.transaction_per_migration">¶</a> &#8211; if True, nest each migration script
in a transaction rather than the full series of migrations to
run.
<div class="versionadded">
New in version 0.6.5.
</div>
</li>
<li>output_buffer<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.output_buffer">¶</a> &#8211; a file-like object that will be used
for textual output
when the <code class="docutils literal">--sql</code> option is used to generate SQL scripts.
Defaults to
<code class="docutils literal">sys.stdout</code> if not passed here and also not present on
the <a class="reference internal" href="config.html#alembic.config.Config" title="alembic.config.Config"><code class="xref py py-class docutils literal">Config</code></a>
object. The value here overrides that of the <a class="reference internal" href="config.html#alembic.config.Config" title="alembic.config.Config"><code class="xref py py-class docutils literal">Config</code></a>
object.</li>
<li>output_encoding<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.output_encoding">¶</a> &#8211; when using <code class="docutils literal">--sql</code> to generate SQL
scripts, apply this encoding to the string output.</li>
<li>literal_binds<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.literal_binds">¶</a> &#8211; when using <code class="docutils literal">--sql</code> to generate SQL
scripts, pass through the <code class="docutils literal">literal_binds</code> flag to the compiler
so that any literal values that would ordinarily be bound
parameters are converted to plain strings.
<div class="admonition warning">
Warning
Dialects can typically only handle simple datatypes
like strings and numbers for auto-literal generation. Datatypes
like dates, intervals, and others may still require manual
formatting, typically using <a class="reference internal" href="../ops.html#alembic.operations.Operations.inline_literal" title="alembic.operations.Operations.inline_literal"><code class="xref py py-meth docutils literal">Operations.inline_literal()</code></a>.
</div>
<div class="admonition note">
Note
the <code class="docutils literal">literal_binds</code> flag is ignored on SQLAlchemy
versions prior to 0.8 where this feature is not supported.
</div>
<div class="versionadded">
New in version 0.7.6.
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="../ops.html#alembic.operations.Operations.inline_literal" title="alembic.operations.Operations.inline_literal"><code class="xref py py-meth docutils literal">Operations.inline_literal()</code></a>
</div>
</li>
<li>starting_rev<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.starting_rev">¶</a> &#8211; Override the &#8220;starting revision&#8221; argument
when using <code class="docutils literal">--sql</code> mode.</li>
<li>tag<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.tag">¶</a> &#8211; a string tag for usage by custom <code class="docutils literal">env.py</code> scripts.
Set via the <code class="docutils literal">--tag</code> option, can be overridden here.</li>
<li>template_args<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.template_args">¶</a> &#8211; dictionary of template arguments which
will be added to the template argument environment when
running the &#8220;revision&#8221; command. Note that the script environment
is only run within the &#8220;revision&#8221; command if the &#8211;autogenerate
option is used, or if the option &#8220;revision_environment=true&#8221;
is present in the alembic.ini file.</li>
<li>version_table<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.version_table">¶</a> &#8211; The name of the Alembic version table.
The default is <code class="docutils literal">'alembic_version'</code>.</li>
<li>version_table_schema<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.version_table_schema">¶</a> &#8211; Optional schema to place version
table within.</li>
</ul>
</td>
</tr>
</tbody>
</table>
Parameters specific to the autogenerate feature, when
<code class="docutils literal">alembic revision</code> is run with the <code class="docutils literal">--autogenerate</code> feature:
<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>target_metadata<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.target_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">sqlalchemy.schema.MetaData</code></a>
object that
will be consulted during autogeneration. The tables present
will be compared against
what is locally available on the target
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Connection</code></a>
to produce candidate upgrade/downgrade operations.</li>
<li>compare_type<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.compare_type">¶</a> &#8211; Indicates type comparison behavior during
an autogenerate
operation. Defaults to <code class="docutils literal">False</code> which disables type
comparison. Set to
<code class="docutils literal">True</code> to turn on default type comparison, which has varied
accuracy depending on backend. See <a class="reference internal" href="../autogenerate.html#compare-types">Comparing Types</a>
for an example as well as information on other type
comparison options.
<div class="admonition seealso">
See also
<a class="reference internal" href="../autogenerate.html#compare-types">Comparing Types</a>
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.compare_server_default" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.compare_server_default</code></a>
</div>
</li>
<li>compare_server_default<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.compare_server_default">¶</a> &#8211; Indicates server default comparison
behavior during
an autogenerate operation. Defaults to <code class="docutils literal">False</code> which disables
server default
comparison. Set to <code class="docutils literal">True</code> to turn on server default comparison,
which has
varied accuracy depending on backend.
To customize server default comparison behavior, a callable may
be specified
which can filter server default comparisons during an
autogenerate operation.
defaults during an autogenerate operation. The format of this
callable is:
<div class="highlight-python"><div class="highlight"><pre>def my_compare_server_default(context, inspected_column,
 metadata_column, inspected_default, metadata_default,
 rendered_metadata_default):
 # return True if the defaults are different,
 # False if not, or None to allow the default implementation
 # to compare these defaults
 return None

context.configure(
 # ...
 compare_server_default = my_compare_server_default
)
</pre></div>
</div>
<code class="docutils literal">inspected_column</code> is a dictionary structure as returned by
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/reflection.html#sqlalchemy.engine.reflection.Inspector.get_columns" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal">sqlalchemy.engine.reflection.Inspector.get_columns()</code></a>, whereas
<code class="docutils literal">metadata_column</code> is 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">sqlalchemy.schema.Column</code></a> from
the local model environment.
A return value of <code class="docutils literal">None</code> indicates to allow default server default
comparison
to proceed. Note that some backends such as Postgresql actually
execute
the two defaults on the database side to compare for equivalence.
<div class="admonition seealso">
See also
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.compare_type" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.compare_type</code></a>
</div>
</li>
<li>include_object<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.include_object">¶</a> &#8211; A callable function which is given
the chance to return <code class="docutils literal">True</code> or <code class="docutils literal">False</code> for any object,
indicating if the given object should be considered in the
autogenerate sweep.
The function accepts the following positional arguments:
<ul>
<li><code class="docutils literal">object</code>: a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.SchemaItem" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">SchemaItem</code></a> object such
as 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>,
<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>,
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/constraints.html#sqlalchemy.schema.Index" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Index</code></a>
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/constraints.html#sqlalchemy.schema.UniqueConstraint" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">UniqueConstraint</code></a>,
or <a class="reference external" href="http://www.sqlalchemy.org/docs/core/constraints.html#sqlalchemy.schema.ForeignKeyConstraint" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">ForeignKeyConstraint</code></a> object</li>
<li><code class="docutils literal">name</code>: the name of the object. This is typically available
via <code class="docutils literal">object.name</code>.</li>
<li><code class="docutils literal">type</code>: a string describing the type of object; currently
<code class="docutils literal">&quot;table&quot;</code>, <code class="docutils literal">&quot;column&quot;</code>, <code class="docutils literal">&quot;index&quot;</code>, <code class="docutils literal">&quot;unique_constraint&quot;</code>,
or <code class="docutils literal">&quot;foreign_key_constraint&quot;</code><div class="versionadded">
New in version 0.7.0: Support for indexes and unique constraints
within the
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.include_object" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">include_object</code></a> hook.
</div>
<div class="versionadded">
New in version 0.7.1: Support for foreign keys within the
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.include_object" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">include_object</code></a> hook.
</div>
</li>
<li><code class="docutils literal">reflected</code>: <code class="docutils literal">True</code> if the given object was produced based on
table reflection, <code class="docutils literal">False</code> if it&#8217;s from a local <code class="xref py py-class docutils literal">MetaData</code>
object.</li>
<li><code class="docutils literal">compare_to</code>: the object being compared against, if available,
else <code class="docutils literal">None</code>.</li>
</ul>
E.g.:
<div class="highlight-python"><div class="highlight"><pre>def include_object(object, name, type_, reflected, compare_to):
 if (type_ == &quot;column&quot; and
 not reflected and
 object.info.get(&quot;skip_autogenerate&quot;, False)):
 return False
 else:
 return True

context.configure(
 # ...
 include_object = include_object
)
</pre></div>
</div>
<a class="reference internal" href="#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> can also
be used to filter on specific schemas to include or omit, when
the <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.include_schemas" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.include_schemas</code></a>
flag is set to <code class="docutils literal">True</code>. The <code class="xref py py-attr docutils literal">Table.schema</code> attribute
on each <code class="xref py py-class docutils literal">Table</code> object reflected will indicate the name of the
schema from which the <code class="xref py py-class docutils literal">Table</code> originates.
<div class="versionadded">
New in version 0.6.0.
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.include_schemas" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.include_schemas</code></a>
</div>
</li>
<li>include_symbol<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.include_symbol">¶</a> &#8211; A callable function which, given a table name
and schema name (may be <code class="docutils literal">None</code>), returns <code class="docutils literal">True</code> or <code class="docutils literal">False</code>,
indicating if the given table should be considered in the
autogenerate sweep.
<div class="deprecated">
Deprecated since version 0.6.0: <a class="reference internal" href="#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>
is superceded by the more generic
<a class="reference internal" href="#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>
parameter.
</div>
E.g.:
<div class="highlight-python"><div class="highlight"><pre>def include_symbol(tablename, schema):
 return tablename not in (&quot;skip_table_one&quot;, &quot;skip_table_two&quot;)

context.configure(
 # ...
 include_symbol = include_symbol
)
</pre></div>
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.include_schemas" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.include_schemas</code></a>
<a class="reference internal" href="#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>
</div>
</li>
<li>render_as_batch<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.render_as_batch">¶</a> &#8211; if True, commands which alter elements
within a table will be placed under a <code class="docutils literal">with batch_alter_table():</code>
directive, so that batch migrations will take place.
<div class="versionadded">
New in version 0.7.0.
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="../batch.html#batch-migrations">Running &#8220;Batch&#8221; Migrations for SQLite and Other Databases</a>
</div>
</li>
<li>include_schemas<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.include_schemas">¶</a> &#8211; If True, autogenerate will scan across
all schemas located by the SQLAlchemy
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/reflection.html#sqlalchemy.engine.reflection.Inspector.get_schema_names" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal">get_schema_names()</code></a>
method, and include all differences in tables found across all
those schemas. When using this option, you may want to also
use the <a class="reference internal" href="#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>
option to specify a callable which
can filter the tables/schemas that get included.
<div class="admonition seealso">
See also
<a class="reference internal" href="#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>
</div>
</li>
<li>render_item<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.render_item">¶</a> &#8211; Callable that can be used to override how
any schema item, i.e. column, constraint, type,
etc., is rendered for autogenerate. The callable receives a
string describing the type of object, the object, and
the autogen context. If it returns False, the
default rendering method will be used. If it returns None,
the item will not be rendered in the context of a Table
construct, that is, can be used to skip columns or constraints
within op.create_table():
<div class="highlight-python"><div class="highlight"><pre>def my_render_column(type_, col, autogen_context):
 if type_ == &quot;column&quot; and isinstance(col, MySpecialCol):
 return repr(col)
 else:
 return False

context.configure(
 # ...
 render_item = my_render_column
)
</pre></div>
</div>
Available values for the type string include: <code class="docutils literal">&quot;column&quot;</code>,
<code class="docutils literal">&quot;primary_key&quot;</code>, <code class="docutils literal">&quot;foreign_key&quot;</code>, <code class="docutils literal">&quot;unique&quot;</code>, <code class="docutils literal">&quot;check&quot;</code>,
<code class="docutils literal">&quot;type&quot;</code>, <code class="docutils literal">&quot;server_default&quot;</code>.
<div class="admonition seealso">
See also
<a class="reference internal" href="../autogenerate.html#autogen-render-types">Affecting the Rendering of Types Themselves</a>
</div>
</li>
<li>upgrade_token<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.upgrade_token">¶</a> &#8211; When autogenerate completes, the text of the
candidate upgrade operations will be present in this template
variable when <code class="docutils literal">script.py.mako</code> is rendered. Defaults to
<code class="docutils literal">upgrades</code>.</li>
<li>downgrade_token<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.downgrade_token">¶</a> &#8211; When autogenerate completes, the text of the
candidate downgrade operations will be present in this
template variable when <code class="docutils literal">script.py.mako</code> is rendered. Defaults to
<code class="docutils literal">downgrades</code>.</li>
<li>alembic_module_prefix<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.alembic_module_prefix">¶</a> &#8211; When autogenerate refers to Alembic
<a class="reference internal" href="../ops.html#module-alembic.operations" title="alembic.operations"><code class="xref py py-mod docutils literal">alembic.operations</code></a> constructs, this prefix will be used
(i.e. <code class="docutils literal">op.create_table</code>) Defaults to &#8220;<code class="docutils literal">op.</code>&#8221;.
Can be <code class="docutils literal">None</code> to indicate no prefix.</li>
<li>sqlalchemy_module_prefix<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.sqlalchemy_module_prefix">¶</a> &#8211; When autogenerate refers to
SQLAlchemy
<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> or type classes, this prefix
will be used
(i.e. <code class="docutils literal">sa.Column(&quot;somename&quot;, sa.Integer)</code>) Defaults to &#8220;<code class="docutils literal">sa.</code>&#8221;.
Can be <code class="docutils literal">None</code> to indicate no prefix.
Note that when dialect-specific types are rendered, autogenerate
will render them using the dialect module name, i.e. <code class="docutils literal">mssql.BIT()</code>,
<code class="docutils literal">postgresql.UUID()</code>.</li>
<li>user_module_prefix<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.user_module_prefix">¶</a> &#8211; When autogenerate refers to a SQLAlchemy
type (e.g. <code class="xref py py-class docutils literal">TypeEngine</code>) where the module name is not
under the <code class="docutils literal">sqlalchemy</code> namespace, this prefix will be used
within autogenerate. If left at its default of
<code class="docutils literal">None</code>, the <code class="docutils literal">__module__</code> attribute of the type is used to
render the import module. It&#8217;s a good practice to set this
and to have all custom types be available from a fixed module space,
in order to future-proof migration files against reorganizations
in modules.
<div class="versionchanged">
Changed in version 0.7.0: <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.user_module_prefix" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.user_module_prefix</code></a>
no longer defaults to the value of
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.sqlalchemy_module_prefix" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.sqlalchemy_module_prefix</code></a>
when left at <code class="docutils literal">None</code>; the <code class="docutils literal">__module__</code> attribute is now used.
</div>
<div class="versionadded">
New in version 0.6.3: added
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.user_module_prefix" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-paramref docutils literal">EnvironmentContext.configure.user_module_prefix</code></a>
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="../autogenerate.html#autogen-module-prefix">Controlling the Module Prefix</a>
</div>
</li>
<li>process_revision_directives<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.process_revision_directives">¶</a> &#8211; a callable function that will
be passed a structure representing the end result of an autogenerate
or plain &#8220;revision&#8221; operation, which can be manipulated to affect
how the <code class="docutils literal">alembic revision</code> command ultimately outputs new
revision scripts. The structure of the callable is:
<div class="highlight-python"><div class="highlight"><pre>def process_revision_directives(context, revision, directives):
 pass
</pre></div>
</div>
The <code class="docutils literal">directives</code> parameter is a Python list containing
a single <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> directive, which represents
the revision file to be generated. This list as well as its
contents may be freely modified to produce any set of commands.
The section <a class="reference internal" href="autogenerate.html#customizing-revision">Customizing Revision Generation</a> shows an example of
doing this. The <code class="docutils literal">context</code> parameter is the
<a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> in use,
and <code class="docutils literal">revision</code> is a tuple of revision identifiers representing the
current revision of the database.
The callable is invoked at all times when the <code class="docutils literal">--autogenerate</code>
option is passed to <code class="docutils literal">alembic revision</code>. If <code class="docutils literal">--autogenerate</code>
is not passed, the callable is invoked only if the
<code class="docutils literal">revision_environment</code> variable is set to True in the Alembic
configuration, in which case the given <code class="docutils literal">directives</code> collection
will contain empty <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>
collections for <code class="docutils literal">.upgrade_ops</code> and <code class="docutils literal">.downgrade_ops</code>. The
<code class="docutils literal">--autogenerate</code> option itself can be inferred by inspecting
<code class="docutils literal">context.config.cmd_opts.autogenerate</code>.
The callable function may optionally be an instance of
a <a class="reference internal" href="autogenerate.html#alembic.autogenerate.rewriter.Rewriter" title="alembic.autogenerate.rewriter.Rewriter"><code class="xref py py-class docutils literal">Rewriter</code></a> object. This is a helper object that
assists in the production of autogenerate-stream rewriter functions.
<div class="versionadded">
New in version 0.8.0.
</div>
<div class="versionchanged">
Changed in version 0.8.1: - The
<a class="reference internal" href="#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 can append op directives into <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> which will be rendered in Python regardless
of whether the <code class="docutils literal">--autogenerate</code> option is in use or not;
the <code class="docutils literal">revision_environment</code> configuration variable should be
set to &#8220;true&#8221; in the config to enable this.
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="autogenerate.html#customizing-revision">Customizing Revision Generation</a>
<a class="reference internal" href="autogenerate.html#autogen-rewriter">Fine-Grained Autogenerate Generation with Rewriters</a>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
Parameters specific to individual backends:
<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>mssql_batch_separator<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.mssql_batch_separator">¶</a> &#8211; The &#8220;batch separator&#8221; which will
be placed between each statement when generating offline SQL Server
migrations. Defaults to <code class="docutils literal">GO</code>. Note this is in addition to the
customary semicolon <code class="docutils literal">;</code> at the end of each statement; SQL Server
considers the &#8220;batch separator&#8221; to denote the end of an
individual statement execution, and cannot group certain
dependent operations in one step.</li>
<li>oracle_batch_separator<a class="paramlink headerlink reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure.params.oracle_batch_separator">¶</a> &#8211; The &#8220;batch separator&#8221; which will
be placed between each statement when generating offline
Oracle migrations. Defaults to <code class="docutils literal">/</code>. Oracle doesn&#8217;t add a
semicolon between statements like most other backends.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.execute">
<code class="descname">execute</code>(sql, execution_options=None)<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.execute" title="Permalink to this definition">¶</a></dt>
<dd>Execute the given SQL using the current change context.
The behavior of <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.execute" title="alembic.runtime.environment.EnvironmentContext.execute"><code class="xref py py-meth docutils literal">execute()</code></a> is the same
as that of <a class="reference internal" href="../ops.html#alembic.operations.Operations.execute" title="alembic.operations.Operations.execute"><code class="xref py py-meth docutils literal">Operations.execute()</code></a>. Please see that
function&#8217;s documentation for full detail including
caveats and limitations.
This function requires that a <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> has
first been made available via <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">configure()</code></a>.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.get_bind">
<code class="descname">get_bind</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.get_bind" title="Permalink to this definition">¶</a></dt>
<dd>Return the current &#8216;bind&#8217;.
In &#8220;online&#8221; mode, this is the
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">sqlalchemy.engine.Connection</code></a> currently being used
to emit SQL to the database.
This function requires that a <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has first been made available via <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">configure()</code></a>.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.get_context">
<code class="descname">get_context</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.get_context" title="Permalink to this definition">¶</a></dt>
<dd>Return the current <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> object.
If <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">EnvironmentContext.configure()</code></a> has not been
called yet, raises an exception.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.get_head_revision">
<code class="descname">get_head_revision</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.get_head_revision" title="Permalink to this definition">¶</a></dt>
<dd>Return the hex identifier of the &#8216;head&#8217; script revision.
If the script directory has multiple heads, this
method raises a <code class="xref py py-class docutils literal">CommandError</code>;
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.get_head_revisions" title="alembic.runtime.environment.EnvironmentContext.get_head_revisions"><code class="xref py py-meth docutils literal">EnvironmentContext.get_head_revisions()</code></a> should be preferred.
This function does not require that the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has been configured.
<div class="admonition seealso">
See also
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.get_head_revisions" title="alembic.runtime.environment.EnvironmentContext.get_head_revisions"><code class="xref py py-meth docutils literal">EnvironmentContext.get_head_revisions()</code></a>
</div>
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.get_head_revisions">
<code class="descname">get_head_revisions</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.get_head_revisions" title="Permalink to this definition">¶</a></dt>
<dd>Return the hex identifier of the &#8216;heads&#8217; script revision(s).
This returns a tuple containing the version number of all
heads in the script directory.
This function does not require that the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has been configured.
<div class="versionadded">
New in version 0.7.0.
</div>
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.get_revision_argument">
<code class="descname">get_revision_argument</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.get_revision_argument" title="Permalink to this definition">¶</a></dt>
<dd>Get the &#8216;destination&#8217; revision argument.
This is typically the argument passed to the
<code class="docutils literal">upgrade</code> or <code class="docutils literal">downgrade</code> command.
If it was specified as <code class="docutils literal">head</code>, the actual
version number is returned; if specified
as <code class="docutils literal">base</code>, <code class="docutils literal">None</code> is returned.
This function does not require that the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has been configured.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.get_starting_revision_argument">
<code class="descname">get_starting_revision_argument</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.get_starting_revision_argument" title="Permalink to this definition">¶</a></dt>
<dd>Return the &#8216;starting revision&#8217; argument,
if the revision was passed using <code class="docutils literal">start:end</code>.
This is only meaningful in &#8220;offline&#8221; mode.
Returns <code class="docutils literal">None</code> if no value is available
or was configured.
This function does not require that the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has been configured.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.get_tag_argument">
<code class="descname">get_tag_argument</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.get_tag_argument" title="Permalink to this definition">¶</a></dt>
<dd>Return the value passed for the <code class="docutils literal">--tag</code> argument, if any.
The <code class="docutils literal">--tag</code> argument is not used directly by Alembic,
but is available for custom <code class="docutils literal">env.py</code> configurations that
wish to use it; particularly for offline generation scripts
that wish to generate tagged filenames.
This function does not require that the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has been configured.
<div class="admonition seealso">
See also
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.get_x_argument" title="alembic.runtime.environment.EnvironmentContext.get_x_argument"><code class="xref py py-meth docutils literal">EnvironmentContext.get_x_argument()</code></a> - a newer and more
open ended system of extending <code class="docutils literal">env.py</code> scripts via the command
line.
</div>
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.get_x_argument">
<code class="descname">get_x_argument</code>(as_dictionary=False)<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.get_x_argument" title="Permalink to this definition">¶</a></dt>
<dd>Return the value(s) passed for the <code class="docutils literal">-x</code> argument, if any.
The <code class="docutils literal">-x</code> argument is an open ended flag that allows any user-defined
value or values to be passed on the command line, then available
here for consumption by a custom <code class="docutils literal">env.py</code> script.
The return value is a list, returned directly from the <code class="docutils literal">argparse</code>
structure. If <code class="docutils literal">as_dictionary=True</code> is passed, the <code class="docutils literal">x</code> arguments
are parsed using <code class="docutils literal">key=value</code> format into a dictionary that is
then returned.
For example, to support passing a database URL on the command line,
the standard <code class="docutils literal">env.py</code> script can be modified like this:
<div class="highlight-python"><div class="highlight"><pre>cmd_line_url = context.get_x_argument(
 as_dictionary=True).get(&#39;dbname&#39;)
if cmd_line_url:
 engine = create_engine(cmd_line_url)
else:
 engine = engine_from_config(
 config.get_section(config.config_ini_section),
 prefix=&#39;sqlalchemy.&#39;,
 poolclass=pool.NullPool)
</pre></div>
</div>
This then takes effect by running the <code class="docutils literal">alembic</code> script as:
<div class="highlight-python"><div class="highlight"><pre>alembic -x dbname=postgresql://user:pass@host/dbname upgrade head
</pre></div>
</div>
This function does not require that the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has been configured.
<div class="versionadded">
New in version 0.6.0.
</div>
<div class="admonition seealso">
See also
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.get_tag_argument" title="alembic.runtime.environment.EnvironmentContext.get_tag_argument"><code class="xref py py-meth docutils literal">EnvironmentContext.get_tag_argument()</code></a>
<a class="reference internal" href="config.html#alembic.config.Config.cmd_opts" title="alembic.config.Config.cmd_opts"><code class="xref py py-attr docutils literal">Config.cmd_opts</code></a>
</div>
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.is_offline_mode">
<code class="descname">is_offline_mode</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.is_offline_mode" title="Permalink to this definition">¶</a></dt>
<dd>Return True if the current migrations environment
is running in &#8220;offline mode&#8221;.
This is <code class="docutils literal">True</code> or <code class="docutils literal">False</code> depending
on the the <code class="docutils literal">--sql</code> flag passed.
This function does not require that the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has been configured.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.is_transactional_ddl">
<code class="descname">is_transactional_ddl</code>()<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.is_transactional_ddl" title="Permalink to this definition">¶</a></dt>
<dd>Return True if the context is configured to expect a
transactional DDL capable backend.
This defaults to the type of database in use, and
can be overridden by the <code class="docutils literal">transactional_ddl</code> argument
to <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">configure()</code></a>
This function requires that a <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
has first been made available via <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">configure()</code></a>.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.run_migrations">
<code class="descname">run_migrations</code>(**kw)<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.run_migrations" title="Permalink to this definition">¶</a></dt>
<dd>Run migrations as determined by the current command line
configuration
as well as versioning information present (or not) in the current
database connection (if one is present).
The function accepts optional <code class="docutils literal">**kw</code> arguments. If these are
passed, they are sent directly to the <code class="docutils literal">upgrade()</code> and
<code class="docutils literal">downgrade()</code>
functions within each target revision file. By modifying the
<code class="docutils literal">script.py.mako</code> file so that the <code class="docutils literal">upgrade()</code> and <code class="docutils literal">downgrade()</code>
functions accept arguments, parameters can be passed here so that
contextual information, usually information to identify a particular
database in use, can be passed from a custom <code class="docutils literal">env.py</code> script
to the migration functions.
This function requires that a <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> has
first been made available via <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">configure()</code></a>.
</dd></dl>

<dl class="attribute">
<dt id="alembic.runtime.environment.EnvironmentContext.script">
<code class="descname">script</code> = None<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.script" title="Permalink to this definition">¶</a></dt>
<dd>An instance of <a class="reference internal" href="script.html#alembic.script.ScriptDirectory" title="alembic.script.ScriptDirectory"><code class="xref py py-class docutils literal">ScriptDirectory</code></a> which provides
programmatic access to version files within the <code class="docutils literal">versions/</code>
directory.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.environment.EnvironmentContext.static_output">
<code class="descname">static_output</code>(text)<a class="headerlink" href="#alembic.runtime.environment.EnvironmentContext.static_output" title="Permalink to this definition">¶</a></dt>
<dd>Emit text directly to the &#8220;offline&#8221; SQL stream.
Typically this is for emitting comments that
start with &#8211;. The statement is not treated
as a SQL execution, no ; or batch separator
is added, etc.
</dd></dl>

</dd></dl>

</div>
<div class="section" id="the-migration-context">
<h2>The Migration Context<a class="headerlink" href="#the-migration-context" title="Permalink to this headline">¶</a></h2>
The <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> handles the actual work to be performed
against a database backend as migration operations proceed. It is generally
not exposed to the end-user.
<dl class="class">
<dt id="alembic.runtime.migration.MigrationContext">
class <code class="descclassname">alembic.runtime.migration.</code><code class="descname">MigrationContext</code>(dialect, connection, opts, environment_context=None)<a class="headerlink" href="#alembic.runtime.migration.MigrationContext" title="Permalink to this definition">¶</a></dt>
<dd>Represent the database state made available to a migration
script.
<a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> is the front end to an actual
database connection, or alternatively a string output
stream given a particular database dialect,
from an Alembic perspective.
When inside the <code class="docutils literal">env.py</code> script, the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
is available via the
<a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.get_context" title="alembic.runtime.environment.EnvironmentContext.get_context"><code class="xref py py-meth docutils literal">EnvironmentContext.get_context()</code></a> method,
which is available at <code class="docutils literal">alembic.context</code>:
<div class="highlight-python"><div class="highlight"><pre># from within env.py script
from alembic import context
migration_context = context.get_context()
</pre></div>
</div>
For usage outside of an <code class="docutils literal">env.py</code> script, such as for
utility routines that want to check the current version
in the database, the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext.configure" title="alembic.runtime.migration.MigrationContext.configure"><code class="xref py py-meth docutils literal">MigrationContext.configure()</code></a>
method to create new <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> objects.
For example, to get at the current revision in the
database using <a class="reference internal" href="#alembic.runtime.migration.MigrationContext.get_current_revision" title="alembic.runtime.migration.MigrationContext.get_current_revision"><code class="xref py py-meth docutils literal">MigrationContext.get_current_revision()</code></a>:
<div class="highlight-python"><div class="highlight"><pre># in any application, outside of an env.py script
from alembic.migration import MigrationContext
from sqlalchemy import create_engine

engine = create_engine(&quot;postgresql://mydatabase&quot;)
conn = engine.connect()

context = MigrationContext.configure(conn)
current_rev = context.get_current_revision()
</pre></div>
</div>
The above context can also be used to produce
Alembic migration operations with an <a class="reference internal" href="../ops.html#alembic.operations.Operations" title="alembic.operations.Operations"><code class="xref py py-class docutils literal">Operations</code></a>
instance:
<div class="highlight-python"><div class="highlight"><pre># in any application, outside of the normal Alembic environment
from alembic.operations import Operations
op = Operations(context)
op.alter_column(&quot;mytable&quot;, &quot;somecolumn&quot;, nullable=True)
</pre></div>
</div>
<dl class="attribute">
<dt id="alembic.runtime.migration.MigrationContext.bind">
<code class="descname">bind</code><a class="headerlink" href="#alembic.runtime.migration.MigrationContext.bind" title="Permalink to this definition">¶</a></dt>
<dd>Return the current &#8220;bind&#8221;.
In online mode, this is an instance of
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">sqlalchemy.engine.Connection</code></a>, and is suitable
for ad-hoc execution of any kind of usage described
in <a class="reference external" href="http://www.sqlalchemy.org/docs/core/tutorial.html#sqlexpression-toplevel" title="(in SQLAlchemy v1.0)">SQL Expression Language Tutorial</a> as well as
for usage with the <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.Table.create" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal">sqlalchemy.schema.Table.create()</code></a>
and <a class="reference external" href="http://www.sqlalchemy.org/docs/core/metadata.html#sqlalchemy.schema.MetaData.create_all" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal">sqlalchemy.schema.MetaData.create_all()</code></a> methods
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>,
<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>.
Note that when &#8220;standard output&#8221; mode is enabled,
this bind will be a &#8220;mock&#8221; connection handler that cannot
return results and is only appropriate for a very limited
subset of commands.
</dd></dl>

<dl class="attribute">
<dt id="alembic.runtime.migration.MigrationContext.config">
<code class="descname">config</code><a class="headerlink" href="#alembic.runtime.migration.MigrationContext.config" title="Permalink to this definition">¶</a></dt>
<dd>Return the <a class="reference internal" href="config.html#alembic.config.Config" title="alembic.config.Config"><code class="xref py py-class docutils literal">Config</code></a> used by the current environment, if any.
<div class="versionadded">
New in version 0.6.6.
</div>
</dd></dl>

<dl class="classmethod">
<dt id="alembic.runtime.migration.MigrationContext.configure">
classmethod <code class="descname">configure</code>(connection=None, url=None, dialect_name=None, dialect=None, environment_context=None, opts=None)<a class="headerlink" href="#alembic.runtime.migration.MigrationContext.configure" title="Permalink to this definition">¶</a></dt>
<dd>Create a new <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>.
This is a factory method usually called
by <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">EnvironmentContext.configure()</code></a>.
<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>connection<a class="paramlink headerlink reference internal" href="#alembic.runtime.migration.MigrationContext.configure.params.connection">¶</a> &#8211; a <a class="reference external" href="http://www.sqlalchemy.org/docs/core/connections.html#sqlalchemy.engine.Connection" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">Connection</code></a>
to use for SQL execution in &#8220;online&#8221; mode. When present,
is also used to determine the type of dialect in use.</li>
<li>url<a class="paramlink headerlink reference internal" href="#alembic.runtime.migration.MigrationContext.configure.params.url">¶</a> &#8211; a string database url, or a
<a class="reference external" href="http://www.sqlalchemy.org/docs/core/engines.html#sqlalchemy.engine.url.URL" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal">sqlalchemy.engine.url.URL</code></a> object.
The type of dialect to be used will be derived from this if
<code class="docutils literal">connection</code> is not passed.</li>
<li>dialect_name<a class="paramlink headerlink reference internal" href="#alembic.runtime.migration.MigrationContext.configure.params.dialect_name">¶</a> &#8211; string name of a dialect, such as
&#8220;postgresql&#8221;, &#8220;mssql&#8221;, etc. The type of dialect to be used will be
derived from this if <code class="docutils literal">connection</code> and <code class="docutils literal">url</code> are not passed.</li>
<li>opts<a class="paramlink headerlink reference internal" href="#alembic.runtime.migration.MigrationContext.configure.params.opts">¶</a> &#8211; dictionary of options. Most other options
accepted by <a class="reference internal" href="#alembic.runtime.environment.EnvironmentContext.configure" title="alembic.runtime.environment.EnvironmentContext.configure"><code class="xref py py-meth docutils literal">EnvironmentContext.configure()</code></a> are passed via
this dictionary.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.migration.MigrationContext.execute">
<code class="descname">execute</code>(sql, execution_options=None)<a class="headerlink" href="#alembic.runtime.migration.MigrationContext.execute" title="Permalink to this definition">¶</a></dt>
<dd>Execute a SQL construct or string statement.
The underlying execution mechanics are used, that is
if this is &#8220;offline mode&#8221; the SQL is written to the
output buffer, otherwise the SQL is emitted on
the current SQLAlchemy connection.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.migration.MigrationContext.get_current_heads">
<code class="descname">get_current_heads</code>()<a class="headerlink" href="#alembic.runtime.migration.MigrationContext.get_current_heads" title="Permalink to this definition">¶</a></dt>
<dd>Return a tuple of the current &#8216;head versions&#8217; that are represented
in the target database.
For a migration stream without branches, this will be a single
value, synonymous with that of
<a class="reference internal" href="#alembic.runtime.migration.MigrationContext.get_current_revision" title="alembic.runtime.migration.MigrationContext.get_current_revision"><code class="xref py py-meth docutils literal">MigrationContext.get_current_revision()</code></a>. However when multiple
unmerged branches exist within the target database, the returned tuple
will contain a value for each head.
If this <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> was configured in &#8220;offline&#8221;
mode, that is with <code class="docutils literal">as_sql=True</code>, the <code class="docutils literal">starting_rev</code>
parameter is returned in a one-length tuple.
If no version table is present, or if there are no revisions
present, an empty tuple is returned.
<div class="versionadded">
New in version 0.7.0.
</div>
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.migration.MigrationContext.get_current_revision">
<code class="descname">get_current_revision</code>()<a class="headerlink" href="#alembic.runtime.migration.MigrationContext.get_current_revision" title="Permalink to this definition">¶</a></dt>
<dd>Return the current revision, usually that which is present
in the <code class="docutils literal">alembic_version</code> table in the database.
This method intends to be used only for a migration stream that
does not contain unmerged branches in the target database;
if there are multiple branches present, an exception is raised.
The <a class="reference internal" href="#alembic.runtime.migration.MigrationContext.get_current_heads" title="alembic.runtime.migration.MigrationContext.get_current_heads"><code class="xref py py-meth docutils literal">MigrationContext.get_current_heads()</code></a> should be preferred
over this method going forward in order to be compatible with
branch migration support.
If this <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a> was configured in &#8220;offline&#8221;
mode, that is with <code class="docutils literal">as_sql=True</code>, the <code class="docutils literal">starting_rev</code>
parameter is returned instead, if any.
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.migration.MigrationContext.run_migrations">
<code class="descname">run_migrations</code>(**kw)<a class="headerlink" href="#alembic.runtime.migration.MigrationContext.run_migrations" title="Permalink to this definition">¶</a></dt>
<dd>Run the migration scripts established for this
<a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>, if any.
The commands in <a class="reference internal" href="commands.html#module-alembic.command" title="alembic.command"><code class="xref py py-mod docutils literal">alembic.command</code></a> will set up a function
that is ultimately passed to the <a class="reference internal" href="#alembic.runtime.migration.MigrationContext" title="alembic.runtime.migration.MigrationContext"><code class="xref py py-class docutils literal">MigrationContext</code></a>
as the <code class="docutils literal">fn</code> argument. This function represents the &#8220;work&#8221;
that will be done when <a class="reference internal" href="#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 called, typically from within the <code class="docutils literal">env.py</code> script of the
migration environment. The &#8220;work function&#8221; then provides an iterable
of version callables and other version information which
in the case of the <code class="docutils literal">upgrade</code> or <code class="docutils literal">downgrade</code> commands are the
list of version scripts to invoke. Other commands yield nothing,
in the case that a command wants to run some other operation
against the database such as the <code class="docutils literal">current</code> or <code class="docutils literal">stamp</code> commands.
<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">**kw<a class="paramlink headerlink reference internal" href="#alembic.runtime.migration.MigrationContext.run_migrations.params.**kw">¶</a> &#8211; keyword arguments here will be passed to each
migration callable, that is the <code class="docutils literal">upgrade()</code> or <code class="docutils literal">downgrade()</code>
method within revision scripts.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="alembic.runtime.migration.MigrationContext.stamp">
<code class="descname">stamp</code>(script_directory, revision)<a class="headerlink" href="#alembic.runtime.migration.MigrationContext.stamp" title="Permalink to this definition">¶</a></dt>
<dd>Stamp the version table with a specific revision.
This method calculates those branches to which the given revision
can apply, and updates those branches as though they were migrated
towards that revision (either up or down). If no current branches
include the revision, it is added as a new branch head.
<div class="versionadded">
New in version 0.7.0.
</div>
</dd></dl>

</dd></dl>

</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="#">Runtime Objects</a><ul>
<li><a class="reference internal" href="#the-environment-context">The Environment Context</a></li>
<li><a class="reference internal" href="#the-migration-context">The Migration Context</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="overview.html"
 title="previous chapter">Overview</a>
 <h4>Next topic</h4>
 <a href="config.html"
 title="next chapter">Configuration</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../_sources/api/runtime.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="config.html" title="Configuration"
 >next</a> |</li>
 <li class="right" >
 <a href="overview.html" title="Overview"
 >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>