- Make sure all your tests pass. (
(rspec | minitest))
- Install Ruby to appropriate version (`(rvm | rbenv) install
- Update Gemfile version of Ruby:
ruby '<appropriate ruby version>'
- Update Gemfile version of Rails:
gem 'rails', '~> <new version>'
bin/rails app:updateand make appropriate choices.
- Make sure all your tests pass. (
(rspec | minitest))
- Test on pre-production environments, just in case. ;-)
- Deploy to production and test.
- On to the next problem!
I want to go over how to update an existing Ruby on Rails application. I will upgrade a Rails application from 5.2.2 to 6.0.3 with details of each step I took showing examples.
You will learn specific steps and what to expect when upgrading a Ruby on Rails application. This article will take you about eight minutes to read.
I never had to “upgrade” a Rails app. The documentation sounds easy and you should refer to them. I felt I needed to get specific step-by-step instructions. Hopefully this will help you (or future me) when upgrading a Rails app.
I had upgrade a Rails project due to security issues from Github’s Dependabot
No time like the present, right?
The steps I outline should work for any version of Rails. The most important thing is to have a working Rails application you want to upgrade.
If you want to use the one I have, it is available at: https://github.com/a-leung/tdd_indepth_callbacks/
You can also see all the code changes I made on this branch of the repository:
Get things in working order
Before upgrading, ensure the application is in a working order. This means:
- The app runs
- The automated test suite run and all pass
- If any, tests don’t pass, solve it.
In my case:
This is a small app, larger apps benefit from automated tests when upgrading Rails because without tests, one won’t know the side effects up upgrading the app’s foundation until the worst possible time(s).
Install and Configure Ruby version
Each version of Rails requires a minimum version of Ruby. The documentation lists required Ruby versions for each version of Rails.
If the version of Ruby installed is equal or greater than the version required by Rails, move on to the next section. Otherwise, follow the next steps to install a new version of Ruby.
To install Ruby 2.6.0, I used
rvm to install it:
Configure Gemfile for new version
If you try to run or update your application now, this error may appear:
This requires an update of the Ruby version in the
Tricky, not too bad.
When you started the project, do you remember installing Rails? In my previous articles, it was via:
Are the same steps taken?
Nope! This isn’t like other software where you just download a new version.
Update Rails’ entry in the
Upgrading Rails is nothing like installing Rails. To upgrade Rails, on
an existing Rails project, update the
rails version in the
Easier than installing, right?!
The part where the actual updating of Rails happens is when running:
If bundle returned an error, especially about compatibility, follow
the next steps, otherwise, you’re good to move onto the next section
Larger and longer lived projects will run into cases where not all gems are compatible with the version of Ruby or Rails. The error may look like:
The solution would be to also update the associated gem’s version to the one compatible with Ruby and/or Rails.
Another option would be to remove the gem from the
completing the Rails update process.
This may be the most complicated part of the process, especially if gems are incompatible or not updated.
If you have a lot of trouble, feel free to contact me.
This is the final step in upgrading Rails: getting latest
configurations for the application. Just run:
and follow the prompts.
Warning, there can be breaking changes to your application if you
accept all changes suggested. (i.e. getting a new clean
Be careful with your choices!
This is what the process can look like:
If you want to merge changes, configure the
variable with an appropriate editor before running
That way, you can incorporate changes into your file as merge instead of copying and pasting.
Now, the moment of truth: did the rails update work?!
This is where tests come into play: use them! They will check if everything still behaves the way you expect it and tell you if Rails made a change that causes your app to misbehave.
I would advise performing the following:
- Run automated tests
- Deploy and test in pre-production environments
- Deploy and test in production environments
Past you may have hated writing all of those tests, present you definitely appreciates them! ;-)
Upgrading Rails is a smooth process when taking the proper steps:
- Making sure your application is in working order.
- Upgrade to appropriate version of Ruby.
- Upgrade Rails, associated gems, and configurations.
- Test and deploy.
Optional: Update Bundler
While you’re updating Ruby AND Rails, why not make sure you have the newest version of Bundler, the tool that glues everything together?!
The project’s Gemfile was still using Bundler 1.17.2.
You can find out which version of bundler your app is using by looking
at the bottom of the
Upgrading Bundler is like installing it the first time:
bundler. To specify a specific version, use the following format:
For example, installing Bundler 2.1.4
With a new version of Bundler, have your Rails project use it by running:
For my project, the result:
Now your project is using another version of Bundler too.