Source / south-doc-ja / commands.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

<html xmlns="">
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>コマンドリファレンス &mdash; South v0.7 documentation</title>
    <link rel="stylesheet" href="_static/nature.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
        URL_ROOT:    '#',
        VERSION:     '0.7',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="author" title="About these documents" href="about.html" />
    <link rel="top" title="South v0.7 documentation" href="index.html" />
    <link rel="next" title="Unit Test Integration" href="unittests.html" />
    <link rel="prev" title="Dependencies" href="dependencies.html" /> 
    <div class="related">
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
        <li class="right" >
          <a href="unittests.html" title="Unit Test Integration"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="dependencies.html" title="Dependencies"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">South v0.7 documentation</a> &raquo;</li> 

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
  <span class="target" id="commands"></span><div class="section" id="id1">
<h1>コマンドリファレンス<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h1>
<p>South is mainly used via the console and its three important commands: migrate,
schemamigration and datamigration. It also overrides a few parts of syncdb.</p>
<div class="section" id="migrate">
<h2>migrate<a class="headerlink" href="#migrate" title="Permalink to this headline"></a></h2>
<p>The migrate command is used to control the migration of the system forwards or
backwards through the series of migrations for any given app.</p>
<p>The most common use is:</p>
<div class="highlight-python"><pre>./ migrate myapp</pre>
<p>This will migrate the app myapp forwards through all the migrations.
If you want to migrate all the apps at once, run:</p>
<div class="highlight-python"><pre>./ migrate</pre>
<p>This has the same effect as calling the first example for every app,
and will deal with Dependencies properly.</p>
<p>You can also specify a specific migration to migrate to:</p>
<div class="highlight-python"><pre>./ migrate myapp 0002_add_username</pre>
<p>Note that, if the system has already migrated past the specified migration,
it will roll back to it instead. If you want to migrate all the way back,
specify the special migration name zero:</p>
<div class="highlight-python"><pre>./ migrate myapp zero</pre>
<p>You can also just give prefixes of migrations, to save typing:</p>
<div class="highlight-python"><pre>./ migrate myapp 0002</pre>
<p>But they must be unique:</p>
<div class="highlight-python"><pre>$ ./ migrate myapp 000
Running migrations for myapp:
 - Prefix 00 matches more than one migration:
<div class="section" id="options">
<h3>Options<a class="headerlink" href="#options" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--all</span></tt>: Used instead of an app name, allows you to migrate all
applications to the same target. For example,
<tt class="docutils literal"><span class="pre">./</span> <span class="pre">migrate</span> <span class="pre">--all</span> <span class="pre">--fake</span> <span class="pre">0001</span></tt> if you are converting a lot of apps.</li>
<li><tt class="docutils literal"><span class="pre">--list</span></tt>: Shows what migrations are available, and puts a * next to
ones which have been applied.</li>
<li><tt class="docutils literal"><span class="pre">--merge</span></tt>: Runs any missed (out-of-order) migrations without rolling
back to them.</li>
<li><tt class="docutils literal"><span class="pre">--no-initial-data</span></tt>: Doesn&#8217;t load in any initial data fixtures after a
full upwards migration, if there are any.</li>
<li><tt class="docutils literal"><span class="pre">--fake</span></tt>: Records the migration sequence as having been applied, but
doesn&#8217;t actually run it. Useful for ConvertingAnApp.</li>
<li><tt class="docutils literal"><span class="pre">--db-dry-run</span></tt>: Loads and runs the migration, but doesn&#8217;t actually
access the database (the SQL generated is thrown away at the last minute).
The migration is also not recorded as being run; this is useful for
sanity-testing migrations to check API calls are correct.</li>
<div class="section" id="conflict-resolution">
<h3>Conflict Resolution<a class="headerlink" href="#conflict-resolution" title="Permalink to this headline"></a></h3>
<p>South&#8217;s migration system really comes into its own when you start getting
conflicting migrations - that is, migrations that have been applied in
the wrong sequence.</p>
<p>One example is if Anne writes new migrations 0003_foo and 0004_bar, runs the
migration up to 0004 to make sure her local copy is up-to-date, and then updates
her code from (say) Subversion. In the meantime, her coworker Bob has written a
migration 0003_baz, which gets pulled in.</p>
<p>Now, there&#8217;s a problem. 0003_phou should have been applied before 0004_bar,
but it hasn&#8217;t been; in this situation, South will helpfully say something like:</p>
<div class="highlight-python"><pre>Running migrations for aeblog:
 - Current migration: 5 (after 0004_bar)
 - Target migration: 5 (after 0004_bar)
 ! These migrations should have been applied already, but aren't:
   - 0003_phou
 ! Please re-run migrate with one of these switches:
   --skip: Ignore this migration mismatch and keep going
   --merge: Just apply the missing migrations out of order
   If you want to roll back to the first of these migrations
   and then roll forward, do:
     ./ migrate --skip 0002_add_username
     ./ migrate</pre>
