Learn about Migration Best Practices and how to avoid common errors.
When working with Django, there are a few things to keep in mind to avoid common migration errors. This article will teach you some best practices for managing migrations and help you avoid common errors.
Migration Best Practices
In Django, you should consider your migrations permanent and atomic. By permanent, we mean that all migrations must be kept--do not delete your migrations! And by atomic, we mean that migrations should be "essentially indivisible, unchangeable, whole, and irreducible." Keeping these two principles in mind, here are some best practices for managing your migrations.
- Commit all DB migrations to the repo. A common source of migration errors on deployment has to do with migrations that exist locally but not in the repo. Avoid this by committing every single migration to your repo. Even if you're just messing around testing out things, it's much easier to apply new migrations for your changes if you hang on to all of your migrations and put them in the repo.
- Do not delete migrations! As above, migrations should be considered permanent and atomic. Deleting them can cause lots of problems for you. Instead of deleting migrations, simply add new migrations reversing your previous migrations.
- Do not change existing migrations! Similar to the previous points, one thing you should never do is modify your existing migrations after they have been committed and deployed. Doing so will cause a lot of problems. If you need to modify your migrations, the best way to do so is by simply writing new migrations instead.
- Watch out for duplicates. Another common cause of migration problems are migrations with duplicate names. By default, Django should generate your file names, but keep an eye on these to make sure they don't overlap.
If you do run into migration problems, see if you can isolate the problem to your production environment vs your local setup. Are migrations failing? If so, check to make sure that you've checked in all your migrations to the Github repo, and ensure that you have no duplicates.
Another migration related error you may run is that, although your app deploys successfully, things don't work correctly after deployment. You may not see any problems during deployment, but afterward, you will see either 500s or certain model related functionality not working. This, too, tends to be a migration error. In this case, check your server logs to see what the specific error you're encountering is.