diff options
Diffstat (limited to 'user_guide/libraries/database/transactions.html')
| -rw-r--r-- | user_guide/libraries/database/transactions.html | 104 |
1 files changed, 102 insertions, 2 deletions
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 <h1>Transactions</h1>
-<p>The following page contains example code showing how the database class is used. For complete details please
-read the individual pages describing each function.</p>
+<p>Code Igniter's database abstraction allows you to use <dfn>transactions</dfn> 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.</p>
+
+<p>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.
+</p>
+
+<h2>Code Igniter's Approach to Transactions</h2>
+
+<p>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.</p>
+
+<p>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 <dfn>commit</dfn> or <dfn>rollback</dfn> 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).</p>
+
+<h2>Running Transactions</h2>
+
+<p>To run your queries using transactions you will use the <kbd>$this->db->trans_start()</kbd> and <kbd>$this->db->trans_complete()</kbd> functions as follows:</p>
+
+<code>
+<kbd>$this->db->trans_start();</kbd><br />
+$this->db->query('AN SQL QUERY...');<br />
+$this->db->query('ANOTHER QUERY...');<br />
+$this->db->query('AND YET ANOTHER QUERY...');<br />
+<kbd>$this->db->trans_complete();</kbd>
+</code>
+
+<p>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.</p>
+
+
+<h2>Managing Errors</h2>
+
+<p>If you have error reporting enabled in your <dfn>config/database.php</dfn> 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:</p>
+
+<code>
+$this->db->trans_start();<br />
+$this->db->query('AN SQL QUERY...');<br />
+$this->db->trans_complete();<br />
+<br />
+if (<kbd>$this->db->trans_status()</kbd> === FALSE)<br />
+{<br />
+ // generate an error....<br />
+}
+</code>
+
+
+<h2>Enabling Transactions</h2>
+
+<p>Transactions are enabled automatically the moment you use <kbd>$this->db->trans_start()</kbd>. If you would like to disable transactions you
+can do so using <kbd>$this->db->trans_off()</kbd>:
+
+<code>
+<kbd>$this->db->trans_off()</kbd><br /><br />
+
+$this->db->trans_start();<br />
+$this->db->query('AN SQL QUERY...');<br />
+$this->db->trans_complete();
+</code>
+
+<p>When transactions are disabled, any queries will be auto-commited, just as they are when running queries normally.</p>
+
+
+<h2>Test Mode</h2>
+
+<p>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 <kbd>$this->db->trans_start()</kbd> function to <samp>TRUE</samp>:
+
+<code>
+$this->db->trans_start(</kbd><samp>TRUE</samp><kbd>);<br />
+$this->db->query('AN SQL QUERY...');<br />
+$this->db->trans_complete();
+</code>
+
+
+<h2>Running Transactions Manually</h2>
+
+<p>If you would like to run transactions manually you can do so as follows:</p>
+
+<code>
+$this->db->trans_begin();<br /><br />
+
+$this->db->query('AN SQL QUERY...');<br />
+$this->db->query('ANOTHER QUERY...');<br />
+$this->db->query('AND YET ANOTHER QUERY...');<br />
+
+<br />
+
+if ($this->db->trans_status() === FALSE)<br />
+{<br />
+ $this->db->trans_rollback();<br />
+}<br />
+else<br />
+{<br />
+ $this->db->trans_commit();<br />
+}<br />
+</code>
+
+<p class="important"><strong>Note:</strong> Make sure to use <kbd>$this->db->trans_begin()</kbd> when running manual trasactions, <strong>NOT</strong>
+<dfn>$this->db->trans_start()</dfn>.</p>
|