From ce586d93f8c7b5381b11a7609adbfab9fac8d4d5 Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 23 Sep 2006 23:04:43 +0000 Subject: --- user_guide/libraries/database/transactions.html | 104 +++++++++++++++++++++++- 1 file changed, 102 insertions(+), 2 deletions(-) (limited to 'user_guide') diff --git a/user_guide/libraries/database/transactions.html b/user_guide/libraries/database/transactions.html index 99b82a51d..41f27fc76 100644 --- a/user_guide/libraries/database/transactions.html +++ b/user_guide/libraries/database/transactions.html @@ -66,8 +66,108 @@ Transactions

Transactions

-

The following page contains example code showing how the database class is used. For complete details please -read the individual pages describing each function.

+

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

-- cgit v1.2.3-24-g4f1b