Installation Guide

Get Rails Migration Guard up and running in your project in just a few minutes.

Requirements

🚂

Rails

6.1+ (including 8.0)

💎

Ruby

3.0+

🔄

Git

Any recent version

Database Support: Works with PostgreSQL, MySQL, SQLite, and any database supported by Rails.

Step-by-Step Installation

Add to your Gemfile

Add the gem to your development and staging environments. We recommend not including it in production for performance reasons.

# Gemfile
group :development, :staging do
  gem 'rails_migration_guard'
end

Install the gem

Run bundle install to download and install the gem.

$ bundle install

Generate configuration and migration

This creates the migration file for the tracking table and an optional configuration file.

$ rails generate migration_guard:install

This generator creates:

db/migrate/xxx_create_migration_guard_records.rb - Database table for tracking
config/initializers/migration_guard.rb - Optional configuration file

Run the migration

Create the tracking table in your database.

$ rails db:migrate

Verify installation

Check that everything is working correctly.

# Check migration status
$ rails db:migration:status

# Run diagnostics
$ rails db:migration:doctor

Optional: Install Git Hooks

For the best experience, install Git hooks that automatically warn you about migration conflicts when switching branches.

Post-checkout Hook

Warns you about orphaned migrations when switching branches.

$ rails generate migration_guard:hooks

Pre-push Hook

Prevents pushing branches with orphaned migrations (recommended for teams).

$ rails generate migration_guard:hooks --pre-push

Install Both

For maximum protection, install both hooks.

$ rails generate migration_guard:hooks --all

Team Recommendation: If you're working in a team, we highly recommend installing the pre-push hook to prevent orphaned migrations from being pushed to shared branches.

Configuration Preview

Rails Migration Guard works great with the default settings, but you can customize it in config/initializers/migration_guard.rb:

# config/initializers/migration_guard.rb
MigrationGuard.configure do |config|
  # Environments where MigrationGuard is active
  config.enabled_environments = [:development, :staging]
  
  # Git integration level (:off, :warning, :auto_rollback)
  config.git_integration_level = :warning
  
  # Branch names to consider as "main"
  config.main_branch_names = %w[main master trunk]
  
  # Show warnings when switching branches
  config.warn_on_switch = true
  
  # Automatically clean up old records
  config.auto_cleanup = false
  config.cleanup_after_days = 30
  
  # Logging preferences
  config.log_level = :info
  config.colorize_output = true
end

See the full configuration documentation for all available options.