cvs: peardoc /en/package/database mdb2.xml /en/package/database/mdb2 intro-transaction.html

lsmith Tue Aug 1 15:08:34 2006 UTC Added files: /peardoc/en/package/database/mdb2 intro-transaction.html Modified files: /peardoc/en/package/database mdb2.xml Log: - added documentation for the transaction API

http://cvs.php.net/viewvc.cgi/peardoc/en/package/database/mdb2.xml?r1=1.9&r2=1.10&diff_format=u Index: peardoc/en/package/database/mdb2.xml diff -u peardoc/en/package/database/mdb2.xml:1.9 peardoc/en/package/database/mdb2.xml:1.10 --- peardoc/en/package/database/mdb2.xml:1.9 Sat Jun 17 09:09:45 2006 +++ peardoc/en/package/database/mdb2.xml Tue Aug 1 15:08:34 2006 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -<!-- $Revision: 1.9 $ --> +<!-- $Revision: 1.10 $ --> <sect1 id="package.database.mdb2"> <title>MDB2</title> <para> @@ -11,6 +11,7 @@ &package.database.mdb2.intro-query; &package.database.mdb2.intro-fetch; &package.database.mdb2.intro-execute; + &package.database.mdb2.intro-transaction; &package.database.mdb2.intro-module; &package.database.mdb2.intro-auto; &package.database.mdb2.intro-portability; http://cvs.php.net/viewvc.cgi/peardoc/en/package/database/mdb2/intro-transaction.html?view=markup&rev=1.1 Index: peardoc/en/package/database/mdb2/intro-transaction.html +++ peardoc/en/package/database/mdb2/intro-transaction.html <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <!-- add information on the following methods: # setTransactionIsolation --> <refentry id="package.database.mdb2.intro-transaction"> <refnamediv> <refname>Introduction - Transaction</refname> <refpurpose>Performing transactions</refpurpose> </refnamediv> <refsect1 id="package.database.mdb2.intro-transaction.desc"> &title.desc; <para> PEAR MDB2 default to auto commiting all queries. However using the <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodbeginNestedTransaction"> <function>beginNestedTransaction</function></ulink> one can open a new transaction and with the <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodcommit"> <function>commit</function></ulink> and <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodrollback"> <function>rollback</function></ulink> a transaction is finished. All of these three methods optionally accept a string name of a savepoint to set, release or rollback to respectively. The method <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodinTransaction"> <function>inTransaction</function> may be used to check if a transaction is currently open. </para> <example> <title>Doing a transaction</title> <programlisting role="php"> <![CDATA[ <?php // Create a valid MDB2 object named $mdb2 // at the beginning of your program... require_once 'MDB2.php'; $mdb2 =& MDB2::connect('pgsql://usr:pw@localhost/dbnam'); if (PEAR::isError($mdb2)) { die($mdb2->getMessage()); } // check if transaction are supported by this driver if ($mdb2->supports('transactions')) { exit(); } // Open a transaction $res = $mdb2->beginTransaction(); ... // check if we are inside a transaction and if savepoints are supported if ($mdb2->inTransaction() && $mdb2->supports('savepoints')) { // Set a savepoint $savepoint = 'MYSAVEPOINT'; $res = $mdb2->beginTransaction(); .. // determine if the savepoint should be released or to rollback to the savepoint if ($error) { $res = $mdb2->commit($savepoint); } else { $res = $mdb2->rollback($savepoint); } } ... // determine if the commit or rollback if ($error) { $res = $mdb2->commit(); } else { $res = $mdb2->rollback(); } ?> ]]> </programlisting> </example> <warning> <para> PEAR MDB2 does not emulate transactions or savepoints. This means that it depends on the underlying RDBMS (and in the case of MySQL the storage engines used) if transactions will be available in MDB2. Also note that some RDBMS implicitly commit transactions when executing DDL statements (noteably exceptions are Oracle and PostgreSQL). </para> </warning> <para> MDB2 also supports "nested" transactions using the <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodbeginNestedTransaction"> <function>beginNestedTransaction</function> method. Actually these are not true nested transactions as they are natively supported in Interbase for example. MDB2 maintains a counter of opened nested transactions. The transaction is finished once that counter is decremented back to 1 with <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodcompleteNestedTransaction"> <function>completeNestedTransaction</function> calls. If the RDBMS supports savepoints then MDB2 will automatically set a savepoint on every call of the <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodbeginNestedTransaction"> <function>beginNestedTransaction</function> method after the initial call and will return the name. These savepoints are automatically released by the <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodcompleteNestedTransaction"> <function>completeNestedTransaction</function> method. The name of these automatic savepoints are determined by the "savepoint_format" (default: 'MDB2_SAVEPOINT_%s') option and the nested transaction counter. <para> </para> If after initial opening of the nested transaction an unexpected PEAR error is raised on the MDB2 instance the transaction is rolled back, otherwise it is commited at this point. Using the <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodgetNestedTransactionError"> <function>getNestedTransactionError</function> method it is possible to check if there has been an error inside the transaction. Alternatively an rollback can be forced using the the <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodcompleteNestedTransaction"> <function>failNestedTransaction</function>. This method optionally accepts a mixed parameter which will set the error to return if the <ulink url="http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2_Driver_Common.html#methodgetNestedTransactionError"> <function>getNestedTransactionError</function> method is called as well as a second boolean parameter that optionally forces an immidiate rollback. </para> <example> <title>Using emulated nested transactions</title> <programlisting role="php"> <![CDATA[ <?php $mdb2->beginNestedTransaction(); # open transaction $query = "INSERT INTO autoinc (id) VALUES (?)"; $stmt = $mdb2->prepare($query); $stmt->execute(array(1)); $savepoint = $mdb2->beginNestedTransaction(); # ignored / sets savepoint ... // never true for this example if (false) { // raise an error $error = $mdb2->raiseError(MDB2_ERROR, null, null, 'kaboom'); $mdb2->failNestedTransaction(); } if(($error = $mdb2->getNestedTransactionError())) { die($error->getUserinfo()); } $mdb2->completeNestedTransaction(); # ignored / releases savepoint $stmt->execute(array(2)); $mdb2->completeNestedTransaction(); # commit ?> ]]> </programlisting> </example> <para> Finally MDB2 supports setting of the transaction isolation level as per the SQL 92 standard. If a given RDBMS does not support a given isolation level but supports a higher more strict isolation level, then MDB2 silently uses that higher transaction level. Some RDBMS support additional options which are silently ignored if they are not supported. <para> <example> <title>Setting the transaction isolation level</title> <programlisting role="php"> <![CDATA[ <?php $options = array('wait' => 'WAIT', 'rw' => 'READ WRITE'); $options = array('wait' => 'NO WAIT', 'rw' => 'READ ONLY'); $isolation_level = READ UNCOMMITTED # (allows dirty reads) $isolation_level = READ COMMITTED # (prevents dirty reads) $isolation_level = REPEATABLE READ # (prevents nonrepeatable reads) $isolation_level = SERIALIZABLE # (prevents phantom reads) $mdb2->setTransactionIsolation($isolation_level, $options); ?> ]]> </programlisting> </example> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->