This article is part of our Upgrade Rails series. To see more of them, click here.
This article will cover the most important aspects that you need to know to get
your Ruby on Rails application from version 4.2 to 5.0.
- Ruby version
- Config files (config/)
- Application code
- Next steps
Before beginning with the upgrade process, we have some recommended preparations:
- Your Rails app should have the latest patch version before you move to the next major/minor version.
- You should have at least 80% test coverage unless you have a dedicated QA team.
- Follow a Git flow workflow to actively manage at least two environments: staging and production.
- Check your Gemfile.lock for incompatibilities by using RailsBump.
- Create a dual boot mechanism, the fastest way to do this is installing the handy gem next_rails.
For full details check out our article on How to Prepare Your App for a Rails Upgrade.
2. Ruby version
Rails 5.0 requires Ruby 2.2.2 or later.
This Ruby upgrade shouldn’t generate any problems. However, if you run into this
exception in your test suite:
cannot load such file -- test/unit/assertions (Load Error)
then you’ll need to add:
- It’s recommended that you check your
Gemfile against RailsBump
to ensure all your gems are compatible with Rails 5.
As of the release of this blog post, there are only a few gems which don’t
support Rails 5 yet. This is more of a problem when you’re upgrading early on.
If any of the gems are missing on RailsBump, you’ll need to manually check the
Github page for the project to find out its status. In case you own the gem,
you’ll need to make sure it works on Rails 5 or update it.
4. Config files
Rails includes the
rails app:update task.
You can use this task as a guideline as explained thoroughly in
As an alternative, check out RailsDiff,
which provides an overview of the changes in a basic Rails app between 4.2.x and
5.0.x (or any other source/target versions).
5. Application code
- ActiveRecord models will now inherit from ApplicationRecord by default instead
of ActiveRecord::Base. You should create an `application_record.rb` file under
class ApplicationRecord < ActiveRecord::Base
self.abstract_class = true
And then update all of your models to inherit from `ApplicationRecord` instead
of `ActiveRecord::Base`. The only class that inherits from `ActiveRecord::Base`
will be `ApplicationRecord`.
- `belongs_to` associations are [now required by default](https://github.com/rails/rails/pull/18937/files).
This means that if the association doesn't exist for a model when saving it, an
error will be triggered. You can turn this feature off for an association by
using `optional: true`:
belongs_to :user, optional: true
- ActiveRecord migrations now need to be tagged with the Rails version they are
created under. One of the reasons for this is that strings in Rails 4.2 had a
default size of 4 bytes. In Rails 5.0, their default size is now of 8 bytes. See
[this comment](https://stackoverflow.com/a/35930912/2754597) from Rails core
team member Rafael França regarding this change.
To resolve this, you'll need to update your current migrations in your `db/migrate` directory:
class CreatePosts < ActiveRecord::Migration
class CreatePosts < ActiveRecord::Migration[4.2]
If you add a new migration after updating to Rails 5.0, you'll also need to tag
class CreateProducts < ActiveRecord::Migration[5.0]
This will help with potential compatibility issues, so your database can be
correctly reconstructed from the migrations. Strings in your 4.2 migrations
will use the previous default size of 4 bytes instead of the new default.
Note you shouldn't add the patch version to the tag, just the major and minor
version numbers (`4.2`, `5.0`, `5.1`, `5.2`).
(Thanks to Cory McDonald in the comments section for reminding us about this
- If you're not already using strong parameters, and still rely on
`protected_attributes`, you should migrate your application to strong
parameters before attempting to upgrade to Rails 5.0.
no longer supported on Rails 5.0.
A few months ago we worked on a project to attempt to automate the strong
parameters migration process, and this resulted in the gem [RailsUpgrader](https://github.com/fastruby/rails_upgrader).
It's in a beta state, but you can try using it if you have too many models, or
at least as a guide for a WIP branch.
There are still efforts being made to keep `protected_attributes` alive though,
like the [`protected_attributes_continued`](https://github.com/westonganger/protected_attributes_continued)
gem. I would strongly recommend against using it since its support is limited,
and it won't work in future Rails versions.
- Parameters now behave differently, they no longer inherit from
`HashWithIndifferentAccess`. Some methods (e.g.: `fetch`, `slice`, `except`) you
may be now calling on `params` will no longer work. You will need to `permit`
the parameters, call `to_h`, and only then you'll be able to run the `Hash`
methods you need on them.
For more information: [https://github.com/rails/rails/pull/20868](https://github.com/rails/rails/pull/20868)
- One of the most common methods in controller tests, `assigns`, has been
extracted from Rails and moved to the [`rails-controller-testing`](https://github.com/rails/rails-controller-testing) gem.
If you wish to continue using it (and `assert_template`), you'll need to add it
to your `Gemfile`:
- Instead of using `ActionDispatch::Http::UploadedFile` to test uploads, you'll
need to update those tests to use [`Rack::Test::UploadedFile`](http://www.rubydoc.info/github/brynary/rack-test/Rack/Test/UploadedFile).
7. Next steps
If you successfully followed all of these steps, you should now be running Rails 5.0! Do you have any other useful tips or recommendations? Share them with us in the comments section.
If you're not on Rails 5.0 yet, we can help! Download our free eBook: [The Complete Guide to Upgrade Rails](https://www.fastruby.io/).