<p>As you can see, you have two real options; <tt class="docutils literal"><span class="pre">--merge</span></tt>, which will just apply
the missing migration and continue, and the two commands which roll back to
before the missing migration (using <tt class="docutils literal"><span class="pre">--skip</span></tt> to ignore the error we&#8217;re dealing
with) and then migrating properly, in order, from there to the end.</p>
<p>Using <tt class="docutils literal"><span class="pre">--skip</span></tt> by itself will let you continue, but isn&#8217;t much of a solution;
South will still complain the next time you run a migrate without <tt class="docutils literal"><span class="pre">--skip</span></tt>.</p>
<p>Sometimes, even worse things happen and South finds out that an applied
migration has gone missing from the filesystem. In this scenario, it will
politely tell you to go fix the problem yourself, although in more recent
versions, you also have the option to tell South to wipe all records of the
missing migrations being applied.</p>
<div class="section" id="initial-data-and-post-syncdb">
<h3>Initial Data and post_syncdb<a class="headerlink" href="#initial-data-and-post-syncdb" title="Permalink to this headline"></a></h3>
<p>South will load initial_data files in the same way as syncdb, but it loads them
at the end of every successful migration process, so ensure they are kept
up-to-date, along with the rest of your fixtures (something to help ease the
pain of migrating fixtures may appear shortly in South).</p>
<p>South also sends the post_syncdb signal when a model&#8217;s table is first created
(this functionality requires that you generated those migrations with
startmigration). This behaviour is intended to mirror the behaviour of syncdb,
although for sanity reasons you may want to consider moving any setup code
connected to such a signal into a migration.</p>
<div class="section" id="schemamigration">
<h2>schemamigration<a class="headerlink" href="#schemamigration" title="Permalink to this headline"></a></h2>
<p><em>(In South 0.6 and below, this is called startmigration)</em></p>
<p>While migrate is the real meat and bones of South, schemamigration is by
comparison an entirely optional extra. It&#8217;s a utility to help write some of
your migrations (specifically, the ones which change the schema) for
you; if you like, you can ignore it and write everything youself, in which
case we wish you good luck, and happy typing.</p>
<p>However, if you have a sense of reason, you&#8217;ll realise that having the large
majority of your migrations written for you in undoubtedly a good thing.</p>
<p>The main use of schemamigration is when you&#8217;ve just finished your shiny new and want to load up your database. In vanilla Django, you&#8217;d just run
syncdb - however, with migrations, you&#8217;ll need a migration to create the tables.</p>
<p>In this scenario, you just run:</p>
<div class="highlight-python"><pre>./ schemamigration myapp --initial</pre>
<p>That will write one big migration to create all the tables for the models in
your app; just run <tt class="docutils literal"><span class="pre">./</span> <span class="pre">migrate</span></tt> to get it in and you&#8217;re done in only
one more step than syncdb!</p>
<p>Later on, you&#8217;ll add models to your app, or change your fields. Each time you do
this, run schemamigration with the &#8211;auto flag:</p>
<div class="highlight-python"><pre>./ schemamigration myapp --auto changed_user_model_bug_434</pre>
<p>You can also manually specify changes:</p>
<div class="highlight-python"><pre>./ schemamigration mitest some_cols --add-field User.age --add-model User</pre>
<p>See the tutorial for more.</p>
<p>Finally, if you&#8217;re writing a schema migration that South can&#8217;t automatically create
for you (yet!) then you can just create a skeleton:</p>
<p>./ schemamigration myapp my_new_column_migration &#8211;empty</p>
<p>Note that if you&#8217;re writing a data migration, you should use the
<a class="reference internal" href="#commands-datamigration"><em>datamigration</em></a> command instead.</p>
<div class="section" id="id2">
<h3>Options<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h3>
<p>Note that you can combine as many <tt class="docutils literal"><span class="pre">--add-X</span></tt> options as you like.</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--add-model</span></tt>: Generates a creation migration for the given modelname.</li>
<li><tt class="docutils literal"><span class="pre">--add-field</span></tt>: Generates an add-column migration for modelname.field.</li>
<li><tt class="docutils literal"><span class="pre">--add-index</span></tt>: Generates an add-index migration for modelname.field.</li>
<li><tt class="docutils literal"><span class="pre">--initial</span></tt>: Like having &#8211;model for every model in your app.
You should use this only for your first migration.</li>
<li><tt class="docutils literal"><span class="pre">--auto</span></tt>: Generates a migration with automatically-detected actions.</li>
<li><tt class="docutils literal"><span class="pre">--stdout</span></tt>: Writes the migration to stdout instead of a file.</li>
<div class="section" id="datamigration">
<span id="commands-datamigration"></span><h2>datamigration<a class="headerlink" href="#datamigration" title="Permalink to this headline"></a></h2>
<p><em>(In South 0.6 and below, this is called startmigration)</em></p>
<p>When you want to create a data migration, use this command to create a blank
template to write your migration with:</p>
<div class="highlight-python"><pre>./ datamigration books capitalise_titles</pre>
<p>You can also freeze in additional apps if you want:</p>
<div class="highlight-python"><pre>./ datamigration books capitalise_titles --freeze awards</pre>
<div class="section" id="id3">
<h3>Options<a class="headerlink" href="#id3" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--freeze</span></tt>: Use appname or appname.modelname to freeze additional models into the app.</li>
<li><tt class="docutils literal"><span class="pre">--stdout</span></tt>: Writes the migration to stdout instead of a file.</li>
<div class="section" id="graphmigrations">
<h2>graphmigrations<a class="headerlink" href="#graphmigrations" title="Permalink to this headline"></a></h2>
<p><em>(New in South 0.7)</em></p>
<p>Run this command to generate a graphviz .dot file for your migrations; you
can then use this to generate a graph of your migrations&#8217; dependencies.</p>
<p>Typical usage:</p>
<div class="highlight-python"><pre>./ graphmigrations | dot -Tpng -omigrations.png</pre>
<p>This command can be particularly helpful to examine complex dependency sets
between lots of different apps <a class="footnote-reference" href="#id5" id="id4">[1]</a>.</p>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[1]</a></td><td>This command was written and used for the first time while helping the
debug the rather complex set of dependencies in django-cms; it&#8217;s quite
a sight to behold.</td></tr>
<div class="section" id="id6">
<h3>Options<a class="headerlink" href="#id6" title="Permalink to this headline"></a></h3>
<p>This command has no options.</p>
<div class="section" id="syncdb">
<h2>syncdb<a class="headerlink" href="#syncdb" title="Permalink to this headline"></a></h2>
<p>South overrides the Django syncdb command; as well as changing the output
to show apps delineated by their migration status, it also makes syncdb only
work on a subset of the apps - those without migrations.</p>
<p>If you want to run syncdb on all of the apps, then use <tt class="docutils literal"><span class="pre">--all</span></tt>, but be warned;
this will put your database schema and migrations out of sync. If you do this,
you <em>might</em> be able to fix it with:</p>
<div class="highlight-python"><pre>./ migrate --fake</pre>
<div class="section" id="id7">
<h3>Options<a class="headerlink" href="#id7" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--all</span></tt>: Makes syncdb operate on all apps, not just unmigrated ones.</li>

      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="index.html">Table Of Contents</a></h3>
