ok
Mini Shell
<!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>Working with Branches — 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="next" title="Operation Reference" href="ops.html" />
<link rel="prev" title="Running “Batch” Migrations for SQLite and Other Databases" href="batch.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="ops.html" title="Operation Reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="batch.html" title="Running “Batch” Migrations for SQLite and Other Databases"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Alembic 0.8.3 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<p>f.. _branches:</p>
<div class="section" id="working-with-branches">
<h1>Working with Branches<a class="headerlink" href="#working-with-branches" title="Permalink to this headline">¶</a></h1>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Alembic 0.7.0 features an all-new versioning model that fully
supports branch points, merge points, and long-lived, labeled branches,
including independent branches originating from multiple bases.
A great emphasis has been placed on there being almost no impact on the
existing Alembic workflow, including that all commands work pretty much
the same as they did before, the format of migration files doesn’t require
any change (though there are some changes that are recommended),
and even the structure of the <code class="docutils literal"><span class="pre">alembic_version</span></code>
table does not change at all. However, most alembic commands now offer
new features which will break out an Alembic environment into
“branch mode”, where things become a lot more intricate. Working in
“branch mode” should be considered as a “beta” feature, with many new
paradigms and use cases still to be stress tested in the wild.
Please tread lightly!</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.7.0.</span></p>
</div>
<p>A <strong>branch</strong> describes a point in a migration stream when two or more
versions refer to the same parent migration as their anscestor. Branches
occur naturally when two divergent source trees, both containing Alembic
revision files created independently within those source trees, are merged
together into one. When this occurs, the challenge of a branch is to <strong>merge</strong> the
branches into a single series of changes, so that databases established
from either source tree individually can be upgraded to reference the merged
result equally. Another scenario where branches are present are when we create them
directly; either at some point in the migration stream we’d like different
series of migrations to be managed independently (e.g. we create a tree),
or we’d like separate migration streams for different features starting
at the root (e.g. a <em>forest</em>). We’ll illustrate all of these cases, starting
with the most common which is a source-merge-originated branch that we’ll
merge.</p>
<p>Starting with the “account table” example we began in <a class="reference internal" href="tutorial.html#create-migration"><span>Create a Migration Script</span></a>,
assume we have our basemost version <code class="docutils literal"><span class="pre">1975ea83b712</span></code>, which leads into
the second revision <code class="docutils literal"><span class="pre">ae1027a6acf</span></code>, and the migration files for these
two revisions are checked into our source repository.
Consider if we merged into our source repository another code branch which contained
a revision for another table called <code class="docutils literal"><span class="pre">shopping_cart</span></code>. This revision was made
against our first Alembic revision, the one that generated <code class="docutils literal"><span class="pre">account</span></code>. After
loading the second source tree in, a new file
<code class="docutils literal"><span class="pre">27c6a30d7c24_add_shopping_cart_table.py</span></code> exists within our <code class="docutils literal"><span class="pre">versions</span></code> directory.
Both it, as well as <code class="docutils literal"><span class="pre">ae1027a6acf_add_a_column.py</span></code>, reference
<code class="docutils literal"><span class="pre">1975ea83b712_add_account_table.py</span></code> as the “downgrade” revision. To illustrate:</p>
<div class="highlight-python"><div class="highlight"><pre># main source tree:
1975ea83b712 (create account table) -> ae1027a6acf (add a column)
# branched source tree
1975ea83b712 (create account table) -> 27c6a30d7c24 (add shopping cart table)
</pre></div>
</div>
<p>Above, we can see <code class="docutils literal"><span class="pre">1975ea83b712</span></code> is our <strong>branch point</strong>; two distinct versions
both refer to it as its parent. The Alembic command <code class="docutils literal"><span class="pre">branches</span></code> illustrates
this fact:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic branches --verbose
Rev: 1975ea83b712 (branchpoint)
Parent: <base>
Branches into: 27c6a30d7c24, ae1027a6acf
Path: foo/versions/1975ea83b712_add_account_table.py
create account table
Revision ID: 1975ea83b712
Revises:
Create Date: 2014-11-20 13:02:46.257104
-> 27c6a30d7c24 (head), add shopping cart table
-> ae1027a6acf (head), add a column
</pre></div>
</div>
<p>History shows it too, illustrating two <code class="docutils literal"><span class="pre">head</span></code> entries as well
as a <code class="docutils literal"><span class="pre">branchpoint</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history
1975ea83b712 -> 27c6a30d7c24 (head), add shopping cart table
1975ea83b712 -> ae1027a6acf (head), add a column
<base> -> 1975ea83b712 (branchpoint), create account table
</pre></div>
</div>
<p>We can get a view of just the current heads using <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">heads</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic heads --verbose
Rev: 27c6a30d7c24 (head)
Parent: 1975ea83b712
Path: foo/versions/27c6a30d7c24_add_shopping_cart_table.py
add shopping cart table
Revision ID: 27c6a30d7c24
Revises: 1975ea83b712
Create Date: 2014-11-20 13:03:11.436407
Rev: ae1027a6acf (head)
Parent: 1975ea83b712
Path: foo/versions/ae1027a6acf_add_a_column.py
add a column
Revision ID: ae1027a6acf
Revises: 1975ea83b712
Create Date: 2014-11-20 13:02:54.849677
</pre></div>
</div>
<p>If we try to run an <code class="docutils literal"><span class="pre">upgrade</span></code> to the usual end target of <code class="docutils literal"><span class="pre">head</span></code>, Alembic no
longer considers this to be an unambiguous command. As we have more than
one <code class="docutils literal"><span class="pre">head</span></code>, the <code class="docutils literal"><span class="pre">upgrade</span></code> command wants us to provide more information:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade head
FAILED: Multiple head revisions are present for given argument 'head'; please specify a specific
target revision, '<branchname>@head' to narrow to a specific head, or 'heads' for all heads
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">upgrade</span></code> command gives us quite a few options in which we can proceed
with our upgrade, either giving it information on <em>which</em> head we’d like to upgrade
towards, or alternatively stating that we’d like <em>all</em> heads to be upgraded
towards at once. However, in the typical case of two source trees being
merged, we will want to pursue a third option, which is that we can <strong>merge</strong> these
branches.</p>
<div class="section" id="merging-branches">
<h2>Merging Branches<a class="headerlink" href="#merging-branches" title="Permalink to this headline">¶</a></h2>
<p>An Alembic merge is a migration file that joins two or
more “head” files together. If the two branches we have right now can
be said to be a “tree” structure, introducing this merge file will
turn it into a “diamond” structure:</p>
<div class="highlight-python"><div class="highlight"><pre> -- ae1027a6acf -->
/ \
<base> --> 1975ea83b712 --> --> mergepoint
\ /
-- 27c6a30d7c24 -->
</pre></div>
</div>
<p>We create the merge file using <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">merge</span></code>; with this command, we can
pass to it an argument such as <code class="docutils literal"><span class="pre">heads</span></code>, meaning we’d like to merge all
heads. Or, we can pass it individual revision numbers sequentally:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic merge -m "merge ae1 and 27c" ae1027 27c6a
Generating /path/to/foo/versions/53fffde5ad5_merge_ae1_and_27c.py ... done
</pre></div>
</div>
<p>Looking inside the new file, we see it as a regular migration file, with
the only new twist is that <code class="docutils literal"><span class="pre">down_revision</span></code> points to both revisions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="sd">"""merge ae1 and 27c</span>
<span class="sd">Revision ID: 53fffde5ad5</span>
<span class="sd">Revises: ae1027a6acf, 27c6a30d7c24</span>
<span class="sd">Create Date: 2014-11-20 13:31:50.811663</span>
<span class="sd">"""</span>
<span class="c"># revision identifiers, used by Alembic.</span>
<span class="n">revision</span> <span class="o">=</span> <span class="s">'53fffde5ad5'</span>
<span class="n">down_revision</span> <span class="o">=</span> <span class="p">(</span><span class="s">'ae1027a6acf'</span><span class="p">,</span> <span class="s">'27c6a30d7c24'</span><span class="p">)</span>
<span class="n">branch_labels</span> <span class="o">=</span> <span class="bp">None</span>
<span class="kn">from</span> <span class="nn">alembic</span> <span class="kn">import</span> <span class="n">op</span>
<span class="kn">import</span> <span class="nn">sqlalchemy</span> <span class="kn">as</span> <span class="nn">sa</span>
<span class="k">def</span> <span class="nf">upgrade</span><span class="p">():</span>
<span class="k">pass</span>
<span class="k">def</span> <span class="nf">downgrade</span><span class="p">():</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>This file is a regular migration file, and if we wish to, we may place
<a class="reference internal" href="ops.html#alembic.operations.Operations" title="alembic.operations.Operations"><code class="xref py py-class docutils literal"><span class="pre">Operations</span></code></a> directives into the <code class="docutils literal"><span class="pre">upgrade()</span></code> and <code class="docutils literal"><span class="pre">downgrade()</span></code>
functions like any other migration file. Though it is probably best to limit
the instructions placed here only to those that deal with any kind of
reconciliation that is needed between the two merged branches, if any.</p>
<p>The <code class="docutils literal"><span class="pre">heads</span></code> command now illustrates that the multiple heads in our
<code class="docutils literal"><span class="pre">versions/</span></code> directory have been resolved into our new head:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic heads --verbose
Rev: 53fffde5ad5 (head) (mergepoint)
Merges: ae1027a6acf, 27c6a30d7c24
Path: foo/versions/53fffde5ad5_merge_ae1_and_27c.py
merge ae1 and 27c
Revision ID: 53fffde5ad5
Revises: ae1027a6acf, 27c6a30d7c24
Create Date: 2014-11-20 13:31:50.811663
</pre></div>
</div>
<p>History shows a similar result, as the mergepoint becomes our head:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history
ae1027a6acf, 27c6a30d7c24 -> 53fffde5ad5 (head) (mergepoint), merge ae1 and 27c
1975ea83b712 -> ae1027a6acf, add a column
1975ea83b712 -> 27c6a30d7c24, add shopping cart table
<base> -> 1975ea83b712 (branchpoint), create account table
</pre></div>
</div>
<p>With a single <code class="docutils literal"><span class="pre">head</span></code> target, a generic <code class="docutils literal"><span class="pre">upgrade</span></code> can proceed:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade head
INFO [alembic.migration] Context impl PostgresqlImpl.
INFO [alembic.migration] Will assume transactional DDL.
INFO [alembic.migration] Running upgrade -> 1975ea83b712, create account table
INFO [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
INFO [alembic.migration] Running upgrade 1975ea83b712 -> ae1027a6acf, add a column
INFO [alembic.migration] Running upgrade ae1027a6acf, 27c6a30d7c24 -> 53fffde5ad5, merge ae1 and 27c
</pre></div>
</div>
<div class="topic">
<p class="topic-title first">merge mechanics</p>
<p>The upgrade process traverses through all of our migration files using
a <strong>topological sorting</strong> algorithm, treating the list of migration
files not as a linked list, but as a <strong>directed acyclic graph</strong>. The starting
points of this traversal are the <strong>current heads</strong> within our database,
and the end point is the “head” revision or revisions specified.</p>
<p>When a migration proceeds across a point at which there are multiple heads,
the <code class="docutils literal"><span class="pre">alembic_version</span></code> table will at that point store <em>multiple</em> rows,
one for each head. Our migration process above will emit SQL against
<code class="docutils literal"><span class="pre">alembic_version</span></code> along these lines:</p>
<blockquote>
<div><div class="highlight-sql"><div class="highlight"><pre><span class="c1">-- Running upgrade -> 1975ea83b712, create account table</span>
<span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">alembic_version</span> <span class="p">(</span><span class="n">version_num</span><span class="p">)</span> <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'1975ea83b712'</span><span class="p">)</span>
<span class="c1">-- Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table</span>
<span class="k">UPDATE</span> <span class="n">alembic_version</span> <span class="k">SET</span> <span class="n">version_num</span><span class="o">=</span><span class="s1">'27c6a30d7c24'</span> <span class="k">WHERE</span> <span class="n">alembic_version</span><span class="p">.</span><span class="n">version_num</span> <span class="o">=</span> <span class="s1">'1975ea83b712'</span>
<span class="c1">-- Running upgrade 1975ea83b712 -> ae1027a6acf, add a column</span>
<span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">alembic_version</span> <span class="p">(</span><span class="n">version_num</span><span class="p">)</span> <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'ae1027a6acf'</span><span class="p">)</span>
<span class="c1">-- Running upgrade ae1027a6acf, 27c6a30d7c24 -> 53fffde5ad5, merge ae1 and 27c</span>
<span class="k">DELETE</span> <span class="k">FROM</span> <span class="n">alembic_version</span> <span class="k">WHERE</span> <span class="n">alembic_version</span><span class="p">.</span><span class="n">version_num</span> <span class="o">=</span> <span class="s1">'ae1027a6acf'</span>
<span class="k">UPDATE</span> <span class="n">alembic_version</span> <span class="k">SET</span> <span class="n">version_num</span><span class="o">=</span><span class="s1">'53fffde5ad5'</span> <span class="k">WHERE</span> <span class="n">alembic_version</span><span class="p">.</span><span class="n">version_num</span> <span class="o">=</span> <span class="s1">'27c6a30d7c24'</span>
</pre></div>
</div>
</div></blockquote>
<p>At the point at which both <code class="docutils literal"><span class="pre">27c6a30d7c24</span></code> and <code class="docutils literal"><span class="pre">ae1027a6acf</span></code> exist within our
database, both values are present in <code class="docutils literal"><span class="pre">alembic_version</span></code>, which now has
two rows. If we upgrade to these two versions alone, then stop and
run <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">current</span></code>, we will see this:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic current --verbose
Current revision(s) for postgresql://scott:XXXXX@localhost/test:
Rev: ae1027a6acf
Parent: 1975ea83b712
Path: foo/versions/ae1027a6acf_add_a_column.py
add a column
Revision ID: ae1027a6acf
Revises: 1975ea83b712
Create Date: 2014-11-20 13:02:54.849677
Rev: 27c6a30d7c24
Parent: 1975ea83b712
Path: foo/versions/27c6a30d7c24_add_shopping_cart_table.py
add shopping cart table
Revision ID: 27c6a30d7c24
Revises: 1975ea83b712
Create Date: 2014-11-20 13:03:11.436407
</pre></div>
</div>
<p>A key advantage to the <code class="docutils literal"><span class="pre">merge</span></code> process is that it will
run equally well on databases that were present on version <code class="docutils literal"><span class="pre">ae1027a6acf</span></code>
alone, versus databases that were present on version <code class="docutils literal"><span class="pre">27c6a30d7c24</span></code> alone;
whichever version was not yet applied, will be applied before the merge point
can be crossed. This brings forth a way of thinking about a merge file,
as well as about any Alembic revision file. As they are considered to
be “nodes” within a set that is subject to topological sorting, each
“node” is a point that cannot be crossed until all of its dependencies
are satisfied.</p>
<p>Prior to Alembic’s support of merge points, the use case of databases
sitting on different heads was basically impossible to reconcile; having
to manually splice the head files together invariably meant that one migration
would occur before the other, thus being incompatible with databases that
were present on the other migration.</p>
</div>
</div>
<div class="section" id="working-with-explicit-branches">
<h2>Working with Explicit Branches<a class="headerlink" href="#working-with-explicit-branches" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">upgrade</span></code> command hinted at other options besides merging when
dealing with multiple heads. Let’s back up and assume we’re back where
we have as our heads just <code class="docutils literal"><span class="pre">ae1027a6acf</span></code> and <code class="docutils literal"><span class="pre">27c6a30d7c24</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic heads
27c6a30d7c24
ae1027a6acf
</pre></div>
</div>
<p>Earlier, when we did <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">upgrade</span> <span class="pre">head</span></code>, it gave us an error which
suggested <code class="docutils literal"><span class="pre">please</span> <span class="pre">specify</span> <span class="pre">a</span> <span class="pre">specific</span> <span class="pre">target</span> <span class="pre">revision,</span> <span class="pre">'<branchname>@head'</span> <span class="pre">to</span>
<span class="pre">narrow</span> <span class="pre">to</span> <span class="pre">a</span> <span class="pre">specific</span> <span class="pre">head,</span> <span class="pre">or</span> <span class="pre">'heads'</span> <span class="pre">for</span> <span class="pre">all</span> <span class="pre">heads</span></code> in order to proceed
without merging. Let’s cover those cases.</p>
<div class="section" id="referring-to-all-heads-at-once">
<h3>Referring to all heads at once<a class="headerlink" href="#referring-to-all-heads-at-once" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal"><span class="pre">heads</span></code> identifier is a lot like <code class="docutils literal"><span class="pre">head</span></code>, except it explicitly refers
to <em>all</em> heads at once. That is, it’s like telling Alembic to do the operation
for both <code class="docutils literal"><span class="pre">ae1027a6acf</span></code> and <code class="docutils literal"><span class="pre">27c6a30d7c24</span></code> simultaneously. If we started
from a fresh database and ran <code class="docutils literal"><span class="pre">upgrade</span> <span class="pre">heads</span></code> we’d see:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade heads
INFO [alembic.migration] Context impl PostgresqlImpl.
INFO [alembic.migration] Will assume transactional DDL.
INFO [alembic.migration] Running upgrade -> 1975ea83b712, create account table
INFO [alembic.migration] Running upgrade 1975ea83b712 -> ae1027a6acf, add a column
INFO [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
</pre></div>
</div>
<p>Since we’ve upgraded to <code class="docutils literal"><span class="pre">heads</span></code>, and we do in fact have more than one head,
that means these two distinct heads are now in our <code class="docutils literal"><span class="pre">alembic_version</span></code> table.
We can see this if we run <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">current</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic current
ae1027a6acf (head)
27c6a30d7c24 (head)
</pre></div>
</div>
<p>That means there’s two rows in <code class="docutils literal"><span class="pre">alembic_version</span></code> right now. If we downgrade
one step at a time, Alembic will <strong>delete</strong> from the <code class="docutils literal"><span class="pre">alembic_version</span></code> table
each branch that’s closed out, until only one branch remains; then it will
continue updating the single value down to the previous versions:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic downgrade -1
INFO [alembic.migration] Running downgrade ae1027a6acf -> 1975ea83b712, add a column
$ alembic current
27c6a30d7c24 (head)
$ alembic downgrade -1
INFO [alembic.migration] Running downgrade 27c6a30d7c24 -> 1975ea83b712, add shopping cart table
$ alembic current
1975ea83b712 (branchpoint)
$ alembic downgrade -1
INFO [alembic.migration] Running downgrade 1975ea83b712 -> , create account table
$ alembic current
</pre></div>
</div>
</div>
<div class="section" id="referring-to-a-specific-version">
<h3>Referring to a Specific Version<a class="headerlink" href="#referring-to-a-specific-version" title="Permalink to this headline">¶</a></h3>
<p>We can pass a specific version number to <code class="docutils literal"><span class="pre">upgrade</span></code>. Alembic will ensure that
all revisions upon which this version depends are invoked, and nothing more.
So if we <code class="docutils literal"><span class="pre">upgrade</span></code> either to <code class="docutils literal"><span class="pre">27c6a30d7c24</span></code> or <code class="docutils literal"><span class="pre">ae1027a6acf</span></code> specifically,
it guarantees that <code class="docutils literal"><span class="pre">1975ea83b712</span></code> will have been applied, but not that
any “sibling” versions are applied:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade 27c6a
INFO [alembic.migration] Running upgrade -> 1975ea83b712, create account table
INFO [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
</pre></div>
</div>
<p>With <code class="docutils literal"><span class="pre">1975ea83b712</span></code> and <code class="docutils literal"><span class="pre">27c6a30d7c24</span></code> applied, <code class="docutils literal"><span class="pre">ae1027a6acf</span></code> is just
a single additional step:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade ae102
INFO [alembic.migration] Running upgrade 1975ea83b712 -> ae1027a6acf, add a column
</pre></div>
</div>
</div>
<div class="section" id="working-with-branch-labels">
<h3>Working with Branch Labels<a class="headerlink" href="#working-with-branch-labels" title="Permalink to this headline">¶</a></h3>
<p>To satisfy the use case where an environment has long-lived branches, especially
independent branches as will be discussed in the next section, Alembic supports
the concept of <strong>branch labels</strong>. These are string values that are present
within the migration file, using the new identifier <code class="docutils literal"><span class="pre">branch_labels</span></code>.
For example, if we want to refer to the “shopping cart” branch using the name
“shoppingcart”, we can add that name to our file
<code class="docutils literal"><span class="pre">27c6a30d7c24_add_shopping_cart_table.py</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="sd">"""add shopping cart table</span>
<span class="sd">"""</span>
<span class="c"># revision identifiers, used by Alembic.</span>
<span class="n">revision</span> <span class="o">=</span> <span class="s">'27c6a30d7c24'</span>
<span class="n">down_revision</span> <span class="o">=</span> <span class="s">'1975ea83b712'</span>
<span class="n">branch_labels</span> <span class="o">=</span> <span class="p">(</span><span class="s">'shoppingcart'</span><span class="p">,)</span>
<span class="c"># ...</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">branch_labels</span></code> attribute refers to a string name, or a tuple
of names, which will now apply to this revision, all descendants of this
revision, as well as all ancestors of this revision up until the preceding
branch point, in this case <code class="docutils literal"><span class="pre">1975ea83b712</span></code>. We can see the <code class="docutils literal"><span class="pre">shoppingcart</span></code>
label applied to this revision:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history
1975ea83b712 -> 27c6a30d7c24 (shoppingcart) (head), add shopping cart table
1975ea83b712 -> ae1027a6acf (head), add a column
<base> -> 1975ea83b712 (branchpoint), create account table
</pre></div>
</div>
<p>With the label applied, the name <code class="docutils literal"><span class="pre">shoppingcart</span></code> now serves as an alias
for the <code class="docutils literal"><span class="pre">27c6a30d7c24</span></code> revision specifically. We can illustrate this
by showing it with <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">show</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic show shoppingcart
Rev: 27c6a30d7c24 (head)
Parent: 1975ea83b712
Branch names: shoppingcart
Path: foo/versions/27c6a30d7c24_add_shopping_cart_table.py
add shopping cart table
Revision ID: 27c6a30d7c24
Revises: 1975ea83b712
Create Date: 2014-11-20 13:03:11.436407
</pre></div>
</div>
<p>However, when using branch labels, we usually want to use them using a syntax
known as “branch at” syntax; this syntax allows us to state that we want to
use a specific revision, let’s say a “head” revision, in terms of a <em>specific</em>
branch. While normally, we can’t refer to <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">upgrade</span> <span class="pre">head</span></code> when
there’s multiple heads, we <em>can</em> refer to this head specifcally using
<code class="docutils literal"><span class="pre">shoppingcart@head</span></code> syntax:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade shoppingcart@head
INFO [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">shoppingcart@head</span></code> syntax becomes important to us if we wish to
add new migration files to our versions directory while maintaining multiple
branches. Just like the <code class="docutils literal"><span class="pre">upgrade</span></code> command, if we attempted to add a new
revision file to our multiple-heads layout without a specific parent revision,
we’d get a familiar error:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "add a shopping cart column"
FAILED: Multiple heads are present; please specify the head revision on
which the new revision should be based, or perform a merge.
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">revision</span></code> command is pretty clear in what we need to do;
to add our new revision specifically to the <code class="docutils literal"><span class="pre">shoppingcart</span></code> branch,
we use the <code class="docutils literal"><span class="pre">--head</span></code> argument, either with the specific revision identifier
<code class="docutils literal"><span class="pre">27c6a30d7c24</span></code>, or more generically using our branchname <code class="docutils literal"><span class="pre">shoppingcart@head</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "add a shopping cart column" --head shoppingcart@head
Generating /path/to/foo/versions/d747a8a8879_add_a_shopping_cart_column.py ... done
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">alembic</span> <span class="pre">history</span></code> shows both files now part of the <code class="docutils literal"><span class="pre">shoppingcart</span></code> branch:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history
1975ea83b712 -> ae1027a6acf (head), add a column
27c6a30d7c24 -> d747a8a8879 (shoppingcart) (head), add a shopping cart column
1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
<base> -> 1975ea83b712 (branchpoint), create account table
</pre></div>
</div>
<p>We can limit our history operation just to this branch as well:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history -r shoppingcart:
27c6a30d7c24 -> d747a8a8879 (shoppingcart) (head), add a shopping cart column
1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
</pre></div>
</div>
<p>If we want to illustrate the path of <code class="docutils literal"><span class="pre">shoppingcart</span></code> all the way from the
base, we can do that as follows:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history -r :shoppingcart@head
27c6a30d7c24 -> d747a8a8879 (shoppingcart) (head), add a shopping cart column
1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
<base> -> 1975ea83b712 (branchpoint), create account table
</pre></div>
</div>
<p>We can run this operation from the “base” side as well, but we get a different
result:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history -r shoppingcart@base:
1975ea83b712 -> ae1027a6acf (head), add a column
27c6a30d7c24 -> d747a8a8879 (shoppingcart) (head), add a shopping cart column
1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
<base> -> 1975ea83b712 (branchpoint), create account table
</pre></div>
</div>
<p>When we list from <code class="docutils literal"><span class="pre">shoppingcart@base</span></code> without an endpoint, it’s really shorthand
for <code class="docutils literal"><span class="pre">-r</span> <span class="pre">shoppingcart@base:heads</span></code>, e.g. all heads, and since <code class="docutils literal"><span class="pre">shoppingcart@base</span></code>
is the same “base” shared by the <code class="docutils literal"><span class="pre">ae1027a6acf</span></code> revision, we get that
revision in our listing as well. The <code class="docutils literal"><span class="pre"><branchname>@base</span></code> syntax can be
useful when we are dealing with individual bases, as we’ll see in the next
section.</p>
<p>The <code class="docutils literal"><span class="pre"><branchname>@head</span></code> format can also be used with revision numbers
instead of branch names, though this is less convenient. If we wanted to
add a new revision to our branch that includes the un-labeled <code class="docutils literal"><span class="pre">ae1027a6acf</span></code>,
if this weren’t a head already, we could ask for the “head of the branch
that includes <code class="docutils literal"><span class="pre">ae1027a6acf</span></code>” as follows:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "add another account column" --head ae10@head
Generating /path/to/foo/versions/55af2cb1c267_add_another_account_column.py ... done
</pre></div>
</div>
</div>
<div class="section" id="more-label-syntaxes">
<h3>More Label Syntaxes<a class="headerlink" href="#more-label-syntaxes" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal"><span class="pre">heads</span></code> symbol can be combined with a branch label, in the case that
your labeled branch itself breaks off into multiple branches:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade shoppingcart@heads
</pre></div>
</div>
<p>Relative identifiers, as introduced in <a class="reference internal" href="tutorial.html#relative-migrations"><span>Relative Migration Identifiers</span></a>,
work with labels too. For example, upgrading to <code class="docutils literal"><span class="pre">shoppingcart@+2</span></code>
means to upgrade from current heads on “shoppingcart” upwards two revisions:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade shoppingcart@+2
</pre></div>
</div>
<p>This kind of thing works from history as well:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history -r current:shoppingcart@+2
</pre></div>
</div>
<p>The newer <code class="docutils literal"><span class="pre">relnum+delta</span></code> format can be combined as well, for example
if we wanted to list along <code class="docutils literal"><span class="pre">shoppingcart</span></code> up until two revisions
before the head:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history -r :shoppingcart@head-2
</pre></div>
</div>
</div>
</div>
<div class="section" id="working-with-multiple-bases">
<span id="multiple-bases"></span><h2>Working with Multiple Bases<a class="headerlink" href="#working-with-multiple-bases" title="Permalink to this headline">¶</a></h2>
<p>We’ve seen in the previous section that <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">upgrade</span></code> is fine
if we have multiple heads, <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">revision</span></code> allows us to tell it which
“head” we’d like to associate our new revision file with, and branch labels
allow us to assign names to branches that we can use in subsequent commands.
Let’s put all these together and refer to a new “base”, that is, a whole
new tree of revision files that will be semi-independent of the account/shopping
cart revisions we’ve been working with. This new tree will deal with
database tables involving “networking”.</p>
<div class="section" id="setting-up-multiple-version-directories">
<span id="multiple-version-directories"></span><h3>Setting up Multiple Version Directories<a class="headerlink" href="#setting-up-multiple-version-directories" title="Permalink to this headline">¶</a></h3>
<p>While optional, it is often the case that when working with multiple bases,
we’d like different sets of version files to exist within their own directories;
typically, if an application is organized into several sub-modules, each
one would have a version directory containing migrations pertinent to
that module. So to start out, we can edit <code class="docutils literal"><span class="pre">alembic.ini</span></code> to refer
to multiple directories; we’ll also state the current <code class="docutils literal"><span class="pre">versions</span></code>
directory as one of them:</p>
<div class="highlight-python"><div class="highlight"><pre># version location specification; this defaults
# to foo/versions. When using multiple version
# directories, initial revisions must be specified with --version-path
version_locations = %(here)s/model/networking %(here)s/alembic/versions
</pre></div>
</div>
<p>The new directory <code class="docutils literal"><span class="pre">%(here)s/model/networking</span></code> is in terms of where
the <code class="docutils literal"><span class="pre">alembic.ini</span></code> file is, as we are using the symbol <code class="docutils literal"><span class="pre">%(here)s</span></code> which
resolves to this location. When we create our first new revision
targeted at this directory,
<code class="docutils literal"><span class="pre">model/networking</span></code> will be created automatically if it does not
exist yet. Once we’ve created a revision here, the path is used automatically
when generating subsequent revision files that refer to this revision tree.</p>
</div>
<div class="section" id="creating-a-labeled-base-revision">
<h3>Creating a Labeled Base Revision<a class="headerlink" href="#creating-a-labeled-base-revision" title="Permalink to this headline">¶</a></h3>
<p>We also want our new branch to have its own name, and for that we want to
apply a branch label to the base. In order to achieve this using the
<code class="docutils literal"><span class="pre">alembic</span> <span class="pre">revision</span></code> command without editing, we need to ensure our
<code class="docutils literal"><span class="pre">script.py.mako</span></code> file, used
for generating new revision files, has the appropriate substitutions present.
If Alembic version 0.7.0 or greater was used to generate the original
migration environment, this is already done. However when working with an older
environment, <code class="docutils literal"><span class="pre">script.py.mako</span></code> needs to have this directive added, typically
underneath the <code class="docutils literal"><span class="pre">down_revision</span></code> directive:</p>
<div class="highlight-python"><div class="highlight"><pre># revision identifiers, used by Alembic.
revision = ${repr(up_revision)}
down_revision = ${repr(down_revision)}
# add this here in order to use revision with branch_label
branch_labels = ${repr(branch_labels)}
</pre></div>
</div>
<p>With this in place, we can create a new revision file, starting up a branch
that will deal with database tables involving networking; we specify the
<code class="docutils literal"><span class="pre">--head</span></code> version of <code class="docutils literal"><span class="pre">base</span></code>, a <code class="docutils literal"><span class="pre">--branch-label</span></code> of <code class="docutils literal"><span class="pre">networking</span></code>,
and the directory we want this first revision file to be
placed in with <code class="docutils literal"><span class="pre">--version-path</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "create networking branch" --head=base --branch-label=networking --version-path=model/networking
Creating directory /path/to/foo/model/networking ... done
Generating /path/to/foo/model/networking/3cac04ae8714_create_networking_branch.py ... done
</pre></div>
</div>
<p>If we ran the above command and we didn’t have the newer <code class="docutils literal"><span class="pre">script.py.mako</span></code>
directive, we’d get this error:</p>
<div class="highlight-python"><div class="highlight"><pre>FAILED: Version 3cac04ae8714 specified branch_labels networking, however
the migration file foo/model/networking/3cac04ae8714_create_networking_branch.py
does not have them; have you upgraded your script.py.mako to include the 'branch_labels'
section?
</pre></div>
</div>
<p>When we receive the above error, and we would like to try again, we need to
either <strong>delete</strong> the incorrectly generated file in order to run <code class="docutils literal"><span class="pre">revision</span></code>
again, <em>or</em> we can edit the <code class="docutils literal"><span class="pre">3cac04ae8714_create_networking_branch.py</span></code>
directly to add the <code class="docutils literal"><span class="pre">branch_labels</span></code> in of our choosing.</p>
</div>
<div class="section" id="running-with-multiple-bases">
<h3>Running with Multiple Bases<a class="headerlink" href="#running-with-multiple-bases" title="Permalink to this headline">¶</a></h3>
<p>Once we have a new, permanent (for as long as we desire it to be)
base in our system, we’ll always have multiple heads present:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic heads
3cac04ae8714 (networking) (head)
27c6a30d7c24 (shoppingcart) (head)
ae1027a6acf (head)
</pre></div>
</div>
<p>When we want to add a new revision file to <code class="docutils literal"><span class="pre">networking</span></code>, we specify
<code class="docutils literal"><span class="pre">networking@head</span></code> as the <code class="docutils literal"><span class="pre">--head</span></code>. The appropriate version directory
is now selected automatically based on the head we choose:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "add ip number table" --head=networking@head
Generating /path/to/foo/model/networking/109ec7d132bf_add_ip_number_table.py ... done
</pre></div>
</div>
<p>It’s important that we refer to the head using <code class="docutils literal"><span class="pre">networking@head</span></code>; if we
only refer to <code class="docutils literal"><span class="pre">networking</span></code>, that refers to only <code class="docutils literal"><span class="pre">3cac04ae8714</span></code> specifically;
if we specify this and it’s not a head, <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">revision</span></code> will make sure
we didn’t mean to specify the head:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "add DNS table" --head=networking
FAILED: Revision 3cac04ae8714 is not a head revision; please
specify --splice to create a new branch from this revision
</pre></div>
</div>
<p>As mentioned earlier, as this base is independent, we can view its history
from the base using <code class="docutils literal"><span class="pre">history</span> <span class="pre">-r</span> <span class="pre">networking@base:</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history -r networking@base:
109ec7d132bf -> 29f859a13ea (networking) (head), add DNS table
3cac04ae8714 -> 109ec7d132bf (networking), add ip number table
<base> -> 3cac04ae8714 (networking), create networking branch
</pre></div>
</div>
<p>At the moment, this is the same output we’d get at this point if we used
<code class="docutils literal"><span class="pre">-r</span> <span class="pre">:networking@head</span></code>. However, that will change later on as we use
additional directives.</p>
<p>We may now run upgrades or downgrades freely, among individual branches
(let’s assume a clean database again):</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade networking@head
INFO [alembic.migration] Running upgrade -> 3cac04ae8714, create networking branch
INFO [alembic.migration] Running upgrade 3cac04ae8714 -> 109ec7d132bf, add ip number table
INFO [alembic.migration] Running upgrade 109ec7d132bf -> 29f859a13ea, add DNS table
</pre></div>
</div>
<p>or against the whole thing using <code class="docutils literal"><span class="pre">heads</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade heads
INFO [alembic.migration] Running upgrade -> 1975ea83b712, create account table
INFO [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
INFO [alembic.migration] Running upgrade 27c6a30d7c24 -> d747a8a8879, add a shopping cart column
INFO [alembic.migration] Running upgrade 1975ea83b712 -> ae1027a6acf, add a column
INFO [alembic.migration] Running upgrade ae1027a6acf -> 55af2cb1c267, add another account column
</pre></div>
</div>
</div>
</div>
<div class="section" id="branch-dependencies">
<h2>Branch Dependencies<a class="headerlink" href="#branch-dependencies" title="Permalink to this headline">¶</a></h2>
<p>When working with multiple roots, it is expected that these different
revision streams will need to refer to one another. For example, a new
revision in <code class="docutils literal"><span class="pre">networking</span></code> which needs to refer to the <code class="docutils literal"><span class="pre">account</span></code>
table will want to establish <code class="docutils literal"><span class="pre">55af2cb1c267,</span> <span class="pre">add</span> <span class="pre">another</span> <span class="pre">account</span> <span class="pre">column</span></code>,
the last revision that
works with the account table, as a dependency. From a graph perspective,
this means nothing more that the new file will feature both
<code class="docutils literal"><span class="pre">55af2cb1c267,</span> <span class="pre">add</span> <span class="pre">another</span> <span class="pre">account</span> <span class="pre">column</span></code> and <code class="docutils literal"><span class="pre">29f859a13ea,</span> <span class="pre">add</span> <span class="pre">DNS</span> <span class="pre">table</span></code> as “down” revisions,
and looks just as though we had merged these two branches together. However,
we don’t want to consider these as “merged”; we want the two revision
streams to <em>remain independent</em>, even though a version in <code class="docutils literal"><span class="pre">networking</span></code>
is going to reach over into the other stream. To support this use case,
Alembic provides a directive known as <code class="docutils literal"><span class="pre">depends_on</span></code>, which allows
a revision file to refer to another as a “dependency”, very similar to
an entry in <code class="docutils literal"><span class="pre">down_revision</span></code> from a graph perspective, but different
from a semantic perspective.</p>
<p>To use <code class="docutils literal"><span class="pre">depends_on</span></code>, we can specify it as part of our <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">revision</span></code>
command:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "add ip account table" --head=networking@head --depends-on=55af2cb1c267
Generating /path/to/foo/model/networking/2a95102259be_add_ip_account_table.py ... done
</pre></div>
</div>
<p>Within our migration file, we’ll see this new directive present:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># revision identifiers, used by Alembic.</span>
<span class="n">revision</span> <span class="o">=</span> <span class="s">'2a95102259be'</span>
<span class="n">down_revision</span> <span class="o">=</span> <span class="s">'29f859a13ea'</span>
<span class="n">branch_labels</span> <span class="o">=</span> <span class="bp">None</span>
<span class="n">depends_on</span><span class="o">=</span><span class="s">'55af2cb1c267'</span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">depends_on</span></code> may be either a real revision number or a branch
name. When specified at the command line, a resolution from a
partial revision number will work as well. It can refer
to any number of dependent revisions as well; for example, if we were
to run the command:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "add ip account table" \\
--head=networking@head \\
--depends-on=55af2cb1c267 --depends-on=d747a --depends-on=fa445
Generating /path/to/foo/model/networking/2a95102259be_add_ip_account_table.py ... done
</pre></div>
</div>
<p>We’d see inside the file:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># revision identifiers, used by Alembic.</span>
<span class="n">revision</span> <span class="o">=</span> <span class="s">'2a95102259be'</span>
<span class="n">down_revision</span> <span class="o">=</span> <span class="s">'29f859a13ea'</span>
<span class="n">branch_labels</span> <span class="o">=</span> <span class="bp">None</span>
<span class="n">depends_on</span> <span class="o">=</span> <span class="p">(</span><span class="s">'55af2cb1c267'</span><span class="p">,</span> <span class="s">'d747a8a8879'</span><span class="p">,</span> <span class="s">'fa4456a9201'</span><span class="p">)</span>
</pre></div>
</div>
<p>We also can of course add or alter this value within the file manually after
it is generated, rather than using the <code class="docutils literal"><span class="pre">--depends-on</span></code> argument.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.8: </span>The <code class="docutils literal"><span class="pre">depends_on</span></code> attribute may be set directly
from the <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">revision</span></code> command, rather than editing the file
directly. <code class="docutils literal"><span class="pre">depends_on</span></code> identifiers may also be specified as
branch names at the command line or directly within the migration file.
The values may be specified as partial revision numbers from the command
line which will be resolved to full revision numbers in the output file.</p>
</div>
<p>We can see the effect this directive has when we view the history
of the <code class="docutils literal"><span class="pre">networking</span></code> branch in terms of “heads”, e.g., all the revisions that
are descendants:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history -r :networking@head
29f859a13ea (55af2cb1c267) -> 2a95102259be (networking) (head), add ip account table
109ec7d132bf -> 29f859a13ea (networking), add DNS table
3cac04ae8714 -> 109ec7d132bf (networking), add ip number table
<base> -> 3cac04ae8714 (networking), create networking branch
ae1027a6acf -> 55af2cb1c267 (effective head), add another account column
1975ea83b712 -> ae1027a6acf, Add a column
<base> -> 1975ea83b712 (branchpoint), create account table
</pre></div>
</div>
<p>What we see is that the full history of the <code class="docutils literal"><span class="pre">networking</span></code> branch, in terms
of an “upgrade” to the “head”, will include that the tree building
up <code class="docutils literal"><span class="pre">55af2cb1c267,</span> <span class="pre">add</span> <span class="pre">another</span> <span class="pre">account</span> <span class="pre">column</span></code>
will be pulled in first. Interstingly, we don’t see this displayed
when we display history in the other direction, e.g. from <code class="docutils literal"><span class="pre">networking@base</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history -r networking@base:
29f859a13ea (55af2cb1c267) -> 2a95102259be (networking) (head), add ip account table
109ec7d132bf -> 29f859a13ea (networking), add DNS table
3cac04ae8714 -> 109ec7d132bf (networking), add ip number table
<base> -> 3cac04ae8714 (networking), create networking branch
</pre></div>
</div>
<p>The reason for the discrepancy is that displaying history from the base
shows us what would occur if we ran a downgrade operation, instead of an
upgrade. If we downgraded all the files in <code class="docutils literal"><span class="pre">networking</span></code> using
<code class="docutils literal"><span class="pre">networking@base</span></code>, the dependencies aren’t affected, they’re left in place.</p>
<p>We also see something odd if we view <code class="docutils literal"><span class="pre">heads</span></code> at the moment:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic heads
2a95102259be (networking) (head)
27c6a30d7c24 (shoppingcart) (head)
55af2cb1c267 (effective head)
</pre></div>
</div>
<p>The head file that we used as a “dependency”, <code class="docutils literal"><span class="pre">55af2cb1c267</span></code>, is displayed
as an “effective” head, which we can see also in the history display earlier.
What this means is that at the moment, if we were to upgrade all versions
to the top, the <code class="docutils literal"><span class="pre">55af2cb1c267</span></code> revision number would not actually be
present in the <code class="docutils literal"><span class="pre">alembic_version</span></code> table; this is because it does not have
a branch of its own subsequent to the <code class="docutils literal"><span class="pre">2a95102259be</span></code> revision which depends
on it:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic upgrade heads
INFO [alembic.migration] Running upgrade 29f859a13ea, 55af2cb1c267 -> 2a95102259be, add ip account table
$ alembic current
2a95102259be (head)
27c6a30d7c24 (head)
</pre></div>
</div>
<p>The entry is still displayed in <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">heads</span></code> because Alembic knows that
even though this revision isn’t a “real” head, it’s still something that
we developers consider semantically to be a head, so it’s displayed, noting
its special status so that we don’t get quite as confused when we don’t
see it within <code class="docutils literal"><span class="pre">alembic</span> <span class="pre">current</span></code>.</p>
<p>If we add a new revision onto <code class="docutils literal"><span class="pre">55af2cb1c267</span></code>, the branch again becomes
a “real” branch which can have its own entry in the database:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic revision -m "more account changes" --head=55af2cb@head
Generating /path/to/foo/versions/34e094ad6ef1_more_account_changes.py ... done
$ alembic upgrade heads
INFO [alembic.migration] Running upgrade 55af2cb1c267 -> 34e094ad6ef1, more account changes
$ alembic current
2a95102259be (head)
27c6a30d7c24 (head)
34e094ad6ef1 (head)
</pre></div>
</div>
<p>For posterity, the revision tree now looks like:</p>
<div class="highlight-python"><div class="highlight"><pre>$ alembic history
29f859a13ea (55af2cb1c267) -> 2a95102259be (networking) (head), add ip account table
109ec7d132bf -> 29f859a13ea (networking), add DNS table
3cac04ae8714 -> 109ec7d132bf (networking), add ip number table
<base> -> 3cac04ae8714 (networking), create networking branch
1975ea83b712 -> 27c6a30d7c24 (shoppingcart) (head), add shopping cart table
55af2cb1c267 -> 34e094ad6ef1 (head), more account changes
ae1027a6acf -> 55af2cb1c267, add another account column
1975ea83b712 -> ae1027a6acf, Add a column
<base> -> 1975ea83b712 (branchpoint), create account table
--- 27c6 --> d747 --> <head>
/ (shoppingcart)
<base> --> 1975 -->
\
--- ae10 --> 55af --> <head>
^
+--------+ (dependency)
|
|
<base> --> 3782 -----> 109e ----> 29f8 ---> 2a95 --> <head>
(networking)
</pre></div>
</div>
<p>If there’s any point to be made here, it’s if you are too freely branching, merging
and labeling, things can get pretty crazy! Hence the branching system should
be used carefully and thoughtfully for best results.</p>
</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="#">Working with Branches</a><ul>
<li><a class="reference internal" href="#merging-branches">Merging Branches</a></li>
<li><a class="reference internal" href="#working-with-explicit-branches">Working with Explicit Branches</a><ul>
<li><a class="reference internal" href="#referring-to-all-heads-at-once">Referring to all heads at once</a></li>
<li><a class="reference internal" href="#referring-to-a-specific-version">Referring to a Specific Version</a></li>
<li><a class="reference internal" href="#working-with-branch-labels">Working with Branch Labels</a></li>
<li><a class="reference internal" href="#more-label-syntaxes">More Label Syntaxes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#working-with-multiple-bases">Working with Multiple Bases</a><ul>
<li><a class="reference internal" href="#setting-up-multiple-version-directories">Setting up Multiple Version Directories</a></li>
<li><a class="reference internal" href="#creating-a-labeled-base-revision">Creating a Labeled Base Revision</a></li>
<li><a class="reference internal" href="#running-with-multiple-bases">Running with Multiple Bases</a></li>
</ul>
</li>
<li><a class="reference internal" href="#branch-dependencies">Branch Dependencies</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="batch.html"
title="previous chapter">Running “Batch” Migrations for SQLite and Other Databases</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="ops.html"
title="next chapter">Operation Reference</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/branches.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="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="ops.html" title="Operation Reference"
>next</a> |</li>
<li class="right" >
<a href="batch.html" title="Running “Batch” Migrations for SQLite and Other Databases"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Alembic 0.8.3 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2010-2015, Mike Bayer.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.1.
</div>
</body>
</html>
Zerion Mini Shell 1.0