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

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.

1.2. What to update in your apps

The following changes are meant for upgrading your application to Rails 3.1.3, the latest 3.1.x version of Rails.

1.2.1. Gemfile

Make the following changes to yourGemfile.

gem"rails","= 3.1.3"gem"mysql2"# Needed for the new asset pipelinegroup:assetsdogem"sass-rails","~> 3.1.5"gem"coffee-rails","~> 3.1.1"gem"uglifier",">= 1.0.3"end# jQuery is the default JavaScript library in Rails 3.1gem"jquery-rails"

1.2.2. config/application.rb

• The asset pipeline requires the following additions:

  config.assets.enabled=trueconfig.assets.version='1.0'

  Copy

• If your application is using the "/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'

  Copy

1.2.3. config/environments/development.rb

• Remove the RJS settingconfig.action_view.debug_rjs = true.

• Add the following, if you enable the asset pipeline.

  # Do not compress assetsconfig.assets.compress=false# Expands the lines which load the assetsconfig.assets.debug=true

  Copy

1.2.4. config/environments/production.rb

• Again, most of the changes below are for the asset pipeline. You can read more about these in theAsset Pipeline guide.

  # Compress JavaScripts and CSSconfig.assets.compress=true# Don't fallback to assets pipeline if a precompiled asset is missedconfig.assets.compile=false# Generate digests for assets URLsconfig.assets.digest=true# Defaults to Rails.root.join("public/assets")# config.assets.manifest = YOUR_PATH# Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added)# config.assets.precompile `= %w( admin.js admin.css )# Force all access to the app over SSL, use Strict-Transport-Security, and use secure cookies.# config.force_ssl = true

  Copy

1.2.5. config/environments/test.rb

# Configure static asset server for tests with Cache-Control for performanceconfig.serve_static_assets=trueconfig.static_cache_control="public, max-age=3600"

1.2.6. 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)dowrap_parameters:format=>[:json]end# Disable root element in JSON by default.ActiveSupport.on_load(:active_record)doself.include_root_in_json=falseend

  Copy

1.2.7. 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.

2. Creating a Rails 3.1 application

# You should have the 'rails' RubyGem installed$railsnew myapp$cdmyapp

2.1. Vendoring Gems

Rails now uses aGemfile in the application root to determine the gems you require for your application to start. ThisGemfile is processed by theBundler 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.

More information: -bundler homepage

2.2. Living on the Edge

Bundler andGemfile makes freezing your Rails application easy as pie with the new dedicatedbundle command. If you want to bundle straight from the Git repository, you can pass the--edge flag:

$railsnew myapp--edge

If you have a local checkout of the Rails repository and want to generate an application using that, you can pass the--dev flag:

$ruby /path/to/rails/railties/bin/rails new myapp--dev

3. Rails Architectural Changes

3.1. Assets Pipeline

The major change in Rails 3.1 is the Assets Pipeline. It makes CSS and JavaScript first-class code citizens and enables proper organization, including use in plugins and engines.

The assets pipeline is powered bySprockets and is covered in theAsset Pipeline guide.

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.

$railsnew 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 thejquery-rails andprototype-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 theGemfile, 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 runsbundle 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.

• Scaffold controller generator creates format block for JSON instead of XML.

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

• Addedconfig.force_ssl configuration which loadsRack::SSL middleware and force all requests to be under HTTPS protocol.

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

• AddedRack::Etag andRack::ConditionalGet to the default middleware stack.

• AddedRack::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.

• Specifyforce_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 inconfig.filter_parameters will now be filtered out from the request paths in the log.

• URL parameters which returnnil forto_param are now removed from the query string.

• AddedActionController::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 inconfig/initializers/wrap_parameters.rb.

• Addedconfig.action_controller.include_all_helpers. By defaulthelper :all is done inActionController::Base, which includes all the helpers by default. Settinginclude_all_helpers tofalse 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.

• AddedBase.http_basic_authenticate_with to do simple http basic authentication with a single class method call.

  classPostsController<ApplicationControllerUSER_NAME,PASSWORD="dhh","secret"before_filter:authenticate,:except=>[:index]defindexrender:text=>"Everyone can see me!"enddefeditrender:text=>"I'm only accessible if you know the password"endprivatedefauthenticateauthenticate_or_request_with_http_basicdo|user_name,password|user_name==USER_NAME&&password==PASSWORDendendend

  Copy

  ..can now be written as

  classPostsController<ApplicationControllerhttp_basic_authenticate_with:name=>"dhh",:password=>"secret",:except=>:indexdefindexrender:text=>"Everyone can see me!"enddefeditrender:text=>"I'm only accessible if you know the password"endend

  Copy

