Metadata-Version: 2.4
Name: django-zdm
Version: 0.4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Database
License-File: LICENSE
Summary: A PostgreSQL migration safety linter for Django
Keywords: django,postgresql,migrations,linter,database,safety
Author-email: Photoroom <eng@photoroom.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/Photoroom/zero-downtime-migrations/issues
Project-URL: Documentation, https://github.com/Photoroom/zero-downtime-migrations#readme
Project-URL: Homepage, https://github.com/Photoroom/zero-downtime-migrations
Project-URL: Repository, https://github.com/Photoroom/zero-downtime-migrations

# zero-downtime-migrations (zdm)

A PostgreSQL migration safety linter for Django.

## Why

Deploying database migrations without downtime requires careful attention to how PostgreSQL acquires locks. Operations like adding an index, altering a column to NOT NULL, or adding a foreign key can lock tables for extended periods on large datasets, blocking reads and writes and causing outages. zdm statically analyzes Django migration files to catch these unsafe patterns before they reach production, helping teams ship schema changes safely during normal deployments.

## What

A standalone Rust CLI tool that statically analyzes Django migration files to catch unsafe patterns that cause table locks, outages, and data loss on large PostgreSQL databases. Distributed like ruff/uv — a single fast binary, installable via `pip`, `uvx`, or standalone download.

**Supports Django 3.2+** — zdm parses migration files directly without importing Django, so it works with any Django version and doesn't require Django to be installed.

## Installation

> **Breaking change:** the `zero-downtime-migrations` command alias has been removed. Use `zdm`. (`alias zero-downtime-migrations=zdm` in your shell is a one-line workaround if you depended on the old name.)

```bash
# Install via pip (PyPI package is django-zdm; binary is `zdm`)
pip install django-zdm

# Or use uvx to run without installing
uvx --from django-zdm zdm .

# Or install with pipx
pipx install django-zdm
```

## Usage

```bash
# Lint a single migration
zdm app/migrations/0042_add_index.py

# Lint all migrations in a directory
zdm app/migrations/

# Lint all migrations in the project
zdm .

# Diff mode: lint changed migrations in a PR
zdm --diff origin/main

# Staged diff mode: lint changes being committed by pre-commit
zdm --diff-staged origin/main

# Output formats
zdm --output-format json .
zdm --output-format compact .

# Select/ignore specific rules
zdm --select R001,R003 .
zdm --ignore R008 .

# Show explanation for a rule
zdm rule R001

# List every rule the binary recognises
zdm --list-rules

# Treat warnings as errors
zdm --warnings-as-errors .
```

`--diff` compares the merge base to `HEAD` and reads file contents from the
`HEAD` tree, giving deterministic PR/CI results even when the worktree is
dirty. `--diff-staged` compares the same merge base to the index and reads the
staged blobs.

### Exit Codes

- `0` — no issues found
- `1` — lint violations found (errors). Warnings alone do NOT cause exit code 1 unless `--warnings-as-errors` is set.
- `2` — tool error (bad arguments, config parse failure, invalid file path)

### JSON Output Schema

`zdm --output-format json` writes a single JSON object to stdout:

```json
{
  "diagnostics": [
    {
      "rule_id":   "R001",
      "rule_name": "non-concurrent-add-index",
      "severity":  "error",
      "message":   "Use AddIndexConcurrently instead of AddIndex …",
      "path":      "app/migrations/0001_bad.py",
      "line":      8,
      "column":    9,
      "help":      "Replace migrations.AddIndex with …"
    }
  ],
  "summary": { "total": 1, "errors": 1, "warnings": 0 }
}
```

`severity` is `"error"` or `"warning"`. `help` is `null` when the
rule has no help text. The schema is pinned by the integration
test suite — every field above is guaranteed on every diagnostic.

## Rules

| Rule | Name | Severity | Description |
|------|------|----------|-------------|
| R001 | non-concurrent-add-index | Error | Use `AddIndexConcurrently` instead of `AddIndex` |
| R002 | unique-constraint-without-index | Error | Unique constraints should have a concurrent index |
| R003 | runsql-create-index | Error | Use `AddIndexConcurrently` instead of raw SQL `CREATE INDEX` |
| R004 | missing-atomic-false | Error | Non-atomic migrations require `atomic = False` |
| R005 | remove-field-without-separate | Error | Use `SeparateDatabaseAndState` to remove fields safely |
| R006 | add-field-foreign-key | Error | Adding FK creates index and validates constraint (merged R007) |
| R008 | disallowed-file-changes | Error | Don't change app code alongside migrations |
| R009 | separate-db-state-same-pr | Error | Don't deploy both steps of `SeparateDatabaseAndState` together |
| R010 | add-field-not-null | Error | Adding NOT NULL field without default rewrites table |
| R011 | rename-field | Error | Renaming fields can break running code |
| R012 | irreversible-run-python | Warning | `RunPython` should have a reverse function |
| R013 | irreversible-run-sql | Warning | `RunSQL` should have a reverse SQL |
| R014 | model-imports | Error | Don't import models in `RunPython` |
| R015 | alter-field-not-null | Warning | `AlterField` whose result is NOT NULL may scan every row |
| R016 | non-concurrent-remove-index | Error | Use `RemoveIndexConcurrently` instead of `RemoveIndex` |
| R017 | non-concurrent-add-constraint | Error | CHECK constraint validates all rows; EXCLUDE constraint builds an index non-concurrently |

### CreateModel Exemption

Several rules (R001, R002, R006, R010, R016, R017) automatically exempt operations that target models created in the same migration. This is because operations on newly created (empty) tables don't cause the locking issues these rules detect. The exemption is order-aware—a `CreateModel` that runs *after* the flagged op cannot retroactively exempt it—and follows `RenameModel` when the fresh table is renamed before a later operation.

