README.rst

django-squash

"django-squash" is a migration enhancement built on top of Django's standard migration classes. It aims to eliminate bloat and slowness in migration processes by replacing certain commands. The vision and architecture of Django migrations remain unchanged.

Before using "django-squash," it's important to understand the normal Django makemigrations and squashmigrations commands. Migration files consist of operations that may or may not affect the database table for a model. "elidable" operations can be eliminated when squashing migrations, while "non-elidable" operations cannot. Best way to think about the word "elidable" is to simply think "forgetable" or "disgardable" -- can this operation be disgarded once it's been ran?

The package introduces a command named squash_migrations as an alternative to Django's squashmigrations. This command minimizes the number of operations needed to build the database's schema, resulting in faster testing pipelines and deployments, especially in scenarios with multiple tenants.

The catch lies in proper usage of elidable vs. non-elidable operations and the requirement that databases must not fall behind to the point where eliminated migration operations are needed. The squash_migrations command removes all elidable operations and preserves non-elidable ones.

It's crucial to run the squash_migrations command once per release after cutting the release. All databases must be on the current release, the prior release, or somewhere in between. Databases before the prior release cannot directly upgrade to the current release; they must first apply the prior release's migrations and then the current release's minimal operations.

This approach is not a tutorial on migration strategy but emphasizes the need for understanding multi-app systems, avoiding circular dependencies, and designing efficient migration processes. The tool is developed based on experience and frustration, aiming to automate and improve the migration squashing process.

You can read more about our motivation to creating this tool.

Setup

1. pip install django-squash

2. Add django_squash to your INSTALLED_APPS.

   (optional) There are some settings you can customize

3. Run ./manage.py squash_migrations once after each release

4. Profit!

Developing

1. clone the repo
2. cd into repo
3. (optional) run inside docker environment that way you can change the python version quickly and iterate faster

docker run --rm -it -v .:/app -v django-squash-pip-cache:/root/.cache/pip -e PYTHONDONTWRITEBYTECODE=1 python:3.12 bash -c "cd app; pip install -e .[test,lint]; echo \"alias linters=\\\"echo '> isort'; isort .; echo '> black'; black .; echo '> ruff'; ruff check .;echo '> flake8'; flake8 .; echo '> rst-lint'; rst-lint README.rst docs/*\\\"\" >> ~/.bash_profile; printf '\n\n\nrun **pytest** to run tests, **linters** to run linters\n\n'; exec bash --init-file ~/.bash_profile"

Alternatively, you can also create a virtual environment and run

python3 -m venv venv

source venv/bin/activate

pip install -e '.[test]'

4. Run tests

pytest

5. Before making a commit, make sure that the formatter and linter tools do not detect any issues.

isort .
black .
flake8 .
ruff check .
rst-lint .