Rails 7 to Rails 8: A Practical Upgrade Guide

Rails 8 landed with less fanfare than some previous major versions, but it brought meaningful changes under the hood — and a handful of deprecations that will break your app if you haven't prepared. This guide covers everything you need to plan and execute a production upgrade from Rails 7.x to Rails 8.0.

One caveat up front: this is a practical guide, not a changelog summary. If you want the full list of changes, the official upgrade guide is authoritative. What I'm giving you here is the operational playbook — what order to do things, what actually goes wrong, and how to recover.

What changed in Rails 8

The headline features in Rails 8 include:

• Solid Cache, Solid Queue, and Solid Cable — database-backed adapters for caching, background jobs, and Action Cable. These let you replace Redis in many setups and simplify infrastructure.
• Kamal 2 integration — first-class deployment tooling baked into the rails new generator.
• Authentication generator — a minimal, secure-by-default auth scaffold (rails generate authentication).
• Propshaft as the default asset pipeline — Sprockets is still supported but Propshaft is the new default, which matters if you're generating a new app.
• Ruby 3.2+ requirement — Rails 8 requires Ruby 3.2 at minimum. If you're on Ruby 2.x or 3.0, you must upgrade Ruby first.

For existing apps, the most impactful changes are the Ruby version requirement, some ActiveRecord and routing deprecations graduating to removals, and configuration defaults shifting.

Before you start: prerequisites

An upgrade attempted without a safety net is a gamble. Before you bump any version numbers:

1. Get your test suite passing. Run bundle exec rspec (or minitest) right now and fix any pre-existing failures. You cannot tell upgrade-caused breakage from pre-existing failures if your suite starts red.
2. Check your Ruby version. Rails 8 requires Ruby 3.2+. If you're on an older Ruby, do the Ruby upgrade first, let it soak in production for a week, then proceed with Rails.
3. Run bundle outdated and bundle audit. Note which gems have known issues. Some gems (especially older ones wrapping ActiveRecord or ActionController internals) will need updates or replacements.
4. Review your config files with rails app:update. Run this on a branch and carefully review each diff. Don't blindly accept changes — understand what each one does. Use railsdiff.org to compare your version to 8.0.

The upgrade sequence

1. Upgrade from Rails 7.0 to 7.1 first (if you haven't)

Rails 8 deprecations were already announced in 7.1. If you're on 7.0, upgrading to 7.1 and fixing deprecation warnings before moving to 8.0 is dramatically easier than doing both jumps at once. Pay close attention to warnings in your logs during this step.

2. Bump to Rails 8.0 in a dedicated branch

# Gemfile
gem "rails", "~> 8.0.0"

Run bundle update rails and note every gem that can't resolve. This list tells you what needs attention first.

3. Run rails app:update

This generates new initializers and updates config files to Rails 8 defaults. Review every change before accepting it. The three files that most commonly cause issues:

• config/application.rb — new default config values may change behaviour
• config/environments/production.rb — defaults around caching and logging changed
• config/initializers/new_framework_defaults_8_0.rb — flip these flags one at a time, not all at once

4. Address the new framework defaults incrementally

The generated new_framework_defaults_8_0.rb file has each new default commented out. Uncomment them one at a time, run your tests after each, and fix anything that breaks before moving to the next. This makes failures diagnosable instead of overwhelming.

5. Handle ActiveRecord changes

Several ActiveRecord query methods changed their behaviour in Rails 7.1 / 8.0. The most common issue: where(attr: nil) previously matched both NULL and missing records in some cases. Verify your most complex query chains are still producing correct SQL with .to_sql.

6. Update your gems

Run bundle update only after your app itself is on Rails 8. Update gems one at a time if possible, rather than all at once. Gems that frequently need attention during major Rails upgrades:

• Devise (or whatever auth library you use)
• Kaminari / Pagy
• Administrate / ActiveAdmin
• Any gem using ActiveRecord::Base internals directly

The pitfalls most teams hit

Upgrading Ruby and Rails simultaneously. These are two separate upgrades with separate risk profiles. Do them in separate deploys with time between them to observe.

Accepting all rails app:update diffs without reading them. The generated files are good defaults, but they can change behaviour your app depends on. One common example: changes to how config.force_ssl is set.

Ignoring deprecation warnings. Deprecation warnings in Rails aren't cosmetic. They are advance notice that something will break in the next major version. If you ran Rails 7.1 and saw warnings, they became errors in 8.0.

Not testing with production data volumes. Query behaviour changes can look fine with a small test database but perform completely differently at scale. Before promoting to production, run a performance test against a production-sized dataset.

Rolling it out

For a zero-drama production upgrade:

1. Deploy to a staging environment that mirrors production as closely as possible.
2. Run your full test suite against staging.
3. Do a dark deploy to a single production server if your infrastructure supports it.
4. Monitor error rates and performance metrics for 24 hours before full rollout.
5. Keep the previous deploy ready to roll back to.

The whole process — from starting the upgrade branch to a clean production deploy — takes most teams between one and three weeks, depending on the size of the codebase and how much test coverage exists. If it takes longer, something is blocking you that's worth investigating directly.