Commits

Michael Elsdörfer committed 373d170

Added documentation for --update switch.

Comments (0)

Files changed (3)

docs/commands.rst

 
  ./manage.py schemamigration myapp --auto changed_user_model_bug_434
 
+If you make further changes to your models, you can further refine the most
+recent migration::
+
+ ./manage.py schemamigration myapp --auto --update
+
 You can also manually specify changes::
 
  ./manage.py schemamigration mitest some_cols --add-field User.age --add-model User
  - ``--initial``: Like having --model for every model in your app.
    You should use this only for your first migration.
  - ``--auto``: Generates a migration with automatically-detected actions.
+ - ``--update``: Update the most recent migration, instead of creating a
+   new one.
  - ``--stdout``: Writes the migration to stdout instead of a file.
 
 .. _commands-datamigration: 

docs/tutorial/part3.rst

 Part 3: Advanced Commands and Data Migrations
 =============================================
 
+Iteratively working on a migration
+----------------------------------
+
+Sometimes, you'll find that you've made model changes that need to be further
+refined. Say you define this model::
+
+ class Group(models.Model):
+     name = models.TextField(verbose_name="Name")
+     facebook_page__id = models.CharField(max_length=255)
+
+and you've created and applied this migration::
+
+ ./manage.py schemamigration southtut --auto
+ ./manage.py migrate southtut
+
+You then notice two things: One, ``name`` should really be a ``CharField``, not
+a ``TextField``; and ``facebook_page__id`` contains double underscores where
+there should be a single one. You can fix these issues in your model, and then
+run::
+
+  ./manage.py schemamigration southtut --auto --update
+   + Added model southtut.Group
+  Migration to be updated, 0026_auto__add_group, is already applied, rolling it back now...
+  previous_migration: 0025_auto__foo (applied: 2012-05-25 21:20:47)
+  Running migrations for southtut:
+    - Migrating backwards to just after 0025_auto__foo.
+    < partner:0026_auto__add_group
+  Updated 0026_auto__add_group.py. You can now apply this migration with: ./manage.py migrate southtut
+
+What happened here is that South removed the most recent migration, which
+created the model, but included the mistakes that were made, and replaced it
+with a new migration that includes the latest corrections made to the model.
+
+It also noticed that the migration had already been applied, and automatically
+rolled it back for you. You can now apply the latest version of the migration
+to create the correct version of the model::
+
+ ./manage.py migrate southtut
+
+You may repeat this process as often as required to iron out any issues and
+come up with the final database changes required; which you can then publish,
+neatly packed into a single migration.
+
+
 Listing current migrations
 --------------------------
 

docs/tutorial/part5.rst

 over several migrations, do each schema change to models.py separately, then make
 the migration, and then make the next small change.
 
+Note that the ``./manage.py schemamigration`` command has an ``--update`` mode
+that allows you to further iteratively refine your migration as such changes
+become necessary while working on your code. It is preferable to distribute a
+single migration for each atomic code change (a particular bug fixed, a new
+feature), then half a dozen migrations that could be merged into one. Remember
+that the purpose of migrations is to replay database changes on multiple
+machines; a separate migration is not required for changes that have only been
+applied locally.
+
 
 Team Workflow
 -------------
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.