diff options
Diffstat (limited to 'activerecord/lib/active_record')
6 files changed, 242 insertions, 32 deletions
diff --git a/activerecord/lib/active_record/association_preload.rb b/activerecord/lib/active_record/association_preload.rb index c60850fc77..cef8cd8647 100644 --- a/activerecord/lib/active_record/association_preload.rb +++ b/activerecord/lib/active_record/association_preload.rb @@ -1,14 +1,88 @@ module ActiveRecord + # See ActiveRecord::AssociationPreload::ClassMethods for documentation. module AssociationPreload #:nodoc: def self.included(base) base.extend(ClassMethods) end + # Implements the details of eager loading of ActiveRecord associations. + # Application developers should not use this module directly. + # + # ActiveRecord::Base is extended with this module. The source code in + # ActiveRecord::Base references methods defined in this module. + # + # Note that 'eager loading' and 'preloading' are actually the same thing. + # However, there are two different eager loading strategies. + # + # The first one is by using table joins. This was only strategy available + # prior to Rails 2.1. Suppose that you have an Author model with columns + # 'name' and 'age', and a Book model with columns 'name' and 'sales'. Using + # this strategy, ActiveRecord would try to retrieve all data for an author + # and all of its books via a single query: + # + # SELECT * FROM authors + # LEFT OUTER JOIN books ON authors.id = books.id + # WHERE authors.name = 'Ken Akamatsu' + # + # However, this could result in many rows that contain redundant data. After + # having received the first row, we already have enough data to instantiate + # the Author object. In all subsequent rows, only the data for the joined + # 'books' table is useful; the joined 'authors' data is just redundant, and + # processing this redundant data takes memory and CPU time. The problem + # quickly becomes worse and worse as the level of eager loading increases + # (i.e. if ActiveRecord is to eager load the associations' assocations as + # well). + # + # The second strategy is to use multiple database queries, one for each + # level of association. Since Rails 2.1, this is the default strategy. In + # situations where a table join is necessary (e.g. when the +:conditions+ + # option references an association's column), it will fallback to the table + # join strategy. + # + # See also ActiveRecord::Associations::ClassMethods, which explains eager + # loading in a more high-level (application developer-friendly) manner. module ClassMethods - - # Loads the named associations for the activerecord record (or records) given - # preload_options is passed only one level deep: don't pass to the child associations when associations is a Hash protected + + # Eager loads the named associations for the given ActiveRecord record(s). + # + # In this description, 'association name' shall refer to the name passed + # to an association creation method. For example, a model that specifies + # <tt>belongs_to :author</tt>, <tt>has_many :buyers</tt> has association + # names +:author+ and +:buyers+. + # + # == Parameters + # +records+ is an array of ActiveRecord::Base. This array needs not be flat, + # i.e. +records+ itself may also contain arrays of records. In any case, + # +preload_associations+ will preload the associations all records by + # flattening +records+. + # + # +associations+ specifies one or more associations that you want to + # preload. It may be: + # - a Symbol or a String which specifies a single association name. For + # example, specifiying +:books+ allows this method to preload all books + # for an Author. + # - an Array which specifies multiple association names. This array + # is processed recursively. For example, specifying <tt>[:avatar, :books]</tt> + # allows this method to preload an author's avatar as well as all of his + # books. + # - a Hash which specifies multiple association names, as well as + # association names for the to-be-preloaded association objects. For + # example, specifying <tt>{ :author => :avatar }</tt> will preload a + # book's author, as well as that author's avatar. + # + # +:associations+ has the same format as the +:include+ option for + # <tt>ActiveRecord::Base.find</tt>. So +associations+ could look like this: + # + # :books + # [ :books, :author ] + # { :author => :avatar } + # [ :books, { :author => :avatar } ] + # + # +preload_options+ contains options that will be passed to ActiveRecord#find + # (which is called under the hood for preloading records). But it is passed + # only one level deep in the +associations+ argument, i.e. it's not passed + # to the child associations when +associations+ is a Hash. def preload_associations(records, associations, preload_options={}) records = [records].flatten.compact.uniq return if records.empty? @@ -30,6 +104,8 @@ module ActiveRecord private + # Preloads a specific named association for the given records. This is + # called by +preload_associations+ as its base case. def preload_one_association(records, association, preload_options={}) class_to_reflection = {} # Not all records have the same class, so group then preload @@ -37,6 +113,10 @@ module ActiveRecord # unnecessarily records.group_by {|record| class_to_reflection[record.class] ||= record.class.reflections[association]}.each do |reflection, records| raise ConfigurationError, "Association named '#{ association }' was not found; perhaps you misspelled it?" unless reflection + + # 'reflection.macro' can return 'belongs_to', 'has_many', etc. Thus, + # the following could call 'preload_belongs_to_association', + # 'preload_has_many_association', etc. send("preload_#{reflection.macro}_association", records, reflection, preload_options) end end @@ -77,6 +157,10 @@ module ActiveRecord end end + # Given a collection of ActiveRecord objects, constructs a Hash which maps + # the objects' IDs to the relevant objects. Returns a 2-tuple + # <tt>(id_to_record_map, ids)</tt> where +id_to_record_map+ is the Hash, + # and +ids+ is an Array of record IDs. def construct_id_map(records) id_to_record_map = {} ids = [] diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 5d91315aad..33457822ff 100755 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -1452,6 +1452,8 @@ module ActiveRecord end end + # Creates before_destroy callback methods that nullify, delete or destroy + # has_one associated objects, according to the defined :dependent rule. def configure_dependency_for_has_one(reflection) if reflection.options.include?(:dependent) case reflection.options[:dependent] @@ -1465,6 +1467,10 @@ module ActiveRecord when :delete method_name = "has_one_dependent_delete_for_#{reflection.name}".to_sym define_method(method_name) do + # Retrieve the associated object and delete it. The retrieval + # is necessary because there may be multiple associated objects + # with foreign keys pointing to this object, and we only want + # to delete the correct one, not all of them. association = send(reflection.name) association.class.delete(association.id) unless association.nil? end diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 556f9f115b..c0c9b8a9b3 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -512,7 +512,7 @@ module ActiveRecord #:nodoc: # # All approaches accept an options hash as their last parameter. # - # ==== Attributes + # ==== Parameters # # * <tt>:conditions</tt> - An SQL fragment like "administrator = 1" or <tt>[ "user_name = ?", username ]</tt>. See conditions in the intro. # * <tt>:order</tt> - An SQL fragment like "created_at DESC, name". @@ -697,7 +697,7 @@ module ActiveRecord #:nodoc: # Updates an object (or multiple objects) and saves it to the database, if validations pass. # The resulting object is returned whether the object was saved successfully to the database or not. # - # ==== Attributes + # ==== Parameters # # * +id+ - This should be the id or an array of ids to be updated. # * +attributes+ - This should be a Hash of attributes to be set on the object, or an array of Hashes. @@ -725,9 +725,10 @@ module ActiveRecord #:nodoc: # is executed on the database which means that no callbacks are fired off running this. This is an efficient method # of deleting records that don't need cleaning up after or other actions to be taken. # - # Objects are _not_ instantiated with this method. + # Objects are _not_ instantiated with this method, and so +:dependent+ rules + # defined on associations are not honered. # - # ==== Attributes + # ==== Parameters # # * +id+ - Can be either an Integer or an Array of Integers. # @@ -750,7 +751,7 @@ module ActiveRecord #:nodoc: # This essentially finds the object (or multiple objects) with the given id, creates a new object # from the attributes, and then calls destroy on it. # - # ==== Attributes + # ==== Parameters # # * +id+ - Can be either an Integer or an Array of Integers. # @@ -774,7 +775,7 @@ module ActiveRecord #:nodoc: # also be supplied. This method constructs a single SQL UPDATE statement and sends it straight to the # database. It does not instantiate the involved models and it does not trigger Active Record callbacks. # - # ==== Attributes + # ==== Parameters # # * +updates+ - A string of column and value pairs that will be set on any records that match conditions. # What goes into the SET clause. @@ -820,34 +821,39 @@ module ActiveRecord #:nodoc: # many records. If you want to simply delete records without worrying about dependent associations or # callbacks, use the much faster +delete_all+ method instead. # - # ==== Attributes + # ==== Parameters # # * +conditions+ - Conditions are specified the same way as with +find+ method. # # ==== Example # - # Person.destroy_all "last_login < '2004-04-04'" + # Person.destroy_all("last_login < '2004-04-04'") # # This loads and destroys each person one by one, including its dependent associations and before_ and # after_destroy callbacks. + # + # +conditions+ can be anything that +find+ also accepts: + # + # Person.destroy_all(:last_login => 6.hours.ago) def destroy_all(conditions = nil) find(:all, :conditions => conditions).each { |object| object.destroy } end # Deletes the records matching +conditions+ without instantiating the records first, and hence not # calling the +destroy+ method nor invoking callbacks. This is a single SQL DELETE statement that - # goes straight to the database, much more efficient than +destroy_all+. Careful with relations - # though, in particular <tt>:dependent</tt> is not taken into account. + # goes straight to the database, much more efficient than +destroy_all+. Be careful with relations + # though, in particular <tt>:dependent</tt> rules defined on associations are not honored. # - # ==== Attributes + # ==== Parameters # # * +conditions+ - Conditions are specified the same way as with +find+ method. # # ==== Example # - # Post.delete_all "person_id = 5 AND (category = 'Something' OR category = 'Else')" + # Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')") + # Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else']) # - # This deletes the affected posts all at once with a single DELETE statement. If you need to destroy dependent + # Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent # associations or call your <tt>before_*</tt> or +after_destroy+ callbacks, use the +destroy_all+ method instead. def delete_all(conditions = nil) sql = "DELETE FROM #{quoted_table_name} " @@ -859,7 +865,7 @@ module ActiveRecord #:nodoc: # The use of this method should be restricted to complicated SQL queries that can't be executed # using the ActiveRecord::Calculations class methods. Look into those before using this. # - # ==== Attributes + # ==== Parameters # # * +sql+ - An SQL statement which should return a count query from the database, see the example below. # @@ -877,7 +883,7 @@ module ActiveRecord #:nodoc: # with the given ID, altering the given hash of counters by the amount # given by the corresponding value: # - # ==== Attributes + # ==== Parameters # # * +id+ - The id of the object you wish to update a counter on. # * +counters+ - An Array of Hashes containing the names of the fields @@ -907,7 +913,7 @@ module ActiveRecord #:nodoc: # For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is # shown it would have to run an SQL query to find how many posts and comments there are. # - # ==== Attributes + # ==== Parameters # # * +counter_name+ - The name of the field that should be incremented. # * +id+ - The id of the object that should be incremented. @@ -924,7 +930,7 @@ module ActiveRecord #:nodoc: # # This works the same as increment_counter but reduces the column value by 1 instead of increasing it. # - # ==== Attributes + # ==== Parameters # # * +counter_name+ - The name of the field that should be decremented. # * +id+ - The id of the object that should be decremented. @@ -1019,7 +1025,7 @@ module ActiveRecord #:nodoc: # The serialization is done through YAML. If +class_name+ is specified, the serialized object must be of that # class on retrieval or SerializationTypeMismatch will be raised. # - # ==== Attributes + # ==== Parameters # # * +attr_name+ - The field name that should be serialized. # * +class_name+ - Optional, class name that the object type should be equal to. @@ -1927,6 +1933,9 @@ module ActiveRecord #:nodoc: # end # end # end + # + # *Note*: the +:find+ scope also has effect on update and deletion methods, + # like +update_all+ and +delete_all+. def with_scope(method_scoping = {}, action = :merge, &block) method_scoping = method_scoping.method_scoping if method_scoping.respond_to?(:method_scoping) @@ -2274,7 +2283,28 @@ module ActiveRecord #:nodoc: end - # Enables Active Record objects to be used as URL parameters in Action Pack automatically. + # Returns a String, which Action Pack uses for constructing an URL to this + # object. The default implementation returns this record's id as a String, + # or nil if this record's unsaved. + # + # For example, suppose that you have a Users model, and that you have a + # <tt>map.resources :users</tt> route. Normally, +users_path+ will + # construct an URI with the user object's 'id' in it: + # + # user = User.find_by_name('Phusion') + # user_path(path) # => "/users/1" + # + # You can override +to_param+ in your model to make +users_path+ construct + # an URI using the user's name instead of the user's id: + # + # class User < ActiveRecord::Base + # def to_param # overridden + # name + # end + # end + # + # user = User.find_by_name('Phusion') + # user_path(path) # => "/users/Phusion" def to_param # We can't use alias_method here, because method 'id' optimizes itself on the fly. (id = self.id) ? id.to_s : nil # Be sure to stringify the id for routes @@ -2356,6 +2386,9 @@ module ActiveRecord #:nodoc: # Deletes the record in the database and freezes this instance to reflect that no changes should # be made (since they can't be persisted). + # + # In addition to deleting this record, any defined +before_delete+ and +after_delete+ + # callbacks are run, and +:dependent+ rules defined on associations are run. def destroy unless new_record? connection.delete <<-end_sql, "#{self.class.name} Destroy" @@ -2493,10 +2526,25 @@ module ActiveRecord #:nodoc: end # Allows you to set all the attributes at once by passing in a hash with keys - # matching the attribute names (which again matches the column names). Sensitive attributes can be protected - # from this form of mass-assignment by using the +attr_protected+ macro. Or you can alternatively - # specify which attributes *can* be accessed with the +attr_accessible+ macro. Then all the + # matching the attribute names (which again matches the column names). + # + # If +guard_protected_attributes+ is true (the default), then sensitive + # attributes can be protected from this form of mass-assignment by using + # the +attr_protected+ macro. Or you can alternatively specify which + # attributes *can* be accessed with the +attr_accessible+ macro. Then all the # attributes not included in that won't be allowed to be mass-assigned. + # + # class User < ActiveRecord::Base + # attr_protected :is_admin + # end + # + # user = User.new + # user.attributes = { :username => 'Phusion', :is_admin => true } + # user.username # => "Phusion" + # user.is_admin? # => false + # + # user.send(:attributes=, { :username => 'Phusion', :is_admin => true }, false) + # user.is_admin? # => true def attributes=(new_attributes, guard_protected_attributes = true) return if new_attributes.nil? attributes = new_attributes.dup diff --git a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb index 8fc89de22b..10dc1a81f3 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb @@ -98,8 +98,14 @@ module ActiveRecord add_limit_offset!(sql, options) if options end - # Appends +LIMIT+ and +OFFSET+ options to an SQL statement. + # Appends +LIMIT+ and +OFFSET+ options to an SQL statement, or some SQL + # fragment that has the same semantics as LIMIT and OFFSET. + # + # +options+ must be a Hash which contains a +:limit+ option (required) + # and an +:offset+ option (optional). + # # This method *modifies* the +sql+ parameter. + # # ===== Examples # add_limit_offset!('SELECT * FROM suppliers', {:limit => 10, :offset => 50}) # generates diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb index bececf82a0..c29c1562b4 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -31,19 +31,25 @@ module ActiveRecord # See the concrete implementation for details on the expected parameter values. def columns(table_name, name = nil) end - # Creates a new table + # Creates a new table with the name +table_name+. +table_name+ may either + # be a String or a Symbol. + # # There are two ways to work with +create_table+. You can use the block # form or the regular form, like this: # # === Block form - # # create_table() yields a TableDefinition instance + # # create_table() passes a TableDefinition object to the block. + # # This form will not only create the table, but also columns for the + # # table. # create_table(:suppliers) do |t| # t.column :name, :string, :limit => 60 # # Other fields here # end # # === Regular form + # # Creates a table called 'suppliers' with no columns. # create_table(:suppliers) + # # Add a column to 'suppliers'. # add_column(:suppliers, :name, :string, {:limit => 60}) # # The +options+ hash can include the following keys: diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb index 518b59e433..73d9b36fc2 100644 --- a/activerecord/lib/active_record/validations.rb +++ b/activerecord/lib/active_record/validations.rb @@ -625,10 +625,6 @@ module ActiveRecord # When the record is created, a check is performed to make sure that no record exists in the database with the given value for the specified # attribute (that maps to a column). When the record is updated, the same check is made but disregarding the record itself. # - # Because this check is performed outside the database there is still a chance that duplicate values - # will be inserted in two parallel transactions. To guarantee against this you should create a - # unique index on the field. See +add_index+ for more information. - # # Configuration options: # * <tt>:message</tt> - Specifies a custom error message (default is: "has already been taken"). # * <tt>:scope</tt> - One or more columns by which to limit the scope of the uniqueness constraint. @@ -641,6 +637,70 @@ module ActiveRecord # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should # not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The # method, proc or string should return or evaluate to a true or false value. + # + # === Concurrency and integrity + # + # Using this validation method in conjunction with ActiveRecord::Base#save + # does not guarantee the absence of duplicate record insertions, because + # uniqueness checks on the application level are inherently prone to racing + # conditions. For example, suppose that two users try to post a Comment at + # the same time, and a Comment's title must be unique. At the database-level, + # the actions performed by these users could be interleaved in the following manner: + # + # User 1 | User 2 + # ------------------------------------+-------------------------------------- + # # User 1 checks whether there's | + # # already a comment with the title | + # # 'My Post'. This is not the case. | + # SELECT * FROM comments | + # WHERE title = 'My Post' | + # | + # | # User 2 does the same thing and also + # | # infers that his title is unique. + # | SELECT * FROM comments + # | WHERE title = 'My Post' + # | + # # User 1 inserts his comment. | + # INSERT INTO comments | + # (title, content) VALUES | + # ('My Post', 'hi!') | + # | + # | # User 2 does the same thing. + # | INSERT INTO comments + # | (title, content) VALUES + # | ('My Post', 'hello!') + # | + # | # ^^^^^^ + # | # Boom! We now have a duplicate + # | # title! + # + # This could even happen if you use transactions with the 'serializable' + # isolation level. There are several ways to get around this problem: + # - By locking the database table before validating, and unlocking it after + # saving. However, table locking is very expensive, and thus not + # recommended. + # - By locking a lock file before validating, and unlocking it after saving. + # This does not work if you've scaled your Rails application across + # multiple web servers (because they cannot share lock files, or cannot + # do that efficiently), and thus not recommended. + # - Creating a unique index on the field, by using + # ActiveRecord::ConnectionAdapters::SchemaStatements#add_index. In the + # rare case that a racing condition occurs, the database will guarantee + # the field's uniqueness. + # + # When the database catches such a duplicate insertion, + # ActiveRecord::Base#save will raise an ActiveRecord::StatementInvalid + # exception. You can either choose to let this error propagate (which + # will result in the default Rails exception page being shown), or you + # can catch it and restart the transaction (e.g. by telling the user + # that the title already exists, and asking him to re-enter the title). + # This technique is also known as optimistic concurrency control: + # http://en.wikipedia.org/wiki/Optimistic_concurrency_control + # + # Active Record currently provides no way to distinguish unique + # index constraint errors from other types of database errors, so you + # will have to parse the (database-specific) exception message to detect + # such a case. def validates_uniqueness_of(*attr_names) configuration = { :case_sensitive => true } configuration.update(attr_names.extract_options!) |