Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 3b11868b3aa56c83419d904435a5b7dfbf997063 / . / user_guide / database / transactions.html
blob: 30c58d4d43fb5cae0b03751bdc8736f16b4dff70 [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 Allard404e35d2007-08-07 01:00:45 +0000[diff] [blame]5<title>CodeIgniter User Guide : Transactions</title>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]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
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]10<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +0000[diff] [blame]11<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]12<script type="text/javascript" src="../nav/moo.fx.js"></script>
Derek Allardb3412372007-10-25 12:15:16 +0000[diff] [blame]13<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]14
15<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
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 Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]31<td><h1>CodeIgniter User Guide Version 1.6.0</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
99<h2>Managing Errors</h2>
100
101<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
102manage your own errors like this:</p>
103
104<code>
105$this->db->trans_start();<br />
106$this->db->query('AN SQL QUERY...');<br />
107$this->db->query('ANOTHER QUERY...');<br />
108$this->db->trans_complete();<br />
109<br />
110if (<kbd>$this->db->trans_status()</kbd> === FALSE)<br />
111{<br />
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]112&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]113}
114</code>
115
116
117<h2>Enabling Transactions</h2>
118
119<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]120can do so using <dfn>$this->db->trans_off()</dfn>:</p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]121
122<code>
123<kbd>$this->db->trans_off()</kbd><br /><br />
124
125$this->db->trans_start();<br />
126$this->db->query('AN SQL QUERY...');<br />
127$this->db->trans_complete();
128</code>
129
130<p class="important">When transactions are disabled, your queries will be auto-commited, just as they are when running queries without transactions.</p>
131
132
133<h2>Test Mode</h2>
134
135<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]136To 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]137
138<code>
139$this->db->trans_start(<samp>TRUE</samp>); // Query will be rolled back<br />
140$this->db->query('AN SQL QUERY...');<br />
141$this->db->trans_complete();
142</code>
143
144
145<h2>Running Transactions Manually</h2>
146
147<p>If you would like to run transactions manually you can do so as follows:</p>
148
149<code>
150$this->db->trans_begin();<br /><br />
151
152$this->db->query('AN SQL QUERY...');<br />
153$this->db->query('ANOTHER QUERY...');<br />
154$this->db->query('AND YET ANOTHER QUERY...');<br />
155
156<br />
157
158if ($this->db->trans_status() === FALSE)<br />
159{<br />
160&nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_rollback();<br />
161}<br />
162else<br />
163{<br />
164&nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_commit();<br />
165}<br />
166</code>
167
168<p class="important"><strong>Note:</strong> Make sure to use <kbd>$this->db->trans_begin()</kbd> when running manual transactions, <strong>NOT</strong>
169<dfn>$this->db->trans_start()</dfn>.</p>
170
171
172
173
174
175
176
177
178</div>
179<!-- END CONTENT -->
180
181
182<div id="footer">
183<p>
Derek Allard9da4dbc2007-04-03 11:39:35 +0000[diff] [blame]184Previous 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]185<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
186<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Derek Allard9da4dbc2007-04-03 11:39:35 +0000[diff] [blame]187Next Topic:&nbsp;&nbsp;<a href="table_data.html">Table Metadata</a>
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]188</p>
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame]189<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2007 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]190</div>
191
192</body>
193</html>