migration-safety
Skill0 starsChanged 47 days agoMITView on GitHub
Changing a database schema, backfilling or transforming data, or any destructive migration — drop/rename/type-change, large UPDATE, dual-write rollout, zero-downtime, reversibility.
6 other projects use a version of this.
Adopted by
Most recently taken up by
- Kuan-AI-com/agent-skillstheir own version, first seen Nov 15, 2026
- Mehul72/skillstheir own version, first seen Nov 8, 2026
- YiftachCohen/skillstheir own version, first seen Nov 3, 2026
- itsofficialadi/boundifftheir own version, first seen Oct 25, 2026
- novatic-cu/nova-skillstheir own version, first seen Sep 20, 2026
- dennisrongo/claude-skillstheir own version, first seen Aug 16, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- dennisrongo/claude-skills★ 1same name
- Mehul72/skills★ 1same name
- novatic-cu/nova-skills★ 1same name
- YiftachCohen/skills★ 1same name
- itsofficialadi/boundiff★ 0same name
- Kuan-AI-com/agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository29 other files it gives its agents.
- hosts/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adrSkill
- api-designSkill
- auditSkill
- code-reviewSkill
- concurrency-performanceSkill
- coverageSkill
- debuggingSkill
- debugSkill
- fast-laneSkill
- fixSkill
- implementSkill
- intakeSkill
- leanSkill
- nonnaSkill
- observabilitySkill
- planSkill
- refactoringSkill
- releaseSkill
- reviewSkill
- rollbackSkill
- security-reviewSkill
- shipSkill
- supply-chainSkill
- syncSkill
- tddSkill
- tdd-workflowSkill
- testSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
4
Distinctive
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 17
Never rename or drop in place.
- Very specific: line 47
Adding an index: use the non-blocking path (CREATE INDEX CONCURRENTLY in Postgres, ALGORITHM=INPLACE, LOCK=NONE in MySQL/InnoDB).
- Distinctive: line 71
Write old + new in the same transaction where possible.
- Distinctive: line 75
Keep the window short and observed.
- Distinctive: line 79
Every migration has a tested down path or an explicit, documented reason it's one-way (you can't un-drop a column — which is exactly why …
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Migration Safety
A migration runs against live data while old and new code are both deployed. The schema you change
is the one your running app is mid-flight querying. Treat every migration as outward-facing and
irreversible-by-default: plan the rollback before the rollout, and never let a single deploy both
change the schema and depend on the change (.claude/rules/safety.md).
Work the bundled templates/migration-checklist.md for any non-trivial migration — it is the gate.
Expand → Migrate → Contract — the one pattern that makes schema change safe
Never rename or drop in place; old code is still reading the old shape. Split every breaking change into separate, independently-deployable releases:
- Expand — add the new shape additively and nullable: new column/table/index, no destructive change. Old code ignores it; new code can write it. Safe to deploy and roll back freely.
- Migrate — backfill existing rows (idempotent, batched), and dual-write: app writes both old and new shape so they stay consistent while reads transition old → new. Verify parity.
- Contract — only after new code is fully deployed and reads are off the old shape: drop the old column/table, stop the dual-write. This is the irreversible step — it gets its own release and a backup taken first.
A rename = add new (expand) + backfill + dual-write (migrate) + drop old (contract). Three deploys, each reversible until the last. Collapsing them is how you take prod down.
Backward / forward compatibility — the deploy is never atomic
During any rollout, old code and new code run simultaneously (rolling deploy, canary, a straggler pod). The schema must satisfy both:
- New column must be nullable or have a default — old code inserts rows without it.
- Never
NOT NULLon add in one step; add nullable → backfill → add the constraint later. - Old code must tolerate new columns (
SELECT *consumers break on shape change — pin columns). - Readers ship before writers; writers ship before the old path is removed. Order deploys so no version ever sees a shape it can't handle.
Online / zero-downtime DDL — know your engine's lock behavior
The killer is the migration that takes an ACCESS EXCLUSIVE / table lock and blocks all queries while
it rewrites the table. Before running DDL, know what it locks and for how long:
- Adding an index: use the non-blocking path (
CREATE INDEX CONCURRENTLYin Postgres,ALGORITHM=INPLACE, LOCK=NONEin MySQL/InnoDB). The plain form locks writes for the whole build. - Adding a column with a volatile default can rewrite the whole table under lock on older engines — add the column, then backfill the value separately.
- Set a short
lock_timeout/statement_timeoutso a migration that can't get its lock fails fast instead of queuing behind it and stalling every request (fail closed, not open). - Large
UPDATE/DELETEin one statement holds locks and bloats the transaction log — batch it.
Idempotent, batched backfills
A backfill will be interrupted (timeout, deploy, OOM) and re-run. It must be safe to run twice and resumable, never one giant transaction:
- Batch by key range with a bounded size and a short pause between batches; track a high-water mark so a restart resumes, not restarts.
- Idempotent writes:
UPDATE ... WHERE new_col IS NULLor upsert on a stable key — re-processing a row is a no-op, not a double-apply (.claude/rules/safety.md). - Throttle to protect prod — a backfill that saturates IO is an outage. Watch replica lag.
- Run it outside the schema-change transaction so a slow backfill never holds DDL locks.
Dual-write windows — keep two shapes consistent in flight
While reads move from old to new, writes must hit both, or the shape you're migrating to drifts:
- Write old + new in the same transaction where possible; if not, make the new write idempotent and reconcilable, and detect divergence.
- Reconcile, don't assume — run a parity check (counts/checksums old vs new) before you trust the
new shape and before Contract. Halt on unexplained divergence (
.claude/rules/safety.md). - Keep the window short and observed; a forgotten dual-write rots silently for months.
Reversibility & rollback — written before you run it
Every migration has a tested down path or an explicit, documented reason it's one-way (you can't un-drop a column — which is exactly why Contract is last and gated by a backup).
- Reversible steps (expand, backfill): ship the
downand test it on a copy. - Irreversible steps (contract/drop): take a verified backup first, run in its own release, and confirm the new path has been live and healthy long enough that rollback is unlikely.
- Rollback of code must not require rollback of schema — that's the whole point of expand/contract.
Test the migration like code (.claude/rules/testing.md)
- Run up → down → up on a seeded copy in CI; assert data survives the round-trip.
- Backfill correctness: golden assertion on a known row set before/after.
- Both-versions test: old code against the post-Expand schema must still pass its suite.
- Dry-run on a production-sized clone to catch lock duration and timeout before prod feels it.
The migration is a proposal; the staging run on real-shaped data and the parity check are the gate.
For the decision record behind a non-trivial migration, write an ADR (/adr).
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.

