1 Upgrading to Rails 3.1

If you’re upgrading an existing application, it’s a great idea to have good test coverage before going in. You should also first upgrade to Rails 3 in case you haven’t and make sure your application still runs as expected before attempting to update to Rails 3.1. Then take heed of the following changes:

1.1 Rails 3.1 requires at least Ruby 1.8.7

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.3, the latest 3.1.x version of Rails.

1.2 Ruby

Rails 3.1 requires Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially and you should upgrade as early as possible. Rails 3.1 is also compatible with Ruby 1.9.2.

Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02 though. 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 on 1.9.2 for smooth sailing.

1.8 config/initializers/wrap_parameters.rb

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

1.9 config/initializers/session_store.rb

You need to change your session key to something new, or remove all sessions:

2 Creating a Rails 3.1 application

# You should have the 'rails' rubygem installed
$ rails new myapp
$ cd myapp

2.1 Vendoring Gems

Rails now uses a Gemfile in the application root to determine the gems you require for your application to start. This Gemfile is processed by the Bundler gem, which then installs all your dependencies. It can even install all the dependencies locally to your application so that it doesn’t depend on the system gems.

3.2 HTTP Streaming

HTTP Streaming is another change that is new in Rails 3.1. This lets the browser download your stylesheets and JavaScript files while the server is still generating the response. This requires Ruby 1.9.2, is opt-in and requires support from the web server as well, but the popular combo of nginx and unicorn is ready to take advantage of it.

3.3 Default JS library is now jQuery

jQuery is the default JavaScript library that ships with Rails 3.1. But if you use Prototype, it’s simple to switch.

$ rails new myapp -j prototype

3.4 Identity Map

Active Record has an Identity Map in Rails 3.1. An identity map keeps previously instantiated records and returns the object associated with the record if accessed again. The identity map is created on a per-request basis and is flushed at request completion.

Rails 3.1 comes with the identity map turned off by default.

4 Railties

jQuery is the new default JavaScript library.

jQuery and Prototype are no longer vendored and is provided from now on by the jquery-rails and prototype-rails gems.

The application generator accepts an option -j which can be an arbitrary string. If passed “foo”, the gem “foo-rails” is added to the Gemfile, and the application JavaScript manifest requires “foo” and “foo_ujs”. Currently only “prototype-rails” and “jquery-rails” exist and provide those files via the asset pipeline.

Generating an application or a plugin runs bundle install unless --skip-gemfile or --skip-bundle is specified.

The controller and resource generators will now automatically produce asset stubs (this can be turned off with --skip-assets). These stubs will use CoffeeScript and Sass, if those libraries are available.

Scaffold and app generators use the Ruby 1.9 style hash when running on Ruby 1.9. To generate old style hash, --old-style-hash can be passed.

Active Record logging is directed to STDOUT and shown inline in the console.

Added config.force_ssl configuration which loads Rack::SSL middleware and force all requests to be under HTTPS protocol.

Added rails plugin new command which generates a Rails plugin with gemspec, tests and a dummy application for testing.

Added Rack::Etag and Rack::ConditionalGet to the default middleware stack.

Added Rack::Cache to the default middleware stack.

Engines received a major update – You can mount them at any path, enable assets, run generators etc.

5 Action Pack

5.1 Action Controller

A warning is given out if the CSRF token authenticity cannot be verified.

Specify force_ssl in a controller to force the browser to transfer data via HTTPS protocol on that particular controller. To limit to specific actions, :only or :except can be used.

Sensitive query string parameters specified in config.filter_parameters will now be filtered out from the request paths in the log.

URL parameters which return nil for to_param are now removed from the query string.

Added ActionController::ParamsWrapper to wrap parameters into a nested hash, and will be turned on for JSON request in new applications by default. This can be customized in config/initializers/wrap_parameters.rb.

Added config.action_controller.include_all_helpers. By default helper :all is done in ActionController::Base, which includes all the helpers by default. Setting include_all_helpers to false will result in including only application_helper and the helper corresponding to controller (like foo_helper for foo_controller).

url_for and named url helpers now accept :subdomain and :domain as options.

Added Base.http_basic_authenticate_with to do simple http basic authentication with a single class method call.

Moved etag responsibility from ActionDispatch::Response to the middleware stack.

Rely on Rack::Session stores API for more compatibility across the Ruby world. This is backwards incompatible since Rack::Session expects #get_session to accept four arguments and requires #destroy_session instead of simply #destroy.

Template lookup now searches further up in the inheritance chain.

5.3 Action View

Added an :authenticity_token option to form_tag for custom handling or to omit the token by passing :authenticity_token => false.

Created ActionView::Renderer and specified an API for ActionView::Context.

6 Active Record

Added a class method pluralize_table_names to singularize/pluralize table names of individual models. Previously this could only be set globally for all models through ActiveRecord::Base.pluralize_table_names.

