--- !ruby/object:RI::MethodDescription 
aliases: []

block_params: ""
comment: 
- !ruby/struct:SM::Flow::P 
  body: Runs the given block in a database transaction, and returns the result of the block.
- !ruby/struct:SM::Flow::H 
  level: 2
  text: Nested transactions support
- !ruby/struct:SM::Flow::P 
  body: Most databases don't support true nested transactions. At the time of writing, the only database that supports true nested transactions that we're aware of, is MS-SQL.
- !ruby/struct:SM::Flow::P 
  body: "In order to get around this problem, #transaction will emulate the effect of nested transactions, by using savepoints: http://dev.mysql.com/doc/refman/5.0/en/savepoints.html Savepoints are supported by MySQL and PostgreSQL, but not SQLite3."
- !ruby/struct:SM::Flow::P 
  body: "It is safe to call this method if a database transaction is already open, i.e. if #transaction is called within another #transaction block. In case of a nested call, #transaction will behave as follows:"
- !ruby/object:SM::Flow::LIST 
  contents: 
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: The block will be run without doing anything. All database statements that happen within the block are effectively appended to the already open database transaction.
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: However, if +:requires_new+ is set, the block will be wrapped in a database savepoint acting as a sub-transaction.
  type: :BULLET
- !ruby/struct:SM::Flow::H 
  level: 3
  text: Caveats
- !ruby/struct:SM::Flow::P 
  body: MySQL doesn't support DDL transactions. If you perform a DDL operation, then any created savepoints will be automatically released. For example, if you've created a savepoint, then you execute a CREATE TABLE statement, then the savepoint that was created will be automatically released.
- !ruby/struct:SM::Flow::P 
  body: "This means that, on MySQL, you shouldn't execute DDL operations inside a #transaction call that you know might create a savepoint. Otherwise, #transaction will raise exceptions when it tries to release the already-automatically-released savepoints:"
- !ruby/struct:SM::Flow::VERB 
  body: "  Model.connection.transaction do  # BEGIN\n    Model.connection.transaction(:requires_new =&gt; true) do  # CREATE SAVEPOINT active_record_1\n      Model.connection.create_table(...)\n      # active_record_1 now automatically released\n    end  # RELEASE SAVEPOINT active_record_1  &lt;--- BOOM! database error!\n  end\n"
full_name: ActiveRecord::ConnectionAdapters::DatabaseStatements#transaction
is_singleton: false
name: transaction
params: (options = {}) {|| ...}
visibility: public
