Planning Rails Upgrade - A Strategic Guide

Rails upgrades can feel daunting due to breaking changes, gem compatibility issues and potential downtime. But staying on outdated versions is riskier. Security vulnerabilities accumulate, performance suffers, and we miss powerful features that make development easier.

With proper planning, Rails upgrades can be smooth and predictable. This five part series shares proven strategies from dozens of successful upgrades.

Why Upgrade Now?

Let’s look at the current Rails ecosystem (as of December 2025):

• Rails 8.x: Early adoption phase (~5% of applications)
• Rails 7.x: ~40% of active applications
• Rails 6.x: ~35% of applications
• Rails 5.x and older: ~20% still running

Rails 8 was released in November 2024, so adoption is still ramping up. If we’re on Rails 6 or earlier, we’re not alone—but we should plan our upgrade path.

The Real Cost of Waiting

Security: Rails 4.2 reached EOL in 2016. Ruby 2.7 reached EOL in March 2023. No security patches means real vulnerability.

Performance: Ruby 3.3 with YJIT (supported by Rails 7.0+) is 30-50% faster than Ruby 2.7. That’s lower infrastructure costs and better user experience.

Technical Debt: Skipping versions compounds complexity. Rails 4 → Rails 8 takes 6-12 months for large apps. Rails 7 → Rails 8 takes 1-2 weeks.

The 5 Step Upgrade Strategy

Step 1: Know Where We Stand

Before touching any code, audit the current state:

rails -v
ruby -v
bundle outdated

Document current Rails, Ruby, gem versions, database version, and test coverage percentage.

Ruby and Rails Compatibility:

Key insight: Often we need to upgrade Ruby first. We can check endoflife.date/ruby for EOL dates.

Critical checks:

• Test coverage: Aim for 80%+ before upgrading
• Gem compatibility: We can use bundler-audit
• Infrastructure: Verify hosting supports target versions

Step 2: Plan the Path

Never jump multiple major versions at once. Go incrementally:

Rails 4.2 → 5.0 → 5.2 → 6.0 → 6.1 → 7.0 → 7.1 → 8.0

Each step is manageable, testable, and reversible.

Prioritize the work:

• Critical: Security vulnerabilities, breaking changes, database issues
• High: Deprecation warnings, performance regressions
• Medium: Code style, minor deprecations
• Low: Cosmetic changes, optional features

Set realistic expectations:

• Small apps (< 10k LOC): 1-2 weeks per major version
• Medium apps (10k-50k LOC): 3-6 weeks per major version
• Large apps (> 50k LOC): 2-4 months per major version

Add 20-30% buffer time for unexpected issues.

Step 3: Use the Right Tools

RailsDiff: We can compare Rails versions to see what changed

next_rails: We can test with the next Rails version without fully committing

bundler-audit: We can scan for security vulnerabilities

RuboCop Rails: We can catch deprecations automatically

Dependabot: We can automate dependency updates in CI/CD

Step 4: Mitigate Risks

Feature Flags: We can roll out changes gradually to a subset of users

Blue-Green Deployment: We can maintain two environments and switch traffic instantly if issues arise

Database Safety: We can use strong_migrations gem to catch dangerous migrations

Monitoring: We should set up APM, error tracking, and logging before upgrading

Rollback Plan: We should always have a tested rollback strategy with clear triggers (error rate > 5%, response time > 20%)

Step 5: Test Thoroughly

Before upgrading: Expand test coverage to 80%+, focusing on critical user paths

During upgrade: Test at each milestone—unit tests, integration tests, system tests

After upgrade: Performance regression testing, manual UAT, monitor production metrics

Quick Checklist

Pre-Upgrade:

• Document current versions (Rails, Ruby, gems, database)
• Check test coverage (80%+ target)
• Set up monitoring and rollback plan

Planning:

• Choose target versions and map incremental path
• Identify breaking changes with RailsDiff
• Allocate dedicated team resources

Execution:

• Upgrade Ruby first (if needed)
• Update Rails one major version at a time
• Fix deprecations at each step
• Test thoroughly at each milestone

Post-Upgrade:

• Monitor error rates and performance
• Verify critical features
• Update documentation

What’s Next

We’ve covered the strategic planning essentials. In the next posts, we’ll dive into version specific upgrades with detailed examples, breaking changes, and solutions.

Coming up in this series:

• Part 2: Rails 4.2 to Rails 5 - Breaking changes, Ruby 2.3+ features, and migration strategies
• Part 3: Rails 5.2 to Rails 6 - Zeitwerk autoloader, Webpacker, and multiple databases
• Part 4: Rails 6.1 to Rails 7 - Import maps, Hotwire, and Ruby 3 compatibility
• Part 5: Rails 7.2 to Rails 8 - Solid Queue, authentication generator, and Ruby 3.3 performance

Each guide will include specific code examples, common gotchas, and proven solutions.

At Saeloun, we’ve successfully guided dozens of teams through Rails upgrades from Rails 4 to Rails 8. Whether you’re planning a major upgrade or need help with a complex migration, we’re here to help.

Learn more about our Rails consulting services or schedule a consultation to discuss your upgrade needs.