diff options
Diffstat (limited to 'activerecord/lib/active_record/base.rb')
| -rwxr-xr-x[-rw-r--r--] | activerecord/lib/active_record/base.rb | 61 |
1 files changed, 42 insertions, 19 deletions
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 2367277c03..3419aad580 100644..100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -500,7 +500,7 @@ module ActiveRecord #:nodoc: # * <tt>:include</tt> - Names associations that should be loaded alongside. The symbols named refer # to already defined associations. See eager loading under Associations. # * <tt>:select</tt> - By default, this is "*" as in "SELECT * FROM", but can be changed if you, for example, want to do a join but not - # include the joined columns. + # include the joined columns. Takes a string with the SELECT SQL fragment (e.g. "id, name"). # * <tt>:from</tt> - By default, this is the table name of the class, but can be changed to an alternate table name (or even the name # of a database view). # * <tt>:readonly</tt> - Mark the returned records read-only so they cannot be saved or updated. @@ -745,13 +745,15 @@ module ActiveRecord #:nodoc: end # Updates all records with details given if they match a set of conditions supplied, limits and order can - # also be supplied. + # 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 # - # * +updates+ - A String of column and value pairs that will be set on any records that match conditions. + # * +updates+ - A string of column and value pairs that will be set on any records that match conditions. + # What goes into the SET clause. # * +conditions+ - An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro for more info. - # * +options+ - Additional options are <tt>:limit</tt> and/or <tt>:order</tt>, see the examples for usage. + # * +options+ - Additional options are <tt>:limit</tt> and <tt>:order</tt>, see the examples for usage. # # ==== Examples # @@ -773,8 +775,8 @@ module ActiveRecord #:nodoc: connection.update(sql, "#{name} Update") end - # Destroys the records matching +conditions+ by instantiating each record and calling the destroy method. - # This means at least 2*N database queries to destroy N records, so avoid destroy_all if you are deleting + # Destroys the records matching +conditions+ by instantiating each record and calling their +destroy+ method. + # This means at least 2*N database queries to destroy N records, so avoid +destroy_all+ if you are deleting # many records. If you want to simply delete records without worrying about dependent associations or # callbacks, use the much faster +delete_all+ method instead. # @@ -793,8 +795,9 @@ module ActiveRecord #:nodoc: end # Deletes the records matching +conditions+ without instantiating the records first, and hence not - # calling the destroy method and invoking callbacks. This is a single SQL query, much more efficient - # than destroy_all. + # 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. # # ==== Attributes # @@ -804,8 +807,8 @@ module ActiveRecord #:nodoc: # # Post.delete_all "person_id = 5 AND (category = 'Something' OR category = 'Else')" # - # This deletes the affected posts all at once with a single DELETE query. If you need to destroy dependent - # associations or call your before_ or after_destroy callbacks, use the +destroy_all+ method instead. + # This deletes 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} " add_conditions!(sql, conditions, scope(:find)) @@ -2248,20 +2251,40 @@ module ActiveRecord #:nodoc: defined?(@new_record) && @new_record end - # * No record exists: Creates a new record with values matching those of the object attributes. - # * A record does exist: Updates the record with values matching those of the object attributes. + # :call-seq: + # save(perform_validation = true) # - # Note: If your model specifies any validations then the method declaration dynamically - # changes to: - # save(perform_validation=true) - # Calling save(false) saves the model without running validations. - # See ActiveRecord::Validations for more information. + # Saves the model. + # + # If the model is new a record gets created in the database, otherwise + # the existing record gets updated. + # + # If +perform_validation+ is true validations run. If any of them fail + # the action is cancelled and +save+ returns +false+. If the flag is + # false validations are bypassed altogether. See + # ActiveRecord::Validations for more information. + # + # There's a series of callbacks associated with +save+. If any of the + # <tt>before_*</tt> callbacks return +false+ the action is cancelled and + # +save+ returns +false+. See ActiveRecord::Callbacks for further + # details. def save create_or_update end - # Attempts to save the record, but instead of just returning false if it couldn't happen, it raises a - # RecordNotSaved exception + # Saves the model. + # + # If the model is new a record gets created in the database, otherwise + # the existing record gets updated. + # + # With <tt>save!</tt> validations always run. If any of them fail + # ActiveRecord::RecordInvalid gets raised. See ActiveRecord::Validations + # for more information. + # + # There's a series of callbacks associated with <tt>save!</tt>. If any of + # the <tt>before_*</tt> callbacks return +false+ the action is cancelled + # and <tt>save!</tt> raises ActiveRecord::RecordNotSaved. See + # ActiveRecord::Callbacks for further details. def save! create_or_update || raise(RecordNotSaved) end |