activerecord 4.1.16 → 4.2.0.beta1

data/README.rdoc

@@ -1,4 +1,4 @@
-= Active Record -- Object-relational mapping put on rails
+= Active Record -- Object-relational mapping in Rails
 
 Active Record connects classes to relational database tables to establish an
 almost zero-configuration persistence layer for applications. The library
@@ -20,8 +20,10 @@ A short rundown of some of the major features:
    class Product < ActiveRecord::Base
    end
 
-   The Product class is automatically mapped to the table named "products",
-   which might look like this:
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+The Product class is automatically mapped to the table named "products",
+which might look like this:
 
    CREATE TABLE products (
      id int(11) NOT NULL auto_increment,
@@ -29,10 +31,8 @@ A short rundown of some of the major features:
      PRIMARY KEY  (id)
    );
 
-   This would also define the following accessors: `Product#name` and
-   `Product#name=(new_name)`
-
-  {Learn more}[link:classes/ActiveRecord/Base.html]
+This would also define the following accessors: `Product#name` and
+`Product#name=(new_name)`.
 
 
 * Associations between objects defined by simple class methods.
@@ -130,7 +130,7 @@ A short rundown of some of the major features:
   SQLite3[link:classes/ActiveRecord/ConnectionAdapters/SQLite3Adapter.html].
 
 
