5.1 unbuffered queries

src/Database/Driver.php

@@ -35,6 +35,7 @@
 use Cake\Database\Schema\TableSchema;
 use Cake\Database\Schema\TableSchemaInterface;
 use Cake\Database\Statement\Statement;
+use Closure;
 use InvalidArgumentException;
 use PDO;
 use PDOException;
@@ -391,13 +392,17 @@ public function prepare(Query|string $query): StatementInterface
             );
         }
 
-        $typeMap = null;
-        if ($query instanceof SelectQuery && $query->isResultsCastingEnabled()) {
-            $typeMap = $query->getSelectTypeMap();
+        $decorators = [];
+        if ($query instanceof SelectQuery) {
+            $decorators = $query->getResultDecorators();
+            if ($query->isResultsCastingEnabled()) {
+                $typeConverter = new FieldTypeConverter($query->getSelectTypeMap(), $this);
+                array_unshift($decorators, Closure::fromCallable($typeConverter));
+            }
         }
 
         /** @var \Cake\Database\StatementInterface */
-        return new (static::STATEMENT_CLASS)($statement, $this, $typeMap);
+        return new (static::STATEMENT_CLASS)($statement, $this, $decorators);
     }
 
     /**

src/Database/Driver/Mysql.php

@@ -18,8 +18,11 @@
 
 use Cake\Database\Driver;
 use Cake\Database\DriverFeatureEnum;
+use Cake\Database\Query;
+use Cake\Database\Query\SelectQuery;
 use Cake\Database\Schema\MysqlSchemaDialect;
 use Cake\Database\Schema\SchemaDialect;
+use Cake\Database\StatementInterface;
 use PDO;
 
 /**
@@ -157,6 +160,28 @@ public function connect(): void
         }
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function run(Query $query): StatementInterface
+    {
+        $statement = $this->prepare($query);
+        $query->getValueBinder()->attachTo($statement);
+
+        if ($query instanceof SelectQuery) {
+            try {
+                $this->getPdo()->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, $query->isBufferedResultsEnabled());
+                $this->executeStatement($statement);
+            } finally {
+                $this->getPdo()->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, true);
+            }
+        } else {
+            $this->executeStatement($statement);
+        }
+
+        return $statement;
+    }
+
     /**
      * Returns whether php is able to use this driver for connecting to database
      *

src/Database/Query/SelectQuery.php

@@ -74,7 +74,7 @@
      * statement upon retrieval. Each one of the callback function will receive
      * the row array as first argument.
      *
-     * @var array<\Closure>
+     * @var list<\Closure>
      */
     protected array $_resultDecorators = [];
 
@@ -85,6 +85,14 @@
      */
     protected ?iterable $_results = null;
 
