Generate Django Database Migrations

Generate Django Database Migrations

Commands

Generate migrations automatically based on model changes:

sentry django makemigrations

For a specific app:

sentry django makemigrations <app_name>

Generate an empty migration (for data migrations or custom work):

sentry django makemigrations <app_name> --empty

After Generating

1. If you added a new model, ensure it's imported in the app's __init__.py
2. Review the generated migration for correctness
3. Run sentry django sqlmigrate <app_name> <migration_name> to verify the SQL
4. Apply the migration locally with sentry django migrate <app_name> — Sentry's migration framework runs its safety checks on apply, so this catches unsafe ops (missing is_post_deployment, unsafe column changes, etc.) before CI does.

When editing a generated migration (e.g. swapping DeleteModel for SafeDeleteModel), leave the auto-generated is_post_deployment comment block in place. It documents a non-obvious flag with concrete guidance for future migration authors — useful context, not fluff. Only remove a comment if it's stale or contradicts the code.

Don't test the ORM

Don't write tests that only exercise Django's ORM. Standard operations — create/update/delete, cascading deletes, unique-constraint enforcement — are provided by Django and Postgres and are assumed to work. Test your logic (business rules, signal receivers, custom managers/validation), not the framework's.

Do test data migrations and backfills

The exception to the above: a migration that backfills or transforms data is your logic, and it must have a test. Use the TestMigrations base class from sentry.testutils.cases; tests live in tests/sentry/migrations/.

Set app, migrate_from (the migration just before yours), and migrate_to (yours). Seed pre-migration rows in setup_before_migration(self, apps) using the historical model registry (apps.get_model("sentry", "MyModel")) — not a direct from sentry.models... import, since the current model may not match the schema at migrate_from. Then assert the post-migration state.