Configuration Guide

Rails Migration Guard is highly configurable to adapt to your team's workflow and requirements. This guide covers all configuration options and provides examples for common scenarios.

Basic Configuration
Git Integration Options
Tracking Options
Behavior Options
Cleanup Policies

Branch Configuration
Logging Options
Common Configurations

Basic Configuration

Rails Migration Guard creates a configuration file at config/initializers/migration_guard.rb during installation. Here's the default configuration:

# config/initializers/migration_guard.rb
MigrationGuard.configure do |config|
  # Environments where MigrationGuard is active
  config.enabled_environments = [:development, :staging]
end

Complete Configuration Example

# config/initializers/migration_guard.rb
MigrationGuard.configure do |config|
  # Environments where MigrationGuard is active
  config.enabled_environments = [:development, :staging]

  # Git integration level
  # :off - No git integration
  # :warning - Warn about orphaned migrations
  # :auto_rollback - Automatically suggest rollback
  config.git_integration_level = :warning

  # Track additional information
  config.track_author = true
  config.track_timestamp = true
  config.track_branch = true
  
  # Branch configuration
  config.main_branch_names = ["main", "master", "trunk"]
  config.target_branches = nil  # Auto-detect or specify custom branches
  
  # Behavior options
  config.warn_on_switch = true
  config.warn_after_migration = true
  config.warning_frequency = :smart
  config.max_warnings_display = 10
  
  # Cleanup policies
  config.auto_cleanup = false
  config.cleanup_after_days = 30
  
  # Logging
  config.log_level = :info
  config.colorize_output = true
end

Git Integration Options

Integration Levels

:off
Disables all Git integration features
:warning
Shows warnings about orphaned migrations (default)
:auto_rollback
Automatically suggests rollback commands

Example Configuration

config.git_integration_level = :warning

# Configure branch detection
config.main_branch_names = ["main", "master", "trunk"]
config.target_branches = nil  # Auto-detect main branch

# Control warning behavior
config.warn_on_switch = true
config.warning_frequency = :smart

Tracking Options

Configure what information Rails Migration Guard tracks about your migrations:

Option	Type	Default	Description
track_author	Boolean	true	Track who created each migration
track_timestamp	Boolean	true	Record when migrations were run
track_branch	Boolean	true	Track which branch migrations were created on

Note: Author tracking requires Git to be configured with user.email. The gem will gracefully handle missing Git configuration.

Behavior Options

Branch Switching Behavior

# Warn when switching branches with orphaned migrations
config.warn_on_switch = true

# Warn after running migrations
config.warn_after_migration = true

# Control warning frequency
config.warning_frequency = :smart  # :each, :once, :smart

# Limit number of warnings displayed
config.max_warnings_display = 10

These options control how Rails Migration Guard behaves when you switch branches and run migrations.

Additional Options

# Timeout for stuck migrations (in minutes)
config.stuck_migration_timeout = 10

# Block deployments when orphaned migrations exist
config.block_deploy_with_orphans = false

# Run migrations in sandbox mode
config.sandbox_mode = false

These options control additional behaviors and safety features of Rails Migration Guard.

Cleanup Policies

Configure automatic cleanup to keep your migration tracking data manageable:

Automatic Cleanup

# Enable automatic cleanup
config.auto_cleanup = false

# Remove records older than (in days)
config.cleanup_after_days = 30

Manual Cleanup

Run cleanup manually with rake tasks:

# Remove old rolled back records
rails db:migration:cleanup

# Force cleanup all orphaned records
rails db:migration:cleanup FORCE=true

# Cleanup records older than 7 days
rails db:migration:cleanup DAYS=7

Branch Configuration

Branch Detection

# Names to try when detecting main branch (in order)
config.main_branch_names = ["main", "master", "trunk"]

# Specific branches to check against (nil for auto-detect)
config.target_branches = nil

Main Branch Detection

The gem will try each name in main_branch_names until it finds an existing branch.

Branch Patterns

Use wildcards in ignored_branches to match multiple branches (e.g., feature/*).

Logging Options

Configure logging to help debug issues and monitor migration activity:

Logging Configuration

# Use Rails logger by default (or specify custom logger)
config.logger = Rails.logger

# Log level (:debug, :info, :warn, :error, :fatal)
config.log_level = :info

# Show debug output visibly
config.visible_debug = false

# Colorize console output
config.colorize_output = true

# Auto-detect TTY for formatting
config.auto_detect_tty = true

Environment Variables: Set MIGRATION_GUARD_DEBUG=true to enable debug logging and visible output.

Common Configurations

Here are recommended configurations for different team workflows:

Solo Developer

Minimal configuration for individual projects

MigrationGuard.configure do |config|
  config.enabled_environments = [:development]
  config.git_integration_level = :warning
  config.auto_cleanup = false
  config.cleanup_after_days = 7
end

Small Team

Enhanced tracking for team collaboration

MigrationGuard.configure do |config|
  config.enabled_environments = [:development, :staging]
  config.git_integration_level = :auto_rollback
  config.track_author = true
  config.warn_on_switch = true
  config.target_branches = nil  # Auto-detect
  config.main_branch_names = ["main", "develop"]
end

Large Team / Enterprise

Strict controls and comprehensive tracking

MigrationGuard.configure do |config|
  config.enabled_environments = [:development, :staging, :test]
  config.git_integration_level = :auto_rollback
  config.track_author = true
  config.track_timestamp = true
  config.track_branch = true
  
  # Branch configuration
  config.main_branch_names = ["main", "master", "trunk"]
  config.target_branches = nil  # Auto-detect
  
  # Behavior settings
  config.warn_on_switch = true
  config.warn_after_migration = true
  config.warning_frequency = :smart
  config.max_warnings_display = 15
  config.block_deploy_with_orphans = true
  
  # Cleanup policies
  config.auto_cleanup = false
  config.cleanup_after_days = 30
  
  # Logging
  config.log_level = :info
  config.colorize_output = true
end

CI/CD Environment

Configuration for automated environments

MigrationGuard.configure do |config|
  config.enabled_environments = [:test, :ci]
  config.git_integration_level = :warning
  
  # CI-specific settings
  config.on_git_error = :warn
  config.git_timeout = 10
  config.author_fallback = ENV['CI_COMMIT_AUTHOR'] || 'ci-bot'
  config.branch_fallback = ENV['CI_COMMIT_REF_NAME'] || 'ci'
  
  # Don't block CI
  config.block_switch_with_orphans = false
  config.warn_on_switch = false
  
  # Output for CI logs
  config.logger = Logger.new(STDOUT)
  config.log_level = :info
end

Environment Variables

You can override configuration using environment variables:

Environment Variable	Description
MIGRATION_GUARD_ENABLED	Enable/disable the gem (true/false)
MIGRATION_GUARD_LOG_LEVEL	Set log level (debug/info/warn/error)
MIGRATION_GUARD_MAIN_BRANCH	Override main branch name
MIGRATION_GUARD_AUTHOR	Override author detection