Code Igniter User Guide Version 1.4.1


Transactions

Code Igniter's database abstraction allows you to use transactions will databases that support transaction-safe table types. In MySQL, you'll need to be running InnoDB or BDB table types rather then the more common MyISAM. Most other databases support transactions natively.

If you are not familiar with transactions we recommend you spend some time learning about them for your particular database. The information below assumes you have a basic understanding of transactions.

Code Igniter's Approach to Transactions

Code Igniter utilizes an approach to transactions that is very similar to the popular database class ADODB. We've chosen that approach becuase it greatly simplifies the process of running transactions. In most cases all that is required are two lines of code.

Traditionally transactions have required a fair amount of work to implement since they demand that you to keep track of your queries and determine whether to commit or rollback based on the success or failure of your queries. In contrast, we've implemented a smart transaction system that does all this for you automatically (you can also manage your transactions manually if you choose to).

Running Transactions

To run your queries using transactions you will use the $this->db->trans_start() and $this->db->trans_complete() functions as follows:

$this->db->trans_start();
$this->db->query('AN SQL QUERY...');
$this->db->query('ANOTHER QUERY...');
$this->db->query('AND YET ANOTHER QUERY...');
$this->db->trans_complete();

You can run as many queries as you want between the start/complete functions and they will all be committed or rolled back based on success or failure.

Managing Errors

If you have error reporting enabled in your config/database.php file you'll see a standard error message if the commit was unsuccessful. If debugging is turned off, you can manage your own errors like this:

$this->db->trans_start();
$this->db->query('AN SQL QUERY...');
$this->db->trans_complete();

if ($this->db->trans_status() === FALSE)
{
    // generate an error....
}

Enabling Transactions

Transactions are enabled automatically the moment you use $this->db->trans_start(). If you would like to disable transactions you can do so using $this->db->trans_off(): $this->db->trans_off()

$this->db->trans_start();
$this->db->query('AN SQL QUERY...');
$this->db->trans_complete();

When transactions are disabled, any queries will be auto-commited, just as they are when running queries normally.

Test Mode

You can optionally put the transaction system into "test mode", which will cause your queries to be rolled back -- even if the queries produce a valid result. To use test mode simply set the first parameter in the $this->db->trans_start() function to TRUE: $this->db->trans_start(TRUE);
$this->db->query('AN SQL QUERY...');
$this->db->trans_complete();

Running Transactions Manually

If you would like to run transactions manually you can do so as follows:

$this->db->trans_begin();

$this->db->query('AN SQL QUERY...');
$this->db->query('ANOTHER QUERY...');
$this->db->query('AND YET ANOTHER QUERY...');

if ($this->db->trans_status() === FALSE)
{
    $this->db->trans_rollback();
}
else
{
    $this->db->trans_commit();
}

Note: Make sure to use $this->db->trans_begin() when running manual trasactions, NOT $this->db->trans_start().