Update Guides, Active Record Validations, better explanation of what methods bypass validations

1 files changed, 28 insertions, 2 deletions

diff --git a/railties/guides/source/activerecord_validations_callbacks.textile b/railties/guides/source/activerecord_validations_callbacks.textile
index 48acde7372..75c4cf69d5 100644
--- a/railties/guides/source/activerecord_validations_callbacks.textile
+++ b/railties/guides/source/activerecord_validations_callbacks.textile
@@ -49,9 +49,35 @@ We can see how it works by looking at some script/console output:
 => false
 </shell>
 
-Saving new records means sending an SQL +INSERT+ operation to the database, while saving existing records (by calling either +save+ or +update_attributes+) will result in a SQL +UPDATE+ operation. Active Record will use these facts to perform validations upon your objects, keeping them out of the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.
+Creating and saving a new record will send an SQL +INSERT+ operation to the database. Updating an existing record will send an SQL +UPDATE+ operation instead. Validations are run before these commands are sent to the database. If any validations fail, the object will be marked as invalid and Active Record will not trigger the +INSERT+ or +UPDATE+ operation. This helps to avoid storing an object in the database that's invalid. You can choose to have specific validations run when an object is created, saved, or updated.
 
-CAUTION: There are four methods that when called will trigger validation: +save+, +save!+, +update_attributes+ and +update_attributes!+. There is one update method for Active Record objects left, which is +update_attribute+. This method will update the value of an attribute _without_ triggering any validation. Be careful when using +update_attribute+, because it can let you save your objects in an invalid state.
+CAUTION: There are many ways to change the state of an object in the database. Some will trigger validations, and some will not. This means it is possible to save an object in the database that's in an invalid state. Be careful when using Active Record methods that bypass validations.
+
+The following methods trigger validations and generally save the object to the database:
+
+* "create":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002214 (creates an object, but does not save to the database)
+* "create!":http://api.rubyonrails.org/classes/ActiveRecord/Validations/ClassMethods.html#M002116
+* "save":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002274
+* "save!":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002275
+* "update":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002215
+* "update_attributes":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002281
+* "update_attributes!":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002282
+
+The following methods _do not_ trigger validations, but _do_ change the state of the object in the database. They should be used with caution:
+
+* "decrement!":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002286
+* "decrement_counter":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002224
+* "increment!":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002284
+* "increment_counter":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002223
+* "toggle":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002287
+* "toggle!":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002288
+* "update_all":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002218
+* "update_attribute":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002280
+* "update_counters":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002222
+
+Note that +save+ has the ability to bypass validations. This technique should be used with caution: 
+
+* "save(false)":http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M002274
 
 h4. Object#valid?