php-doc-en/reference/mysqlinfo/concepts.xml

<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>