> **Note:** R007 (`fk-without-concurrent-index`) was merged into R006 and retired. R006 now takes the conservative stance that a prebuilt concurrent index does not make a one-step `AddField(ForeignKey)` safe on an existing table. Split the rollout instead of relying on an index exemption.

For example, this migration will NOT trigger R001:

```python
class Migration(migrations.Migration):
    operations = [
        migrations.CreateModel(
            name='Order',
            fields=[('id', models.AutoField(primary_key=True))],
        ),
        migrations.AddIndex(  # Exempt: 'order' was just created above
            model_name='order',
            index=models.Index(fields=['created_at'], name='order_idx'),
        ),
    ]
```

### R015 Limitation

R015 (alter-field-not-null) cannot tell, from a single `AlterField` operation, whether the column was previously nullable. It flags any `AlterField` whose resulting field is NOT NULL, which catches a genuine nullable→NOT NULL transition (the dangerous case) alongside benign re-stipulations of an already-NOT-NULL column. Because static analysis has no schema history, the rule emits `Warning` rather than `Error` — surfaced for review without breaking CI. Add `# zdm: ignore R015` on operations you have verified are safe.

### Inline Suppression

You can silence specific rules on a per-operation basis with a comment:

```python
operations = [
    # zdm: ignore R001
    migrations.AddIndex(
        model_name='order',
        index=models.Index(fields=['created_at'], name='order_idx'),
    ),
    migrations.AlterField(  # zdm: ignore R015, R010
        model_name='product',
        name='sku',
        field=models.CharField(max_length=50),
    ),
]
```

The comment can sit on the line just above the operation or on the same line as any line in the operation's range. Multiple rule IDs may be listed, separated by commas.

## Configuration

Configure via `pyproject.toml` or `zero-downtime-migrations.toml`:

```toml
[tool.zdm]
select = ["R001", "R002"]
ignore = ["R008"]
warnings-as-errors = false
allowed-file-patterns = ["*.txt", "*.md", "models.py"]
exclude = ["**/test_migrations/**"]
```

### Configuration Precedence

Settings are applied in this order (highest to lowest priority):

1. **CLI flags** (`--select`, `--ignore`, `--warnings-as-errors`)
2. **`zero-downtime-migrations.toml`** found in the current directory or a trusted repo ancestor
3. **`pyproject.toml`** `[tool.zdm]` section in the same directory
4. **Default values**

The config search starts in the current working directory. On Unix, if zdm is running inside a trusted git repository, it walks upward within that repository and stops at the first directory that contains `zero-downtime-migrations.toml` or a `pyproject.toml` with `[tool.zdm]`. The nearest `.git` is always the boundary; an untrusted boundary never falls through to an outer repository. A pyproject for another tool is ignored, so running `zdm` from `repo/apps/myapp/migrations/` still picks up `repo/zero-downtime-migrations.toml`. Without a trusted `.git` ancestor—and on Windows, where zdm cannot yet validate repository ACL ownership—only the current directory is checked. Config inputs must be regular UTF-8 files no larger than 1 MiB.

CLI flags always override config file settings. If both `zero-downtime-migrations.toml` and `pyproject.toml` exist in the same directory, the standalone file takes precedence; multi-level merging is not performed.

## Pre-commit Integration

Install `zdm` in the environment where pre-commit runs, then call that installed
binary from your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: local
    hooks:
      - id: zdm
        name: zdm
        entry: zdm
        language: system
        types: [python]
        files: .*/migrations/.*\.py$
        exclude: __init__\.py$
```

Or use diff mode to only check changed migrations:

```yaml
repos:
  - repo: local
    hooks:
      - id: zdm-diff
        name: zdm diff
        entry: zdm --diff-staged origin/main
        language: system
        pass_filenames: false
        always_run: true
```

The `zdm-diff` hook uses `--diff-staged` so it checks the staged index that
pre-commit is validating, rather than the previous `HEAD` commit.

The repository also publishes source-based pre-commit hooks for users who prefer
`repo: https://github.com/Photoroom/zero-downtime-migrations` with
`rev: <latest release tag>`. Those hooks install the package from source, so
Rust must be available in the pre-commit environment.

## GitHub Actions

```yaml
- uses: actions/checkout@v4
  with:
    # --diff needs the base ref and enough history to compute a merge base.
    fetch-depth: 0

- name: Install zdm
  run: pip install django-zdm

- name: Lint migrations
  run: zdm --diff origin/main
```

## Rust library API

The Rust crate exposes a small programmatic API, but it remains experimental
while the project is in the 0.x series. Prefer `Migration::from_path` or
`Migration::from_source`, `Config`, and the built-in rule registries. Low-level
parser, extractor, diagnostic-construction, discovery, and git helpers may
change between minor 0.x releases.

## Comparison with Other Tools

| | zdm | django-migration-linter | Django's `makemigrations --check` |
|---|---|---|---|
| **Requires Django installed** | No | Yes | Yes |
| **Requires project setup** | No | Yes (settings.py) | Yes (full environment) |
| **Checks for missing migrations** | No | No | Yes |
| **Checks for unsafe operations** | Yes (16 active rules; `zdm --list-rules`) | Yes (~8 rules) | No |
| **Configurable via `pyproject.toml`** | Yes (walks up within trusted repos) | Yes | N/A |
| **Can run without database** | Yes | Yes | No |
| **Language** | Rust | Python | Python |

**When to use what:**
- Use `makemigrations --check` to ensure all model changes have migrations
- Use zdm or django-migration-linter to catch unsafe migration patterns
- zdm is useful when you want to run checks in CI without setting up Django, or when you need the additional rules (NOT NULL alterations, RenameField, irreversible migrations, RemoveIndex)

## License

MIT

