A Guide for Upgrading Ruby on Rails
This guide provides steps to be followed when you upgrade your applications to a newer version of Ruby on Rails. These steps are also available in individual release guides.
Before attempting to upgrade an existing application, you should be sure you have a good reason to upgrade. You need to balance out several factors: the need for new features, the increasing difficulty of finding support for old code, and your available time and skills, to name a few.
The best way to be sure that your application still works after upgrading is to have good test coverage before you start the process. If you don't have automated tests that exercise the bulk of your application, you'll need to spend time manually exercising all the parts that have changed. In the case of a Rails upgrade, that will mean every single piece of functionality in the application. Do yourself a favor and make sure your test coverage is good before you start an upgrade.
Rails generally stays close to the latest released Ruby version when it's released:
- Rails 3 and above require Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially. You should upgrade as early as possible.
- Rails 3.2.x is the last branch to support Ruby 1.8.7.
- Rails 4 prefers Ruby 2.0 and requires 1.9.3 or newer.
TIP: Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails. Ruby Enterprise Edition has these fixed since the release of 1.8.7-2010.02. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults, so if you want to use 1.9.x, jump straight to 1.9.3 for smooth sailing.
Upgrading from Rails 3.2 to Rails 4.0
NOTE: This section is a work in progress.
If your application is currently on any version of Rails older than 3.2.x, you should upgrade to Rails 3.2 before attempting one to Rails 4.0.
The following changes are meant for upgrading your application to Rails 4.0.
Rails 4.0 no longer supports loading plugins from
vendor/plugins. You must replace any plugins by extracting them to gems and adding them to your Gemfile. If you choose not to make them gems, you can move them into, say,
lib/my_plugin/* and add an appropriate initializer in
Rails 4.0 has removed the identity map from Active Record, due to some inconsistencies with associations. If you have manually enabled it in your application, you will have to remove the following config that has no effect anymore:
deletemethod in collection associations can now receive
Stringarguments as record ids, besides records, pretty much like the
destroymethod does. Previously it raised
ActiveRecord::AssociationTypeMismatchfor such arguments. From Rails 4.0 on
deleteautomatically tries to find the records matching the given ids before deleting them.
Rails 4.0 has changed how orders get stacked in
ActiveRecord::Relation. In previous versions of Rails, the new order was applied after the previously defined order. But this is no longer true. Check Active Record Query guide for more information.
Rails 4.0 has changed
attr_readonlyto class methods only. Now you shouldn't use instance methods, it's deprecated. You must change them, e.g.
Rails 4.0 has removed
attr_protectedfeature in favor of Strong Parameters. You can use the Protected Attributes gem to a smoothly upgrade path.
Rails 4.0 extracted Active Resource to its own gem. If you still need the feature you can add the Active Resource gem in your Gemfile.
Rails 4.0 has changed how errors attach with the
ActiveModel::Validations::ConfirmationValidator. Now when confirmation validations fail the error will be attached to
Rails 4.0 has changed
ActiveModel::Serializers::JSON.include_root_in_jsondefault value to
false. Now, Active Model Serializers and Active Record objects have the same default behaviour. This means that you can comment or remove the following option in the
# Disable root element in JSON by default. # ActiveSupport.on_load(:active_record) do # self.include_root_in_json = false # end
- Rails 4.0 introduces a new
UpgradeSignatureToEncryptionCookieStorecookie store. This is useful for upgrading apps using the old default
CookieStoreto the new default
EncryptedCookieStore. To use this transitional cookie store, you'll want to leave your existing
secret_tokenin place, add a new
secret_key_base, and change your
# config/initializers/session_store.rb Myapp::Application.config.session_store :upgrade_signature_to_encryption_cookie_store, key: 'existing session key' # config/initializers/secret_token.rb Myapp::Application.config.secret_token = 'existing secret token' Myapp::Application.config.secret_key_base = 'new secret key base'
Rails 4.0 removed the
ActionController::Base.asset_pathoption. Use the assets pipeline feature.
Rails 4.0 has deprecated
Rails 4.0 has removed Action and Page caching from Action Pack. You will need to add the
actionpack-action_cachinggem in order to use
caches_pagesin your controllers.
Rails 4.0 has the removed XML parameters parser. You will need to add the
actionpack-xml_parsergem if you require this feature.
Rails 4.0 changes the default memcached client from
dalli. To upgrade, simply add
gem 'dalli'to your
Rails 4.0 changed how
assert_routingwork. Now all these assertions raise
Rails 4.0 also changed the way unicode character routes are drawn. Now you can draw unicode character routes directly. If you already draw such routes, you must change them, for example:
get Rack::Utils.escape('こんにちは'), controller: 'welcome', action: 'index'
get 'こんにちは', controller: 'welcome', action: 'index'
- Rails 4.0 has removed ActionDispatch::BestStandardsSupport middleware, !DOCTYPE html already triggers standards mode per http://msdn.microsoft.com/en-us/library/jj676915(v=vs.85).aspx and ChromeFrame header has been moved to
Remember you must also remove any references to the middleware from your application code, for example:
# Raise exception config.middleware.insert_before(Rack::Lock, ActionDispatch::BestStandardsSupport)
Also check your environment settings for
config.action_dispatch.best_standards_support and remove it if present.
In Rails 4.0, precompiling assets no longer automatically copies non-JS/CSS assets from
lib/assets. Rails application and engine developers should put these assets in
In Rails 4.0, a rescuable exception
ActionController::UnknownFormatis raised when Rails doesn't know what to do with the request format, rather than responding with a head :not_acceptable (406).
In Rails 4.0,
SCRIPT_NAMEis properly handled for mounted apps and engines. One caveat of the fix is that you should not set
default_url_options[:script_name]explicitly if your server already passes correct
SCRIPT_NAMEto rack env.
Rails 4.0 removes the
j alias for
j is already used for
Helpers Loading Order
The order in which helpers from more than one directory are loaded has changed in Rails 4.0. Previously, they were gathered and then sorted alphabetically. After upgrading to Rails 4.0, helpers will preserve the order of loaded directories and will be sorted alphabetically only within each directory. Unless you explicitly use the
helpers_path parameter, this change will only impact the way of loading helpers from engines. If you rely on the ordering, you should check if correct methods are available after upgrade. If you would like to change the order in which engines are loaded, you can use
Active Record Observer and Action Controller Sweeper
Active Record Observer and Action Controller Sweeper have been extracted to the
rails-observers gem. You will need to add the
rails-observers gem if you require these features.
asset_urlwith two arguments is deprecated. For example:
Upgrading from Rails 3.1 to Rails 3.2
If your application is currently on any version of Rails older than 3.1.x, you should upgrade to Rails 3.1 before attempting an update to Rails 3.2.
The following changes are meant for upgrading your application to Rails 3.2.12, the latest 3.2.x version of Rails.
Make the following changes to your
gem 'rails', '= 3.2.12' group :assets do gem 'sass-rails', '~> 3.2.3' gem 'coffee-rails', '~> 3.2.1' gem 'uglifier', '>= 1.0.3' end
There are a couple of new configuration settings that you should add to your development environment:
# Raise exception on mass assignment protection for Active Record models config.active_record.mass_assignment_sanitizer = :strict # Log the query plan for queries taking more than this (works # with SQLite, MySQL, and PostgreSQL) config.active_record.auto_explain_threshold_in_seconds = 0.5
mass_assignment_sanitizer configuration setting should also be be added to
# Raise exception on mass assignment protection for Active Record models config.active_record.mass_assignment_sanitizer = :strict
Rails 3.2 deprecates
vendor/plugins and Rails 4.0 will remove them completely. While it's not strictly necessary as part of a Rails 3.2 upgrade, you can start replacing any plugins by extracting them to gems and adding them to your Gemfile. If you choose not to make them gems, you can move them into, say,
lib/my_plugin/* and add an appropriate initializer in
Upgrading from Rails 3.0 to Rails 3.1
If your application is currently on any version of Rails older than 3.0.x, you should upgrade to Rails 3.0 before attempting an update to Rails 3.1.
The following changes are meant for upgrading your application to Rails 3.1.11, the latest 3.1.x version of Rails.
Make the following changes to your
The asset pipeline requires the following additions:
config.assets.enabled = true config.assets.version = '1.0'
If your application is using an "/assets" route for a resource you may want change the prefix used for assets to avoid conflicts:
# Defaults to '/assets' config.assets.prefix = '/asset-files'
Remove the RJS setting
config.action_view.debug_rjs = true.
Add these settings if you enable the asset pipeline:
# Do not compress assets config.assets.compress = false # Expands the lines which load the assets config.assets.debug = true
Again, most of the changes below are for the asset pipeline. You can read more about these in the Asset Pipeline guide.
You can help test performance with these additions to your test environment:
# Configure static asset server for tests with Cache-Control for performance config.serve_static_assets = true config.static_cache_control = "public, max-age=3600"
Add this file with the following contents, if you wish to wrap parameters into a nested hash. This is on by default in new applications.
# Be sure to restart your server when you modify this file. # This file contains settings for ActionController::ParamsWrapper which # is enabled by default. # Enable parameter wrapping for JSON. You can disable this by setting :format to an empty array. ActiveSupport.on_load(:action_controller) do wrap_parameters format: [:json] end # Disable root element in JSON by default. ActiveSupport.on_load(:active_record) do self.include_root_in_json = false end
You need to change your session key to something new, or remove all sessions:
# in config/initializers/session_store.rb AppName::Application.config.session_store :cookie_store, key: 'SOMETHINGNEW'
$ rake db:sessions:clear
Remove :cache and :concat options in asset helpers references in views
- With the Asset Pipeline the :cache and :concat options aren't used anymore, delete these options from your views.