Permalink
Browse files

Rename ActiveRecord::Base#transaction's :force option to :nest. Impro…

…ve documentation for nested transactions.
  • Loading branch information...
1 parent 885c11b commit e916aa7ea1613be966959c05ad41d13fee55a683 @FooBarWidget FooBarWidget committed Oct 9, 2008
Showing with 62 additions and 7 deletions.
  1. +57 −2 activerecord/lib/active_record/transactions.rb
  2. +5 −5 activerecord/test/cases/transactions_test.rb
@@ -120,14 +120,69 @@ def self.included(base)
# 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 treat a certain #transaction call as its own
+ # sub-transaction, by passing <tt>:nest => true</tt> to #transaction. If
+ # anything goes wrong inside that transaction block, then the parent
+ # transaction will remain unaffected. For example:
+ #
+ # User.transaction do
+ # User.create(:username => 'Kotori')
+ # User.transaction(:nest => 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(true) do # CREATE SAVEPOINT rails_savepoint_1
+ # Model.connection.create_table(...) # rails_savepoint_1 now automatically released
+ # end # RELEASE savepoint rails_savepoint_1
+ # # ^^^^ BOOM! database error!
+ # end
module ClassMethods
# See ActiveRecord::Transactions::ClassMethods for detailed documentation.
def transaction(options = {}, &block)
- options.assert_valid_keys :force
+ options.assert_valid_keys :nest
# See the API documentation for ConnectionAdapters::DatabaseStatements#transaction
# for useful information.
- connection.transaction(options[:force], &block)
+ connection.transaction(options[:nest], &block)
end
end
@@ -215,7 +215,7 @@ def test_manually_rolling_back_a_transaction
def test_invalid_keys_for_transaction
assert_raises ArgumentError do
- Topic.transaction :forced => true do
+ Topic.transaction :nested => true do
end
end
end
@@ -228,7 +228,7 @@ def test_force_savepoint_in_nested_transaction
@second.save!
begin
- Topic.transaction :force => true do
+ Topic.transaction :nest => true do
@first.happy = false
@first.save!
raise
@@ -268,17 +268,17 @@ def test_many_savepoints
@first.save!
begin
- Topic.transaction :force => true do
+ Topic.transaction :nest => true do
@first.content = "Two"
@first.save!
begin
- Topic.transaction :force => true do
+ Topic.transaction :nest => true do
@first.content = "Three"
@first.save!
begin
- Topic.transaction :force => true do
+ Topic.transaction :nest => true do
@first.content = "Four"
@first.save!
raise

0 comments on commit e916aa7

Please sign in to comment.