Django Migration Linter

6.0.0 · active · verified Sun Apr 12

django-migration-linter is a tool for Django projects designed to detect backward incompatible database migrations. It analyzes new migrations against a baseline (e.g., a Git branch) to prevent accidental breaking changes to your database schema. The current version is 6.0.0, and it maintains an active release cadence, frequently adding support for new Python and Django versions.

Warnings

breaking As of v6.0.0, `django-migration-linter` now correctly handles custom Django app labels when determining migrations from a Git reference. Previously, it might have relied on folder names. If your project uses custom app labels, the linter will now reference apps by their Django label, which might change detection behavior if you were implicitly relying on folder names.
Fix: No direct code change is typically needed unless your specific setup or scripts relied on the old behavior for custom-labeled apps. Ensure your `django_migration_linter` configuration and expectations align with app labels.
breaking Beginning with v5.0.0, the linter no longer silently ignores failures that occur during its internal calls to Django's `sqlmigrate` command. Instead, it will now crash and raise the `sqlmigrate` error. This change prevents problematic migrations from passing the linter unnoticed, especially if SQL generation requires specific database conditions.
Fix: Ensure your environment (e.g., CI/CD) provides a correctly configured and accessible database for `sqlmigrate` to run successfully. Address any underlying issues causing `sqlmigrate` errors. If an error is truly ignorable (rare), you can use the `--ignore-sqlmigrate-errors` option (available from v5.1.0 and later).
breaking In v3.0.0, the command-line interface for `lintmigrations` underwent a breaking change. The `GIT_COMMIT_ID` positional argument became an optional named argument (`--git-commit-id [GIT_COMMIT_ID]`), and the command now accepts `[app_label]` and `[migration_name]` as new positional arguments.
Fix: Update any scripts or CI/CD configurations that invoke `manage.py lintmigrations` to use the new argument syntax, for example: `manage.py lintmigrations --git-commit-id <commit_id>`.
gotcha The linter's deep analysis often depends on Django's `sqlmigrate` command, which typically requires an active database connection to generate and inspect the SQL for migration files. Running the linter in an environment without a configured or accessible database can lead to `sqlmigrate` failures, which will crash the linter (since v5.0.0).
Fix: Ensure your environment where `lintmigrations` is run (e.g., local development, CI/CD pipeline) has a valid database connection configured in Django settings. You can use a lightweight database like SQLite for testing purposes if full database functionality isn't strictly needed for the SQL analysis.
breaking Numerous releases have dropped support for older Python and Django versions. For instance, Python 3.7 and 3.8 were dropped in v5.2.0. Django 1.11, 2.0, 2.1, 3.0, and 3.1 were dropped in v4.0.0, alongside Python 2.7, 3.5, and 3.6.
Fix: Always consult the specific release notes for the `django-migration-linter` version you intend to use to confirm compatibility with your project's Python and Django versions. Upgrade your Python/Django stack if it falls outside the supported range for the desired linter version.

Install

pip install django-migration-linter Install via pip

Quickstart

To quickly use `django-migration-linter`, add it to your `INSTALLED_APPS` and then execute the `lintmigrations` management command. The example demonstrates how to run the linter to compare migrations in your current branch against the 'main' branch, ensuring that any detected warnings will cause the command to fail. This is typically run in CI/CD pipelines.

# 1. Add 'django_migration_linter' to your INSTALLED_APPS in settings.py:
#    INSTALLED_APPS = [
#        ...,
#        'django_migration_linter',
#    ]

# 2. Run the linter as a Django management command.
#    This example compares new migrations against the 'main' Git branch
#    and treats any linter warnings as errors (failing the check).
import subprocess
import os

# Ensure your Django settings are configured for manage.py
# (e.g., DJANGO_SETTINGS_MODULE environment variable)

try:
    print("Running django-migration-linter...")
    subprocess.check_call([
        "python", "manage.py", "lintmigrations",
        "--git-commit-id", "main",
        "--warnings-as-errors"
    ])
    print("\nMigrations linted successfully with no backward incompatible changes detected.")
except subprocess.CalledProcessError as e:
    print(f"\nMigration linter failed with exit code {e.returncode}:")
    print("Please review the output for backward incompatible changes and fix them.")
except FileNotFoundError:
    print("Error: 'python' command not found. Ensure Python is in your PATH and manage.py exists.")

view raw JSON →