database-migration

name	database-migration
description	Use when creating, updating, reviewing, or debugging database migrations, schema changes, indexes, constraints, seeds, data migrations, rollback safety, or tenant-safe database changes.

Database Migration

Use this skill for safe schema, index, seed, and data migration work.

Rules

• Follow the project’s existing database, ORM, migration, and naming patterns.
• Do not add a new ORM, migration tool, database provider, or schema system unless already used or explicitly requested.
• Treat migrations as production-sensitive.
• Avoid destructive changes unless explicitly required and safe.
• Preserve existing data.
• Add indexes and constraints intentionally.
• Keep migrations reversible when the project supports rollback.
• For multi-tenant systems, preserve tenant isolation.
• Do not edit generated migration history carelessly.
• Avoid unrelated schema changes.

Inspect First

Before changing database code, check existing patterns for:

• ORM/database client
• migration folder
• schema naming
• indexes
• constraints
• seeds
• soft delete behavior
• tenant columns/scoping
• rollback strategy
• migration commands
• test database setup

Implementation Checklist

• Identify the exact schema/data change.
• Check existing models and relations.
• Add or update schema definitions.
• Generate or write migration using the project’s tool.
• Add constraints only when existing data allows it.
• Add indexes for common filters, joins, sorts, and tenant scope.
• Handle nullable/backfill steps safely.
• Keep data migrations idempotent where possible.
• Update affected queries, types, tests, and seeds.
• Run migration and relevant tests.

Safety Rules

• Do not drop columns/tables without explicit need.
• For risky changes, prefer expand-and-contract:
  • add new nullable field
  • backfill data
  • switch code
  • enforce constraint
  • remove old field later
• Avoid long locks on large tables.
• Avoid unbounded data updates without batching when the project is large.
• Do not put secrets or production data in seeds.
• Do not break existing rollback or deploy flow.

Multi-Tenant Rules

• Tenant-owned tables need tenant scope when the project uses tenancy.
• Add tenant-aware indexes for tenant-filtered queries.
• Do not create cross-tenant uniqueness accidentally.
• Verify joins and foreign keys do not break tenant isolation.
• Seeds and fixtures must not mix tenant data incorrectly.

Tests

Cover relevant paths:

• migration applies cleanly
• schema matches model expectations
• affected queries still work
• constraints reject invalid data
• indexes support expected query paths when relevant
• tenant isolation still holds
• rollback if the project supports it