saleor/saleor-django-migration

Saleor Django Schema Migration

Scope

This skill handles schema-only migrations: CreateModel, AddField, AlterField, RemoveField, AddIndex, AddConstraint, etc. It does NOT cover:

• Data migrations (RunPython, RunSQL with data changes)
• Async/background migrations (celery tasks, post_migrate signals)

If the change requires data transformation, stop and ask the user.

Critical Rules

1. NEVER write migration files by hand. Always let Django generate them.
2. ALWAYS use ./manage.py makemigrations to generate migrations.
3. Activate the virtual environment first — run . .venv/bin/activate before any manage.py command.
4. If database connection fails, stop and ask the user to start the database.

Workflow

Step 1: Make model changes

Edit the Django model file(s) as needed. Do not touch any migration files.

Step 2: Generate migration

. .venv/bin/activate && python manage.py makemigrations

If Django asks interactive questions (e.g. "Did you rename field X to Y?"), answer based on the model changes you made.

Step 3: Read and analyze the generated migration

Read every generated migration file. Verify:

• It contains only schema operations (CreateModel, AddField, AlterField, RemoveField, AddIndex, etc.)
• Dependencies look correct
• No unexpected operations

Step 4: Apply separation rules

Apply these rules to the generated migration(s):

Rule A — One model per migration for new models: If the migration creates MORE THAN ONE new model (multiple CreateModel operations), split them. Generate each separately:

python manage.py makemigrations <app>

If Django generates them together, delete the combined migration, then create models one at a time (add one model to models.py, run makemigrations, repeat).

Rule B — One field change per migration: If the migration alters MORE THAN ONE field within a single model (e.g. two AddField or two AlterField operations on the same model), split into separate migrations — one per field. Delete the combined migration, make one field change at a time, and run makemigrations after each.

Exceptions (do NOT split):

• A CreateModel with all its fields is one operation — do not split the fields of a new model
• Cross-model dependencies where Django requires them together (e.g. ForeignKey + related model creation)
• Field + its index/constraint in the same migration is acceptable when auto-generated together

Step 5: Verify

Run the check command to confirm no pending migrations remain:

python manage.py makemigrations --check --dry-run

Expected output: No changes detected — meaning all model changes are captured in migrations.

Error Handling

| Error | Action | |-------|--------| | django.db.utils.OperationalError: could not connect | Ask user to start the database | | Conflicting migrations detected | Stop and let user decide | | ModuleNotFoundError | Virtual environment not activated — run . .venv/bin/activate |

Tips

• Rely on autogenerated migrations for correct timestamps, sequential numbers, dependencies, and field definitions. If you must hand-edit (e.g. to split), regenerate rather than edit — delete the migration, adjust models.py, and re-run makemigrations.
• When splitting, let Django figure out dependencies between the new smaller migrations.
• Check the newest existing migration in the app (ls saleor/<app>/migrations/ | tail -5) before generating, so you can confirm the new migration number is sequential.