Upgrading an Old Ruby on Rails Application Safely, One Version at a Time

A Rails application that has been running for eight or ten years is usually a sign of success. It holds years of business rules, it pays the bills, and nobody wants to touch it. The trouble is that it is often several major versions behind, on a Ruby the host no longer supports, with gems that stopped receiving security fixes long ago. At some point the upgrade stops being optional, and the question becomes how to do it without breaking the thing the business depends on.

Taking over and upgrading existing applications is a regular part of our Ruby on Rails development work. The approach below is the one we use: slow, staged and deliberately unexciting.

First, Find Out Where You Are

Before changing a line, take an inventory:

• Versions: Ruby, Rails, Bundler, the database and its adapter, and Node if the asset build uses it.
• Gems: run bundle outdated for the full picture and bundler-audit for known vulnerabilities. Mark each gem as maintained, abandoned or forked.
• Monkey patches: anything in config/initializers or lib that reopens Rails or gem classes. These break silently on upgrade.
• Deprecation warnings: the current version is already telling you what the next one will remove. Collect them from the test run and the production logs.
• Infrastructure: how the app is deployed, which job system it uses, and anything pinned at operating-system level, such as an old ImageMagick or OpenSSL.

The inventory is also the basis of an honest estimate. An application one major version behind with maintained gems is a few weeks of careful work. One on Rails 4 with a dozen abandoned gems is a project, and should be planned as one.

Tests Before Upgrades

An upgrade is only as safe as your ability to notice what it broke. Many inherited applications have a test suite that has not passed in years, or hardly any tests at all. Fixing that comes first.

We do not aim for full coverage before starting; that could take longer than the upgrade. We aim for coverage of what would hurt: request specs for the critical journeys (sign-up, checkout, invoicing, whatever earns money) and characterisation tests around the business rules that are hardest to reason about. A characterisation test records what the code does today, right or wrong, so any change in behaviour shows up as a failure. SimpleCov shows where the gaps are.

We took the same approach outside Rails when we upgraded a trade supplier's CodeIgniter order desk to PHP 8: the trade-discount logic was covered by tests before anything was touched, so the upgrade could not silently change prices. Different framework, same principle.

One Version at a Time

It is tempting to jump straight from Rails 5 to Rails 8. Do not. Each release removes things the previous one deprecated, and the official upgrade guides are written step by step. Skipping steps means facing every removal at once, without the deprecation warnings that would have pointed the way.

The rhythm for each step:

1. Fix every deprecation warning on the current version.
2. Bump Rails to the next minor version and update the gems that require it.
3. Run the app:update task and review the generated configuration changes by hand rather than accepting them wholesale.
4. Get the tests passing, then deploy to staging and production.
5. Switch on the new framework defaults one at a time using the generated defaults file, then update load_defaults.

Deploying after every step matters. A problem found in production after one minor version is easy to trace. A problem found after five is a week of bisecting.

Ruby and Rails have to leapfrog. Each Rails release sets a minimum Ruby version, and older Rails releases do not support the newest Rubies, so the path alternates: upgrade Ruby as far as the current Rails allows, then Rails as far as that Ruby allows, and repeat. Check the supported combinations in the release notes before planning the sequence.

For larger applications, dual booting helps. The app runs against both the current and the next Rails version from one branch, switched by an environment variable, so the upgrade proceeds in small merged pull requests rather than a long-lived branch that drifts away from everyone else's work.

The Usual Sticking Points

• Autoloading. Rails 6 introduced the Zeitwerk autoloader and Rails 7 removed the classic one. Files whose names do not match the class they define, common in old code, need renaming. The zeitwerk:check task lists them.
• Front-end assets. Webpacker has been retired, so apps that used it move to jsbundling-rails, import maps or a separate build. This is often the most time-consuming single step, and it can be done separately from a Rails bump.
• Abandoned gems. Paperclip, once the standard for file attachments, was deprecated in favour of Active Storage, and old authentication or admin gems may need replacing or forking. Budget for each one individually.
• Background jobs. Check that jobs queued by the old version can still be processed by the new one during the deployment window.
• Behaviour changes in very old apps, such as the move from attribute protection to strong parameters, where code still runs but no longer does what it used to.

Upgrade, Migrate or Rewrite?

A rewrite throws away years of encoded business rules and replaces them with new bugs. For a reasonably structured Rails app, upgrading incrementally is nearly always cheaper and safer. Where parts of the application are genuinely beyond saving, replace them one module at a time behind the same URLs, which is how the CodeIgniter order desk moved to Laravel. Our article on whether Rails is still a good choice covers the longer-term question of staying on the framework, and the same decision for CodeIgniter shows how we weigh it in another ecosystem.

New Rails work does not have to become tomorrow's rescue job. The field-service quoting SaaS we built in Rails has RSpec tests, Sidekiq for background work and Docker for deployment, the foundations that keep future upgrades routine rather than frightening.

Keep It Current Afterwards

The cheapest upgrade is the one done a little at a time. Once an application is current, a maintenance plan that applies Ruby, Rails and gem updates every month or two keeps it there, with the test suite as the safety net. Moving the app to a containerised deployment through our Docker and DevOps service also removes the "it only runs on that one server" problem that makes Ruby upgrades so nerve-racking.

If you have a Rails application nobody wants to touch, send us its Gemfile.lock and the Ruby version it runs on. From those two things we can tell you how far behind it is, which gems will cause trouble and roughly how many steps the upgrade will take.