rails 4.0.13 → 4.1.16

data/guides/source/active_record_querying.md

@@ -58,6 +58,7 @@ The methods are:
 
 * `bind`
 * `create_with`
+* `distinct`
 * `eager_load`
 * `extending`
 * `from`
@@ -76,7 +77,6 @@ The methods are:
 * `reorder`
 * `reverse_order`
 * `select`
-* `distinct`
 * `uniq`
 * `where`
 
@@ -91,7 +91,7 @@ The primary operation of `Model.find(options)` can be summarized as:
 
 ### Retrieving a Single Object
 
-Active Record provides five different ways of retrieving a single object.
+Active Record provides several different ways of retrieving a single object.
 
 #### Using a Primary Key
 
@@ -473,7 +473,7 @@ In the case of a belongs_to relationship, an association key can be used to spec
 
 ```ruby
 Post.where(author: author)
-Author.joins(:posts).where(posts: {author: author})
+Author.joins(:posts).where(posts: { author: author })
 ```
 
 NOTE: The values cannot be symbols. For example, you cannot do `Client.where(status: :active)`.
@@ -685,9 +685,9 @@ This will return single order objects for each day, but only those that are orde
 Overriding Conditions
 ---------------------
 
-### `except`
+### `unscope`
 
-You can specify certain conditions to be excepted by using the `except` method. For example:
+You can specify certain conditions to be removed using the `unscope` method. For example:
 
 ```ruby
 Post.where('id > 10').limit(20).order('id asc').except(:order)
@@ -697,27 +697,25 @@ The SQL that would be executed:
 
 ```sql
 SELECT * FROM posts WHERE id > 10 LIMIT 20
-```
 
-### `unscope`
+# Original query without `unscope`
+SELECT * FROM posts WHERE id > 10 ORDER BY id asc LIMIT 20
 
-The `except` method does not work when the relation is merged. For example:
-
-```ruby
-Post.comments.except(:order)
 ```
 
-will still have an order if the order comes from a default scope on Comment. In order to remove all ordering, even from relations which are merged in, use unscope as follows:
+You can additionally unscope specific where clauses. For example:
 
 ```ruby
-Post.order('id DESC').limit(20).unscope(:order) = Post.limit(20)
-Post.order('id DESC').limit(20).unscope(:order, :limit) = Post.all
+Post.where(id: 10, trashed: false).unscope(where: :id)
+# SELECT "posts".* FROM "posts" WHERE trashed = 0
 ```
 
-You can additionally unscope specific where clauses. For example:
+A relation which has used `unscope` will affect any relation it is
+merged in to:
 
 ```ruby
-Post.where(:id => 10).limit(1).unscope(where: :id, :limit).order('id DESC') = Post.order('id DESC')
+Post.order('id asc').merge(Post.unscope(:order))
+# SELECT "posts".* FROM "posts"
 ```
 
 ### `only`
@@ -732,6 +730,10 @@ The SQL that would be executed:
 
 ```sql
 SELECT * FROM posts WHERE id > 10 ORDER BY id DESC
+
+# Original query without `only`
+SELECT "posts".* FROM "posts" WHERE (id > 10) ORDER BY id desc LIMIT 20
+
 ```
 
 ### `reorder`
@@ -742,7 +744,7 @@ The `reorder` method overrides the default scope order. For example:
 class Post < ActiveRecord::Base
   ..
   ..
-  has_many :comments, order: 'posted_at DESC'
+  has_many :comments, -> { order('posted_at DESC') }
 end
 
 Post.find(10).comments.reorder('name')
@@ -751,13 +753,15 @@ Post.find(10).comments.reorder('name')
 The SQL that would be executed:
 
 ```sql
-SELECT * FROM posts WHERE id = 10 ORDER BY name
+SELECT * FROM posts WHERE id = 10
+SELECT * FROM comments WHERE post_id = 10 ORDER BY name
 ```
 
 In case the `reorder` clause is not used, the SQL executed would be:
 
 ```sql
