Skip to content
Skills Library
Programming · Planning

database-migrations

/database-migrations

Design and verify schema migrations, bounded backfills and deployment compatibility for databases. Use when adding constraints or indexes, changing column types, evolving schemas or recovering failed migrations; distinguish reversible application rollback from data restoration.

Repository
wrongstack ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Design and verify schema migrations, bounded backfills and deployment compatibility for databases. Use when adding constraints or indexes, changing column types, evolving schemas or recovering failed migrations; distinguish reversible application rollback from data restoration.

Original author description

Design and verify schema migrations, bounded backfills and deployment compatibility for databases. Use when adding constraints or indexes, changing column types, evolving schemas or recovering failed migrations; distinguish reversible application rollback from data restoration.

How it works

  1. Selection card
  2. Overview
  3. Rules
  4. Workflow
  5. Core Patterns & Pitfalls
  6. Sources
  7. Acceptance checks
  8. Skills in scope
Original SKILL.md headings · 68 lines, 547 words
SKILL.md preview
---
name: database-migrations
version: 1.0.1
description: "Design and verify schema migrations, bounded backfills and deployment compatibility for databases. Use when adding constraints or indexes, changing column types, evolving schemas or recovering failed migrations; distinguish reversible application rollback from data restoration."
trigger: "adding constraints or indexes, changing column types, evolving schemas or recovering failed migrations; distinguish reversible application rollback from data restoration."
required-capabilities: [filesystem.read, filesystem.write]
required-tools: []
optional-capabilities: [verification.run, web.research]
metadata:
  routing-group: data
paths: ["**/migrations/**"]
---

# Database Migrations

## Selection card
- Task: Deploy compatible schema changes and backfills.
- Start: Identify the data owner, query/schema, consistency and recovery contract.
- Finish: apply the acceptance checks below; report observed results and unresolved constraints.

## Overview

Ship schema changes that preserve data and work across deployment overlap.
Database engine, version and migration tool determine transactional DDL,
locking, index creation and rollback behavior.

## Rules

1. Inspect the current schema, migration history, engine/version, ORM and real
   readers/writers. Do not assume every DDL operation is transactional.
2. Use expand/backfill/validate/contract where old and new code overlap.
   Destructive contraction needs verified consumer retirement and a recovery plan.
3. Estimate lock/write amplification and data volume. Use bounded batches,
   stable progress keys, idempotency and checkpointed restart for large backfills.
4. Separate data restoration from a down migration. Dropped information cannot
   be recreated merely by reversing a schema statement.
5. Plan backup/restore or forward repair, monitor progress and define abort
   conditions. A backup existence check is not a tested restoration.
6. Use local fixtures or an authorized isolated database for verification;
   a migration plan does not authorize production execution.

## Workflow

1. Record invariants and compatibility across the old/new application versions.
2. Generate migrations with the project's tool and inspect resulting SQL,
   lock behavior, constraints and index strategy for the actual engine.
3. Apply to a fresh database and a representative existing schema.
4. Inject failure/restart in a bounded backfill and verify no omissions/duplicates.
   Compare row counts, constraints and important application queries.
5. Exercise rollback where reversible; otherwise test the documented forward
   repair/restore in the isolated environment.
6. Report migration commands, data verification, estimated production impact
   and the execution boundary.

## Core Patterns & Pitfalls

- **Zero-Downtime PostgreSQL Lock Discipline**: Set a bounded `lock_timeout` (e.g., `SET lock_timeout = '3s'`) before DDL so a blocked `ACCESS EXCLUSIVE` lock fails fast instead of queuing all application reads/writes behind it.
- **Online Index & Constraint Creation**: Create indexes on live tables with `CREATE INDEX CONCURRENTLY` (outside a transaction block), and add foreign-key or `CHECK` constraints as `NOT VALID` first (which takes only a brief lock) followed by `VALIDATE CONSTRAINT` in a separate step.
- **Anti-pattern — Renaming or Dropping Active Columns in One Deploy**: Dropping or renaming a column in the same deployment that updates application code breaks rolling pods (`vN-1`) and blocks instant application rollback; use the 4-phase expand → dual-write/backfill → switch reads → contract pattern.

## Sources

[PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html)
is an engine-specific reference; use the selected engine's current documentation
and exact version for operational decisions.

## Acceptance checks

- [ ] Generated SQL inspected for table rewrites, `ACCESS EXCLUSIVE` lock duration, and transactional DDL rules
- [ ] Old (`vN-1`) and new (`vN`) application code remain compatible during rolling deployment overlap
- [ ] Large backfills batched by primary-key cursor with idempotent restart and progress checkpoints
- [ ] Migration tested against both an empty schema and representative existing data with rollback/forward-fix verified

## Skills in scope

- data-governance — data retention, PII anonymization, and audit compliance during schema/backfill changes.
- api-design — keeping public API payloads backward-compatible while underlying database columns evolve.
- testing — automated up/down/backfill migration tests against realistic seed datasets.
- observability — monitoring database lock waits, replication lag, and query latency during migration rollout.

Versions

RepositoryScoreLicence
This page · wrongstack/wrongstack90MIT
VasulenkoIllia/claude-code-base100MIT
affaan-m/ECC100MIT
affaan-m/ECC100MIT
reddygopalkrishna/developer-agent-skills100MIT
SHRIJANAGAIN/Nemo-Cli100Apache-2.0
hugrverk/riggverk90MIT
Amey-Thakur/AI-SKILLS90MIT

Database snapshot: 13.11.2026 · package version 4735b06105fd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100data-contract-migrations
    Design and verify data contracts, schema changes, migrations, rollbacks, backfills, compatibility windows, tenant isolation, and API-to-database field mapping. Use when changing database schema, event payloads, persisted documents, analytics tables, multi-tenant data boundaries,…
  • 90database-design
    Picks a database and ORM, designs schemas and indexes, plans safe migrations. Use when designing a schema, adding indexes or planning a migration.
  • 90safe-database-migrations
    Use when schema evolution, backfills, production migrations or data retention changes. Plan and execute backward-compatible data changes with reversible checkpoints. Do not use when ephemeral development database reset with no preserved data.
  • 95database-pro
    Use when writing or optimizing SQL queries, designing database schemas, planning database migrations, or administering PostgreSQL/MySQL. Invoke for EXPLAIN analysis, indexing, JSONB, replication, VACUUM, schema changes, data backfills, zero-downtime deployment, monitoring, or partitioning.
  • 100designing-database-schemas
    Process use when you need to work with database schema design. This skill provides schema design and migrations with comprehensive guidance and automation. Trigger with phrases like "design schema", "create migration", or "model database".
  • 100designing-database-schemas
    Process use when you need to work with database schema design. This skill provides schema design and migrations with comprehensive guidance and automation. Trigger with phrases like "design schema", "create migration", or "model database".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.