migrationstructure.rst 1.9 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849
  1. .. _migration-structure:
  2. Migration Structure
  3. ===================
  4. Migrations are, at the most basic level, files inside your app's migrations/
  5. directory.
  6. When South loads migrations, it loads all the python files inside migrations/
  7. in ASCII sort order (e.g. 1 is before 10 is before 2), and expects to find a
  8. class called Migration inside each one, with at least a ``forwards()``
  9. and ``backwards()`` method.
  10. When South wants to apply a migration, it simply calls the ``forwards()``
  11. method, and similarly when it wants to roll back a migration it calls
  12. ``backwards()``. It's up to you what you do inside these methods; the usual
  13. thing is to do database changes, but you don't have to.
  14. Sort Order
  15. ----------
  16. Since migrations are loaded in ASCII sort order, they won't be applied in the
  17. correct order if you call them ``1_first, 2_second, ..., 10_tenth``.
  18. (10 sorts before 2).
  19. Rather than force a specific naming convention, we suggest that if you want to
  20. use numerical migrations in this fashion (as we suggest you do) that you prefix
  21. the numbers with zeroes like so: ``0001_first, 0002_second, 0010_tenth``.
  22. All of South's automatic creation code will follow this scheme.
  23. Transactions
  24. ------------
  25. Whenever ``forwards()`` or ``backwards()`` is called it is called inside a
  26. database transaction, which is committed if the method executes successfully
  27. or rolled back if it raises an error.
  28. If you need to use two or more transactions inside a migration, either use
  29. two separate migrations (if you think it's appropriate), or have a snippet
  30. like this where you want a new transaction::
  31. db.commit_transaction() # Commit the first transaction
  32. db.start_transaction() # Start the second, committed on completion
  33. Note that you must commit and start the next transaction if you are making
  34. both data and column changes. If you don't do this, you'll end up with your
  35. database hating you for asking it the impossible.