Rails Migration DSL and Relational Database Rollback Safety: Which Schema Changes Require Explicit Reversible Logic?

Reversibility Contract in the Rails Migration DSL

In Ruby on Rails, a migration is automatically reversible if the DSL can infer the exact state of the database prior to the operation. When this inference is impossible, Rails raises an ActiveRecord::IrreversibleMigration error during db:rollback rather than silently skipping the change.

Guaranteed Reversible Operations

The following change_table and standalone operations are generally guaranteed to invert automatically across PostgreSQL and MySQL, provided they are used within a change method:

• create_table $\rightarrow$ drop_table
• add_column $\rightarrow$ remove_column
• add_index $\rightarrow$ remove_index
• rename_column $\rightarrow$ rename_column (inverse)
• rename_table $\rightarrow$ rename_table (inverse)

Operations Requiring Explicit Logic

Certain operations destroy metadata or change data types, making them irreversible by default. These require a reversible block or separate up and down methods:

Operation	Reversibility Status	Requirement for Rollback
remove_column	Conditional	Must provide the column type (e.g., :string) to recreate it.
change_column	Irreversible	Must explicitly define the previous type/constraints in a down method.
drop_table	Irreversible	Must define the full table schema in the down method.

Modeling the Integration Boundary

To ensure db:rollback safety, teams should treat the Migration DSL as a high-level abstraction and the database DDL as the source of truth. The following boundaries apply:

• Data Loss Boundary: A rollback of remove_column recreates the column structure but cannot restore the deleted data. This is a database-level limitation, not a DSL failure.
• Type Casting Boundary: When using change_column, the rollback may fail at the database level if the current data cannot be cast back to the original type (e.g., converting a string to an integer).
• Database-Specific DDL: Any use of execute "SQL..." is inherently irreversible. These must always be wrapped in a reversible block.

Verification Steps

To verify if a migration is safe for production rollback, run the following sequence in a development environment:

# Apply the migration
bin/rails db:migrate

# Attempt to rollback
bin/rails db:rollback

# Verify schema consistency
bin/rails db:schema:dump

Diagnostic Detail Needed: Are you utilizing any database-specific extensions (e.g., PostgreSQL hstore or citext) that are not natively mapped to Rails types?