David Cain
0c5519d9dc
Briefly, this check helps prevent a long-running index creation from preventing all reads and writes to a table. This supplements an existing check ================================== There is an existing check, `CREATE_INDEX` which warns about creating indices without the `CONCURRENTLY` argument. It's a helpful check! However, there are some valid reasons to prefer non-concurrent index creation. For example, concurrent index creation may struggle to complete when applied to write-heavy tables (since Postgres will have to make repeated passes on the table to accommodate the new reads since the last round). The danger of `EXCLUSIVE` locks =============================== If you *do* want to create indices nonconcurrently, there is still a **huge footgun** to be aware of -- locks which are held in a transaction are not released until the transaction closes. Dangerous Django defaults ========================= By default, any time you add a new Django field with `db_index=True` or `unique=True`, the automatically generated `Migration` has: - implicit setting of `atomic=True` (transactions are on) - an `ALTER TABLE...ADD COLUMN` call (exclusively locks the table) - a `CREATE INDEX` invocation (*hopefully* quick, due to nullable columns) It's even more dangerous if you combine an `ALTER TABLE` call with `CREATE INDEX` of an existing, non-nullable column. Favor `atomic=False` if you must index ====================================== Index-creating migrations should have few `operations`. Since index creation does not modify row-level data (and only requires locking against writes), there's no reason to use transactions. It's prudent to bypass the default `atomic=True` for index creation.
Django migration linter
Detect backward incompatible migrations for your Django project. It will save you time by making sure migrations will not break with a older codebase.
Quick installation
pip install django-migration-linter
And add the migration linter to your INSTALLED_APPS:
INSTALLED_APPS = [
...,
"django_migration_linter",
...,
]
Optionally, add a configuration:
MIGRATION_LINTER_OPTIONS = {
...
}
For details about configuration options, checkout Usage.
Usage example
$ python manage.py lintmigrations
(app_add_not_null_column, 0001_create_table)... OK
(app_add_not_null_column, 0002_add_new_not_null_field)... ERR
NOT NULL constraint on columns
(app_drop_table, 0001_initial)... OK
(app_drop_table, 0002_delete_a)... ERR
DROPPING table
(app_ignore_migration, 0001_initial)... OK
(app_ignore_migration, 0002_ignore_migration)... IGNORE
(app_rename_table, 0001_initial)... OK
(app_rename_table, 0002_auto_20190414_1500)... ERR
RENAMING tables
*** Summary ***
Valid migrations: 4/8
Erroneous migrations: 3/8
Migrations with warnings: 0/8
Ignored migrations: 1/8
The linter analysed all migrations from the Django project. It found 3 migrations that are doing backward incompatible operations and 1 that is explicitly ignored. The list of incompatibilities that the linter analyses can be found at docs/incompatibilities.md.
More advanced usages of the linter and options can be found at docs/usage.md.
Integration
One can either integrate the linter in the CI using its lintmigrations command, or detect incompatibilities during generation of migrations with
$ python manage.py makemigrations --lint
Migrations for 'app_correct':
tests/test_project/app_correct/migrations/0003_a_column.py
- Add field column to a
Linting for 'app_correct':
(app_correct, 0003_a_column)... ERR
NOT NULL constraint on columns
The migration linter detected that this migration is not backward compatible.
- If you keep the migration, you will want to fix the issue or ignore the migration.
- By default, the newly created migration file will be deleted.
Do you want to keep the migration? [y/N] n
Deleted tests/test_project/app_correct/migrations/0003_a_column.py
The linter found that the newly created migration is not backward compatible and deleted the file after confirmation.
This behaviour can be the default of the makemigrations command through the MIGRATION_LINTER_OVERRIDE_MAKEMIGRATIONS Django setting.
Find out more about the makemigrations command at docs/makemigrations.md.
More information
Please find more documentation in the docs/ folder.
Some implementation details can be found in the ./docs/internals/ folder.
Blog post
They talk about the linter
Related
- django-test-migrations - Test django schema and data migrations, including migrations' order and best practices.
License
django-migration-linter is released under the Apache 2.0 License.