migration-immutability

Editing a deployed SQL migration causes schema drift because environments that already applied the original file retain the old schema state, desynchronizing them from databases that apply the newly edited version. You must create a new migration instead of modifying the existing one in place.

To correct a deployed database migration, create a new migration file with a descriptive name under your migrations directory, document the rationale for the corrective change, and apply it to update the deployed schema across all environments rather than editing the original.

The best practice for managing immutable database migrations is to enforce a rule that deployed migrations must never be edited in place. Any corrective changes must be added as new migration files to prevent drift and maintain database synchronization.

You need to enforce migration immutability once a migration file has merged into origin/main and is deployed across multiple environments. At that point, the migration content is effectively frozen and in-place edits will cause desynchronization between databases.

Migration immutability validation applies to SQL migrations deployed through workflows like golang-migrate. It prevents in-place edits to merged migration files under your migrations directory by requiring new corrective migrations and validating the overall migration workflow.