Django migrations
Read these files first, before writing or editing a migration:
-
docs/published/handbook/engineering/developing-locally.md (## Django migrations , ### Non-blocking migrations , ### Resolving merge conflicts )
-
docs/published/handbook/engineering/safe-django-migrations.md
-
docs/published/handbook/engineering/databases/schema-changes.md
-
products/README.md (## Adding or moving backend models and migrations ) when working in products/*
If the task is a ClickHouse migration, use clickhouse-migrations instead.
Workflow
-
Classify the change as additive (new nullable column, new table) or risky (drop/rename, NOT NULL , indexes, constraints, large data updates, model moves).
-
Generate: DEBUG=1 ./manage.py makemigrations [app_label] . For merge conflicts: python manage.py rebase_migration <app> && git add <app>/migrations (posthog or ee ).
-
Apply safety rules from safe-django-migrations.md — the doc covers multi-phase rollouts, SeparateDatabaseAndState , concurrent operations, idempotency, and all risky patterns in detail.
-
Validate: ./manage.py sqlmigrate <app> <migration_number> , run tests, confirm linear migration sequence.