Added ActiveRecord::Base.attribute_names to return a list of attribute names. This will return an empty array if the model is abstract or the table does not exist.

CSV Fixtures are deprecated and support will be removed in Rails 3.2.0.

ActiveRecord#new, ActiveRecord#create and ActiveRecord#update_attributes all accept a second hash as an option that allows you to specify which role to consider when assigning attributes. This is built on top of Active Model’s new mass assignment capabilities:

default_scope can now take a block, lambda, or any other object which responds to call for lazy evaluation.

Default scopes are now evaluated at the latest possible moment, to avoid problems where scopes would be created which would implicitly contain the default scope, which would then be impossible to get rid of via Model.unscoped.

PostgreSQL adapter only supports PostgreSQL version 8.2 and higher.

ConnectionManagement middleware is changed to clean up the connection pool after the rack body has been flushed.

Added an update_column method on Active Record. This new method updates a given attribute on an object, skipping validations and callbacks. It is recommended to use update_attributes or update_attribute unless you are sure you do not want to execute any callback, including the modification of the updated_at column. It should not be called on new records.

Associations with a :through option can now use any association as the through or source association, including other associations which have a :through option and has_and_belongs_to_many associations.

The configuration for the current database connection is now accessible via ActiveRecord::Base.connection_config.

limits and offsets are removed from COUNT queries unless both are supplied.

ActiveRecord::Associations::AssociationProxy has been split. There is now an Association class (and subclasses) which are responsible for operating on associations, and then a separate, thin wrapper called CollectionProxy, which proxies collection associations. This prevents namespace pollution, separates concerns, and will allow further refactorings.

Singular associations (has_one, belongs_to) no longer have a proxy and simply returns the associated record or nil. This means that you should not use undocumented methods such as bob.mother.create – use bob.create_mother instead.

Support the :dependent option on has_many :through associations. For historical and practical reasons, :delete_all is the default deletion strategy employed by association.delete(*records), despite the fact that the default strategy is :nullify for regular has_many. Also, this only works at all if the source reflection is a belongs_to. For other situations, you should directly modify the through association.

The behavior of association.destroy for has_and_belongs_to_many and has_many :through is changed. From now on, ‘destroy’ or ‘delete’ on an association will be taken to mean ‘get rid of the link’, not (necessarily) ‘get rid of the associated records’.

Previously, has_and_belongs_to_many.destroy(*records) would destroy the records themselves. It would not delete any records in the join table. Now, it deletes the records in the join table.

Previously, has_many_through.destroy(*records) would destroy the records themselves, and the records in the join table. [Note: This has not always been the case; previous version of Rails only deleted the records themselves.] Now, it destroys only the records in the join table.

Note that this change is backwards-incompatible to an extent, but there is unfortunately no way to ‘deprecate’ it before changing it. The change is being made in order to have consistency as to the meaning of ‘destroy’ or ‘delete’ across the different types of associations. If you wish to destroy the records themselves, you can do records.association.each(&:destroy).

Add :bulk => true option to change_table to make all the schema changes defined in a block using a single ALTER statement.

Some things cannot be automatically reversed for you. If you know how to reverse those things, you should define up and down in your migration. If you define something in change that cannot be reversed, an IrreversibleMigration exception will be raised when going down.

Migrations now use instance methods rather than class methods:

class FooMigration < ActiveRecord::Migration
def up # Not self.up
...
end
end

Migration files generated from model and constructive migration generators (for example, add_name_to_users) use the reversible migration’s change method instead of the ordinary up and down methods.

Removed support for interpolating string SQL conditions on associations. Instead, a proc should be used.

Calling ActiveRecord::Base#clone will result in a shallow copy of the record, including copying the frozen state. No callbacks will be called.

Calling ActiveRecord::Base#dup will duplicate the record, including calling after initialize hooks. Frozen state will not be copied, and all associations will be cleared. A duped record will return true for new_record?, have a nil id field, and is saveable.

The query cache now works with prepared statements. No changes in the applications are required.

7 Active Model

attr_accessible accepts an option :as to specify a role.

InclusionValidator, ExclusionValidator, and FormatValidator now accepts an option which can be a proc, a lambda, or anything that respond to call. This option will be called with the current record as an argument and returns an object which respond to include? for InclusionValidator and ExclusionValidator, and returns a regular expression object for FormatValidator.

Feedback

You're encouraged to help improve the quality of this guide.

If you see any typos or factual errors you are confident to
patch, please clone the rails
repository and open a new pull request. You can also ask for commit rights on
docrails if you plan to submit
several patches. Commits are reviewed, but that happens after you've submitted your
contribution. This repository is cross-merged with master periodically.

You may also find incomplete content, or stuff that is not up to date.
Please do add any missing documentation for master. Check the
Ruby on Rails Guides Guidelines
for style and conventions.

If for whatever reason you spot something to fix but cannot patch it yourself, please
open an issue.