Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 7a3b96e27988deeebeeff4469f5de3b9fb50918f / . / user_guide / database / transactions.html
blob: 5fcc8e391d3923ff6b471d8546c7e6103190ff23 [file] [log] [blame]
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Derek Allardafd99ac2008-01-19 19:59:14 +0000[diff] [blame]2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]3<head>
4
Derek Allard8039d4c2008-05-31 02:47:56 +0000[diff] [blame]5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Derek Jonesfd93d222008-05-06 15:18:50 +0000[diff] [blame]6<title>Transactions : CodeIgniter User Guide</title>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]7
8<style type='text/css' media='all'>@import url('../userguide.css');</style>
9<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
10
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]11<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +0000[diff] [blame]12<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]13<script type="text/javascript" src="../nav/moo.fx.js"></script>
Derek Allardb3412372007-10-25 12:15:16 +0000[diff] [blame]14<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]15
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
Derek Allard3d879d52008-01-18 19:41:32 +0000[diff] [blame]19<meta name='author' content='ExpressionEngine Dev Team' />
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]20<meta name='description' content='CodeIgniter User Guide' />
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]21
22</head>
23<body>
24
25<!-- START NAVIGATION -->
26<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
27<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>
28<div id="masthead">
29<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
30<tr>
Derek Jones6b7b11f2008-05-06 16:07:27 +0000[diff] [blame]31<td><h1>CodeIgniter User Guide Version 1.6.2</h1></td>
adminc0d5d522006-10-30 19:40:35 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]33</tr>
34</table>
35</div>
36<!-- END NAVIGATION -->
37
38
39
40<!-- START BREADCRUMB -->
41<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
42<tr>
43<td id="breadcrumb">
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame]44<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]45<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
46<a href="index.html">Database Library</a> &nbsp;&#8250;&nbsp;
47Transactions
48</td>
Derek Allardbc030912007-06-24 18:25:29 +0000[diff] [blame]49<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="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>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]50</tr>
51</table>
52<!-- END BREADCRUMB -->
53
54
55<br clear="all" />
56
57
58<!-- START CONTENT -->
59<div id="content">
60
61
62<h1>Transactions</h1>
63
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]64<p>CodeIgniter's database abstraction allows you to use <dfn>transactions</dfn> with databases that support transaction-safe table types. In MySQL, you'll need
admina33ec0a2006-10-10 23:38:05 +0000[diff] [blame]65to be running InnoDB or BDB table types rather then the more common MyISAM. Most other database platforms support transactions natively.</p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]66
admine334c472006-10-21 19:44:22 +0000[diff] [blame]67<p>If you are not familiar with
68transactions we recommend you find a good online resource to learn about them for your particular database. The information below assumes you
admina33ec0a2006-10-10 23:38:05 +0000[diff] [blame]69have a basic understanding of transactions.
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]70</p>
71
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]72<h2>CodeIgniter's Approach to Transactions</h2>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]73
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]74<p>CodeIgniter utilizes an approach to transactions that is very similar to the process used by the popular database class ADODB. We've chosen that approach
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]75because it greatly simplifies the process of running transactions. In most cases all that is required are two lines of code.</p>
76
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]77<p>Traditionally, transactions have required a fair amount of work to implement since they demand that you to keep track of your queries
admine334c472006-10-21 19:44:22 +0000[diff] [blame]78and determine whether to <dfn>commit</dfn> or <dfn>rollback</dfn> based on the success or failure of your queries. This is particularly cumbersome with
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]79nested queries. In contrast,
80we've implemented a smart transaction system that does all this for you automatically (you can also manage your transactions manually if you choose to,
81but there's really no benefit).</p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]82
83<h2>Running Transactions</h2>
84
85<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>
86
87<code>
88<kbd>$this->db->trans_start();</kbd><br />
89$this->db->query('AN SQL QUERY...');<br />
90$this->db->query('ANOTHER QUERY...');<br />
91$this->db->query('AND YET ANOTHER QUERY...');<br />
92<kbd>$this->db->trans_complete();</kbd>
93</code>
94
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]95<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
96of any given query.</p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]97
98
Rick Ellis2d2b2b92008-05-12 18:16:30 +0000[diff] [blame]99<h2>Strict Mode</h2>
100
101<p>By default CodeIgniter runs all transactions in <dfn>Strict Mode</dfn>. When strict mode is enabled, if you are running multiple groups of
102transactions, if one group fails all groups will be rolled back. If strict mode is disabled, each group is treated independently, meaning
103a failure of one group will not affect any others.</p>
104
105<p>Strict Mode can be disabled as follows:</p>
106
107<code>$this->db->trans_strict(FALSE);</code>
108
109
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]110<h2>Managing Errors</h2>
111
112<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
113manage your own errors like this:</p>
114
115<code>
116$this->db->trans_start();<br />
117$this->db->query('AN SQL QUERY...');<br />
118$this->db->query('ANOTHER QUERY...');<br />
119$this->db->trans_complete();<br />
120<br />
121if (<kbd>$this->db->trans_status()</kbd> === FALSE)<br />
122{<br />
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]123&nbsp;&nbsp;&nbsp;&nbsp;// generate an error... or use the log_message() function to log your error<br />
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]124}
125</code>
126
127
128<h2>Enabling Transactions</h2>
129
130<p>Transactions are enabled automatically the moment you use <dfn>$this->db->trans_start()</dfn>. If you would like to disable transactions you
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]131can do so using <dfn>$this->db->trans_off()</dfn>:</p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]132
133<code>
134<kbd>$this->db->trans_off()</kbd><br /><br />
135
136$this->db->trans_start();<br />
137$this->db->query('AN SQL QUERY...');<br />
138$this->db->trans_complete();
139</code>
140
141<p class="important">When transactions are disabled, your queries will be auto-commited, just as they are when running queries without transactions.</p>
142
143
144<h2>Test Mode</h2>
145
146<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.
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]147To use test mode simply set the first parameter in the <dfn>$this->db->trans_start()</dfn> function to <samp>TRUE</samp>:</p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]148
149<code>
150$this->db->trans_start(<samp>TRUE</samp>); // Query will be rolled back<br />
151$this->db->query('AN SQL QUERY...');<br />
152$this->db->trans_complete();
153</code>
154
155
156<h2>Running Transactions Manually</h2>
157
158<p>If you would like to run transactions manually you can do so as follows:</p>
159
160<code>
161$this->db->trans_begin();<br /><br />
162
163$this->db->query('AN SQL QUERY...');<br />
164$this->db->query('ANOTHER QUERY...');<br />
165$this->db->query('AND YET ANOTHER QUERY...');<br />
166
167<br />
168
169if ($this->db->trans_status() === FALSE)<br />
170{<br />
171&nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_rollback();<br />
172}<br />
173else<br />
174{<br />
175&nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_commit();<br />
176}<br />
177</code>
178
179<p class="important"><strong>Note:</strong> Make sure to use <kbd>$this->db->trans_begin()</kbd> when running manual transactions, <strong>NOT</strong>
180<dfn>$this->db->trans_start()</dfn>.</p>
181
182
183
184
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]185</div>
186<!-- END CONTENT -->
187
188
189<div id="footer">
190<p>
Derek Allard9da4dbc2007-04-03 11:39:35 +0000[diff] [blame]191Previous Topic:&nbsp;&nbsp; <a href="fields.html">Field MetaData</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]192<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
193<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Derek Allard9da4dbc2007-04-03 11:39:35 +0000[diff] [blame]194Next Topic:&nbsp;&nbsp;<a href="table_data.html">Table Metadata</a>
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]195</p>
Derek Jones07870432008-02-13 03:49:26 +0000[diff] [blame]196<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006-2008 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]197</div>
198
199</body>
200</html>