Added concepts section for MySQL docs. And added basic info about buffered vs unbuffered. Incomplete but should be helpful for discussion and/or lure others into adding content. :) That part deals with PHP Bug #61060

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@325320 c90b9560-bf6c-de11-be94-00142212c4b1

reference/mysqlinfo/concepts.xml

@@ -0,0 +1,91 @@
+<chapter xml:id="mysqlinfo.concepts" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Concepts</title>
+ <para>
+  These concepts are specific to the MySQL drivers for PHP.
+ </para>
+
+ <section xml:id="mysqlinfo.concepts.buffering">
+  <title>Buffered and Unbuffered queries</title>
+  
+  <para>
+   Queries are buffered by default. This means that query results are stored in memory, which
+   allows additional operations like counting the number of rows, and moving (seeking) the
+   current result pointer.
+  </para>
+  
+  <para>
+   Unbuffered MySQL queries execute the query and then return a <type>resource</type> that
+   points to the result set. This uses less memory, and allows MySQL to continue executing the
+   query as the result set is used. It also increases load on the server.
+  </para>
+  
+  <!-- @TODO
+    - Add list of issues people run into with unbuffered queries
+    - Add list of specific use cases for when unbuffered queries are useful
+    - Question: Unbuffered queries still require all rows to be returned or resource free before executing another? Applies to all extensions?
+   -->
+  
+  <para>
+   Because buffered queries are the default, the examples below will demonstrate how to
+   execute unbuffered queries with each API.
+  </para>
+
+  <example>
+   <title>Unbuffered query example: mysqli</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli  = new mysqli("localhost", "my_user", "my_password", "world");
+$uresult = $mysqli->query("SELECT Name FROM City", MYSQLI_USE_RESULT);
+
+if ($uresult) {
+   while ($row = $uresult->fetch_assoc()) {
+       echo $row['Name'] . PHP_EOL;
+   }
+}
+$uresult->close();
+?>
+]]>
+   </programlisting>
+  </example>
+
+  <example>
+   <title>Unbuffered query example: pdo_mysql</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_pass');
+$pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, TRUE);
+
+$uresult = $pdo->query("SELECT Name FROM City");
+if ($uresult) {
+   while ($row = $uresult->fetch(PDO::FETCH_ASSOC)) {
+       echo $row['Name'] . PHP_EOL;
+   }
+}
+?>
+]]>
+   </programlisting>
+  </example>
+
+  <example>
+   <title>Unbuffered query example: mysql</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$conn = mysql_connect("localhost", "my_user", "my_pass");
+$db   = mysql_select_db("world");
+
+$uresult = mysql_unbuffered_query("SELECT Name FROM City");
+if ($uresult) {
+   while ($row = mysql_fetch_assoc($uresult)) {
+       echo $row['Name'] . PHP_EOL;
+   }
+}
+?>
+]]>
+   </programlisting>
+  </example>
+ </section>
+
+</chapter>

reference/mysqlinfo/set.xml

@@ -491,6 +491,9 @@ $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysq
     </tgroup>
    </informaltable>
   </chapter>
+  
+  &reference.mysqlinfo.concepts;
+  
  </book>
 
  &reference.mysql.book;