aboutsummaryrefslogtreecommitdiffstats
path: root/railties
diff options
context:
space:
mode:
authorBrian Durand <brian@embellishedvisions.com>2011-02-17 10:18:56 -0600
committerBrian Durand <brian@embellishedvisions.com>2011-02-17 10:18:56 -0600
commit017012b43ac80a79b99afbe35e1d9e7f73e62ee9 (patch)
tree46625a93de6e4241dad2d8838270ca021a2c7fb8 /railties
parentfead0fc44850480f2f431b8befb5cba284e5e633 (diff)
downloadrails-017012b43ac80a79b99afbe35e1d9e7f73e62ee9.tar.gz
rails-017012b43ac80a79b99afbe35e1d9e7f73e62ee9.tar.bz2
rails-017012b43ac80a79b99afbe35e1d9e7f73e62ee9.zip
Add description of transaction callbacks to ActiveRecord callbacks guide.
Diffstat (limited to 'railties')
-rw-r--r--railties/guides/source/active_record_validations_callbacks.textile35
1 files changed, 35 insertions, 0 deletions
diff --git a/railties/guides/source/active_record_validations_callbacks.textile b/railties/guides/source/active_record_validations_callbacks.textile
index 6f857ab9cc..ea8cf8afaf 100644
--- a/railties/guides/source/active_record_validations_callbacks.textile
+++ b/railties/guides/source/active_record_validations_callbacks.textile
@@ -1160,8 +1160,43 @@ In this example, the +after_create+ method would be called whenever a +Registrat
config.active_record.observers = :mailer_observer
</ruby>
+h3. Transaction Callbacks
+
+There are two additional callbacks that are triggered by the completion of a database transaction: +after_commit+ and +after_rollback+. These callbacks are very similar to the +after_save+ callback except that they don't execute until after database changes have either been committed or rolled back. They are most useful when your active record models need to interact with external systems which are not part of the database transaction.
+
+Consider, for example, the previous example where the +PictureFile+ model needs to delete a file after a record is destroyed. If anything raises an exception after the +after_destroy+ callback is called and the transaction rolls back, the file will have been deleted and the model will be left in an inconsistent state. For example, suppose that +picture_file_2+ in the code below is not valid and the +save!+ method raises an error.
+
+<ruby>
+PictureFile.transaction do
+ picture_file_1.destroy
+ picture_file_2.save!
+end
+</ruby>
+
+By using the +after_commit+ callback we can account for this case.
+
+<ruby>
+class PictureFile < ActiveRecord::Base
+ attr_accessor :delete_file
+
+ after_destroy do |picture_file|
+ picture_file.delete_file = picture_file.filepath
+ end
+
+ after_commit do |picture_file|
+ if picture_file.delete_file && File.exist?(picture_file.delete_file)
+ File.delete(picture_file.delete_file)
+ picture_file.delete_file = nil
+ end
+ end
+end
+</ruby>
+
+The +after_commit+ and +after_rollback+ callbacks are guaranteed to be called for all models created, updated, or destroyed within a transaction block. If any exceptions are raised within one of these callbacks, they will be ignored so that they don't interfere with the other callbacks. As such, if your callback code could raise an exception, you'll need to rescue it and handle it appropriately within the callback.
+
h3. Changelog
+* February 17, 2011: Add description of transaction callbacks.
* July 20, 2010: Fixed typos and rephrased some paragraphs for clarity. "Jaime Iniesta":http://jaimeiniesta.com
* May 24, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
* May 15, 2010: Validation Errors section updated by "Emili ParreƱo":http://www.eparreno.com