Upgrade Rails from 8.0 to 8.1

This article is part of our Upgrade Rails series. To see more of them, click here opens a new window .

This article will cover the most important aspects that you need to know to get your Ruby on Rails opens a new window application from version 8.0 opens a new window to version 8.1 opens a new window .

1. 1. Preparations
2. 2. Ruby Version
3. 3. Gems
4. 4. Config Files
5. 5. Rails Guides
6. 6. Notable New Features
7. 7. Application Code
   • 7.1 Railties
   • 7.2 Action Pack
   • 7.3 Active Record
   • 7.4 Active Storage
   • 7.5 Active Support
   • 7.6 Active Job
8. 8. Next Steps

1. Preparations

Before beginning with the upgrade process, we have some recommended preparations:

• Your Rails app should have the latest patch version opens a new window before you move to the next major/minor version.
• You should have at least 80% test coverage. We do have an article for strategies on upgrading with low test coverage opens a new window as well.
• Have a staging environment that is as similar as possible to production, so that proper QA can be completed.
• Check your Gemfile.lock for incompatibilities by using RailsBump opens a new window .
• Create a dual boot mechanism, the fastest way to do this is installing the handy gem next_rails opens a new window . Find out more about how and why to dual boot opens a new window .
• To learn more about dual booting with non-backwards compatible changes you can refer to our Solving Dual Booting Issues when Changes aren’t Backwards Compatible opens a new window article.

For full details check out our article on How to Prepare Your App for a Rails Upgrade opens a new window .

2. Ruby Version

For the Rails 8.1 release, Ruby 3.2 opens a new window is the required minimum version.

Check out our Ruby & Rails Compatibility Table opens a new window to see all the required Ruby versions across all Rails versions.

3. Gems

Make sure you check the GitHub page of the gems currently installed in your application for more information about compatibility with Rails 8.1. If you are the maintainer of the gem, you’ll need to make sure it supports Rails 8.1. A great tool to checkout gems compatibility is RailsBump opens a new window . We also encourage you to use the next-rails opens a new window gem to run bundle_report outdated for more information on gems that will require an update. Check out our article on The Next Rails Gem opens a new window to learn more.

4. Config Files

Rails includes the rails app:update task opens a new window . You can use this task as a guideline as explained thoroughly by this Revisiting rails:update opens a new window blog post.

As an alternative, check out RailsDiff opens a new window , which provides an overview of the changes in a basic Rails app between 8.0.x and 8.1.x (or any other source/target versions).

5. Rails Guides

It is important to check through the official Rails Guides opens a new window and follow any of the steps necessary for your application.

6. Notable New Features

Active Job Continuations: Long-running jobs can now be broken into discrete steps that allow execution to continue from the last completed step rather than the beginning after a restart. This is especially helpful when doing deploys with Kamal, which will only give job-running containers thirty seconds to shut down by default.

Structured Event Reporting: The new Event Reporter provides a unified interface for producing structured events in Rails applications. Check out this article opens a new window on what that means for your Rails app.

Local CI: Rails has added a default CI declaration DSL, which is defined in config/ci.rb and run by bin/ci. You can learn more about this here opens a new window .

Mardown Rendering: Markdown has become the lingua franca of AI, and Rails has embraced this adoption by making it easier to respond to markdown requests and render them directly.

Command-line Credentials Fetching: Kamal can now easily grab its secrets from the encrypted Rails credentials store for deploys. This makes it a low-fi alternative to external secret stores that only needs the master key available to work.

7. Application Code

If you have ignored deprecation warnings on past version jumps, and haven’t stayed up to date with them you may find that you have issues with broken tests or broken parts of the application. If you have trouble figuring out why something is broken it may be because a deprecation is removed. The following is a list of the removals in Rails 8.1.

7.1 Railties

• Remove deprecated rails/console/methods.rb file.
• Remove deprecated bin/rake stats command.
• Remove deprecated STATS_DIRECTORIES.
• See full list of changes in the changelog opens a new window .

7.2 Action Pack

• Remove deprecated support to skipping over leading brackets in parameter names in the parameter parser.
• Remove deprecated support for using semicolons as a query string separator.
• Remove deprecated support to a route to multiple paths.
• See full list of changes in the changelog opens a new window .

7.3 Active Record

• Remove deprecated :retries option for the SQLite3 adapter.
• Remove deprecated :unsigned_float and :unsigned_decimal column methods for MySQL.
• See full list of changes in the changelog opens a new window .

7.4 Active Storage

• Remove deprecated :azure storage service.
• See full list of changes in the changelog opens a new window .

7.5 Active Support

• Remove deprecated passing a Time object to Time#since.
• Remove deprecated Benchmark.ms method. It is now defined in the benchmark gem.
• Remove deprecated addition for Time instances with ActiveSupport::TimeWithZone.
• Remove deprecated support for to_time to preserve the system local time. It will now always preserve the receiver timezone.
• See full list of changes in the changelog opens a new window .

7.6 Active Job

• Remove support to set ActiveJob::Base.enqueue_after_transaction_commit to :never, :always and :default.
• Remove deprecated Rails.application.config.active_job.enqueue_after_transaction_commit.
• Remove deprecated internal SuckerPunch adapter in favor of the adapter included with the sucker_punch gem.
• See full list of changes in the changelog opens a new window .

8. Next Steps

If you successfully followed all of these steps, you should now be running Rails 8.1!

If you find yourself in need of assistance or your team doesn’t have the time to tackle these challenges, you can always contact us. Our experts are here to help you navigate the upgrade process and ensure your Rails application continues to thrive. opens a new window

Download our free eBook: The Complete Guide to Upgrade Rails opens a new window .