playbooks

home / skills / tlabs-xyz / tbtc-v2-performance / backend-migrations

backend-migrations skill

/.claude/skills/backend-migrations

This skill guides you through creating and maintaining safe, reversible database migrations for zero-downtime deployments and schema evolution.

npx playbooks add skill tlabs-xyz/tbtc-v2-performance --skill backend-migrations

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.9 KB
---
name: Backend Migrations
description: Create and manage database migrations following best practices for reversibility, zero-downtime deployments, and safe schema changes. Use this skill when creating new database migrations, writing migration up/down methods, implementing schema changes (adding/removing tables, columns, indexes, constraints), performing data migrations or transformations, refactoring database structure, implementing backwards-compatible migrations, creating indexes on large tables, renaming database objects, or working with migration files in directories like migrations/, db/migrate/, alembic/versions/, or similar. Use when working with ORMs like Sequelize, TypeORM, Prisma, SQLAlchemy, ActiveRecord, Django ORM, or raw SQL migration files.
---

## When to use this skill

- When creating new database migration files
- When implementing migration up/down (or upgrade/downgrade) methods
- When adding, removing, or modifying database tables
- When adding, removing, or modifying database columns
- When creating, dropping, or modifying indexes or constraints
- When performing data migrations or transformations
- When refactoring database structure
- When implementing backwards-compatible schema changes
- When creating indexes on large tables (considering concurrent options)
- When renaming tables, columns, or other database objects
- When working with migration directories (migrations/, db/migrate/, alembic/versions/)
- When working with ORMs like Sequelize, TypeORM, Prisma, SQLAlchemy, ActiveRecord, Django ORM
- When writing raw SQL migration files

# Backend Migrations

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle backend migrations.

## Instructions

For details, refer to the information provided in this file:
[backend migrations](../../../agent-os/standards/backend/migrations.md)

Overview

This skill helps create and manage database migrations that are safe, reversible, and compatible with zero-downtime deployment patterns. It guides authors to produce up/down (or upgrade/downgrade) methods, handle large-table operations safely, and maintain backward compatibility across releases. The focus is practical: avoid locking, enable rollbacks, and ensure predictable behavior across environments.

How this skill works

The skill inspects migration files and surrounding code to validate patterns: presence of reverse operations, transactional boundaries, and safe ordering of schema and data changes. It flags risky constructs (unbounded table scans, blocking DDL, destructive deletes) and recommends alternatives (chunked updates, concurrent index creation, feature-flagged rollouts). It tailors advice for common ORMs and raw SQL migration directories.

When to use it

  • Creating new migration files or implementing up/down (upgrade/downgrade) methods
  • Adding, removing, or modifying tables, columns, indexes, or constraints
  • Performing data migrations, backfills, or large-scale transformations
  • Refactoring database structure while preserving backward compatibility
  • Renaming tables/columns or working in migrations/, db/migrate/, alembic/versions/
  • Creating indexes on large tables or other operations that can block production

Best practices

  • Always provide a reversible down/rollback path and document limitations explicitly
  • Prefer non-blocking operations: create indexes concurrently, avoid long locks, and run heavy work in background jobs
  • Split schema and data changes into separate migrations: deploy schema first, backfill data later, then flip feature flags
  • Use transactions where supported, but avoid wrapping DDL that cannot run inside transactions
  • Chunk large data migrations, add idempotency checks, and measure execution time on staging
  • Test migrations on a copy of production data, include sanity checks, and add clear logging for long-running steps

Example use cases

  • Add a nullable column, backfill values in a separate non-blocking migration, then alter to non-null
  • Create an index concurrently on a large table to avoid long locks during deployment
  • Rename a column by adding a new column, migrating data gradually, and switching reads/writes via feature flag
  • Perform a data transformation in chunks with retry logic to handle transient failures
  • Write up/down methods for an Alembic or ActiveRecord migration that cleanly revert schema and data changes

FAQ

What if a migration cannot be fully reversible?

Document the irreversible parts clearly in the migration, provide a safe mitigation plan, and avoid deploying irreversible destructive changes during peak traffic. Prefer soft deletes or feature-flagged rollouts when possible.

How do I add an index without blocking production?

Use the database's concurrent or online index creation feature when available, create the index in a separate migration, and monitor progress. Avoid creating large indexes inside a transactional migration if the DB prohibits it.