+    /**
+     * Boolean for tracking whether buffered results
+     * are enabled.
+     *
+     * @var bool
+     */
+    protected bool $useBufferedResults = true;
+
     /**
      * The Type map for fields in the select clause
      *
@@ -111,13 +119,6 @@
     {
         if ($this->_results === null || $this->_dirty) {
             $this->_results = $this->execute()->fetchAll(StatementInterface::FETCH_TYPE_ASSOC);
-            if ($this->_resultDecorators) {
-                foreach ($this->_results as &$row) {
-                    foreach ($this->_resultDecorators as $decorator) {
-                        $row = $decorator($row);
-                    }
-                }
-            }
         }
 
         return $this->_results;
@@ -761,17 +762,21 @@
      * iterated without having to call all() manually, thus making it look like
      * a result set instead of the query itself.
      *
      * @return \Traversable
      */
     public function getIterator(): Traversable
     {
-        /** @var \Traversable|array $results */
-        $results = $this->all();
-        if (is_array($results)) {
-            return new ArrayIterator($results);
+        if ($this->useBufferedResults) {
+            /** @var \Traversable|array $results */
+            $results = $this->all();
+            if (is_array($results)) {
+                return new ArrayIterator($results);
+            }
+
+            return $results;
         }
 
-        return $results;
+        return $this->execute();
     }
 
     /**
@@ -816,6 +821,69 @@
         return $this;
     }
 
+    /**
+     * Get result decorators.
+     *
+     * @return array
+     */
+    public function getResultDecorators(): array
+    {
+        return $this->_resultDecorators;
+    }
+
+    /**
+     * Enables/Disables buffered results.
+     *
+     * When enabled the results returned by this query will be
+     * buffered. This enables you to iterate a result set multiple times, or
+     * both cache and iterate it.
+     *
+     * When disabled it will consume less memory as fetched results are not
+     * remembered for future iterations.
+     *
+     * @return $this
+     */
+    public function enableBufferedResults()
+    {
+        $this->_dirty();
+        $this->useBufferedResults = true;
+
+        return $this;
+    }
+
+    /**
+     * Disables buffered results.
+     *
+     * Disabling buffering will consume less memory as fetched results are not
+     * remembered for future iterations.
+     *
+     * @return $this
+     */
+    public function disableBufferedResults()
+    {
+        $this->_dirty();
+        $this->useBufferedResults = false;
+
+        return $this;
+    }
+
+    /**
+     * Returns whether buffered results are enabled/disabled.
+     *
+     * When enabled the results returned by this query will be
+     * buffered. This enables you to iterate a result set multiple times, or
+     * both cache and iterate it.
+     *
+     * When disabled it will consume less memory as fetched results are not
+     * remembered for future iterations.
+     *
+     * @return bool
+     */
+    public function isBufferedResultsEnabled(): bool
+    {
+        return $this->useBufferedResults;
+    }
+
     /**
      * Sets the TypeMap class where the types for each of the fields in the
      * select clause are stored.

src/Database/Statement/Statement.php

@@ -17,16 +17,16 @@
 namespace Cake\Database\Statement;
 
 use Cake\Database\Driver;
-use Cake\Database\FieldTypeConverter;
 use Cake\Database\StatementInterface;
 use Cake\Database\TypeFactory;
 use Cake\Database\TypeInterface;
-use Cake\Database\TypeMap;
+use Generator;
 use InvalidArgumentException;
+use IteratorAggregate;
 use PDO;
 use PDOStatement;
 
-class Statement implements StatementInterface
+class Statement implements StatementInterface, IteratorAggregate
 {
     /**
      * @var array<string, int>
@@ -42,16 +42,6 @@
      */
     protected Driver $_driver;
 
-    /**
-     * @var \PDOStatement
-     */
-    protected PDOStatement $statement;
-
-    /**
-     * @var \Cake\Database\FieldTypeConverter|null
-     */
-    protected ?FieldTypeConverter $typeConverter;
-
     /**
      * Cached bound parameters used for logging
      *
@@ -62,16 +52,14 @@
     /**
      * @param \PDOStatement $statement PDO statement
      * @param \Cake\Database\Driver $driver Database driver
-     * @param \Cake\Database\TypeMap|null $typeMap Results type map
+     * @param list<\Closure> $resultDecorators Results decorators
      */
     public function __construct(
-        PDOStatement $statement,
+        protected PDOStatement $statement,
         Driver $driver,
-        ?TypeMap $typeMap = null,
+        protected array $resultDecorators = [],
     ) {
         $this->_driver = $driver;
-        $this->statement = $statement;
-        $this->typeConverter = $typeMap !== null ? new FieldTypeConverter($typeMap, $driver) : null;
     }
 
     /**
@@ -170,8 +158,8 @@
             return false;
         }
 
-        if ($this->typeConverter !== null) {
-            return ($this->typeConverter)($row);
+        foreach ($this->resultDecorators as $decorator) {
+            $row = $decorator($row);
         }
 
         return $row;
@@ -206,8 +194,8 @@
         $mode = $this->convertMode($mode);
         $rows = $this->statement->fetchAll($mode);
 
-        if ($this->typeConverter !== null) {
-            return array_map($this->typeConverter, $rows);
+        foreach ($this->resultDecorators as $decorator) {
+            $rows = array_map($decorator, $rows);
         }
 
         return $rows;
@@ -297,4 +285,24 @@
     {
         return $this->statement->queryString;
     }
+
+    /**
+     * Get the inner iterator
+     *
+     * @return \Generator
+     */
+    public function getIterator(): Generator
+    {
+        $this->statement->setFetchMode(PDO::FETCH_ASSOC);
+
+        foreach ($this->statement as $row) {
+            foreach ($this->resultDecorators as $decorator) {
+                $row = $decorator($row);
+            }
+
+            yield $row;
+        }
+
+        $this->closeCursor();
+    }
 }