From a2932784bb71e72a78c32819ebd7ed2bed551e3e Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sun, 5 Oct 2008 22:16:26 +0100 Subject: Merge docrails --- activerecord/lib/active_record/transactions.rb | 87 ++++++++++++++++++++------ 1 file changed, 69 insertions(+), 18 deletions(-) (limited to 'activerecord/lib/active_record/transactions.rb') diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb index 970da701c7..27b5aca18f 100644 --- a/activerecord/lib/active_record/transactions.rb +++ b/activerecord/lib/active_record/transactions.rb @@ -1,7 +1,8 @@ require 'thread' module ActiveRecord - module Transactions # :nodoc: + # See ActiveRecord::Transactions::ClassMethods for documentation. + module Transactions class TransactionError < ActiveRecordError # :nodoc: end @@ -15,26 +16,33 @@ module ActiveRecord end end - # Transactions are protective blocks where SQL statements are only permanent if they can all succeed as one atomic action. - # The classic example is a transfer between two accounts where you can only have a deposit if the withdrawal succeeded and - # vice versa. Transactions enforce the integrity of the database and guard the data against program errors or database break-downs. - # So basically you should use transaction blocks whenever you have a number of statements that must be executed together or - # not at all. Example: + # Transactions are protective blocks where SQL statements are only permanent + # if they can all succeed as one atomic action. The classic example is a + # transfer between two accounts where you can only have a deposit if the + # withdrawal succeeded and vice versa. Transactions enforce the integrity of + # the database and guard the data against program errors or database + # break-downs. So basically you should use transaction blocks whenever you + # have a number of statements that must be executed together or not at all. + # Example: # - # transaction do + # ActiveRecord::Base.transaction do # david.withdrawal(100) # mary.deposit(100) # end # - # This example will only take money from David and give to Mary if neither +withdrawal+ nor +deposit+ raises an exception. - # Exceptions will force a ROLLBACK that returns the database to the state before the transaction was begun. Be aware, though, - # that the objects will _not_ have their instance data returned to their pre-transactional state. + # This example will only take money from David and give to Mary if neither + # +withdrawal+ nor +deposit+ raises an exception. Exceptions will force a + # ROLLBACK that returns the database to the state before the transaction was + # begun. Be aware, though, that the objects will _not_ have their instance + # data returned to their pre-transactional state. # # == Different Active Record classes in a single transaction # # Though the transaction class method is called on some Active Record class, # the objects within the transaction block need not all be instances of - # that class. + # that class. This is because transactions are per-database connection, not + # per-model. + # # In this example a Balance record is transactionally saved even # though transaction is called on the Account class: # @@ -43,6 +51,14 @@ module ActiveRecord # account.save! # end # + # Note that the +transaction+ method is also available as a model instance + # method. For example, you can also do this: + # + # balance.transaction do + # balance.save! + # account.save! + # end + # # == Transactions are not distributed across database connections # # A transaction acts on a single database connection. If you have @@ -62,17 +78,48 @@ module ActiveRecord # # == Save and destroy are automatically wrapped in a transaction # - # Both Base#save and Base#destroy come wrapped in a transaction that ensures that whatever you do in validations or callbacks - # will happen under the protected cover of a transaction. So you can use validations to check for values that the transaction - # depends on or you can raise exceptions in the callbacks to rollback, including after_* callbacks. + # Both Base#save and Base#destroy come wrapped in a transaction that ensures + # that whatever you do in validations or callbacks will happen under the + # protected cover of a transaction. So you can use validations to check for + # values that the transaction depends on or you can raise exceptions in the + # callbacks to rollback, including after_* callbacks. # # == Exception handling and rolling back # - # Also have in mind that exceptions thrown within a transaction block will be propagated (after triggering the ROLLBACK), so you - # should be ready to catch those in your application code. + # Also have in mind that exceptions thrown within a transaction block will + # be propagated (after triggering the ROLLBACK), so you should be ready to + # catch those in your application code. # - # One exception is the ActiveRecord::Rollback exception, which will trigger a ROLLBACK when raised, - # but not be re-raised by the transaction block. + # One exception is the ActiveRecord::Rollback exception, which will trigger + # a ROLLBACK when raised, but not be re-raised by the transaction block. + # + # *Warning*: one should not catch ActiveRecord::StatementInvalid exceptions + # inside a transaction block. StatementInvalid exceptions indicate that an + # error occurred at the database level, for example when a unique constraint + # is violated. On some database systems, such as PostgreSQL, database errors + # inside a transaction causes the entire transaction to become unusable + # until it's restarted from the beginning. Here is an example which + # demonstrates the problem: + # + # # Suppose that we have a Number model with a unique column called 'i'. + # Number.transaction do + # Number.create(:i => 0) + # begin + # # This will raise a unique constraint error... + # Number.create(:i => 0) + # rescue ActiveRecord::StatementInvalid + # # ...which we ignore. + # end + # + # # On PostgreSQL, the transaction is now unusable. The following + # # statement will cause a PostgreSQL error, even though the unique + # # constraint is no longer violated: + # Number.create(:i => 1) + # # => "PGError: ERROR: current transaction is aborted, commands + # # ignored until end of transaction block" + # end + # + # One should restart the entire transaction if a StatementError occurred. module ClassMethods # See ActiveRecord::Transactions::ClassMethods for detailed documentation. def transaction(&block) @@ -86,6 +133,7 @@ module ActiveRecord end end + # See ActiveRecord::Transactions::ClassMethods for detailed documentation. def transaction(&block) self.class.transaction(&block) end @@ -122,6 +170,9 @@ module ActiveRecord # Executes +method+ within a transaction and captures its return value as a # status flag. If the status is true the transaction is committed, otherwise # a ROLLBACK is issued. In any case the status flag is returned. + # + # This method is available within the context of an ActiveRecord::Base + # instance. def with_transaction_returning_status(method, *args) status = nil transaction do -- cgit v1.2.3