require 'thread' module ActiveRecord module Transactions # :nodoc: class TransactionError < ActiveRecordError # :nodoc: end def self.included(base) base.extend(ClassMethods) base.class_eval do [:destroy, :save, :save!].each do |method| alias_method_chain method, :transactions end 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: # # 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 by default will _not_ have their instance data returned to their pre-transactional state. # # == Rolling back a transaction manually # # Instead of relying on exceptions to rollback your transactions, you can also do so manually from within the scope # of the transaction by accepting a yield parameter and calling rollback! on it. Example: # # transaction do |transaction| # david.withdrawal(100) # mary.deposit(100) # transaction.rollback! # rolls back the transaction that was otherwise going to be successful # end # # == Different ActiveRecord classes in a single transaction # # Though the transaction class method is called on some ActiveRecord class, # the objects within the transaction block need not all be instances of # that class. # In this example a Balance record is transactionally saved even # though transaction is called on the Account class: # # Account.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 # multiple class-specific databases, the transaction will not protect # interaction among them. One workaround is to begin a transaction # on each class whose models you alter: # # Student.transaction do # Course.transaction do # course.enroll(student) # student.units += course.units # end # end # # This is a poor solution, but full distributed transactions are beyond # the scope of Active Record. # # == 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. # # == Exception handling # # 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. module ClassMethods def transaction(&block) previous_handler = trap('TERM') { raise TransactionError, "Transaction aborted" } increment_open_transactions begin connection.transaction(Thread.current['start_db_transaction'], &block) ensure decrement_open_transactions trap('TERM', previous_handler) end end private def increment_open_transactions #:nodoc: open = Thread.current['open_transactions'] ||= 0 Thread.current['start_db_transaction'] = open.zero? Thread.current['open_transactions'] = open + 1 end def decrement_open_transactions #:nodoc: Thread.current['open_transactions'] -= 1 end end def transaction(&block) self.class.transaction(&block) end def destroy_with_transactions #:nodoc: transaction { destroy_without_transactions } end def save_with_transactions(perform_validation = true) #:nodoc: rollback_active_record_state! { transaction { save_without_transactions(perform_validation) } } end def save_with_transactions! #:nodoc: rollback_active_record_state! { transaction { save_without_transactions! } } end # Reset id and @new_record if the transaction rolls back. def rollback_active_record_state! id_present = has_attribute?(self.class.primary_key) previous_id = id previous_new_record = @new_record yield rescue Exception @new_record = previous_new_record if id_present self.id = previous_id else @attributes.delete(self.class.primary_key) @attributes_cache.delete(self.class.primary_key) end raise end end end