Ruby on Rails
Rails 7 to 8 Upgrade Guide: What Breaks and How to Plan the Upgrade
Rails 8 is mostly an additive release: new defaults such as Propshaft, the Solid Queue, Solid Cache and Solid Cable trio, Kamal 2 and an authentication generator are aimed at new applications, and none of them is mandatory for an existing one. What makes an upgrade from Rails 7 risky is everything that was deprecated along the way and is now gone. This guide covers the path we follow for production applications and the changes that tend to break real code.
Go one minor version at a time
The official guidance is to upgrade one minor version at a time, and it matters in practice: each release turns the previous release's deprecation warnings into removals. If the application is on Rails 7.0, the path is 7.0 to 7.1, then 7.2, then 8.0, and optionally 8.1. Skipping a step means fixing the deprecations of two releases at once without the warnings that would have pointed to them.
Rails 8 requires Ruby 3.2 or newer, and Rails 7.2 already requires Ruby 3.1. Upgrade Ruby as its own step, deploy it, and only then move Rails. Mixing both changes in one release makes any regression harder to trace. If you move to Ruby 3.4, add gems such as csv explicitly to the Gemfile, because they are no longer default gems.
Prepare before touching the Rails version
Most of the work happens on the current version, before the Gemfile changes.
- Make deprecations fail the test suite (config.active_support.deprecation = :raise in the test environment) and fix every warning.
- Check the gems that depend on Rails (authentication, admin, background jobs, file uploads) and confirm each one supports the target version.
- Raise test coverage on the areas you are least confident about, especially money, permissions, and background jobs.
- Consider dual booting with a tool such as the next_rails gem, so the suite runs against both versions while the branch is in progress.
The changes that actually break code
Release notes list dozens of items. These are the ones we see most often in existing applications.
- Enum keyword arguments are removed: enum status: { active: 0 } must become enum :status, { active: 0 }, and options such as _prefix become prefix.
- ActiveRecord::ConnectionAdapters::ConnectionPool#connection is removed; code that grabs a raw connection should use with_connection or lease_connection.
- Time#to_time now always preserves the receiver's time zone, and the legacy config.active_support.to_time_preserves_timezone = false option is gone. Check any code that relied on conversion to system local time.
- Custom console extensions through Rails::ConsoleMethods are removed; move helpers to a module loaded from a console block in the environment configuration.
- Rails.application.secrets was already removed in 7.2; anything still reading it must move to encrypted credentials or environment variables.
Run the framework update deliberately
After bumping the version, run bin/rails app:update and review every file it proposes to change instead of accepting all of them. Keep config.load_defaults on the previous version at first, and enable the new defaults one by one from the generated new_framework_defaults_8_0.rb file, deploying in between. Only when all of them are active should load_defaults move to 8.0.
Existing applications keep working with Sprockets, Redis, and Sidekiq. If you use Sprockets, make sure sprockets-rails is declared explicitly in the Gemfile. Migrating to Propshaft or the Solid stack is a separate project with its own benefits, not a requirement of the upgrade.
If you continue to Rails 8.1
Rails 8.1 dumps table columns in schema.rb in alphabetical order, which produces a large but harmless diff the first time a migration runs. Regenerate the schema right after upgrading and commit it on its own so code reviews stay readable. Also review query string handling in any code that parses unusual parameter names, since parsing of keys with leading brackets changed.
Key takeaways
- Upgrade one minor version at a time, and upgrade Ruby in its own release first.
- Make deprecations raise in tests and fix them before changing the Rails version.
- Expect enum syntax, connection pool access, to_time behavior, and console extensions to break.
- Propshaft and the Solid stack are optional for existing apps; enable new defaults gradually.
Related
Want to review your case with context?
Share the codebase, workflow, or systems involved and the result you need. We will use the call to decide a practical next step.