Home › PostgreSQL › SQL migrations Copilot path instructions
SQL migrations Copilot path instructions
Path-specific Copilot instructions for SQL migration files: zero-downtime changes, locks, and reversible steps.
GitHub CopilotPostgreSQL
How to use
Save this as .github/instructions/migrations.instructions.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.
.github/instructions/migrations.instructions.mdDownload ---
applyTo: "**/migrations/**,**/*.sql"
description: Rules for database migrations
---
# Database migrations
- Never edit a migration that has been merged; create a new one with the next sequence/timestamp.
- One logical change per migration with a descriptive name (`20261016_add_orders_status_index`).
- Provide a down/rollback step when the tool supports it, or document why it's irreversible.
## Zero-downtime patterns (PostgreSQL)
- Indexes on existing tables: `CREATE INDEX CONCURRENTLY IF NOT EXISTS` (non-transactional migration).
- New columns: nullable or with a constant default. Backfill in a separate, batched step.
- `NOT NULL` on big tables: add `CHECK (col IS NOT NULL) NOT VALID`, `VALIDATE CONSTRAINT`, then set `NOT NULL`.
- Foreign keys: add `NOT VALID`, then `VALIDATE CONSTRAINT`.
- Renames and drops are two-phase: ship code that no longer uses the column, then drop it in a later migration.
- Start lock-taking migrations with `SET lock_timeout = '5s';` so they fail fast instead of blocking traffic.
## Never
- No data-destroying statements (`DROP TABLE`, `TRUNCATE`, unbounded `DELETE`) without an explicit note in the PR description.
- No environment-specific data or secrets in migrations.