Why You Might Not Want to Run `rails app:update`.
At FastRuby.io, we don’t always run
rails app:update in our process to upgrade Rails apps.
It might seem like a sacrilege - after all, that’s why the task was created, to make upgrading Rails as painless as possible, right? But we have found while upgrading dozens of applications that running
rails app:update isn’t the best idea in all situations.
In this article, you will learn what
rails app:update does, when it should not be used, and how to upgrade your Rails app without it.
Note: In Rails versions before 5.0,
rails app:update was called
rails app:update command in Ruby on Rails is used to update various configuration files in your application to match the conventions and settings of a newer version of Rails. The specific files that
rails app:update updates can vary depending on the changes introduced in the new version of Rails.
Here are some of the common files that the command might update:
bin/: These files might be updated if there are changes to the scripts that setup and boot Rails.
config/application.rb: This file containing application-level configurations might be updated to include any new configurations or settings introduced in the newer version of Rails.
config/environments/*.rb: These environment-specific configuration files might be updated to include changes related to the new Rails version.
config/routes.rb: This file might be updated if there are changes to routing conventions or new routing features introduced in the new Rails version.
config/initializers/: These files might be updated to include any changes required for compatibility with the new Rails version.
database migrations: If the new Rails version introduces changes to the database schema or migration conventions, your existing migrations might need updates.
rails app:update can also add new files. For example, it can add new initializers inside
config/initializers to update Rails’ framework defaults (see What Does load_defaults Do? for more of an explanation of those defaults). These defaults don’t always need to be changed between Rails versions - at best you might be making unnecessary changes, at worst you might be breaking functionality for your app.
For reference, the following files are the source code for
rails app:update and can give context on which particular files are updated during a Rails upgrade:
- rake task for app:update
railties/lib/rails/generators/rails/app/app_generator.rbcontain the code that generates the app and copies the configuration files.
rails app:update not be used?
rails app:update isn’t inherently bad. However, there are certain considerations you should be aware of before using it. There are two main reasons why running
rails app:update might be considered a bad idea:
data loss or incompatibility: As mentioned above, running
rails app:updatemight involve changes to the database schema. If not done carefully, this could lead to data loss or data incompatibility.
customizations and overrides: Running
rails app:updatecan override changes in
config/application.rb, any of the
config/environmentsfiles, or in
The command does ask whether you want to overwrite each file, and gives you several options to choose from including but not limited to: yes overwrite, no don’t overwrite, diff to show the differences between the old and the new. But it is up to the individual to decide what option to choose - if done carelessly, this could also lead to loss of customization.
How to upgrade your Rails app without
There are several ways you can update the files that
rails app:update touches.
If you still want to use
rails app:update as a guideline to determine what files need to be changed during a Rails upgrade, you can always use this strategy:
rails app:updateto update all files.
- Compare the diffs between the old and the new versions to see what was changed.
If you don’t want to use
rails app:update, you can update each file individually using the template from Rails itself. These are the templates for the most recent version of Rails (as of this writing 7.0.8). This allows us to only make the minimum number of changes needed to complete the upgrade.
rails app:update is a convenient tool, it can sometimes make unintended changes to our configuration files.
Instead we can use the templates found in the Rails source to make only needed changes - thus limiting one source of difficulty when working through the Rails upgrade process.
Has your team been struggling with an upgrade? We can help .