-SELECT * FROM posts WHERE id = 10 ORDER BY posted_at DESC
+SELECT * FROM posts WHERE id = 10
+SELECT * FROM comments WHERE post_id = 10 ORDER BY posted_at DESC
 ```
 
 ### `reverse_order`
@@ -788,6 +792,32 @@ SELECT * FROM clients WHERE orders_count > 10 ORDER BY clients.id DESC
 
 This method accepts **no** arguments.
 
+### `rewhere`
+
+The `rewhere` method overrides an existing, named where condition. For example:
+
+```ruby
+Post.where(trashed: true).rewhere(trashed: false)
+```
+
+The SQL that would be executed:
+
+```sql
+SELECT * FROM posts WHERE `trashed` = 0
+```
+
+In case the `rewhere` clause is not used,
+
+```ruby
+Post.where(trashed: true).where(trashed: false)
+```
+
+the SQL executed would be:
+
+```sql
+SELECT * FROM posts WHERE `trashed` = 1 AND `trashed` = 0
+```
+
 Null Relation
 -------------
 
@@ -826,8 +856,6 @@ client.save
 
 As `client` is explicitly set to be a readonly object, the above code will raise an `ActiveRecord::ReadOnlyRecord` exception when calling `client.save` with an updated value of _visits_.
 
-NOTE: using `joins` without an explicit `select` will return readonly records.
-
 Locking Records for Update
 --------------------------
 
@@ -931,15 +959,13 @@ This will result in the following SQL:
 SELECT clients.* FROM clients LEFT OUTER JOIN addresses ON addresses.client_id = clients.id
 ```
 