• Added streaming support, you can enable it with:

  classPostsController<ActionController::Basestreamend

  Copy

  You can restrict it to some actions by using:only or:except. Please read the docs atActionController::Streaming for more information.

• The redirect route method now also accepts a hash of options which will only change the parts of the URL in question, or an object which responds to call, allowing for redirects to be reused.

5.2. Action Dispatch

• config.action_dispatch.x_sendfile_header now defaults tonil andconfig/environments/production.rb doesn't set any particular value for it. This allows servers to set it throughX-Sendfile-Type.

• ActionDispatch::MiddlewareStack now uses composition over inheritance and is no longer an array.

• AddedActionDispatch::Request.ignore_accept_header to ignore accept headers.

• AddedRack::Cache to the default stack.

• Moved etag responsibility fromActionDispatch::Response to the middleware stack.

• Rely onRack::Session stores API for more compatibility across the Ruby world. This is backwards incompatible sinceRack::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 toform_tag for custom handling or to omit the token by passing:authenticity_token => false.

• CreatedActionView::Renderer and specified an API forActionView::Context.

• In placeSafeBuffer mutation is prohibited in Rails 3.1.

• Added HTML5button_tag helper.

• file_field automatically adds:multipart => true to the enclosing form.

• Added a convenience idiom to generate HTML5 data-* attributes in tag helpers from a:data hash of options:

  tag("div",:data=>{:name=>'Stephen',:city_state=>%w(Chicago IL)})# => <div data-name="Stephen" data-city-state="[&quot;Chicago&quot;,&quot;IL&quot;]" />

  Copy

Keys are dasherized. Values are JSON-encoded, except for strings and symbols.

• csrf_meta_tag is renamed tocsrf_meta_tags and aliasescsrf_meta_tag for backwards compatibility.

• The old template handler API is deprecated and the new API simply requires a template handler to respond to call.

• rhtml and rxml are finally removed as template handlers.

• config.action_view.cache_template_loading is brought back which allows to decide whether templates should be cached or not.

• The submit form helper does not generate an id "object_name_id" anymore.

• AllowsFormHelper#form_for to specify the:method as a direct option instead of through the:html hash.form_for(@post, remote: true, method: :delete) instead ofform_for(@post, remote: true, html: { method: :delete }).

• ProvidedJavaScriptHelper#j() as an alias forJavaScriptHelper#escape_javascript(). This supersedes theObject#j() method that the JSON gem adds within templates using the JavaScriptHelper.

• Allows AM/PM format in datetime selectors.

• auto_link has been removed from Rails and extracted into therails_autolink gem

6. Active Record

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

  classUser<ActiveRecord::Baseself.pluralize_table_names=falseend

  Copy

• Added block setting of attributes to singular associations. The block will get called after the instance is initialized.

  classUser<ActiveRecord::Basehas_one:accountenduser.build_account{|a|a.credit_limit=100.0}

  Copy

• AddedActiveRecord::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 andActiveRecord#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:

  classPost<ActiveRecord::Baseattr_accessible:titleattr_accessible:title,:published_at,:as=>:adminendPost.new(params[:post],:as=>:admin)

  Copy

• 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 anupdate_column method on Active Record. This new method updates a given attribute on an object, skipping validations and callbacks. It is recommended to useupdate_attributes orupdate_attribute unless you are sure you do not want to execute any callback, including the modification of theupdated_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 andhas_and_belongs_to_many associations.

• The configuration for the current database connection is now accessible viaActiveRecord::Base.connection_config.

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

  People.limit(1).count# => 'SELECT COUNT(*) FROM people'People.offset(1).count# => 'SELECT COUNT(*) FROM people'People.limit(1).offset(1).count# => 'SELECT COUNT(*) FROM people LIMIT 1 OFFSET 1'

  Copy

• ActiveRecord::Associations::AssociationProxy has been split. There is now anAssociation class (and subclasses) which are responsible for operating on associations, and then a separate, thin wrapper calledCollectionProxy, 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 ornil. This means that you should not use undocumented methods such asbob.mother.create - usebob.create_mother instead.

