236 lines
9.4 KiB
Ruby
236 lines
9.4 KiB
Ruby
require 'thread'
|
|
|
|
module ActiveRecord
|
|
# See ActiveRecord::Transactions::ClassMethods for documentation.
|
|
module Transactions
|
|
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:
|
|
#
|
|
# 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.
|
|
#
|
|
# == 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. This is because transactions are per-database connection, not
|
|
# per-model.
|
|
#
|
|
# In this example a <tt>Balance</tt> record is transactionally saved even
|
|
# though <tt>transaction</tt> is called on the <tt>Account</tt> class:
|
|
#
|
|
# Account.transaction do
|
|
# balance.save!
|
|
# 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
|
|
# 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, including <tt>after_*</tt> 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.
|
|
#
|
|
# 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.
|
|
#
|
|
# == Nested transactions
|
|
#
|
|
# #transaction calls can be nested. By default, this makes all database
|
|
# statements in the nested transaction block become part of the parent
|
|
# transaction. For example:
|
|
#
|
|
# User.transaction do
|
|
# User.create(:username => 'Kotori')
|
|
# User.transaction do
|
|
# User.create(:username => 'Nemu')
|
|
# raise ActiveRecord::Rollback
|
|
# end
|
|
# end
|
|
#
|
|
# User.find(:all) # => empty
|
|
#
|
|
# It is also possible to requires a sub-transaction by passing
|
|
# <tt>:requires_new => true</tt>. If anything goes wrong, the
|
|
# database rolls back to the beginning of the sub-transaction
|
|
# without rolling back the parent transaction. For example:
|
|
#
|
|
# User.transaction do
|
|
# User.create(:username => 'Kotori')
|
|
# User.transaction(:requires_new => true) do
|
|
# User.create(:username => 'Nemu')
|
|
# raise ActiveRecord::Rollback
|
|
# end
|
|
# end
|
|
#
|
|
# User.find(:all) # => Returns only Kotori
|
|
#
|
|
# Most databases don't support true nested transactions. At the time of
|
|
# writing, the only database that we're aware of that supports true nested
|
|
# transactions, is MS-SQL. Because of this, Active Record emulates nested
|
|
# transactions by using savepoints. See
|
|
# http://dev.mysql.com/doc/refman/5.0/en/savepoints.html
|
|
# for more information about savepoints.
|
|
#
|
|
# === Caveats
|
|
#
|
|
# If you're on MySQL, then do not use DDL operations in nested transactions
|
|
# blocks that are emulated with savepoints. That is, do not execute statements
|
|
# like 'CREATE TABLE' inside such blocks. This is because MySQL automatically
|
|
# releases all savepoints upon executing a DDL operation. When #transaction
|
|
# is finished and tries to release the savepoint it created earlier, a
|
|
# database error will occur because the savepoint has already been
|
|
# automatically released. The following example demonstrates the problem:
|
|
#
|
|
# Model.connection.transaction do # BEGIN
|
|
# Model.connection.transaction(:requires_new => true) do # CREATE SAVEPOINT active_record_1
|
|
# Model.connection.create_table(...) # active_record_1 now automatically released
|
|
# end # RELEASE savepoint active_record_1
|
|
# # ^^^^ BOOM! database error!
|
|
# end
|
|
module ClassMethods
|
|
# See ActiveRecord::Transactions::ClassMethods for detailed documentation.
|
|
def transaction(options = {}, &block)
|
|
# See the ConnectionAdapters::DatabaseStatements#transaction API docs.
|
|
connection.transaction(options, &block)
|
|
end
|
|
end
|
|
|
|
# See ActiveRecord::Transactions::ClassMethods for detailed documentation.
|
|
def transaction(&block)
|
|
self.class.transaction(&block)
|
|
end
|
|
|
|
def destroy_with_transactions #:nodoc:
|
|
with_transaction_returning_status(:destroy_without_transactions)
|
|
end
|
|
|
|
def save_with_transactions(perform_validation = true) #:nodoc:
|
|
rollback_active_record_state! { with_transaction_returning_status(:save_without_transactions, perform_validation) }
|
|
end
|
|
|
|
def save_with_transactions! #:nodoc:
|
|
rollback_active_record_state! { self.class.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
|
|
|
|
# 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
|
|
self.class.transaction do
|
|
status = send(method, *args)
|
|
raise ActiveRecord::Rollback unless status
|
|
end
|
|
status
|
|
end
|
|
end
|
|
end
|