How do I install the Safe Migrations skill?

Run npx skillmds@latest add scott-garvin/safe-migrations in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Safe Migrations safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Safe Migrations?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Safe Migrations free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Safe Migrations?

scott-garvin (@scott-garvin) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Safe Migrations by scott-garvin — Agent Skill

Name: Safe Migrations
Author: scott-garvin

Safe Migrations

Use when changing a database schema or seed/lookup data - adding or altering tables, columns, indexes, constraints, stored procedures, functions, or one-time data fixes. Every change is authored as an idempotent forward migration with a matching reverse (rollback) migration, keeps each object's canonical source file authoritative, and is applied through the migration pipeline behind the production-write-gate, never by editing production directly. Triggers on schema change, migration, DDL, add/alter column or table or index, stored procedure, seed data, or one-time data fix.

scott-garvin b49f9d8 2.2 KB Updated Sep 17, 2026

File contents

safe-migrations

Every schema change is reversible, idempotent, and applied through the pipeline. No one-way doors, no manual production edits.

Rules

Forward + reverse, always. Author the migration and its rollback in the same change. If a change genuinely can't be reversed — a destructive data transformation — say so explicitly and get sign-off. Don't silently ship a one-way door.
Idempotent DDL. Guard every statement so re-running the migration is safe: IF NOT EXISTS on creates, existence checks before alters, no-op when already applied. Migrations get re-run more often than you expect — partial failures, replays, parallel environments.
Canonical source stays authoritative. When a migration changes an object (a table, a procedure, a view), update that object's source-of-truth file in the repo too, so the checked-in schema reflects reality. The migration is how it changed; the source file is what it is now.
Never edit production directly. Changes reach prod only through the migration pipeline, and applying them is gated (see production-write-gate).
Verify the pair. Before shipping, confirm the forward migration applies cleanly on a fresh database and the reverse returns it to the prior state.

Rollback

A rollback you have never run is a guess, not a safety net. Run the reverse migration at least once against real schema before you rely on it. The moment you need it is the worst moment to discover it doesn't work.

Enforcement

scripts/check-migration-pairs.mjs fails CI when a forward migration lacks a matching rollback — rule 1, in code rather than in good intentions.

---name: safe-migrationsdescription: Use when changing a database schema or seed/lookup data - adding or altering tables, columns, indexes, constraints, stored procedures, functions, or one-time data fixes. Every change is authored as an idempotent forward migration with a matching reverse (rollback) migration, keeps each object's canonical source file authoritative, and is applied through the migration pipeline behind the production-write-gate, never by editing production directly. Triggers on schema change, migration, DDL, add/alter column or table or index, stored procedure, seed data, or one-time data fix.---# safe-migrationsEvery schema change is reversible, idempotent, and applied through the pipeline. No one-way doors, no manual production edits.## Rules1. **Forward + reverse, always.** Author the migration and its rollback in the same change. If a change genuinely can't be reversed — a destructive data transformation — say so explicitly and get sign-off. Don't silently ship a one-way door.2. **Idempotent DDL.** Guard every statement so re-running the migration is safe: `IF NOT EXISTS` on creates, existence checks before alters, no-op when already applied. Migrations get re-run more often than you expect — partial failures, replays, parallel environments.3. **Canonical source stays authoritative.** When a migration changes an object (a table, a procedure, a view), update that object's source-of-truth file in the repo too, so the checked-in schema reflects reality. The migration is *how* it changed; the source file is *what it is now*.4. **Never edit production directly.** Changes reach prod only through the migration pipeline, and applying them is gated (see `production-write-gate`).5. **Verify the pair.** Before shipping, confirm the forward migration applies cleanly on a fresh database and the reverse returns it to the prior state.## RollbackA rollback you have never run is a guess, not a safety net. Run the reverse migration at least once against real schema before you rely on it. The moment you need it is the worst moment to discover it doesn't work.## Enforcement`scripts/check-migration-pairs.mjs` fails CI when a forward migration lacks a matching rollback — rule 1, in code rather than in good intentions.

Frequently asked questions