good_migrations

This gem prevents Rails from auto-loading app code while it’s running migrations,
preventing the common mistake of referencing ActiveRecord models from migration
code.

Usage

Add good_migrations to your Gemfile:

gem 'good_migrations'

And you’re done! That’s it.

Prerequisites

This gem requires that your app uses either of these autoloader strategies:

• The classic ActiveSupport::Dependencies autoloader (e.g. config.autoloader = :classic), which is going away with Rails 7
• Version 2.5 or higher of the Zeitwerk autoloader (e.g. config.autoloader = :zeitwerk) If your app uses an earlier version of zeitwerk, you’ll see a
  warning every time db:migrate is run

Background

Over the life of your Ruby on Rails application, your
app’s models will change dramatically, but according to the Rails
guides, your migrations shouldn’t:

In general, editing existing migrations is not a good idea. You will be
creating extra work for yourself and your co-workers and cause major headaches
if the existing version of the migration has already been run on production
machines. Instead, you should write a new migration that performs the changes you
require.

That means that if your migrations reference the ActiveRecord model objects
you’ve defined in app/models, your old migrations are likely to break. That’s
not good.

By adding this gem to your project’s Gemfile, autoloading paths inside 'app/'
while running any of the db:migrate Rake tasks will raise an error, explaining
the dangers inherent.

Some will reply, “who cares if old migrations are broken? I can still run rake db:setup because I have a db/schema.rb file”. The problem with this approach
is that, so long as some migrations aren’t runnable, the db/schema.rb can’t
be regenerated from scratch and its veracity can no longer be trusted. In
practice, we’ve seen numerous projects accumulate cruft in db/schema.rb as the
result of erroneous commits to work-in-progress migrations, leading to the
development and test databases falling out of sync with production. That’s not
good!

For more background, see the last section of this blog post on healthy migration
habits

Adding to an existing app

If you add good_migrations to an existing application and any of those
migrations relied on auto-loading code from app/, then you’ll see errors
raised whenever those migrations are run.

You have several options if this happens:

• If you’re confident that every long-lasting environment has run the latest
  migrations, you could consider squashing your existing migrations into a
  single migration file that reflects the current state of your schema. This is
  a tricky procedure to pull off in complex apps, and can require extra
  coordination in cases where a high number of contributors are working on the
  application simultaneously. The
  squasher gem may be able to help.
• You can rewrite those past migrations to inline any application code inside
  the migration’s namespace. One way to do this is to run migrations until they
  fail, check out the git ref of the failing migration so the codebase is
  rewound to where it was at the time the migration was written, and finally
  inline the necessary app code to get the migration passing before checking out
  your primary branch. Rewriting any migration introduces risk of the resulting
  schema diverging from production, so this requires significant care and
  attention
• If neither of the above options are feasible, you can configure the
  good_migrations gem to ignore migrations prior to a specified date with the
  permit_autoloading_before
  option, which will effectively disable the gem’s auto-loading prevention for
  all migrations prior to a specified time

Configuration

To configure the gem, call GoodMigrations.config at some point as Rails is
loading (a good idea would be an initializer like
config/initializers/good_migrations.rb)

GoodMigrations.config do |config|
  # Setting `permit_autoloading_before` will DISABLE good_migrations for
  # any migrations before the given time. Don't set this unless you need to!
  #
  # Accepts parseable time strings as well as `Date` & `Time` objects
  # config.permit_autoloading_before = "20140728132502"
end

Working around good_migrations

The gem only prevents auto-loading, so you can always can explicitly require
the app code that you need in your migration.

If needed, it is possible to run a command with good_migrations disabled by
running the command with the env var GOOD_MIGRATIONS=skip.

Acknowledgements

Credit for figuring out where to hook into the ActiveSupport autoloader goes
to @tenderlove for this
gist. And thanks to
@fxn for implementing the hook necessary for zeitwerk
support to be possible.

Caveats

Because this gem works by augmenting the auto-loader, it will not work if your
Rails environment (development, by default) is configured to eager load your
application’s classes (see:
config.eager_load).