How do I handle migrations as a Django package maintainer?

Question

I have been writing a new Django package that will be pip-installable. I've been stuck for awhile because I'm unsure how to make migrations for my particular package so to allow for the normal workflow of an install to be:

1. pip install my package
2. add my package to your "INSTALLED_APPS"
3. run python manage.py migrate

Currently, my package looks like this:

package_root/
    dist/
    actual_package/
        __init__.py
        models.py
    setup.py

The problem I am facing is that when I package the app and install it using pip install dist/... and then add it to my example apps "INSTALLED_APPS", running python manage.py migrate does not create any tables for the models in actual_package/models.py and hence I (from a users perspective) need to then run python manage.py makemigrations actual_package first, which is not ideal.

Any ideas on how to have the migrations already sorted before a user installs would be excellent.

Answer 1

1 - Include the initial migrations in the package - e.g., actual_package/migrations/0001_initial.py

2 - Include python manage.py migrate actual_package as part of the installation process - whether new or update.

3 - If you publish updates to actual_package, include any new migrations.

This should work for both new installations and updates. If the migrations have already been done (e.g., update but no new migrations included) then the migrate command won't hurt.

One key warning: Make sure your package installation checks for the appropriate Django version. There have been a lot of changes between versions and code - and migrations - for one version may not work for another.

Answer 2

Reading the comments it seems like the question is how do we go about creating the migration file for our models in the package, i.e. what is the equivalent of python manage.py makemigrations for a package developer.

I went around this by including an example django project in the package at /example/ then if you run makemigrations with the project's manage.py and settings.py, it will magically create migrations in your package migrations folder too!