Django migrations

• 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/*

clickhouse-migrations

Workflow

1. Classify the change as additive (new nullable column, new table) or risky (drop/rename,

   NOT NULL

   , indexes, constraints, large data updates, model moves).
2. Generate:

   DEBUG=1 ./manage.py makemigrations [app_label]

   . For merge conflicts:

   python manage.py rebase_migration <app> && git add <app>/migrations

   (

   posthog

   or

   ee

   ).
3. Apply safety rules from

   safe-django-migrations.md

   — the doc covers multi-phase rollouts,

   SeparateDatabaseAndState

   , concurrent operations, idempotency, and all risky patterns in detail.
4. Validate:

   ./manage.py sqlmigrate <app> <migration_number>

   , run tests, confirm linear migration sequence.