SQL Migration Guide

Database migrations should be versioned, reversible, and tested. Never modify a migration that has already been applied to production.

Naming Convention

Use timestamps as prefixes: 20250601120000createusers.sql. This ensures migrations run in the correct order regardless of when they were created.

Safe Practices

Add columns as nullable first, then backfill, then add constraints. Never drop columns in the same deployment that stops writing to them. Use transactions for DDL when your database supports it.