<li><a class="reference external" href="#">コマンドリファレンス</a><ul>
<li><a class="reference external" href="#migrate">migrate</a><ul>
<li><a class="reference external" href="#options">Options</a></li>
<li><a class="reference external" href="#conflict-resolution">Conflict Resolution</a></li>
<li><a class="reference external" href="#initial-data-and-post-syncdb">Initial Data and post_syncdb</a></li>
<li><a class="reference external" href="#schemamigration">schemamigration</a><ul>
<li><a class="reference external" href="#id2">Options</a></li>
<li><a class="reference external" href="#datamigration">datamigration</a><ul>
<li><a class="reference external" href="#id3">Options</a></li>
<li><a class="reference external" href="#graphmigrations">graphmigrations</a><ul>
<li><a class="reference external" href="#id6">Options</a></li>
<li><a class="reference external" href="#syncdb">syncdb</a><ul>
<li><a class="reference external" href="#id7">Options</a></li>

            <h4>Previous topic</h4>
            <p class="topless"><a href="dependencies.html"
                                  title="previous chapter">Dependencies</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="unittests.html"
                                  title="next chapter">Unit Test Integration</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/commands.txt"
                     rel="nofollow">Show Source</a></li>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
          <script type="text/javascript">$('#searchbox').show(0);</script>
      <div class="clearer"></div>
    <div class="related">
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
        <li class="right" >
          <a href="unittests.html" title="Unit Test Integration"
             >next</a> |</li>
        <li class="right" >
          <a href="dependencies.html" title="Dependencies"
             >previous</a> |</li>
        <li><a href="index.html">South v0.7 documentation</a> &raquo;</li> 
    <div class="footer">
      &copy; Copyright 2010, Andrew Godwin.
      Created using <a href="">Sphinx</a> 0.6.5.