Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 7d8a3c7a5de132cd540b637753f10333694b9420 / . / user_guide / libraries / database / transactions.html
blob: 35e49428238491994f2056b39e6a01362bfebe7d [file] [log] [blame]
adminb728d882006-09-23 20:27:20 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html>
3<head>
4
5<title>Code Igniter User Guide</title>
6
7<style type='text/css' media='all'>@import url('../../userguide.css');</style>
8<link rel='stylesheet' type='text/css' media='all' href='../../userguide.css' />
9
10<script type="text/javascript" src="../../scripts/nav.js"></script>
11<script type="text/javascript" src="../../scripts/prototype.lite.js"></script>
12<script type="text/javascript" src="../../scripts/moo.fx.js"></script>
13<script type="text/javascript">
14window.onload = function() {
15 myHeight = new fx.Height('nav', {duration: 400});
16 myHeight.hide();
17}
18</script>
19
20<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
21<meta http-equiv='expires' content='-1' />
22<meta http-equiv= 'pragma' content='no-cache' />
23<meta name='robots' content='all' />
24<meta name='author' content='Rick Ellis' />
25<meta name='description' content='Code Igniter User Guide' />
26
27</head>
28<body>
29
30<!-- START NAVIGATION -->
31<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../../');</script></div></div>
32<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../../images/nav_toggle.jpg" width="153" height="44" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
33<div id="masthead">
34<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
35<tr>
36<td><h1>Code Igniter User Guide Version 1.4.1</h1></td>
37<td id="breadcrumb_right"><a href="../../toc.html">Full Table of Contents</a></td>
38</tr>
39</table>
40</div>
41<!-- END NAVIGATION -->
42
43
44
45<!-- START BREADCRUMB -->
46<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
47<tr>
48<td id="breadcrumb">
49<a href="http://www.codeigniter.com/">Code Igniter Home</a> &nbsp;&#8250;&nbsp;
50<a href="../../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
51<a href="index.html">Database Library</a> &nbsp;&#8250;&nbsp;
52Transactions
53</td>
54<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="www.codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
55</tr>
56</table>
57<!-- END BREADCRUMB -->
58
59
60<br clear="all" />
61
62
63<!-- START CONTENT -->
64<div id="content">
65
66
67<h1>Transactions</h1>
68
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]69<p>Code Igniter's database abstraction allows you to use <dfn>transactions</dfn> with databases that support transaction-safe table types. In MySQL, you'll need
admince586d92006-09-23 23:04:43 +0000[diff] [blame]70to be running InnoDB or BDB table types rather then the more common MyISAM. Most other databases support transactions natively.</p>
71
72<p>If you are not familiar with
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]73transactions we recommend you find a good online resource to learn about them for your particular database. The information below assumes you
74have a basic understanding of transactions. For most sites, however, transactions won't be necessary.
admince586d92006-09-23 23:04:43 +0000[diff] [blame]75</p>
76
77<h2>Code Igniter's Approach to Transactions</h2>
78
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]79<p>Code Igniter utilizes an approach to transactions that is very similar to the process used by the popular database class ADODB. We've chosen that approach
80because it greatly simplifies the process of running transactions. In most cases all that is required are two lines of code.</p>
admince586d92006-09-23 23:04:43 +0000[diff] [blame]81
82<p>Traditionally transactions have required a fair amount of work to implement since they demand that you to keep track of your queries
83and determine whether to <dfn>commit</dfn> or <dfn>rollback</dfn> based on the success or failure of your queries. In contrast,
84we'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>
85
86<h2>Running Transactions</h2>
87
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]88<p>To run your queries using transactions you will use the <dfn>$this->db->trans_start()</dfn> and <dfn>$this->db->trans_complete()</dfn> functions as follows:</p>
admince586d92006-09-23 23:04:43 +0000[diff] [blame]89
90<code>
91<kbd>$this->db->trans_start();</kbd><br />
92$this->db->query('AN SQL QUERY...');<br />
93$this->db->query('ANOTHER QUERY...');<br />
94$this->db->query('AND YET ANOTHER QUERY...');<br />
95<kbd>$this->db->trans_complete();</kbd>
96</code>
97
98<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>
99
100
101<h2>Managing Errors</h2>
102
103<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
104manage your own errors like this:</p>
105
106<code>
107$this->db->trans_start();<br />
108$this->db->query('AN SQL QUERY...');<br />
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]109$this->db->query('ANOTHER QUERY...');<br />
admince586d92006-09-23 23:04:43 +0000[diff] [blame]110$this->db->trans_complete();<br />
111<br />
112if (<kbd>$this->db->trans_status()</kbd> === FALSE)<br />
113{<br />
114&nbsp;&nbsp;&nbsp;&nbsp;// generate an error....<br />
115}
116</code>
117
118
119<h2>Enabling Transactions</h2>
120
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]121<p>Transactions are enabled automatically the moment you use <dfn>$this->db->trans_start()</dfn>. If you would like to disable transactions you
122can do so using <dfn>$this->db->trans_off()</dfn>:
admince586d92006-09-23 23:04:43 +0000[diff] [blame]123
124<code>
125<kbd>$this->db->trans_off()</kbd><br /><br />
126
127$this->db->trans_start();<br />
128$this->db->query('AN SQL QUERY...');<br />
129$this->db->trans_complete();
130</code>
131
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]132<p class="important">When transactions are disabled, your queries will be auto-commited, just as they are when running queries without transactions.</p>
admince586d92006-09-23 23:04:43 +0000[diff] [blame]133
134
135<h2>Test Mode</h2>
136
137<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.
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]138To use test mode simply set the first parameter in the <dfn>$this->db->trans_start()</dfn> function to <samp>TRUE</samp>:
admince586d92006-09-23 23:04:43 +0000[diff] [blame]139
140<code>
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]141$this->db->trans_start(<samp>TRUE</samp>); // Query will be rolled back<br />
admince586d92006-09-23 23:04:43 +0000[diff] [blame]142$this->db->query('AN SQL QUERY...');<br />
143$this->db->trans_complete();
144</code>
145
146
147<h2>Running Transactions Manually</h2>
148
149<p>If you would like to run transactions manually you can do so as follows:</p>
150
151<code>
152$this->db->trans_begin();<br /><br />
153
154$this->db->query('AN SQL QUERY...');<br />
155$this->db->query('ANOTHER QUERY...');<br />
156$this->db->query('AND YET ANOTHER QUERY...');<br />
157
158<br />
159
160if ($this->db->trans_status() === FALSE)<br />
161{<br />
162&nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_rollback();<br />
163}<br />
164else<br />
165{<br />
166&nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_commit();<br />
167}<br />
168</code>
169
admin7d8a3c72006-09-24 01:12:07 +0000[diff] [blame^]170<p class="important"><strong>Note:</strong> Make sure to use <kbd>$this->db->trans_begin()</kbd> when running manual transactions, <strong>NOT</strong>
admince586d92006-09-23 23:04:43 +0000[diff] [blame]171<dfn>$this->db->trans_start()</dfn>.</p>
adminb728d882006-09-23 20:27:20 +0000[diff] [blame]172
173
174
175
176
177
178
179
180</div>
181<!-- END CONTENT -->
182
183
184<div id="footer">
185<p>
186Previous Topic:&nbsp;&nbsp;<a href="index.html">Database Class</a>
187&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
188<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
189<a href="../../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
190Next Topic:&nbsp;&nbsp;<a href="configuration.html">Database Configuration</a>
191<p>
192<p><a href="http://www.codeigniter.com">Code Igniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 &nbsp;&middot;&nbsp; <a href="http://www.pmachine.com">pMachine, Inc.</a></p>
193</div>
194
195</body>
196</html>