= Tutorial, part 4: Workflow and Teams = ''(You may want to read [wiki:Tutorial1 Part 1: The Basics], [wiki:Tutorial2 Part 2: Changing Models], or [wiki:Tutorial3 Part 3: Data Migrations])'' Migrations are all about improving the workflow for the developers and database administrators of projects, and we think it's very important that it doesn't add too much overhead to your daily coding, while at the same time reducing headaches caused by the inevitable changes in schema every project has. Firstly, note that migrations aren't a magic bullet. If you've suddenly decided you're going to rearchitect your entire database schema, it might well be easier to not write migrations and just start again, especially if you have no production sites using the code (if you do, you might find custom serialisation/unserialisation to be a better way of saving your data). With that in mind, migrations are really something you should be using the rest of the time. Hopefully, the previous parts of the tutorial have got you familiar with what can easily be achieved with them; we've tried to cover a good percentage of use cases, and if you think something should be included, don't hesitate to [wiki:Documentation#Support get in touch]. == Developer Workflow == As a developer, you should be doing things in this order: * Make the change to your models.py file (and affected code, such as post_syncdb signal hooks) * Make the migration * Rinse, repeat. Don't try to make migrations before you make the changes; this will both invalidate the frozen model data on the migration and make `startmigration --auto` think nothing has changed. If you're making a large change, and want to split it over several migrations, do each schema change to `models.py` separately, then make the migration, and then make the next small change. == Team Workflow == While migrations for an individual developer are useful, teams are the real reason they exist. It's very likely more than one member of your team will be making database changes, and migrations allow the other developers to apply their schema changes effortlessly and reproducibly. You should keep all of your migrations in a VCS (for obvious reasons), and encourage developers to run `./manage.py migrate` if they see a new migration come in when they do an `update` or `pull`. The issue with teams and migrations occurs when more than one person makes a migration in the same timeslot, and they both get committed without the other having been applied. This is analogous to two people editing the same file in a VCS at the same time, and like a VCS, South has ways of resolving the problem. If this happens, the first thing to note is that South will detect the problem, and issue a message like this: {{{ $ ./manage.py migrate game Running migrations for game: ! Migration (game, 0011_game_masters) should not have been applied before (game, 0010_test) but was. ! Inconsistent migration history ! The following options are available: --merge: will just attempt the migration ignoring any potential dependency conflicts. }}} South knows that, while the 0010 migration should have been applied before 0011, it has not been (since the developer has presumably written their own 0010 and 0011 migrations, and then pulled in another developer's 0010). The two 0010 migrations will still exist, as they have different names (if not, your VCS will have thrown a wobbly already). If we run the command `./manage.py migrate --list`, South will give us a listing of what migrations we have, and which are applied: {{{ $ ./manage.py migrate --list game * 0001_initial * 0002_rule_system * 0003_players_n_stuff * 0004_rule_slug * 0005_player_location * 0006_location_stop * 0007_move_stops * 0008_game_rules * 0009_player_user * 0010_player_users_m2m 0010_test * 0011_game_masters }}} This shows the problem more clearly (migrations with a `*` have been applied; those without have not). In normal operation, there will be a continuous set of `*`s, and then a continuous set of unapplied migrations, but here there's a gap. The proposed solution South has offered you is `./manage.py migrate game --merge`, which will simply run through the missing migrations in order and apply them straight away. If the migrations are in different parts of the codebase, this generally works; if they both touch the same table or column, it may end in tears. The alternative is to manually roll back to the gap, apply the migration, and roll forwards again. (In order to prevent South issuing the 'missing migrations' warning all the time, you will need to use `--skip`, which will simply ignore the missing migrations for now) In this example, that would be: {{{ ./manage.py migrate game 0010_player_users_m2m --skip ./manage.py migrate game }}} Once we've rolled back to the migration before the gap, the migrations are now in an acceptable order, and South will then happily apply the second `0010` migration and then `0011` as normal. However, this could still be somewhat dodgy if both migrations are really playing with the same area. '''South is no substitute for team coordination''' - in fact, most of the features are there purely to warn you that you haven't coordinated, and the simple merging on offer is only there for the easy cases. Make sure your team know who is working on what, so they don't write migrations that affect the same parts of the DB at the same time. Note that after any kind of merge, '''autodetection will not work correctly until you make a new blank migration'''. To do this, just run: {{{ ./manage.py startmigration appname autodetect_fix }}} == Real-world Examples == We'd love to have some real-world case studies of projects that have used South to stick here. If you have one, or end up making one, please [wiki:Documentation#Support get in touch]. == Adding South to existing projects == One of the great problems people have with migrations is that they always need them after they've started the project. One of the goals of South is to lower the barrier to entry as much as possible, and make adding migrations to your pre-existing applications a breeze; this process is documented on the ConvertingAnApp page. == Complex Application Sets == It is often the case that, with Django projects, there is a set of apps which references each others' models.py files. This is, at its truest form, a dependency, and to ensure your migrations for such sets of applications apply sanely (i.e. the migrations that create the tables in one app happen before the migration that adds !ForeignKeys to them in another app), South has a [wiki:Dependencies Dependencies] feature. Once you've added dependencies to your migrations, South will ensure all prerequisites of a migration are applied before applying the migration itself. == That's All, Folks == Thanks for reading through the South tutorial; we hope you found it useful. * South has more documentation and reference articles on many parts of the system; check the [wiki:Documentation Documentation] page. * There's plenty of [wiki:Documentation#Support support] available if you have advanced needs, or are confused on some issues. * If you think a feature is missing or broken, then [wiki:Documentation#Support get in touch]! We're more than happy to get suggestions; a large part of the current design of South is driven by user input. * Finally, if you feel like contributing to the code, there's a [wiki:Contributing page about that], too.