sre-migration-safety
Skill4 starsChanged 25 days agoMITView on GitHub
Review a SQL schema migration for PostgreSQL or MySQL/MariaDB before it merges. Says which statements lock, rewrite or block writes, and gives the safe pattern for each. Never connects to production.
In this repository84 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/sre-safety-gates.mdcCursor rule
- sre-awsSkill
- sre-azureSkill
- sre-capacity-planningSkill
- sre-change-safetySkill
- sre-chaos-engineeringSkill
- sre-cloud-cost-reviewSkill
- sre-database-triageSkill
- sre-datadogSkill
- sre-dependency-mappingSkill
- sre-diagnosticsSkill
- sre-dr-backup-testSkill
- sre-dynatraceSkill
- sre-emudhra-ca-checkSkill
- sre-engineerSkill
- sre-expiry-auditSkill
- sre-gcpSkill
- sre-incident-commandSkill
- sre-incident-communicationSkill
- sre-k8s-safe-remediationSkill
- sre-k8s-triageSkill
- sre-k8s-upgrade-autopilotSkill
- sre-message-queue-triageSkill
- sre-observability-cost-cutterSkill
- sre-observability-query-cookbookSkill
- sre-oncall-auditSkill
- sre-oncall-handoffSkill
- sre-pagerduty-opsgenieSkill
- sre-php2shell-checkSkill
- sre-postmortem-templatesSkill
- sre-production-readinessSkill
- sre-prometheus-grafanaSkill
- sre-remediation-actionsSkill
- sre-runbook-templatesSkill
- sre-safety-gatesSkill
- sre-security-incident-triageSkill
- sre-service-mesh-triageSkill
- sre-slo-alertingSkill
- sre-slo-burn-rate-rulesSkill
- sre-terraformSkill
- sre-toil-reviewSkill
- sre-awsSkill
- sre-azureSkill
- sre-capacity-planningSkill
- sre-change-safetySkill
- sre-chaos-engineeringSkill
- sre-cloud-cost-reviewSkill
- sre-database-triageSkill
- sre-datadogSkill
- sre-dependency-mappingSkill
- sre-diagnosticsSkill
- sre-dr-backup-testSkill
- sre-dynatraceSkill
- sre-emudhra-ca-checkSkill
- sre-engineerSkill
- sre-expiry-auditSkill
- sre-gcpSkill
- sre-incident-commandSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 8 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Wait for explicit human approval before any prod-changing command, MCP write tool, or external post.
- Distinctive: line 20
Test in non-production first.
- Distinctive: line 40
Read the static checker's blind spots in references/rules.md and review the SQL by hand for them: triggers, partitioned tables, enum …
- Distinctive: line 41
Write the review in the format under Output: one entry per risky statement with the rewritten, safe SQL.
- Distinctive: line 45
Read-only by default. The checker never connects to a database.
- Distinctive: line 89
Stop and say so if you can't get the SQL the tool will actually run.
- Very specific: line 90
Stop if anyone asks you to run the migration, VACUUM FULL, pg_repack, or gh-ost against a real database.
- Distinctive: line 91
Never run the proof scripts against a database that holds real data.
- Distinctive: line 92
If the engine isn't PostgreSQL or MySQL/MariaDB with InnoDB, say the checker doesn't cover it and review by hand, marking the review as not …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Migration safety reviewer
Safety gates (REQUIRED)
- Read-only diagnosis first.
- Propose each change with risk (low/med/high) and reversibility.
- Wait for explicit human approval before any prod-changing command, MCP write tool, or external post.
- Act only as approved, verify, and stop and escalate if anything gets worse.
Full rules: sre-safety-gates. Read-only MCP setup: sre-safety-gates/references/mcp.md.
Reviews a schema migration (a SQL file, a pull request diff, or the SQL a migration tool prints) and reports, statement by statement, the lock it takes, whether it rewrites or scans the table, and a safer way to get the same result. Every claim the checker makes about lock behaviour is backed by a test that ran on real PostgreSQL 13–17, MySQL 8.0/8.4 and MariaDB 10.11/11.8 servers. The result is a review a team can paste into the pull request.
Test in non-production first. The operator approves every change, and this skill never runs a migration.
Inputs
- The migration SQL. For ORM tools, get the SQL they will run, not the model code:
python manage.py sqlmigrate <app> <migration>for Django,alembic upgrade <rev> --sqlfor Alembic,liquibase update-sqlfor Liquibase, or the raw.sqlfile. - The engine: PostgreSQL, or MySQL/MariaDB with InnoDB.
- The engine's major version, if known. Some rules depend on it (noted per rule).
- Roughly how big and how busy the affected tables are. Ask once if unknown; a lock on an empty table doesn't matter, and on a hot 500 GB table it is an outage.
Steps
Save the SQL to a file, then run the checker. It only reads the file.
python3 scripts/migration-lint.py --engine pg migration.sql python3 scripts/migration-lint.py --engine mysql --format json migration.sqlExit code 2 means at least one blocker, 1 means warnings only, 0 means nothing found (or info only). Exit 3 means the checker couldn't run: bad arguments, or a file it can't read. Paths are relative to the current folder, so give an absolute path if you
cdinto the skill folder first. Treat 3 as a failed review, never as a pass.- For each finding, check it against the table sizes and traffic from the inputs. Downgrade a finding only when the table is small or idle, and say so.
- Read the static checker's blind spots in references/rules.md and review the SQL by hand for them: triggers, partitioned tables, enum changes, and anything the migration tool wraps in its own transaction.
- Write the review in the format under Output: one entry per risky statement with the rewritten, safe SQL.
- Optional, for a change you can't settle from the rules: reproduce it on a throwaway or staging server with the proof scripts (see Skill-specific gates). They create a scratch database, test the lock and rewrite behaviour, and drop it.
Skill-specific gates
Read-only by default. The checker never connects to a database.
The proof scripts write to the server they point at. They create and drop a database named migration_proof_<pid> and refuse to start unless MIGPROOF_SCRATCH_OK=yes is set. Never point them at production.
PostgreSQL:
Gate: approval required.
MIGPROOF_SCRATCH_OK=yes PGHOST=<staging-host> PGUSER=<role-with-createdb> PGPASSFILE=<path> bash scripts/proof-pg.shMySQL or MariaDB:
Gate: approval required.
MIGPROOF_SCRATCH_OK=yes MYSQL_DEFAULTS=<option-file> bash scripts/proof-mysql.shThe safe SQL this skill suggests is still a schema change. The team runs it through its normal deploy process; this skill doesn't apply it.
Output
For each risky statement:
- Where: file and line.
- Problem: the lock, and whether it blocks reads, writes or both, rewrites, or scans.
- Safe version: the replacement SQL, split into separate migrations where needed (for example,
CREATE INDEX CONCURRENTLYin its own non-transactional migration). - Severity: blocker (will block writes or fail on a real table), warn (risky on a busy table), info.
End with a verdict (safe to merge / merge with changes / don't merge) and the order to apply the changes. Expand-and-contract changes (renames, type changes, drops) list each deploy step.
Tested vs docs-only
| Part | Status | Where |
| Checker rules and statement splitting | tested | python3 scripts/tests/test_lint.py, 39 checks on bad and safe fixtures |
| PostgreSQL lock modes, rewrites, NOT NULL shortcut, CONCURRENTLY, lock queueing | tested | scripts/proof-pg.sh, 19/19 on PostgreSQL 13.23, 14.24, 15.19, 16.15, 17.11 |
| MySQL/MariaDB INSTANT and INPLACE limits, foreign keys, metadata-lock queueing | tested | scripts/proof-mysql.sh, 11/11 on MySQL 8.0.46, 8.4.11 and MariaDB 10.11.19, 11.8.9 |
| Managed services (RDS, Aurora, Cloud SQL, Azure) | docs-only | Same engines and lock rules; not run on a managed instance |
gh-ost, pt-online-schema-change, pg_repack | docs-only | Suggested as alternatives; not run here |
| Real table sizes and timings | not tested | Lab tables are small; lock behaviour is the same, durations are not |
Stop rules
- Stop and say so if you can't get the SQL the tool will actually run. Don't review ORM model code by guessing what it generates.
- Stop if anyone asks you to run the migration,
VACUUM FULL,pg_repack, orgh-ostagainst a real database. Hand back the plan; the team applies it. - Never run the proof scripts against a database that holds real data.
- If the engine isn't PostgreSQL or MySQL/MariaDB with InnoDB, say the checker doesn't cover it and review by hand, marking the review as not tool-checked.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

