From 54f424385c806db46fbf3efa1b4eda486b51a421 Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Wed, 18 Apr 2012 21:19:59 +0000
Subject: [PATCH] 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 | 91 ++++++++++++++++++++++++++++++++
 reference/mysqlinfo/set.xml      |  3 ++
 2 files changed, 94 insertions(+)
 create mode 100644 reference/mysqlinfo/concepts.xml

diff --git a/reference/mysqlinfo/concepts.xml b/reference/mysqlinfo/concepts.xml
new file mode 100644
index 0000000000..a8a5e0e609
--- /dev/null
+++ b/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>
diff --git a/reference/mysqlinfo/set.xml b/reference/mysqlinfo/set.xml
index 6a3e390b81..67c0408986 100644
--- a/reference/mysqlinfo/set.xml
+++ b/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;