backend--migrations skill

Overview

This skill applies the Agent OS standard for backend migrations to ensure database changes are consistent, reversible, and auditable. It guides developers through best practices for writing, testing, and deploying migrations in TypeScript backends. The goal is predictable schema evolution and minimal production risk.

How this skill works

The skill inspects migration code and metadata to verify adherence to the Agent OS migration standard, checking naming conventions, up/down or reversible operation patterns, and required tests or checks. It flags missing rollbacks, unsafe operations, and gaps in deployment steps, and provides concrete remediation suggestions. It also validates migration ordering and compatibility with the deployment pipeline.

When to use it

• Adding or removing columns, tables, indexes, or constraints
• Refactoring schema that affects data format or access patterns
• Preparing a multi-step rollout that requires reversible steps
• Before merging migration PRs to prevent unsafe changes
• When auditing existing migrations for correctness and safety

Best practices

• Write clear, idempotent up and down migration paths or reversible commands
• Avoid long-running blocking operations; use background jobs for heavy data migrations
• Include data backfill strategies and feature toggles when changing critical fields
• Name migrations with timestamps and descriptive action verbs for ordering and clarity
• Add tests that run migrations and rollbacks against a representative schema snapshot

Example use cases

• Adding a non-nullable column: create a nullable column, backfill data, then make it non-nullable
• Renaming a column safely: add new column, backfill, switch reads, remove old column in a later migration
• Creating an index with minimal impact: use concurrently or online index creation patterns, then verify performance
• Deploying feature-flags tied schema changes: coordinate code rollout with gradual schema changes
• Auditing historical migrations: detect missing down paths or unsafe production operations

FAQ