Why You Might Not Want to Run `rails app:update`.

At FastRuby.io, we don’t always run rails app:update opens a new window 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 rake rails:update.

What is rails app:update?

The 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? opens a new window 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 opens a new window
• railties/lib/rails/app_updater.rb opens a new window and railties/lib/rails/generators/rails/app/app_generator.rb opens a new window contain the code that generates the app and copies the configuration files.

When should rails app:update not be used?

Using 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:update might 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:update can override changes in config/application.rb, any of the config/environments files, or in config/routes.rb.

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 rails app:update

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:

1. Run rails app:update to update all files.
2. 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 opens a new window 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.

Conclusion

While 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 opens a new window .