Michael Elsdörfer  committed 373d170 Draft

Added documentation for --update switch.

  • Participants
  • Parent commits 0508490
  • Branches migration-update2

Comments (0)

Files changed (3)

File docs/commands.rst

  ./ schemamigration myapp --auto changed_user_model_bug_434
+If you make further changes to your models, you can further refine the most
+recent migration::
+ ./ schemamigration myapp --auto --update
 You can also manually specify changes::
  ./ 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: 

File 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::
+ ./ schemamigration southtut --auto
+ ./ 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
+  ./ 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 You can now apply this migration with: ./ 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::
+ ./ 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

File docs/tutorial/part5.rst

 over several migrations, do each schema change to separately, then make
 the migration, and then make the next small change.
+Note that the ``./ 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