• Support the:dependent option onhas_many :through associations. For historical and practical reasons,:delete_all is the default deletion strategy employed byassociation.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 ofassociation.destroy forhas_and_belongs_to_many andhas_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 dorecords.association.each(&:destroy).

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

  change_table(:users,:bulk=>true)do|t|t.string:company_namet.change:birthdate,:datetimeend

  Copy

• Removed support for accessing attributes on ahas_and_belongs_to_many join table.has_many :through needs to be used.

• Added acreate_association! method forhas_one andbelongs_to associations.

• Migrations are now reversible, meaning that Rails will figure out how to reverse your migrations. To use reversible migrations, just define thechange method.

  classMyMigration<ActiveRecord::Migrationdefchangecreate_table(:horses)do|t|t.column:content,:textt.column:remind_at,:datetimeendendend

  Copy

• Some things cannot be automatically reversed for you. If you know how to reverse those things, you should defineup anddown in your migration. If you define something in change that cannot be reversed, anIrreversibleMigration exception will be raised when going down.

• Migrations now use instance methods rather than class methods:

  classFooMigration<ActiveRecord::Migrationdefup# Not self.up# ...endend

  Copy

• Migration files generated from model and constructive migration generators (for example, add_name_to_users) use the reversible migration'schange method instead of the ordinaryup anddown methods.

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

  has_many:things,:conditions=>'foo = #{bar}'# beforehas_many:things,:conditions=>proc{"foo =#{bar}"}# after

  Copy

  Inside the proc,self is the object which is the owner of the association, unless you are eager loading the association, in which caseself is the class which the association is within.

  You can have any "normal" conditions inside the proc, so the following will work too:

  has_many:things,:conditions=>proc{["foo = ?",bar]}

  Copy

• Previously:insert_sql and:delete_sql onhas_and_belongs_to_many association allowed you to call 'record' to get the record being inserted or deleted. This is now passed as an argument to the proc.

• AddedActiveRecord::Base#has_secure_password (viaActiveModel::SecurePassword) to encapsulate dead-simple password usage with BCrypt encryption and salting.

  # Schema: User(name:string, password_digest:string, password_salt:string)classUser<ActiveRecord::Basehas_secure_passwordend

  Copy

• When a model is generatedadd_index is added by default forbelongs_to orreferences columns.

• Setting the id of abelongs_to object will update the reference to the object.

• ActiveRecord::Base#dup andActiveRecord::Base#clone semantics have changed to closer match normal Ruby dup and clone semantics.

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

• CallingActiveRecord::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 returntrue fornew_record?, have anil 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, andFormatValidator now accepts an option which can be a proc, a lambda, or anything that respond tocall. This option will be called with the current record as an argument and returns an object which respond toinclude? forInclusionValidator andExclusionValidator, and returns a regular expression object forFormatValidator.

• AddedActiveModel::SecurePassword to encapsulate dead-simple password usage with BCrypt encryption and salting.

• ActiveModel::AttributeMethods allows attributes to be defined on demand.

• Added support for selectively enabling and disabling observers.

• AlternateI18n namespace lookup is no longer supported.

8. Active Resource

• The default format has been changed to JSON for all requests. If you want to continue to use XML you will need to setself.format = :xml in the class. For example,

  classUser<ActiveResource::Baseself.format=:xmlend

  Copy

9. Active Support

• ActiveSupport::Dependencies now raisesNameError if it finds an existing constant inload_missing_constant.

• Added a new reporting methodKernel#quietly which silences bothSTDOUT andSTDERR.

• AddedString#inquiry as a convenience method for turning a String into aStringInquirer object.

• AddedObject#in? to test if an object is included in another object.

• LocalCache strategy is now a real middleware class and no longer an anonymous class.

• ActiveSupport::Dependencies::ClassCache class has been introduced for holding references to reloadable classes.

• ActiveSupport::Dependencies::Reference has been refactored to take direct advantage of the newClassCache.

• BackportsRange#cover? as an alias forRange#include? in Ruby 1.8.

• Addedweeks_ago andprev_week to Date/DateTime/Time.

• Addedbefore_remove_const callback toActiveSupport::Dependencies.remove_unloadable_constants!.

Deprecations:

• ActiveSupport::SecureRandom is deprecated in favor ofSecureRandom from the Ruby standard library.

10. Credits

See thefull list of contributors to Rails for the many people who spent many hours making Rails, the stable and robust framework it is. Kudos to all of them.

Rails 3.1 Release Notes were compiled byVijay Dev