commands.rst 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247
  1. .. _commands:
  2. Command Reference
  3. =================
  4. South is mainly used via the console and its three important commands: migrate,
  5. schemamigration and datamigration. It also overrides a few parts of syncdb.
  6. migrate
  7. -------
  8. The migrate command is used to control the migration of the system forwards or
  9. backwards through the series of migrations for any given app.
  10. The most common use is::
  11. ./manage.py migrate myapp
  12. This will migrate the app myapp forwards through all the migrations.
  13. If you want to migrate all the apps at once, run::
  14. ./manage.py migrate
  15. This has the same effect as calling the first example for every app,
  16. and will deal with Dependencies properly.
  17. You can also specify a specific migration to migrate to::
  18. ./manage.py migrate myapp 0002_add_username
  19. Note that, if the system has already migrated past the specified migration,
  20. it will roll back to it instead. If you want to migrate all the way back,
  21. specify the special migration name zero::
  22. ./manage.py migrate myapp zero
  23. You can also just give prefixes of migrations, to save typing::
  24. ./manage.py migrate myapp 0002
  25. But they must be unique::
  26. $ ./manage.py migrate myapp 000
  27. Running migrations for myapp:
  28. - Prefix 00 matches more than one migration:
  29. 0001_initial
  30. 0002_add_username
  31. Options
  32. ^^^^^^^
  33. - ``--all``: Used instead of an app name, allows you to migrate all
  34. applications to the same target. For example,
  35. ``./manage.py migrate --all --fake 0001`` if you are converting a lot of apps.
  36. - ``--list``: Shows what migrations are available, and puts a * next to
  37. ones which have been applied.
  38. - ``--merge``: Runs any missed (out-of-order) migrations without rolling
  39. back to them.
  40. - ``--no-initial-data``: Doesn't load in any initial data fixtures after a
  41. full upwards migration, if there are any.
  42. - ``--fake``: Records the migration sequence as having been applied, but
  43. doesn't actually run it. Useful for ConvertingAnApp.
  44. - ``--db-dry-run``: Loads and runs the migration, but doesn't actually
  45. access the database (the SQL generated is thrown away at the last minute).
  46. The migration is also not recorded as being run; this is useful for
  47. sanity-testing migrations to check API calls are correct.
  48. Conflict Resolution
  49. ^^^^^^^^^^^^^^^^^^^
  50. South's migration system really comes into its own when you start getting
  51. conflicting migrations - that is, migrations that have been applied in
  52. the wrong sequence.
  53. One example is if Anne writes new migrations 0003_foo and 0004_bar, runs the
  54. migration up to 0004 to make sure her local copy is up-to-date, and then updates
  55. her code from (say) Subversion. In the meantime, her coworker Bob has written a
  56. migration 0003_baz, which gets pulled in.
  57. Now, there's a problem. 0003_phou should have been applied before 0004_bar,
  58. but it hasn't been; in this situation, South will helpfully say something like::
  59. Running migrations for aeblog:
  60. - Current migration: 5 (after 0004_bar)
  61. - Target migration: 5 (after 0004_bar)
  62. ! These migrations should have been applied already, but aren't:
  63. - 0003_phou
  64. ! Please re-run migrate with one of these switches:
  65. --skip: Ignore this migration mismatch and keep going
  66. --merge: Just apply the missing migrations out of order
  67. If you want to roll back to the first of these migrations
  68. and then roll forward, do:
  69. ./manage.py migrate --skip 0002_add_username
  70. ./manage.py migrate
  71. As you can see, you have two real options; ``--merge``, which will just apply
  72. the missing migration and continue, and the two commands which roll back to
  73. before the missing migration (using ``--skip`` to ignore the error we're dealing
  74. with) and then migrating properly, in order, from there to the end.
  75. Using ``--skip`` by itself will let you continue, but isn't much of a solution;
  76. South will still complain the next time you run a migrate without ``--skip``.
  77. Sometimes, even worse things happen and South finds out that an applied
  78. migration has gone missing from the filesystem. In this scenario, it will
  79. politely tell you to go fix the problem yourself, although in more recent
  80. versions, you also have the option to tell South to wipe all records of the
  81. missing migrations being applied.
  82. Initial Data and post_syncdb
  83. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  84. South will load initial_data files in the same way as syncdb, but it loads them
  85. at the end of every successful migration process, so ensure they are kept
  86. up-to-date, along with the rest of your fixtures (something to help ease the
  87. pain of migrating fixtures may appear shortly in South).
  88. South also sends the post_syncdb signal when a model's table is first created
  89. (this functionality requires that you generated those migrations with
  90. startmigration). This behaviour is intended to mirror the behaviour of syncdb,
  91. although for sanity reasons you may want to consider moving any setup code
  92. connected to such a signal into a migration.
  93. schemamigration
  94. ---------------
  95. *(In South 0.6 and below, this is called startmigration)*
  96. While migrate is the real meat and bones of South, schemamigration is by
  97. comparison an entirely optional extra. It's a utility to help write some of
  98. your migrations (specifically, the ones which change the schema) for
  99. you; if you like, you can ignore it and write everything youself, in which
  100. case we wish you good luck, and happy typing.
  101. However, if you have a sense of reason, you'll realise that having the large
  102. majority of your migrations written for you in undoubtedly a good thing.
  103. The main use of schemamigration is when you've just finished your shiny new
  104. models.py and want to load up your database. In vanilla Django, you'd just run
  105. syncdb - however, with migrations, you'll need a migration to create the tables.
  106. In this scenario, you just run::
  107. ./manage.py schemamigration myapp --initial
  108. That will write one big migration to create all the tables for the models in
  109. your app; just run ``./manage.py migrate`` to get it in and you're done in only
  110. one more step than syncdb!
  111. Later on, you'll add models to your app, or change your fields. Each time you do
  112. this, run schemamigration with the --auto flag::
  113. ./manage.py schemamigration myapp --auto changed_user_model_bug_434
  114. You can also manually specify changes::
  115. ./manage.py schemamigration mitest some_cols --add-field User.age --add-model User
  116. See the tutorial for more.
  117. Finally, if you're writing a schema migration that South can't automatically create
  118. for you (yet!) then you can just create a skeleton:
  119. ./manage.py schemamigration myapp my_new_column_migration --empty
  120. Note that if you're writing a data migration, you should use the
  121. :ref:`commands-datamigration` command instead.
  122. Options
  123. ^^^^^^^
  124. Note that you can combine as many ``--add-X`` options as you like.
  125. - ``--add-model``: Generates a creation migration for the given modelname.
  126. - ``--add-field``: Generates an add-column migration for modelname.field.
  127. - ``--add-index``: Generates an add-index migration for modelname.field.
  128. - ``--initial``: Like having --model for every model in your app.
  129. You should use this only for your first migration.
  130. - ``--auto``: Generates a migration with automatically-detected actions.
  131. - ``--stdout``: Writes the migration to stdout instead of a file.
  132. .. _commands-datamigration:
  133. datamigration
  134. -------------
  135. *(In South 0.6 and below, this is called startmigration)*
  136. When you want to create a data migration, use this command to create a blank
  137. template to write your migration with::
  138. ./manage.py datamigration books capitalise_titles
  139. You can also freeze in additional apps if you want::
  140. ./manage.py datamigration books capitalise_titles --freeze awards
  141. Options
  142. ^^^^^^^
  143. - ``--freeze``: Use appname or appname.modelname to freeze additional models into the app.
  144. - ``--stdout``: Writes the migration to stdout instead of a file.
  145. graphmigrations
  146. ---------------
  147. *(New in South 0.7)*
  148. Run this command to generate a graphviz .dot file for your migrations; you
  149. can then use this to generate a graph of your migrations' dependencies.
  150. Typical usage::
  151. ./manage.py graphmigrations | dot -Tpng -omigrations.png
  152. This command can be particularly helpful to examine complex dependency sets
  153. between lots of different apps [#]_.
  154. .. [#] This command was written and used for the first time while helping the
  155. debug the rather complex set of dependencies in django-cms; it's quite
  156. a sight to behold.
  157. Options
  158. ^^^^^^^
  159. This command has no options.
  160. syncdb
  161. ------
  162. South overrides the Django syncdb command; as well as changing the output
  163. to show apps delineated by their migration status, it also makes syncdb only
  164. work on a subset of the apps - those without migrations.
  165. If you want to run syncdb on all of the apps, then use ``--all``, but be warned;
  166. this will put your database schema and migrations out of sync. If you do this,
  167. you *might* be able to fix it with::
  168. ./manage.py migrate --fake
  169. Options
  170. ^^^^^^^
  171. - ``--all``: Makes syncdb operate on all apps, not just unmigrated ones.