Documentation/database/transactions.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 14px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin: 0 0 5px 0;
  24                 }
  25
  26                 h2 {
  27                         font-size: 13px;
  28                         font-weight: bold;
  29                         margin: 5px 0 5px 0;
  30                 }
  31
  32                 ol, ul {
  33                         margin: 10px 0 10px 0;
  34                         list-style-position: inside;
  35                 }
  36
  37                 p {
  38                         margin: 5px 0 5px 0;
  39                 }
  40
  41                 .content {
  42                         border: 1px dotted #444;
  43                         margin: 10px;
  44                         padding: 10px;
  45                         text-align: justify;
  46                         width: 700px;
  47                 }
  48
  49                 .example {
  50                         border: 1px solid #ccc;
  51                         background: #eee;
  52                         margin: 10px;
  53                         padding: 10px;
  54                         text-align: left;
  55                 }
  56         </style>
  57 </head>
  58
  59 <body>
  60         <div class="content">
  61                 <h1>Database Transactions</h1>
  62
  63                 <p>CarbonPHP's database classes allow you to use <b>transactions</b> with databases that support transaction
  64                 safe table types.  In MySQL, you will need to be running InnoDB or BDB table types instead of the common
  65                 MyISAM/.  Most other database platforms support transactions natively.</p>
  66
  67                 <p>If you do not have experience with database transactions we recommend you find a resource to learn about
  68                 them for your database platform.  This page assume you have previous experience with transactions.</p>
  69         </div>
  70
  71         <div class="content">
  72                 <h1>Transacations in CarbonPHP</h1>
  73
  74                 <p>CarbonPHP uses an approach similar to that of the ADODB class for transactions.  This approach simplifies
  75                 the process of running transactions.  In most cases all that is needed are two lines of code.</p>
  76
  77                 <p>Usually transactions require a fair amount of code to implement since they demand that you keep track of
  78                 your queries and determine whether to commit or rollback based on success or failure of the query.</p>
  79         </div>
  80
  81         <div class="content">
  82                 <h1>Running a Transaction</h1>
  83
  84                 <p>To run a query using a transaction you will need to use the <b>trans_start()</b> and
  85                 <b>trans_complete()</b> methods.</p>
  86
  87                 <div class="example">
  88                         <b>$this->db->trans_start();</b><br />
  89                         $this->db->query('SOME QUERY');<br />
  90                         $this->db->query('ANOTHER QUERY');<br />
  91                         <b>$this->db->trans_complete();</b>
  92                 </div>
  93
  94                 <p>You are allowed to run any amount of queries between the start and complete methods.  They will be committed
  95                 or rolled back depending on success or failure.</p>
  96         </div>
  97
  98         <div class="content">
  99                 <h1>Managing Errors</h1>
 100
 101                 <p>If you have error reporting enabled in the <b>application/config/config.php</b> file you will see a
 102                 standard error message if your commit was unsuccessful.  If debugging is enabled you can manage your own
 103                 errors.</p>
 104
 105                 <div class="example">
 106                         $this->db->trans_start();<br />
 107                         $this->db->query('SOME QUERY');<br />
 108                         $this->db->query('ANOTHER QUERY');<br />
 109                         $this->db->trans_complete();<br />
 110                         <br />
 111                         if ($this->db->trans_status() === false)<br />
 112                         &#123;<br />
 113                         &nbsp;&nbsp;&nbsp;&nbsp;// Generate an error message...<br />
 114                         &#125;
 115                 </div>
 116         </div>
 117
 118         <div class="content">
 119                 <h1>Enabling Transactions</h1>
 120
 121                 <p>Transactions are enabled automatically the moment you call the <b>trans_start()</b> method.  If you wish
 122                 to disabled transactions you can do so by calling the <b>trans_off()</b> method.</p>
 123
 124                 <div class="example">
 125                         $this->db->trans_off();<br />
 126                         <br />
 127                         $this->db->trans_start();<br />
 128                         $this->db->query('SOME QUERY');<br />
 129                         $this->db->query('ANOTHER QUERY');<br />
 130                         $this->db->trans_complete();
 131                 </div>
 132
 133                 <p>When transcations are disabled your queries will be committed, just as they are when running queries
 134                 without transactions.</p>
 135         </div>
 136
 137         <div class="content">
 138                 <h1>Test Mode</h1>
 139
 140                 <p>You can optionally put the transaction system into 'test mode' which will cause your queries to be rolled
 141                 back, even if the queries produce a successful result.</p>
 142
 143                 <div class="example">
 144                         $this->db->trans_start(<b>true</b>);<br />
 145                         $this->db->query('SOME QUERY');<br />
 146                         $this->db->trans_complete();<br />
 147                 </div>
 148         </div>
 149
 150         <div class="content">
 151                 <h1>Manually Running a Transaction</h1>
 152
 153                 <p>If you wish to manually run a transaction you can do so like the following example.</p>
 154
 155                 <div class="example">
 156                         <b>$this->db->trans_begin();</b><br />
 157                         <br />
 158                         $this->db->query('SOME QUERY');<br />
 159                         $this->db->query('ANOTHER QUERY');<br />
 160                         <br />
 161                         if ($this->db->trans_status() === false)<br />
 162                         &#123;<br />
 163                         &nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_rollback();<br />
 164                         &#125;<br />
 165                         else<br />
 166                         &#123;<br />
 167                         &nbsp;&nbsp;&nbsp;&nbsp;$this->db->trans_commit();<br />
 168                         &#125;
 169                 </div>
 170
 171                 <p>You should remember to use <b>trans_begin()</b> when running manual transactions instead of
 172                 <b>trans_start()</b>.</p>
 173         </div>
 174 </body>
 175
 176 </html>