Skip to main content

Detect backward incompatible migrations for your django project

Project description

Detect backward incompatible migrations for your django project. It will save you time by making sure migrations will not break anything.

https://travis-ci.org/3YOURMIND/django-migration-linter.svg?branch=master https://img.shields.io/pypi/v/django-migration-linter.svg https://img.shields.io/github/license/3yourmind/django-migration-linter.svg https://img.shields.io/badge/PR-welcome-green.svg https://img.shields.io/badge/3YOURMIND-Hiring-brightgreen.svg https://img.shields.io/github/stars/3YOURMIND/django-migration-linter.svg?style=social&label=Stars

Installation

pip install django-migration-linter

Usage

Add the migration linter your INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "django_migration_linter",
    ...,
]

python manage.py lintmigrations [GIT_COMMIT_ID] [--ignore-name-contains IGNORE_NAME_CONTAINS] [--include-apps INCLUDE_APPS [INCLUDE_APPS ...] | --exclude-apps EXCLUDE_APPS [EXCLUDE_APPS ...]] [--project-root-path DJANGO_PROJECT_FOLDER]

Parameter

Description

GIT_COMMIT_ID

If specified, only migrations since this commit will be taken into account. If not specified, all migrations will be linted.

--ignore-name-contains IGNORE_NAME_CONTAINS

Ignore migrations containing this name.

--ignore-name IGNORE_NAME [IGNORE_NAME ...]

Ignore migrations with exactly one of these names.

--include-apps INCLUDE_APPS [INCLUDE_APPS ...]

Check only migrations that are in the specified django apps.

--exclude-apps EXCLUDE_APPS [EXCLUDE_APPS ...]

Ignore migrations that are in the specified django apps.

--verbose or -v

Print more information during execution.

--database DATABASE

Specify the database for which to generate the SQL. Defaults to default.

--cache-path PATH

specify a directory that should be used to store cache-files in.

--no-cache

Don’t use a cache.

--applied-migrations

Only lint migrations that are applied to the selected database. Other migrations are ignored.

--unapplied-migrations

Only lint migrations that are not yet applied to the selected database. Other migrations are ignored.

--project-root-path DJANGO_PROJECT_FOLDER

An absolute or relative path to the django project.

Examples

3YOURMIND is running the linter on every build getting pushed through CI. That enables to be sure that the migrations will allow A/B testing, Blue/Green deployment and they won’t break your development environment. As every reasonable tool, a non-zero error code means that at least one invalid migration has been found.

Backward incompatible migrations

The linter analyses your migrations and checks the SQL for:

  • Added NOT NULL columns, which don’t have a DEFAULT value

  • Dropping columns

  • Renaming columns

  • Renaming tables

  • Altering columns (which can be backward compatible and potentially ignored)

Those are the most important and frequent backward incompatible migrations. We are happy to add more if you can specify them to us.

Ignoring migrations

You can also ignore migrations by adding this to your migrations:

import django_migration_linter as linter
# ...

    operations = [
        linter.IgnoreMigration(),
        # ...
    ]
# ...

Cache

By default, the linter uses a cache to prevent linting the same migration multiple times. The default location of the cache on Linux is /home/<username>/.cache/django-migration-linter/<version>/<ldjango-project>_<database_name>.pickle.

Since the linter uses hashes of the file’s content, modifying a migration file will re-run the linter on that migration. If you want to run the linter without cache, use the flag --no-cache. If you want to invalidate the cache, delete the cache folder. The cache folder can also be defined manually through the --cache-path option.

Tests

The easiest way to run the tests is to invoke tox.

You will need to install the test requirements, which can be found in the setup.py file. A good way to get started is to install the development version of the linter by doing pip install -e .[test].

To be able to fully test the linter, you will need both MySQL and PostgreSQL databases running. You can either tweak the tests/test_project/settings.py file to get your DB settings right, or to have databases and users corresponding to the default Travis users.

Contributing

First, thank you very much if you want to contribute to the project. Please base your work on the master branch and also target this branch in your pull request.

Publishing the package

A small note on how the linter is usually published to PyPi:

  • python setup.py check --restructuredtext

  • python3 setup.py sdist bdist_wheel --universal

  • twine upload dist/django_migration_linter-X.Y.Z-py2.py3-none-any.whl dist/django-migration-linter-X.Y.Z.tar.gz

Blog post

Keeping Django database migrations backward compatible

License

django-migration-linter is released under the Apache 2.0 License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-migration-linter-1.2.0.tar.gz (24.1 kB view details)

Uploaded Source

Built Distribution

django_migration_linter-1.2.0-py2.py3-none-any.whl (56.3 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file django-migration-linter-1.2.0.tar.gz.

File metadata

  • Download URL: django-migration-linter-1.2.0.tar.gz
  • Upload date:
  • Size: 24.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.3 requests-toolbelt/0.8.0 tqdm/4.29.1 CPython/3.6.8

File hashes

Hashes for django-migration-linter-1.2.0.tar.gz
Algorithm Hash digest
SHA256 d2bcfd9d6379b01acfed992bec674f3d6d8c2ee15fe55a7bf3589faf4c863647
MD5 abf90dd141d8171bd166bd22eefc1204
BLAKE2b-256 4179ed2fd276afef0600965d98b56e8485247ffc3c08cca45fb20a4f176e1760

See more details on using hashes here.

File details

Details for the file django_migration_linter-1.2.0-py2.py3-none-any.whl.

File metadata

  • Download URL: django_migration_linter-1.2.0-py2.py3-none-any.whl
  • Upload date:
  • Size: 56.3 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.3 requests-toolbelt/0.8.0 tqdm/4.29.1 CPython/3.6.8

File hashes

Hashes for django_migration_linter-1.2.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 fc73c27320253421755e2f978b79e497f9e7b53b479af85efa7a1bd3b3eaab9c
MD5 ff66925d0108da8afd7ae3c1266db71e
BLAKE2b-256 d8d54ae994dc909b4a6ea912efd0fd807ff3dd56f6c12eba1a519242fc86ab92

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page