ADOdb

Database Abstraction Layer for PHP

User Tools

Site Tools


v5:userguide:transactions

This is an old revision of the document!


Transaction Handling In ADOdb

Overview

There are 2 ways of handling transactions 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

Granular Transactions

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

/*
* 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();

Stacking Transactions

Granular transactions cannot be stacked, i.e. each beginTrans() in a procedure must be followed by a rollbackTrans() or a commitTrans()


Smart Transactions

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():

/*
* 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();

CompleteTrans() detects when an SQL error occurs, and will Rollback/Commit as appropriate.

You can force a rollback even if no error occured, using failTrans(). Note that the rollback is done in CompleteTrans().

$conn->startTrans();
 
$conn->execute($sql);
 
if (!CheckRecords()) 
    $conn->failTrans();
 
$conn->Execute($Sql2);
 
$conn->CompleteTrans();

You can also check if a transaction has failed, using HasFailedTrans(), which returns true if FailTrans() was called, or there was an error in the SQL execution. Make sure you call HasFailedTrans() before you call CompleteTrans(), as it is only works between StartTrans/CompleteTrans.

Lastly, StartTrans/CompleteTrans is nestable, and only the outermost block is executed. In contrast, BeginTrans/CommitTrans/RollbackTrans is NOT nestable.

$conn->StartTrans();
 
$conn->Execute($sql);
$conn->StartTrans();    # ignored
if (!CheckRecords()) 
    $conn->FailTrans();
 
$conn->CompleteTrans(); # ignored
$conn->Execute($Sql2);
$conn->CompleteTrans();

Note: Savepoints are currently not supported.

v5/userguide/transactions.1451417074.txt.gz · Last modified: 2017/04/21 11:39 (external edit)