Merge branch develop of github.com:/EllisLab/CodeIgniter into session

1 files changed, 127 insertions, 0 deletions

diff --git a/user_guide_src/source/database/transactions.rst b/user_guide_src/source/database/transactions.rst
new file mode 100644
index 000000000..e9190e59a
--- /dev/null
+++ b/user_guide_src/source/database/transactions.rst
@@ -0,0 +1,127 @@
+############
+Transactions
+############
+
+CodeIgniter's database abstraction allows you to use transactions with
+databases that support transaction-safe table types. In MySQL, you'll
+need to be running InnoDB or BDB table types rather than the more common
+MyISAM. Most other database platforms support transactions natively.
+
+If you are not familiar with transactions we recommend you find a good
+online resource to learn about them for your particular database. The
+information below assumes you have a basic understanding of
+transactions.
+
+CodeIgniter's Approach to Transactions
+======================================
+
+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 because it greatly simplifies the process of running
+transactions. In most cases all that is required are two lines of code.
+
+Traditionally, transactions have required a fair amount of work to
+implement since they demand that you to keep track of your queries and
+determine whether to commit or rollback based on the success or failure
+of your queries. This is particularly cumbersome with nested queries. In
+contrast, we've implemented a smart transaction system that does all
+this for you automatically (you can also manage your transactions
+manually if you choose to, but there's really no benefit).
+
+Running Transactions
+====================
+
+To run your queries using transactions you will use the
+$this->db->trans_start() and $this->db->trans_complete() functions as
+follows::
+
+	$this->db->trans_start();
+	$this->db->query('AN SQL QUERY...');
+	$this->db->query('ANOTHER QUERY...');
+	$this->db->query('AND YET ANOTHER QUERY...');
+	$this->db->trans_complete();
+
+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 of any given query.
+
+Strict Mode
+===========
+
+By default CodeIgniter runs all transactions in Strict Mode. When strict
+mode is enabled, if you are running multiple groups of transactions, if
+one group fails all groups will be rolled back. If strict mode is
+disabled, each group is treated independently, meaning a failure of one
+group will not affect any others.
+
+Strict Mode can be disabled as follows::
+
+	$this->db->trans_strict(FALSE);
+
+Managing Errors
+===============
+
+If you have error reporting enabled in your config/database.php file
+you'll see a standard error message if the commit was unsuccessful. If
+debugging is turned off, you can manage your own errors like this::
+
+	$this->db->trans_start();
+	$this->db->query('AN SQL QUERY...');
+	$this->db->query('ANOTHER QUERY...');
+	$this->db->trans_complete();
+	
+	if ($this->db->trans_status() === FALSE)
+	{
+		// generate an error... or use the log_message() function to log your error
+	}
+
+Enabling Transactions
+=====================
+
+Transactions are enabled automatically the moment you use
+$this->db->trans_start(). If you would like to disable transactions you
+can do so using $this->db->trans_off()::
+
+	$this->db->trans_off();
+	
+	$this->db->trans_start();
+	$this->db->query('AN SQL QUERY...');
+	$this->db->trans_complete();
+
+When transactions are disabled, your queries will be auto-commited, just
+as they are when running queries without transactions.
+
+Test Mode
+=========
+
+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. To use test mode simply set the first parameter in the
+$this->db->trans_start() function to TRUE::
+
+	$this->db->trans_start(TRUE); // Query will be rolled back
+	$this->db->query('AN SQL QUERY...');
+	$this->db->trans_complete();
+
+Running Transactions Manually
+=============================
+
+If you would like to run transactions manually you can do so as follows::
+
+	$this->db->trans_begin();
+	
+	$this->db->query('AN SQL QUERY...');
+	$this->db->query('ANOTHER QUERY...');
+	$this->db->query('AND YET ANOTHER QUERY...');
+	
+	if ($this->db->trans_status() === FALSE)
+	{
+		$this->db->trans_rollback();
+	}
+	else
+	{
+		$this->db->trans_commit();
+	}
+
+.. note:: Make sure to use $this->db->trans_begin() when running manual
+	transactions, **NOT** $this->db->trans_start().