Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 4d02a4feaf2ad7b5e5e29cedf446b777a5547321 / . / user_guide / database / transactions.html
blob: fb1f1fc2e25faac2491fd63e6bb7d52cee21cab8 [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">
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
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>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]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>
admin10c3f412006-10-08 07:21:12 +0000[diff] [blame]36<td><h1>Code Igniter User Guide Version 1.5.0b1</h1></td>
admin4d02a4f2006-10-11 19:40:24 +0000[diff] [blame^]37<td id="breadcrumb_right"><a href="../toc.html">Linear Table of Contents</a></td>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]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
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
admina33ec0a2006-10-10 23:38:05 +0000[diff] [blame]70to 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]71
72<p>If you are not familiar with
73transactions 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]74have a basic understanding of transactions.
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]75</p>
76
77<h2>Code Igniter's Approach to Transactions</h2>
78
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>
81
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]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. This is particularly cumbersome with
84nested queries. In contrast,
85we've implemented a smart transaction system that does all this for you automatically (you can also manage your transactions manually if you choose to,
86but there's really no benefit).</p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]87
88<h2>Running Transactions</h2>
89
90<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>
91
92<code>
93<kbd>$this->db->trans_start();</kbd><br />
94$this->db->query('AN SQL QUERY...');<br />
95$this->db->query('ANOTHER QUERY...');<br />
96$this->db->query('AND YET ANOTHER QUERY...');<br />
97<kbd>$this->db->trans_complete();</kbd>
98</code>
99
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]100<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
101of any given query.</p>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]102
103
104<h2>Managing Errors</h2>
105
106<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
107manage your own errors like this:</p>
108
109<code>
110$this->db->trans_start();<br />
111$this->db->query('AN SQL QUERY...');<br />
112$this->db->query('ANOTHER QUERY...');<br />
113$this->db->trans_complete();<br />
114<br />
115if (<kbd>$this->db->trans_status()</kbd> === FALSE)<br />
116{<br />
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]117&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]118}
119</code>
120
121
122<h2>Enabling Transactions</h2>
123
124<p>Transactions are enabled automatically the moment you use <dfn>$this->db->trans_start()</dfn>. If you would like to disable transactions you
125can do so using <dfn>$this->db->trans_off()</dfn>:
126
127<code>
128<kbd>$this->db->trans_off()</kbd><br /><br />
129
130$this->db->trans_start();<br />
131$this->db->query('AN SQL QUERY...');<br />
132$this->db->trans_complete();
133</code>
134
135<p class="important">When transactions are disabled, your queries will be auto-commited, just as they are when running queries without transactions.</p>
136
137
138<h2>Test Mode</h2>
139
140<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.
141To use test mode simply set the first parameter in the <dfn>$this->db->trans_start()</dfn> function to <samp>TRUE</samp>:
142
143<code>
144$this->db->trans_start(<samp>TRUE</samp>); // Query will be rolled back<br />
145$this->db->query('AN SQL QUERY...');<br />
146$this->db->trans_complete();
147</code>
148
149
150<h2>Running Transactions Manually</h2>
151
152<p>If you would like to run transactions manually you can do so as follows:</p>
153
154<code>
155$this->db->trans_begin();<br /><br />
156
157$this->db->query('AN SQL QUERY...');<br />
158$this->db->query('ANOTHER QUERY...');<br />
159$this->db->query('AND YET ANOTHER QUERY...');<br />
160
161<br />
162
163if ($this->db->trans_status() === FALSE)<br />
164{<br />
165&nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_rollback();<br />
166}<br />
167else<br />
168{<br />
169&nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_commit();<br />
170}<br />
171</code>
172
173<p class="important"><strong>Note:</strong> Make sure to use <kbd>$this->db->trans_begin()</kbd> when running manual transactions, <strong>NOT</strong>
174<dfn>$this->db->trans_start()</dfn>.</p>
175
176
177
178
179
180
181
182
183</div>
184<!-- END CONTENT -->
185
186
187<div id="footer">
188<p>
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]189Previous Topic:&nbsp;&nbsp;<a href="active_record.html">Active Record</a>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]190&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
191<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
192<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
admind125c5c2006-09-25 23:26:12 +0000[diff] [blame]193Next Topic:&nbsp;&nbsp;<a href="fields.html">Field Metadata</a>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]194<p>
195<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>
196</div>
197
198</body>
199</html>