-* Logging support for Log4r[http://log4r.rubyforge.org] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc].
+* Logging support for Log4r[https://github.com/colbygk/log4r] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc].
 
     ActiveRecord::Base.logger = ActiveSupport::Logger.new(STDOUT)
     ActiveRecord::Base.logger = Log4r::Logger.new('Application Log')
@@ -192,7 +192,7 @@ The latest version of Active Record can be installed with RubyGems:
 
 Source code can be downloaded as part of the Rails project on GitHub:
 
-* https://github.com/rails/rails/tree/4-1-stable/activerecord
+* https://github.com/rails/rails/tree/master/activerecord
 
 
 == License
@@ -208,6 +208,11 @@ API documentation is at:
 
 * http://api.rubyonrails.org
 
-Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
+Bug reports can be filed for the Ruby on Rails project here:
 
 * https://github.com/rails/rails/issues
+
+Feature requests should be discussed on the rails-core mailing list here:
+
+* https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core
+

data/lib/active_record.rb

@@ -27,10 +27,12 @@ require 'active_model'
 require 'arel'
 
 require 'active_record/version'
+require 'active_record/attribute_set'
 
 module ActiveRecord
   extend ActiveSupport::Autoload
 
+  autoload :Attribute
   autoload :Base
   autoload :Callbacks
   autoload :Core
@@ -50,7 +52,6 @@ module ActiveRecord
   autoload :QueryCache
   autoload :Querying
   autoload :ReadonlyAttributes
-  autoload :RecordInvalid, 'active_record/validations'
   autoload :Reflection
   autoload :RuntimeRegistry
   autoload :Sanitization

data/lib/active_record/aggregations.rb

@@ -129,10 +129,10 @@ module ActiveRecord
     # is an instance of the value class. Specifying a custom converter allows the new value to be automatically
     # converted to an instance of value class if necessary.
     #
-    # For example, the NetworkResource model has +network_address+ and +cidr_range+ attributes that
-    # should be aggregated using the NetAddr::CIDR value class (http://netaddr.rubyforge.org). The constructor
-    # for the value class is called +create+ and it expects a CIDR address string as a parameter. New
-    # values can be assigned to the value object using either another NetAddr::CIDR object, a string
+    # For example, the NetworkResource model has +network_address+ and +cidr_range+ attributes that should be
+    # aggregated using the NetAddr::CIDR value class (http://www.ruby-doc.org/gems/docs/n/netaddr-1.5.0/NetAddr/CIDR.html).
+    # The constructor for the value class is called +create+ and it expects a CIDR address string as a parameter.
+    # New values can be assigned to the value object using either another NetAddr::CIDR object, a string
     # or an array. The <tt>:constructor</tt> and <tt>:converter</tt> options can be used to meet
     # these requirements:
     #
@@ -230,8 +230,8 @@ module ActiveRecord
       private
         def reader_method(name, class_name, mapping, allow_nil, constructor)
           define_method(name) do
-            if @aggregation_cache[name].nil? && (!allow_nil || mapping.any? {|pair| !read_attribute(pair.first).nil? })
-              attrs = mapping.collect {|pair| read_attribute(pair.first)}
+            if @aggregation_cache[name].nil? && (!allow_nil || mapping.any? {|key, _| !read_attribute(key).nil? })
+              attrs = mapping.collect {|key, _| read_attribute(key)}
               object = constructor.respond_to?(:call) ?
                 constructor.call(*attrs) :
                 class_name.constantize.send(constructor, *attrs)
@@ -244,15 +244,19 @@ module ActiveRecord
         def writer_method(name, class_name, mapping, allow_nil, converter)
           define_method("#{name}=") do |part|
             klass = class_name.constantize
+            if part.is_a?(Hash)
+              part = klass.new(*part.values)
+            end
+
             unless part.is_a?(klass) || converter.nil? || part.nil?
               part = converter.respond_to?(:call) ? converter.call(part) : klass.send(converter, part)
             end
 
             if part.nil? && allow_nil
-              mapping.each { |pair| self[pair.first] = nil }
+              mapping.each { |key, _| self[key] = nil }
               @aggregation_cache[name] = nil
             else
-              mapping.each { |pair| self[pair.first] = part.send(pair.last) }
+              mapping.each { |key, value| self[key] = part.send(value) }
               @aggregation_cache[name] = part.freeze
             end
           end

data/lib/active_record/associations.rb

@@ -202,12 +202,13 @@ module ActiveRecord
     # For instance, +attributes+ and +connection+ would be bad choices for association names.
     #
     # == Auto-generated methods
+    # See also Instance Public methods below for more details.
     #
     # === Singular associations (one-to-one)
     #                                     |            |  belongs_to  |
     #   generated methods                 | belongs_to | :polymorphic | has_one
     #   ----------------------------------+------------+--------------+---------
-    #   other                             |     X      |      X       |    X
+    #   other(force_reload=false)         |     X      |      X       |    X
     #   other=(other)                     |     X      |      X       |    X
     #   build_other(attributes={})        |     X      |              |    X
     #   create_other(attributes={})       |     X      |              |    X
@@ -217,7 +218,7 @@ module ActiveRecord
     #                                     |       |          | has_many
     #   generated methods                 | habtm | has_many | :through
     #   ----------------------------------+-------+----------+----------
-    #   others                            |   X   |    X     |    X
+    #   others(force_reload=false)        |   X   |    X     |    X
     #   others=(other,other,...)          |   X   |    X     |    X
     #   other_ids                         |   X   |    X     |    X
     #   other_ids=(id,id,...)             |   X   |    X     |    X
@@ -419,6 +420,10 @@ module ActiveRecord
     #     has_many :birthday_events, ->(user) { where starts_on: user.birthday }, class_name: 'Event'
     #   end
     #
+    # Note: Joining, eager loading and preloading of these associations is not fully possible.
+    # These operations happen before instance creation and the scope will be called with a +nil+ argument.
+    # This can lead to unexpected behavior and is deprecated.
+    #
     # == Association callbacks
     #
     # Similar to the normal callbacks that hook into the life cycle of an Active Record object,
@@ -536,8 +541,8 @@ module ActiveRecord
     #   end
     #
     #   @firm = Firm.first
-    #   @firm.clients.collect { |c| c.invoices }.flatten # select all invoices for all clients of the firm
-    #   @firm.invoices                                   # selects all invoices by going through the Client join model
+    #   @firm.clients.flat_map { |c| c.invoices } # select all invoices for all clients of the firm
+    #   @firm.invoices                            # selects all invoices by going through the Client join model
     #
     # Similarly you can go through a +has_one+ association on the join model:
     #
@@ -712,9 +717,9 @@ module ActiveRecord
     # == Eager loading of associations
     #
     # Eager loading is a way to find objects of a certain class and a number of named associations.
-    # This is one of the easiest ways of to prevent the dreaded 1+N problem in which fetching 100
+    # This is one of the easiest ways of to prevent the dreaded N+1 problem in which fetching 100
     # posts that each need to display their author triggers 101 database queries. Through the
-    # use of eager loading, the 101 queries can be reduced to 2.
+    # use of eager loading, the number of queries will be reduced from 101 to 2.
     #
     #   class Post < ActiveRecord::Base
     #     belongs_to :author
@@ -774,16 +779,15 @@ module ActiveRecord
     # In the above example posts with no approved comments are not returned at all, because
     # the conditions apply to the SQL statement as a whole and not just to the association.
     #
+    # You must disambiguate column references for this fallback to happen, for example
+    # <tt>order: "author.name DESC"</tt> will work but <tt>order: "name DESC"</tt> will not.
+    #
     # If you want to load all posts (including posts with no approved comments) then write
     # your own LEFT OUTER JOIN query using ON
     #
-    #   Post.joins('LEFT OUTER JOIN comments ON comments.post_id = posts.id AND comments.approved = true')
+    #   Post.joins("LEFT OUTER JOIN comments ON comments.post_id = posts.id AND comments.approved = '1'")
     #
-    # You must disambiguate column references for this fallback to happen, for example
-    # <tt>order: "author.name DESC"</tt> will work but <tt>order: "name DESC"</tt> will not.
-    #
-    # If you do want eager load only some members of an association it is usually more natural
-    # to include an association which has conditions defined on it:
+    # In this case it is usually more natural to include an association which has conditions defined on it:
     #
     #   class Post < ActiveRecord::Base
     #     has_many :approved_comments, -> { where approved: true }, class_name: 'Comment'
@@ -1048,6 +1052,9 @@ module ActiveRecord
       # Specifies a one-to-many association. The following methods for retrieval and query of
       # collections of associated objects will be added:
       #
+      # +collection+ is a placeholder for the symbol passed as the +name+ argument, so
+      # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.
+      #
       # [collection(force_reload = false)]
       #   Returns an array of all the associated objects.
       #   An empty array is returned if none are found.
@@ -1106,9 +1113,6 @@ module ActiveRecord
       #   Does the same as <tt>collection.create</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
       #   if the record is invalid.
       #
-      # (*Note*: +collection+ is replaced with the symbol passed as the first argument, so
-      # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.)
-      #
       # === Example
       #
       # A <tt>Firm</tt> class declares <tt>has_many :clients</tt>, which will add:
@@ -1127,7 +1131,7 @@ module ActiveRecord
       # * <tt>Firm#clients.build</tt> (similar to <tt>Client.new("firm_id" => id)</tt>)
       # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save; c</tt>)
       # * <tt>Firm#clients.create!</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save!</tt>)
-      # The declaration can also include an options hash to specialize the behavior of the association.
+      # The declaration can also include an +options+ hash to specialize the behavior of the association.
       #
       # === Options
       # [:class_name]
@@ -1205,7 +1209,7 @@ module ActiveRecord
       # Option examples:
       #   has_many :comments, -> { order "posted_on" }
       #   has_many :comments, -> { includes :author }
-      #   has_many :people, -> { where("deleted = 0").order("name") }, class_name: "Person"
+      #   has_many :people, -> { where(deleted: false).order("name") }, class_name: "Person"
       #   has_many :tracks, -> { order "position" }, dependent: :destroy
       #   has_many :comments, dependent: :nullify
       #   has_many :tags, as: :taggable
@@ -1223,6 +1227,9 @@ module ActiveRecord
       #
       # The following methods for retrieval and query of a single associated object will be added:
       #
+      # +association+ is a placeholder for the symbol passed as the +name+ argument, so
+      # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>.
+      #
       # [association(force_reload = false)]
       #   Returns the associated object. +nil+ is returned if none is found.
       # [association=(associate)]
@@ -1241,9 +1248,6 @@ module ActiveRecord
       #   Does the same as <tt>create_association</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
       #   if the record is invalid.
       #
-      # (+association+ is replaced with the symbol passed as the first argument, so
-      # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>.)
-      #
       # === Example
       #
       # An Account class declares <tt>has_one :beneficiary</tt>, which will add:
@@ -1255,7 +1259,7 @@ module ActiveRecord
       #
       # === Options
       #
-      # The declaration can also include an options hash to specialize the behavior of the association.
+      # The declaration can also include an +options+ hash to specialize the behavior of the association.
       #
       # Options are:
       # [:class_name]
@@ -1305,6 +1309,10 @@ module ActiveRecord
       #   that is the inverse of this <tt>has_one</tt> association. Does not work in combination
       #   with <tt>:through</tt> or <tt>:as</tt> options.
       #   See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
+      # [:required]
+      #   When set to +true+, the association will also have its presence validated.
+      #   This will validate the association itself, not the id. You can use
+      #   +:inverse_of+ to avoid an extra query during validation.
       #
       # Option examples:
       #   has_one :credit_card, dependent: :destroy  # destroys the associated credit card
@@ -1316,6 +1324,7 @@ module ActiveRecord
       #   has_one :boss, readonly: :true
       #   has_one :club, through: :membership
       #   has_one :primary_address, -> { where primary: true }, through: :addressables, source: :addressable
+      #   has_one :credit_card, required: true
       def has_one(name, scope = nil, options = {})
         reflection = Builder::HasOne.build(self, name, scope, options)
         Reflection.add_reflection self, name, reflection
@@ -1329,6 +1338,9 @@ module ActiveRecord
       # Methods will be added for retrieval and query for a single associated object, for which
       # this object holds an id:
       #
+      # +association+ is a placeholder for the symbol passed as the +name+ argument, so
+      # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>.
+      #
       # [association(force_reload = false)]
       #   Returns the associated object. +nil+ is returned if none is found.
       # [association=(associate)]
@@ -1344,9 +1356,6 @@ module ActiveRecord
       #   Does the same as <tt>create_association</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
       #   if the record is invalid.
       #
-      # (+association+ is replaced with the symbol passed as the first argument, so
-      # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>.)
-      #
       # === Example
       #
       # A Post class declares <tt>belongs_to :author</tt>, which will add:
@@ -1355,7 +1364,18 @@ module ActiveRecord
       # * <tt>Post#build_author</tt> (similar to <tt>post.author = Author.new</tt>)
       # * <tt>Post#create_author</tt> (similar to <tt>post.author = Author.new; post.author.save; post.author</tt>)
       # * <tt>Post#create_author!</tt> (similar to <tt>post.author = Author.new; post.author.save!; post.author</tt>)
-      # The declaration can also include an options hash to specialize the behavior of the association.
+      # The declaration can also include an +options+ hash to specialize the behavior of the association.
+      #
+      # === Scopes
+      #
+      # You can pass a second argument +scope+ as a callable (i.e. proc or
+      # lambda) to retrieve a specific record or customize the generated query
+      # when you access the associated object.
+      #
+      # Scope examples:
+      #   belongs_to :user, -> { where(id: 2) }
+      #   belongs_to :user, -> { joins(:friends) }
+      #   belongs_to :level, ->(level) { where("game_level > ?", level.current) }
       #
       # === Options
       #
@@ -1409,7 +1429,7 @@ module ActiveRecord
       #
       #   Note that <tt>accepts_nested_attributes_for</tt> sets <tt>:autosave</tt> to <tt>true</tt>.
       # [:touch]
-      #   If true, the associated object will be touched (the updated_at/on attributes set to now)
+      #   If true, the associated object will be touched (the updated_at/on attributes set to current time)
       #   when this record is either saved or destroyed. If you specify a symbol, that attribute
       #   will be updated with the current time in addition to the updated_at/on attribute.
       # [:inverse_of]
@@ -1417,6 +1437,10 @@ module ActiveRecord
       #   object that is the inverse of this <tt>belongs_to</tt> association. Does not work in
       #   combination with the <tt>:polymorphic</tt> options.
       #   See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
+      # [:required]
+      #   When set to +true+, the association will also have its presence validated.
+      #   This will validate the association itself, not the id. You can use
+      #   +:inverse_of+ to avoid an extra query during validation.
       #
       # Option examples:
       #   belongs_to :firm, foreign_key: "client_of"
@@ -1429,6 +1453,7 @@ module ActiveRecord
       #   belongs_to :post, counter_cache: true
       #   belongs_to :company, touch: true
       #   belongs_to :company, touch: :employees_last_updated_at
+      #   belongs_to :company, required: true
       def belongs_to(name, scope = nil, options = {})
         reflection = Builder::BelongsTo.build(self, name, scope, options)
         Reflection.add_reflection self, name, reflection
@@ -1466,6 +1491,9 @@ module ActiveRecord
       #
       # Adds the following methods for retrieval and query:
       #
+      # +collection+ is a placeholder for the symbol passed as the +name+ argument, so
+      # <tt>has_and_belongs_to_many :categories</tt> would add among others <tt>categories.empty?</tt>.
+      #
       # [collection(force_reload = false)]
       #   Returns an array of all the associated objects.
       #   An empty array is returned if none are found.
@@ -1507,9 +1535,6 @@ module ActiveRecord
       #   with +attributes+, linked to this object through the join table, and that has already been
       #   saved (if it passed the validation).
       #
-      # (+collection+ is replaced with the symbol passed as the first argument, so
-      # <tt>has_and_belongs_to_many :categories</tt> would add among others <tt>categories.empty?</tt>.)
-      #
       # === Example
       #
       # A Developer class declares <tt>has_and_belongs_to_many :projects</tt>, which will add:
@@ -1527,7 +1552,7 @@ module ActiveRecord
       # * <tt>Developer#projects.exists?(...)</tt>
       # * <tt>Developer#projects.build</tt> (similar to <tt>Project.new("developer_id" => id)</tt>)
       # * <tt>Developer#projects.create</tt> (similar to <tt>c = Project.new("developer_id" => id); c.save; c</tt>)
-      # The declaration may include an options hash to specialize the behavior of the association.
+      # The declaration may include an +options+ hash to specialize the behavior of the association.
       #
       # === Options
       #
@@ -1573,7 +1598,7 @@ module ActiveRecord
           scope   = nil
         end
 
-        habtm_reflection = ActiveRecord::Reflection::AssociationReflection.new(:has_and_belongs_to_many, name, scope, options, self)
+        habtm_reflection = ActiveRecord::Reflection::HasAndBelongsToManyReflection.new(name, scope, options, self)
 
         builder = Builder::HasAndBelongsToMany.new name, self, options
 
@@ -1588,7 +1613,7 @@ module ActiveRecord
 
         Builder::HasMany.define_callbacks self, middle_reflection
         Reflection.add_reflection self, middle_reflection.name, middle_reflection
-        middle_reflection.parent_reflection = [name.to_sym, habtm_reflection]
+        middle_reflection.parent_reflection = [name.to_s, habtm_reflection]
 
         include Module.new {
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -1609,7 +1634,7 @@ module ActiveRecord
         end
 
         has_many name, scope, hm_options, &extension
-        self._reflections[name.to_sym].parent_reflection = [name.to_sym, habtm_reflection]
+        self._reflections[name.to_s].parent_reflection = [name.to_s, habtm_reflection]
       end
     end
   end

data/lib/active_record/associations/association.rb

@@ -179,7 +179,7 @@ module ActiveRecord
         def creation_attributes
           attributes = {}
 
-          if (reflection.macro == :has_one || reflection.macro == :has_many) && !options[:through]
+          if (reflection.has_one? || reflection.collection?) && !options[:through]
             attributes[reflection.foreign_key] = owner[reflection.active_record_primary_key]
 
             if reflection.options[:as]

data/lib/active_record/associations/association_scope.rb

@@ -1,12 +1,34 @@
 module ActiveRecord
   module Associations
     class AssociationScope #:nodoc:
-      INSTANCE = new
-
       def self.scope(association, connection)
         INSTANCE.scope association, connection
       end
 
+      class BindSubstitution
+        def initialize(block)
+          @block = block
+        end
+
+        def bind_value(scope, column, value, alias_tracker)
+          substitute = alias_tracker.connection.substitute_at(
+            column, scope.bind_values.length)
+          scope.bind_values += [[column, @block.call(value)]]
+          substitute
+        end
+      end
+
+      def self.create(&block)
+        block = block ? block : lambda { |val| val }
+        new BindSubstitution.new(block)
+      end
+
+      def initialize(bind_substitution)
+        @bind_substitution = bind_substitution
+      end
+
+      INSTANCE = create
+
       def scope(association, connection)
         klass         = association.klass
         reflection    = association.reflection
@@ -22,6 +44,23 @@ module ActiveRecord
         Arel::Nodes::InnerJoin
       end
 
+      def self.get_bind_values(owner, chain)
+        bvs = []
+        chain.each_with_index do |reflection, i|
+          if reflection == chain.last
+            bvs << reflection.join_id_for(owner)
+            if reflection.type
+              bvs << owner.class.base_class.name
+            end
+          else
+            if reflection.type
+              bvs << chain[i + 1].klass.base_class.name
+            end
+          end
+        end
+        bvs
+      end
+
       private
 
       def construct_tables(chain, klass, refl, alias_tracker)
@@ -49,10 +88,7 @@ module ActiveRecord
       end
 
       def bind_value(scope, column, value, alias_tracker)
-        substitute = alias_tracker.connection.substitute_at(
-          column, scope.bind_values.length)
-        scope.bind_values += [[column, value]]
-        substitute
+        @bind_substitution.bind_value scope, column, value, alias_tracker
       end
 
       def bind(scope, table_name, column_name, value, tracker)
@@ -69,18 +105,9 @@ module ActiveRecord
         chain.each_with_index do |reflection, i|
           table, foreign_table = tables.shift, tables.first
 
-          if reflection.source_macro == :belongs_to
-            if reflection.options[:polymorphic]
-              key = reflection.association_primary_key(assoc_klass)
-            else
-              key = reflection.association_primary_key
-            end
-
-            foreign_key = reflection.foreign_key
-          else
-            key         = reflection.foreign_key
-            foreign_key = reflection.active_record_primary_key
-          end
+          join_keys = reflection.join_keys(assoc_klass)
+          key = join_keys.key
+          foreign_key = join_keys.foreign_key
 
           if reflection == chain.last
             bind_val = bind scope, table.table_name, key.to_s, owner[foreign_key], tracker
@@ -88,7 +115,7 @@ module ActiveRecord
 
             if reflection.type
               value    = owner.class.base_class.name
-              bind_val = bind scope, table.table_name, reflection.type.to_s, value, tracker
+              bind_val = bind scope, table.table_name, reflection.type, value, tracker
               scope    = scope.where(table[reflection.type].eq(bind_val))
             end
           else
@@ -96,7 +123,7 @@ module ActiveRecord
 
             if reflection.type
               value    = chain[i + 1].klass.base_class.name
-              bind_val = bind scope, table.table_name, reflection.type.to_s, value, tracker
+              bind_val = bind scope, table.table_name, reflection.type, value, tracker
               scope    = scope.where(table[reflection.type].eq(bind_val))
             end
 
@@ -120,6 +147,7 @@ module ActiveRecord
             end
 
             scope.where_values += item.where_values
+            scope.bind_values  += item.bind_values
             scope.order_values |= item.order_values
           end
         end
@@ -143,7 +171,11 @@ module ActiveRecord
       end
 
       def eval_scope(klass, scope, owner)
-        klass.unscoped.instance_exec(owner, &scope)
+        if scope.is_a?(Relation)
+          scope
+        else
+          klass.unscoped.instance_exec(owner, &scope)
+        end
       end
     end
   end