ADOdb

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======Transaction Handling In ADOdb ======
===== Overview =====
There are 2 ways of overriding the default database transaction handling methods in ADOdb, **Granular** and **Smart**. Each way holds benefits but they cannot be mixed. Each method comprises a series of methods.

  * Granular transactions allow full control of individual commits
  * Smart transactions are easier to control

-------------------------------------------

===== Default Behaviour =====
<WRAP right info 300px>
MySQL myIsam tables are always granular, and ignore any transaction control methods coded. You cannot rollback or fail an update into that table type. Use InnoDB table types instead.

This also applies to any sequences that might have been updated in the transaction, and are not subject to transactional rollback.
</WRAP>
If ADOdb transaction handling is not used, then the transaction handling method is controlled by whatever is set by the database. Possible methods are:

  * Automatically creating granular updates
  * Automatically rolling back the transactions at the end of procedures
  * Failing unless a transaction handling method is assigned on connection

----------------------------------------------

===== Granular Transactions =====
<WRAP right box>
== Available Methods ==
[[v5:reference:connection:begintrans|beginTrans()]]\\
[[v5:reference:connection:rollbacktrans|rollbackTrans()]]\\
[[v5:reference:connection:completetrans|completeTrans()]]\\
== See Also ==
[[v5:reference:connection:transOff|Temporarily Disabling Transactions]]\\
[[v5:reference:connection:transCnt|Checking Transaction Status]]\\
</WRAP>
When using granular transactions, it is the duty of the programmer to check whether a transaction execution has succeeded or failed. This allows the code to branch as desired in the case of a transaction failure.
---------------------------------
==== Usage ====
<code php>
/*
* Start transaction scope
*/
$conn->beginTrans();

/*
* Execute some insert or update SQL
*/
$ok = $conn->execute($sql);

if ($ok) {
   /*
   * The previous execution succeeded, do some more
   */ 
   $ok = $conn->execute($sql2);
} else {
   /*
   * Branch, do some other work, then return
   */
}

if (!$ok) {
    /*
    * Test the last insertion, if not successful roll 
    * back the entire transaction scope
    */
    $conn->rollbackTrans();
} else {
    /*
    * Go ahead and commit
    */ 
    $conn->commitTrans();
}
</code>
-----------------------------
===== Smart Transactions =====
<WRAP right box>
== Available Methods ==
[[v5:reference:connection:starttrans|startTrans()]]\\
[[v5:reference:connection:failtrans|failTrans()]]\\
[[v5:reference:connection:hasfailedtrans|hasFailedTrans()]]\\
[[v5:reference:connection:completetrans|completeTrans()]]
== See Also ==
[[v5:reference:connection:transOff|Temporarily Disabling Transactions]]\\
[[v5:reference:connection:transCnt|Checking Transaction Status]]\\
</WRAP>
Smart Transactions are much easier to use in large procedures because you do not have to track the error status. You start a smart transaction by calling startTrans():

<code php>
/*
* Begin with startTrans
*/
$conn->startTrans();

/*
* Execute some SQL
*/
$conn->execute($sql);

/*
* Execute some more SQL
*/
$conn->execute($sql2);

/*
* Call completetrans. If any of the executions in the above 
* code have failed, the transactions will roll back automatically
*/
$conn->completeTrans();
</code>

[[v5:reference:connection:completetrans|completeTrans()]] detects when an SQL error occurs, and will Rollback or Commit the transactions as appropriate. 

You can force a rollback even if no transactional error has occured, using [[v5:reference:connection:failtrans|failTrans()]]. Note that the rollback is done in completeTrans(), so any updates/inserts done after ''failTrans()'' is called will also be rolled back.

<code php>
$conn->startTrans();

$conn->execute($sql);

if (!checkRecords()) 
    $conn->failTrans();

/*
* Even though failTrans was issued before this statement,
* it will also be rolled back
*/
$conn->execute($sql2);

$conn->completeTrans();
</code>

You can also check if a transaction has failed, using [[v5:reference:connection:hasfailedtrans|hasFailedTrans()]], which returns true:
  * if [[v5:reference:connection:failtrans|failTrans()]] was called, 
  * There was an error in the SQL execution. This execution comprises all scenarios where the SQL statement was successfully issued, but failed to complete. This does not include scenarios where the construction of the statement failed, and an error occurred that was trapped by PHP error handling.

Make sure you call ''hasFailedTrans()'' before you call ''completeTrans()'', as it is only works between startTrans/completeTrans.


==== Nesting Transactions ====
Smart Transactions are nestable, which means that you can have multiple groups of startTrans/completeTrans inside each other. This is extremely useful when writing re-usable classes, as the transaction scope is automatically directed to the outermost block.

The only caveat for nesting is that the startTrans/completeTrans pairs **must match**. If they do not, the database default behaviour for transaction processing will take control.

<code php>
/*
* Outer block, takes control of transactions
*/
$conn->startTrans();

$conn->execute($sql);
/*
* This is ignored
*/
$conn->startTrans();
if (!checkRecords()) 
    /*
    * This is applied to the outer block
   */
    $conn->failTrans();

/*
* This is ignored
*/
$conn->completeTrans();

$conn->execute($Sql2);
/*
* This completes the transaction scope
*/
$conn->completeTrans();
</code>
==== Savepoints ====
Savepoints are currently not supported.