Introduction

Migrating a legacy application to Ruby on Rails 7 can be challenging, but it offers massive improvements in performance, security, and maintainability. With Hotwire, Turbo, and eschewing Webpacker in favor of import maps, Rails 7 brings modern development practices to the framework.

In this guide, we’ll cover:
✅ Why migrate to Rails 7?
✅ Step-by-step migration strategy
✅ Handling dependencies and gems
✅ Dealing with database migrations
✅ Refactoring old code for better performance

1. Why Upgrade to Ruby on Rails 7?

If your application is running on an older version of Rails, you might face:
❌ Security vulnerabilities (Older Rails versions receive limited support)
❌ Performance bottlenecks
❌ Dependency issues (Outdated gems and libraries)
❌ Difficulty integrating modern frontend tools

Rails 7 introduces:
✅ Hotwire (Turbo & Stimulus) – Replaces WebSockets and AJAX for real-time updates
✅ Import Maps – No need for Webpack, simplifying JavaScript handling
✅ Concurrent Database Queries – Faster queries with Active Record
✅ Zeitwerk Autoloader – Efficient and faster code loading
✅ Better Encryption & Security Features

If you’re maintaining a legacy Rails 4, 5, or 6 application, now is the best time to upgrade!

2. Migration Strategy: Step-by-Step Approach

Migrating a Rails application should be done incrementally to minimize downtime and errors.

Step 1: Review Dependencies and Upgrade Path

Run:

rails -v
ruby -v
bundle outdated

Check your Rails version and outdated dependencies. Upgrade step-by-step if jumping multiple versions (e.g., Rails 5 → 6 → 7).

Step 2: Upgrade Ruby Version

Rails 7 requires Ruby 3.0+. Upgrade if necessary:

rbenv install 3.2.0
rbenv global 3.2.0
Step 3: Update the Rails Gem

Modify your Gemfile:

gem 'rails', '~> 7.0'

Run:

bundle update rails
rails app:update
Step 4: Fix Deprecated Code

Check for deprecations:

rails console
DEPRECATION WARNING

Common issues:

  • Replace before_filter with before_action
  • Migrate from ActiveRecord::Migration[4.2] to [7.0]
  • Update gem versions that no longer support Rails 7
Step 5: Migrate JavaScript & Frontend Assets

Rails 7 removes Webpacker in favor of Import Maps, esbuild, or jsbundling-rails.

If using Webpacker, migrate:

bundle remove webpacker
bundle add importmap-rails
rails importmap:install

For ESBuild:

bundle add jsbundling-rails
rails javascript:install:esbuild
Step 6: Update Database Schema & Queries

If you are upgrading from Rails 5 or older, update database handling:

  • Convert find_by_sql queries to Active Record queries
  • Replace old migrations (rails db:migrate)
  • Use Concurrent Queries in Active Record: 
    User.includes(:posts).load_async
Step 7: Test and Debug

Run the full test suite:

rails test
rspec

Check logs for compatibility issues:

tail -f log/development.log

3. Handling Third-Party Gems

Many legacy applications rely on outdated gems. Use these steps to check compatibility:

1️⃣ Run:

bundle outdated

2️⃣ Check Rails 7 compatibility:

  • Visit RubyGems.org
  • Look for updates on GitHub
  • If a gem is abandoned, consider alternatives

Example:
❌ paperclip (deprecated) → ✅ Use active_storage
❌ sprockets → ✅ Use propshaft

4. Performance Improvements in Rails 7

Migrating to Rails 7 brings massive performance improvements:

✅ Parallel Database Queries

users = User.where(active: true).load_async

✅ Improved Caching

Rails.cache.fetch("user_#{user.id}") { user.expensive_query }

✅ Built-in Encryption

class User < ApplicationRecord
encrypts :email
end

5. Deployment Considerations

Once your migration is complete, test in a staging environment before deploying.

🔹 Check Background Jobs (Sidekiq, Delayed Job, Resque)
🔹 Ensure JavaScript assets are properly loaded
🔹 Monitor database performance using tools like New Relic

Deploy with:

cap production deploy

6. Common Pitfalls & How to Avoid Them

❌ Skipping incremental upgrades – Always upgrade Rails one version at a time
❌ Forgetting to check dependencies – Update gems before upgrading Rails
❌ Ignoring deprecation warnings – Fix issues before deploying
❌ Not testing enough – Use RSpec & system tests to verify changes

Conclusion

Migrating a legacy application to Rails 7 requires careful planning, testing, and incremental updates.

💡 Key Takeaways:
✅ Follow an incremental migration path
✅ Upgrade dependencies before Rails
✅ Refactor old code for better performance
✅ Leverage Rails 7 features for security & speed

With modern tools like Hotwire, Turbo, and Async Queries, your app will be faster, more secure, and future-proof! 🚀