-NOTE: using `joins` might return readonly records. See [readonly](active_record_querying.html#readonly-objects) for more details.
-
 ### Using Array/Hash of Named Associations
 
 WARNING: This method only works with `INNER JOIN`.
 
 Active Record lets you use the names of the [associations](association_basics.html) defined on the model as a shortcut for specifying `JOIN` clause for those associations when using the `joins` method.
 
-For example, consider the following `Category`, `Post`, `Comments` and `Guest` models:
+For example, consider the following `Category`, `Post`, `Comment`, `Guest` and `Tag` models:
 
 ```ruby
 class Category < ActiveRecord::Base
@@ -1018,7 +1044,7 @@ Or, in English: "return all posts that have a comment made by a guest."
 #### Joining Nested Associations (Multiple Level)
 
 ```ruby
-Category.joins(posts: [{comments: :guest}, :tags])
+Category.joins(posts: [{ comments: :guest }, :tags])
 ```
 
 This produces:
@@ -1044,7 +1070,7 @@ An alternative and cleaner syntax is to nest the hash conditions:
 
 ```ruby
 time_range = (Time.now.midnight - 1.day)..Time.now.midnight
-Client.joins(:orders).where(orders: {created_at: time_range})
+Client.joins(:orders).where(orders: { created_at: time_range })
 ```
 
 This will find all clients who have orders that were created yesterday, again using a `BETWEEN` SQL expression.
@@ -1105,7 +1131,7 @@ This loads all the posts and the associated category and comments for each post.
 #### Nested Associations Hash
 
 ```ruby
-Category.includes(posts: [{comments: :guest}, :tags]).find(1)
+Category.includes(posts: [{ comments: :guest }, :tags]).find(1)
 ```
 
 This will find the category with id 1 and eager load all of the associated posts, the associated posts' tags and comments, and every comment's guest association.
@@ -1117,18 +1143,30 @@ Even though Active Record lets you specify conditions on the eager loaded associ
 However if you must do this, you may use `where` as you would normally.
 
 ```ruby
-Post.includes(:comments).where("comments.visible" => true)
+Post.includes(:comments).where(comments: { visible: true })
 ```
 
-This would generate a query which contains a `LEFT OUTER JOIN` whereas the `joins` method would generate one using the `INNER JOIN` function instead.
+This would generate a query which contains a `LEFT OUTER JOIN` whereas the
+`joins` method would generate one using the `INNER JOIN` function instead.
 
 ```ruby
   SELECT "posts"."id" AS t0_r0, ... "comments"."updated_at" AS t1_r5 FROM "posts" LEFT OUTER JOIN "comments" ON "comments"."post_id" = "posts"."id" WHERE (comments.visible = 1)
 ```
 
-If there was no `where` condition, this would generate the normal set of two queries.
+If there was no `where` condition, this would generate the normal set of two
+queries.
+
+NOTE: Using `where` like this will only work when you pass it a Hash. For
+SQL-fragments you need use `references` to force joined tables:
+
+```ruby
+Post.includes(:comments).where("comments.visible = true").references(:comments)
+```
+
+If, in the case of this `includes` query, there were no comments for any posts,
+all the posts would still be loaded. By using `joins` (an INNER JOIN), the join
+conditions **must** match, otherwise no records will be returned.
 
-If, in the case of this `includes` query, there were no comments for any posts, all the posts would still be loaded. By using `joins` (an INNER JOIN), the join conditions **must** match, otherwise no records will be returned.
 
 Scopes
 ------
@@ -1185,7 +1223,7 @@ class Post < ActiveRecord::Base
 end
 ```
 
-This may then be called using this:
+Call the scope as if it were a class method:
 
 ```ruby
 Post.created_before(Time.zone.now)
@@ -1218,46 +1256,46 @@ class User < ActiveRecord::Base
 end
 
 User.active.inactive
-# => SELECT "users".* FROM "users" WHERE "users"."state" = 'active' AND "users"."state" = 'inactive'
+# SELECT "users".* FROM "users" WHERE "users"."state" = 'active' AND "users"."state" = 'inactive'
 ```
 
 We can mix and match `scope` and `where` conditions and the final sql
-will have all conditions joined with `AND` .
+will have all conditions joined with `AND`.
 
 ```ruby
 User.active.where(state: 'finished')
-# => SELECT "users".* FROM "users" WHERE "users"."state" = 'active' AND "users"."state" = 'finished'
+# SELECT "users".* FROM "users" WHERE "users"."state" = 'active' AND "users"."state" = 'finished'
 ```
 
 If we do want the `last where clause` to win then `Relation#merge` can
-be used .
+be used.
 
 ```ruby
 User.active.merge(User.inactive)
-# => SELECT "users".* FROM "users" WHERE "users"."state" = 'inactive'
+# SELECT "users".* FROM "users" WHERE "users"."state" = 'inactive'
 ```
 
-One important caveat is that `default_scope` will be overridden by
+One important caveat is that `default_scope` will be prepended in
 `scope` and `where` conditions.
 
 ```ruby
 class User < ActiveRecord::Base
-  default_scope  { where state: 'pending' }
+  default_scope { where state: 'pending' }
   scope :active, -> { where state: 'active' }
   scope :inactive, -> { where state: 'inactive' }
 end
 
 User.all
-# => SELECT "users".* FROM "users" WHERE "users"."state" = 'pending'
+# SELECT "users".* FROM "users" WHERE "users"."state" = 'pending'
 
 User.active
-# => SELECT "users".* FROM "users" WHERE "users"."state" = 'active'
+# SELECT "users".* FROM "users" WHERE "users"."state" = 'pending' AND "users"."state" = 'active'
 
 User.where(state: 'inactive')
-# => SELECT "users".* FROM "users" WHERE "users"."state" = 'inactive'
+# SELECT "users".* FROM "users" WHERE "users"."state" = 'pending' AND "users"."state" = 'inactive'
 ```
 
-As you can see above the `default_scope` is being overridden by both
+As you can see above the `default_scope` is being merged in both
 `scope` and `where` conditions.
 
 
@@ -1354,7 +1392,7 @@ COMMIT
 
 The new record might not be saved to the database; that depends on whether validations passed or not (just like `create`).
 
-Suppose we want to set the 'locked' attribute to true if we're
+Suppose we want to set the 'locked' attribute to `false` if we're
 creating a new record, but we don't want to include it in the query. So
 we want to find the client named "Andy", or if that client doesn't
 exist, create a client named "Andy" which is not locked.
@@ -1431,7 +1469,7 @@ If you'd like to use your own SQL to find records in a table you can use `find_b
 ```ruby
 Client.find_by_sql("SELECT * FROM clients
   INNER JOIN orders ON clients.id = orders.client_id
-  ORDER clients.created_at desc")
+  ORDER BY clients.created_at desc")
 ```
 
 `find_by_sql` provides you with a simple way of making custom calls to the database and retrieving instantiated objects.
@@ -1532,18 +1570,21 @@ Person.ids
 Existence of Objects
 --------------------
 
-If you simply want to check for the existence of the object there's a method called `exists?`. This method will query the database using the same query as `find`, but instead of returning an object or collection of objects it will return either `true` or `false`.
+If you simply want to check for the existence of the object there's a method called `exists?`.
+This method will query the database using the same query as `find`, but instead of returning an
+object or collection of objects it will return either `true` or `false`.
 
 ```ruby
 Client.exists?(1)
 ```
 
-The `exists?` method also takes multiple ids, but the catch is that it will return true if any one of those records exists.
+The `exists?` method also takes multiple values, but the catch is that it will return `true` if any
+one of those records exists.
 
 ```ruby
-Client.exists?(1,2,3)
+Client.exists?(id: [1,2,3])
 # or
-Client.exists?([1,2,3])
+Client.exists?(name: ['John', 'Sergei'])
 ```
 
 It's even possible to use `exists?` without any arguments on a model or a relation.
@@ -1552,7 +1593,8 @@ It's even possible to use `exists?` without any arguments on a model or a relati
 Client.where(first_name: 'Ryan').exists?
 ```
 
-The above returns `true` if there is at least one client with the `first_name` 'Ryan' and `false` otherwise.
+The above returns `true` if there is at least one client with the `first_name` 'Ryan' and `false`
+otherwise.
 
 ```ruby
 Client.exists?
@@ -1602,7 +1644,7 @@ Client.where(first_name: 'Ryan').count
 You can also use various finder methods on a relation for performing complex calculations:
 
 ```ruby
-Client.includes("orders").where(first_name: 'Ryan', orders: {status: 'received'}).count
+Client.includes("orders").where(first_name: 'Ryan', orders: { status: 'received' }).count
 ```
 
 Which will execute:

data/guides/source/active_record_validations.md

@@ -85,7 +85,7 @@ end
 We can see how it works by looking at some `rails console` output:
 
 ```ruby
-$ rails console
+$ bin/rails console
 >> p = Person.new(name: "John Doe")
 => #<Person id: nil, name: "John Doe", created_at: nil, updated_at: nil>
 >> p.new_record?
@@ -162,8 +162,8 @@ Person.create(name: nil).valid? # => false
 ```
 
 After Active Record has performed validations, any errors found can be accessed
-through the `errors` instance method, which returns a collection of errors. By
-definition, an object is valid if this collection is empty after running
+through the `errors.messages` instance method, which returns a collection of errors.
+By definition, an object is valid if this collection is empty after running
 validations.
 
 Note that an object instantiated with `new` will not report errors even if it's
@@ -175,28 +175,28 @@ class Person < ActiveRecord::Base
 end
 
 >> p = Person.new
-#=> #<Person id: nil, name: nil>
->> p.errors
-#=> {}
+# => #<Person id: nil, name: nil>
+>> p.errors.messages
+# => {}
 
 >> p.valid?
-#=> false
->> p.errors
-#=> {name:["can't be blank"]}
+# => false
+>> p.errors.messages
+# => {name:["can't be blank"]}
 
 >> p = Person.create
-#=> #<Person id: nil, name: nil>
->> p.errors
-#=> {name:["can't be blank"]}
+# => #<Person id: nil, name: nil>
+>> p.errors.messages
+# => {name:["can't be blank"]}
 
 >> p.save
-#=> false
+# => false
 
 >> p.save!
-#=> ActiveRecord::RecordInvalid: Validation failed: Name can't be blank
+# => ActiveRecord::RecordInvalid: Validation failed: Name can't be blank
 
 >> Person.create!
-#=> ActiveRecord::RecordInvalid: Validation failed: Name can't be blank
+# => ActiveRecord::RecordInvalid: Validation failed: Name can't be blank
 ```
 
 `invalid?` is simply the inverse of `valid?`. It triggers your validations,
@@ -357,7 +357,7 @@ given regular expression, which is specified using the `:with` option.
 ```ruby
 class Product < ActiveRecord::Base
   validates :legacy_code, format: { with: /\A[a-zA-Z]+\z/,
-    message: "Only letters allowed" }
+    message: "only allows letters" }
 end
 ```
 
@@ -526,7 +526,7 @@ If you validate the presence of an object associated via a `has_one` or
 Since `false.blank?` is true, if you want to validate the presence of a boolean
 field you should use `validates :field_name, inclusion: { in: [true, false] }`.
 
-The default error message is _"can't be empty"_.
+The default error message is _"can't be blank"_.
 
 ### `absence`
 
@@ -575,7 +575,9 @@ This helper validates that the attribute's value is unique right before the
 object gets saved. It does not create a uniqueness constraint in the database,
 so it may happen that two different database connections create two records
 with the same value for a column that you intend to be unique. To avoid that,
-you must create a unique index in your database.
+you must create a unique index on both columns in your database. See
+[the MySQL manual](http://dev.mysql.com/doc/refman/5.6/en/multiple-column-indexes.html)
+for more details about multiple column indexes.
 
 ```ruby
 class Account < ActiveRecord::Base
@@ -682,7 +684,7 @@ class GoodnessValidator
     end
   end
 
-  # …
+  # ...
 end
 ```
 
@@ -734,8 +736,8 @@ class Topic < ActiveRecord::Base
   validates :title, length: { is: 5 }, allow_blank: true
 end
 
-Topic.create("title" => "").valid?  # => true
-Topic.create("title" => nil).valid? # => true
+Topic.create(title: "").valid?  # => true
+Topic.create(title: nil).valid? # => true
 ```
 
 ### `:message`
@@ -781,7 +783,7 @@ end
 Person.new.valid?  # => ActiveModel::StrictValidationFailed: Name can't be blank
 ```
 
-There is also an ability to pass custom exception to `:strict` option
+There is also an ability to pass custom exception to `:strict` option.
 
 ```ruby
 class Person < ActiveRecord::Base
@@ -990,12 +992,12 @@ end
 
 person = Person.new
 person.valid? # => false
-person.errors
+person.errors.messages
  # => {:name=>["can't be blank", "is too short (minimum is 3 characters)"]}
 
 person = Person.new(name: "John Doe")
 person.valid? # => true
-person.errors # => []
+person.errors.messages # => {}
 ```
 
 ### `errors[]`