Subversion-Projekte lars-tiefland.laravel_shop

<?php

namespace Doctrine\DBAL;

use Closure;

use Doctrine\Common\EventManager;

use Doctrine\DBAL\Cache\ArrayResult;

use Doctrine\DBAL\Cache\CacheException;

use Doctrine\DBAL\Cache\QueryCacheProfile;

use Doctrine\DBAL\Driver\API\ExceptionConverter;

use Doctrine\DBAL\Driver\Connection as DriverConnection;

use Doctrine\DBAL\Driver\ServerInfoAwareConnection;

use Doctrine\DBAL\Driver\Statement as DriverStatement;

use Doctrine\DBAL\Event\TransactionBeginEventArgs;

use Doctrine\DBAL\Event\TransactionCommitEventArgs;

use Doctrine\DBAL\Event\TransactionRollBackEventArgs;

use Doctrine\DBAL\Exception\ConnectionLost;

use Doctrine\DBAL\Exception\DriverException;

use Doctrine\DBAL\Exception\InvalidArgumentException;

use Doctrine\DBAL\Platforms\AbstractPlatform;

use Doctrine\DBAL\Query\Expression\ExpressionBuilder;

use Doctrine\DBAL\Query\QueryBuilder;

use Doctrine\DBAL\Schema\AbstractSchemaManager;

use Doctrine\DBAL\SQL\Parser;

use Doctrine\DBAL\Types\Type;

use Doctrine\Deprecations\Deprecation;

use LogicException;

use Throwable;

use Traversable;

use function array_key_exists;

use function assert;

use function count;

use function get_class;

use function implode;

use function is_int;

use function is_string;

use function key;

use function method_exists;

use function sprintf;

/**

 * A database abstraction-level connection that implements features like events, transaction isolation levels,

 * configuration, emulated transaction nesting, lazy connecting and more.

 *

 * @psalm-import-type Params from DriverManager

 * @psalm-consistent-constructor

 */

class Connection

{

    /**

     * Represents an array of ints to be expanded by Doctrine SQL parsing.

     */

    public const PARAM_INT_ARRAY = ParameterType::INTEGER + self::ARRAY_PARAM_OFFSET;

    /**

     * Represents an array of strings to be expanded by Doctrine SQL parsing.

     */

    public const PARAM_STR_ARRAY = ParameterType::STRING + self::ARRAY_PARAM_OFFSET;

    /**

     * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.

     */

    public const PARAM_ASCII_STR_ARRAY = ParameterType::ASCII + self::ARRAY_PARAM_OFFSET;

    /**

     * Offset by which PARAM_* constants are detected as arrays of the param type.

     *

     * @internal Should be used only within the wrapper layer.

     */

    public const ARRAY_PARAM_OFFSET = 100;

    /**

     * The wrapped driver connection.

     *

     * @var \Doctrine\DBAL\Driver\Connection|null

     */

    protected $_conn;

    /** @var Configuration */

    protected $_config;

    /**

     * @deprecated

     *

     * @var EventManager

     */

    protected $_eventManager;

    /**

     * @deprecated Use {@see createExpressionBuilder()} instead.

     *

     * @var ExpressionBuilder

     */

    protected $_expr;

    /**

     * The current auto-commit mode of this connection.

     */

    private bool $autoCommit = true;

    /**

     * The transaction nesting level.

     */

    private int $transactionNestingLevel = 0;

    /**

     * The currently active transaction isolation level or NULL before it has been determined.

     *

     * @var TransactionIsolationLevel::*|null

     */

    private $transactionIsolationLevel;

    /**

     * If nested transactions should use savepoints.

     */

    private bool $nestTransactionsWithSavepoints = false;

    /**

     * The parameters used during creation of the Connection instance.

     *

     * @var array<string,mixed>

     * @psalm-var Params

     */

    private array $params;

    /**

     * The database platform object used by the connection or NULL before it's initialized.

     */

    private ?AbstractPlatform $platform = null;

    private ?ExceptionConverter $exceptionConverter = null;

    private ?Parser $parser                         = null;

    /**

     * The schema manager.

     *

     * @deprecated Use {@see createSchemaManager()} instead.

     *

     * @var AbstractSchemaManager|null

     */

    protected $_schemaManager;

    /**

     * The used DBAL driver.

     *

     * @var Driver

     */

    protected $_driver;

    /**

     * Flag that indicates whether the current transaction is marked for rollback only.

     */

    private bool $isRollbackOnly = false;

    /**

     * Initializes a new instance of the Connection class.

     *

     * @internal The connection can be only instantiated by the driver manager.

     *

     * @param array<string,mixed> $params       The connection parameters.

     * @param Driver              $driver       The driver to use.

     * @param Configuration|null  $config       The configuration, optional.

     * @param EventManager|null   $eventManager The event manager, optional.

     * @psalm-param Params $params

     *

     * @throws Exception

     */

    public function __construct(

        array $params,

        Driver $driver,

        ?Configuration $config = null,

        ?EventManager $eventManager = null

    ) {

        $this->_driver = $driver;

        $this->params  = $params;

        // Create default config and event manager if none given

        $config       ??= new Configuration();

        $eventManager ??= new EventManager();

        $this->_config       = $config;

        $this->_eventManager = $eventManager;

        if (isset($params['platform'])) {

            if (! $params['platform'] instanceof Platforms\AbstractPlatform) {

                throw Exception::invalidPlatformType($params['platform']);

            }

            Deprecation::trigger(

                'doctrine/dbal',

                'https://github.com/doctrine/dbal/pull/5699',

                'The "platform" connection parameter is deprecated.'

                    . ' Use a driver middleware that would instantiate the platform instead.',

            );

            $this->platform = $params['platform'];

            $this->platform->setEventManager($this->_eventManager);

        }

        $this->_expr = $this->createExpressionBuilder();

        $this->autoCommit = $config->getAutoCommit();

    }

    /**

     * Gets the parameters used during instantiation.

     *

     * @internal

     *

     * @return array<string,mixed>

     * @psalm-return Params

     */

    public function getParams()

    {

        return $this->params;

    }

    /**

     * Gets the name of the currently selected database.

     *

     * @return string|null The name of the database or NULL if a database is not selected.

     *                     The platforms which don't support the concept of a database (e.g. embedded databases)

     *                     must always return a string as an indicator of an implicitly selected database.

     *

     * @throws Exception

     */

    public function getDatabase()

    {

        $platform = $this->getDatabasePlatform();

        $query    = $platform->getDummySelectSQL($platform->getCurrentDatabaseExpression());

        $database = $this->fetchOne($query);

        assert(is_string($database) || $database === null);

        return $database;

    }

    /**

     * Gets the DBAL driver instance.

     *

     * @return Driver

     */

    public function getDriver()

    {

        return $this->_driver;

    }

    /**

     * Gets the Configuration used by the Connection.

     *

     * @return Configuration

     */

    public function getConfiguration()

    {

        return $this->_config;

    }

    /**

     * Gets the EventManager used by the Connection.

     *

     * @deprecated

     *

     * @return EventManager

     */

    public function getEventManager()

    {

        Deprecation::triggerIfCalledFromOutside(

            'doctrine/dbal',

            'https://github.com/doctrine/dbal/issues/5784',

            '%s is deprecated.',

            __METHOD__,

        );

        return $this->_eventManager;

    }

    /**

     * Gets the DatabasePlatform for the connection.

     *

     * @return AbstractPlatform

     *

     * @throws Exception

     */

    public function getDatabasePlatform()

    {

        if ($this->platform === null) {

            $this->platform = $this->detectDatabasePlatform();

            $this->platform->setEventManager($this->_eventManager);

        }

        return $this->platform;

    }

    /**

     * Creates an expression builder for the connection.

     */

    public function createExpressionBuilder(): ExpressionBuilder

    {

        return new ExpressionBuilder($this);

    }

    /**

     * Gets the ExpressionBuilder for the connection.

     *

     * @deprecated Use {@see createExpressionBuilder()} instead.

     *

     * @return ExpressionBuilder

     */

    public function getExpressionBuilder()

    {

        Deprecation::triggerIfCalledFromOutside(

            'doctrine/dbal',

            'https://github.com/doctrine/dbal/issues/4515',

            'Connection::getExpressionBuilder() is deprecated,'

                . ' use Connection::createExpressionBuilder() instead.',

        );

        return $this->_expr;

    }

    /**

     * Establishes the connection with the database.

     *

     * @internal This method will be made protected in DBAL 4.0.

     *

     * @return bool TRUE if the connection was successfully established, FALSE if

     *              the connection is already open.

     *

     * @throws Exception

     */

    public function connect()

    {

        Deprecation::triggerIfCalledFromOutside(

            'doctrine/dbal',

            'https://github.com/doctrine/dbal/issues/4966',

            'Public access to Connection::connect() is deprecated.',

        );

        if ($this->_conn !== null) {

            return false;

        }

        try {

            $this->_conn = $this->_driver->connect($this->params);

        } catch (Driver\Exception $e) {

            throw $this->convertException($e);

        }

        if ($this->autoCommit === false) {

            $this->beginTransaction();

        }

        if ($this->_eventManager->hasListeners(Events::postConnect)) {

            Deprecation::trigger(

                'doctrine/dbal',

                'https://github.com/doctrine/dbal/issues/5784',

                'Subscribing to %s events is deprecated. Implement a middleware instead.',

                Events::postConnect,

            );

            $eventArgs = new Event\ConnectionEventArgs($this);

            $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);

        }

        return true;

    }

    /**

     * Detects and sets the database platform.

     *

     * Evaluates custom platform class and version in order to set the correct platform.

     *

     * @throws Exception If an invalid platform was specified for this connection.

     */

    private function detectDatabasePlatform(): AbstractPlatform

    {

        $version = $this->getDatabasePlatformVersion();

        if ($version !== null) {

            assert($this->_driver instanceof VersionAwarePlatformDriver);

            return $this->_driver->createDatabasePlatformForVersion($version);

        }

        return $this->_driver->getDatabasePlatform();

    }

    /**

     * Returns the version of the related platform if applicable.

     *

     * Returns null if either the driver is not capable to create version

     * specific platform instances, no explicit server version was specified

     * or the underlying driver connection cannot determine the platform

     * version without having to query it (performance reasons).

     *

     * @return string|null

     *

     * @throws Throwable

     */

    private function getDatabasePlatformVersion()

    {

        // Driver does not support version specific platforms.

        if (! $this->_driver instanceof VersionAwarePlatformDriver) {

            return null;

        }

        // Explicit platform version requested (supersedes auto-detection).

        if (isset($this->params['serverVersion'])) {

            return $this->params['serverVersion'];

        }

        // If not connected, we need to connect now to determine the platform version.

        if ($this->_conn === null) {

            try {

                $this->connect();

            } catch (Exception $originalException) {

                if (! isset($this->params['dbname'])) {

                    throw $originalException;

                }

                Deprecation::trigger(

                    'doctrine/dbal',

                    'https://github.com/doctrine/dbal/pull/5707',

                    'Relying on a fallback connection used to determine the database platform while connecting'

                        . ' to a non-existing database is deprecated. Either use an existing database name in'

                        . ' connection parameters or omit the database name if the platform'

                        . ' and the server configuration allow that.',

                );

                // The database to connect to might not yet exist.

                // Retry detection without database name connection parameter.

                $params = $this->params;

                unset($this->params['dbname']);

                try {

                    $this->connect();

                } catch (Exception $fallbackException) {

                    // Either the platform does not support database-less connections

                    // or something else went wrong.

                    throw $originalException;

                } finally {

                    $this->params = $params;

                }

                $serverVersion = $this->getServerVersion();

                // Close "temporary" connection to allow connecting to the real database again.

                $this->close();

                return $serverVersion;

            }

        }

        return $this->getServerVersion();

    }

    /**

     * Returns the database server version if the underlying driver supports it.

     *

     * @return string|null

     *

     * @throws Exception

     */

    private function getServerVersion()

    {

        $connection = $this->getWrappedConnection();

        // Automatic platform version detection.

        if ($connection instanceof ServerInfoAwareConnection) {

            try {

                return $connection->getServerVersion();

            } catch (Driver\Exception $e) {

                throw $this->convertException($e);

            }

        }

        Deprecation::trigger(

            'doctrine/dbal',

            'https://github.com/doctrine/dbal/pull/4750',

            'Not implementing the ServerInfoAwareConnection interface in %s is deprecated',

            get_class($connection),

        );

        // Unable to detect platform version.

        return null;

    }

    /**

     * Returns the current auto-commit mode for this connection.

     *

     * @see    setAutoCommit

     *

     * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.

     */

    public function isAutoCommit()

    {

        return $this->autoCommit === true;

    }

    /**

     * Sets auto-commit mode for this connection.

     *

     * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual

     * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either

     * the method commit or the method rollback. By default, new connections are in auto-commit mode.

     *

     * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is

     * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.

     *

     * @see   isAutoCommit

     *

     * @param bool $autoCommit True to enable auto-commit mode; false to disable it.

     *

     * @return void

     */

    public function setAutoCommit($autoCommit)

    {

        $autoCommit = (bool) $autoCommit;

        // Mode not changed, no-op.

        if ($autoCommit === $this->autoCommit) {

            return;

        }

        $this->autoCommit = $autoCommit;

        // Commit all currently active transactions if any when switching auto-commit mode.

        if ($this->_conn === null || $this->transactionNestingLevel === 0) {

            return;

        }

        $this->commitAll();

    }

    /**

     * Prepares and executes an SQL query and returns the first row of the result

     * as an associative array.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return array<string, mixed>|false False is returned if no rows are found.

     *

     * @throws Exception

     */

    public function fetchAssociative(string $query, array $params = [], array $types = [])

    {

        return $this->executeQuery($query, $params, $types)->fetchAssociative();

    }

    /**

     * Prepares and executes an SQL query and returns the first row of the result

     * as a numerically indexed array.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return list<mixed>|false False is returned if no rows are found.

     *

     * @throws Exception

     */

    public function fetchNumeric(string $query, array $params = [], array $types = [])

    {

        return $this->executeQuery($query, $params, $types)->fetchNumeric();

    }

    /**

     * Prepares and executes an SQL query and returns the value of a single column

     * of the first row of the result.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return mixed|false False is returned if no rows are found.

     *

     * @throws Exception

     */

    public function fetchOne(string $query, array $params = [], array $types = [])

    {

        return $this->executeQuery($query, $params, $types)->fetchOne();

    }

    /**

     * Whether an actual connection to the database is established.

     *

     * @return bool

     */

    public function isConnected()

    {

        return $this->_conn !== null;

    }

    /**

     * Checks whether a transaction is currently active.

     *

     * @return bool TRUE if a transaction is currently active, FALSE otherwise.

     */

    public function isTransactionActive()

    {

        return $this->transactionNestingLevel > 0;

    }

    /**

     * Adds condition based on the criteria to the query components

     *

     * @param array<string,mixed> $criteria   Map of key columns to their values

     * @param string[]            $columns    Column names

     * @param mixed[]             $values     Column values

     * @param string[]            $conditions Key conditions

     *

     * @throws Exception

     */

    private function addCriteriaCondition(

        array $criteria,

        array &$columns,

        array &$values,

        array &$conditions

    ): void {

        $platform = $this->getDatabasePlatform();

        foreach ($criteria as $columnName => $value) {

            if ($value === null) {

                $conditions[] = $platform->getIsNullExpression($columnName);

                continue;

            }

            $columns[]    = $columnName;

            $values[]     = $value;

            $conditions[] = $columnName . ' = ?';

        }

    }

    /**

     * Executes an SQL DELETE statement on a table.

     *

     * Table expression and columns are not escaped and are not safe for user-input.

     *

     * @param string                                                               $table    Table name

     * @param array<string, mixed>                                                 $criteria Deletion criteria

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types

     *

     * @return int|string The number of affected rows.

     *

     * @throws Exception

     */

    public function delete($table, array $criteria, array $types = [])

    {

        if (count($criteria) === 0) {

            throw InvalidArgumentException::fromEmptyCriteria();

        }

        $columns = $values = $conditions = [];

        $this->addCriteriaCondition($criteria, $columns, $values, $conditions);

        return $this->executeStatement(

            'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),

            $values,

            is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types,

        );

    }

    /**

     * Closes the connection.

     *

     * @return void

     */

    public function close()

    {

        $this->_conn                   = null;

        $this->transactionNestingLevel = 0;

    }

    /**

     * Sets the transaction isolation level.

     *

     * @param TransactionIsolationLevel::* $level The level to set.

     *

     * @return int|string

     *

     * @throws Exception

     */

    public function setTransactionIsolation($level)

    {

        $this->transactionIsolationLevel = $level;

        return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));

    }

    /**

     * Gets the currently active transaction isolation level.

     *

     * @return TransactionIsolationLevel::* The current transaction isolation level.

     *

     * @throws Exception

     */

    public function getTransactionIsolation()

    {

        return $this->transactionIsolationLevel ??= $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();

    }

    /**

     * Executes an SQL UPDATE statement on a table.

     *

     * Table expression and columns are not escaped and are not safe for user-input.

     *

     * @param string                                                               $table    Table name

     * @param array<string, mixed>                                                 $data     Column-value pairs

     * @param array<string, mixed>                                                 $criteria Update criteria

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types

     *

     * @return int|string The number of affected rows.

     *

     * @throws Exception

     */

    public function update($table, array $data, array $criteria, array $types = [])

    {

        $columns = $values = $conditions = $set = [];

        foreach ($data as $columnName => $value) {

            $columns[] = $columnName;

            $values[]  = $value;

            $set[]     = $columnName . ' = ?';

        }

        $this->addCriteriaCondition($criteria, $columns, $values, $conditions);

        if (is_string(key($types))) {

            $types = $this->extractTypeValues($columns, $types);

        }

        $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)

                . ' WHERE ' . implode(' AND ', $conditions);

        return $this->executeStatement($sql, $values, $types);

    }

    /**

     * Inserts a table row with specified data.

     *

     * Table expression and columns are not escaped and are not safe for user-input.

     *

     * @param string                                                               $table Table name

     * @param array<string, mixed>                                                 $data  Column-value pairs

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types

     *

     * @return int|string The number of affected rows.

     *

     * @throws Exception

     */

    public function insert($table, array $data, array $types = [])

    {

        if (count($data) === 0) {

            return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');

        }

        $columns = [];

        $values  = [];

        $set     = [];

        foreach ($data as $columnName => $value) {

            $columns[] = $columnName;

            $values[]  = $value;

            $set[]     = '?';

        }

        return $this->executeStatement(

            'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .

            ' VALUES (' . implode(', ', $set) . ')',

            $values,

            is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types,

        );

    }

    /**

     * Extract ordered type list from an ordered column list and type map.

     *

     * @param array<int, string>                                                   $columnList

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types

     *

     * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>

     */

    private function extractTypeValues(array $columnList, array $types): array

    {

        $typeValues = [];

        foreach ($columnList as $columnName) {

            $typeValues[] = $types[$columnName] ?? ParameterType::STRING;

        }

        return $typeValues;

    }

    /**

     * Quotes a string so it can be safely used as a table or column name, even if

     * it is a reserved name.

     *

     * Delimiting style depends on the underlying database platform that is being used.

     *

     * NOTE: Just because you CAN use quoted identifiers does not mean

     * you SHOULD use them. In general, they end up causing way more

     * problems than they solve.

     *

     * @param string $str The name to be quoted.

     *

     * @return string The quoted name.

     */

    public function quoteIdentifier($str)

    {

        return $this->getDatabasePlatform()->quoteIdentifier($str);

    }

    /**

     * The usage of this method is discouraged. Use prepared statements

     * or {@see AbstractPlatform::quoteStringLiteral()} instead.

     *

     * @param mixed                $value

     * @param int|string|Type|null $type

     *

     * @return mixed

     */

    public function quote($value, $type = ParameterType::STRING)

    {

        $connection = $this->getWrappedConnection();

        [$value, $bindingType] = $this->getBindingInfo($value, $type);

        return $connection->quote($value, $bindingType);

    }

    /**

     * Prepares and executes an SQL query and returns the result as an array of numeric arrays.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return list<list<mixed>>

     *

     * @throws Exception

     */

    public function fetchAllNumeric(string $query, array $params = [], array $types = []): array

    {

        return $this->executeQuery($query, $params, $types)->fetchAllNumeric();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an array of associative arrays.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return list<array<string,mixed>>

     *

     * @throws Exception

     */

    public function fetchAllAssociative(string $query, array $params = [], array $types = []): array

    {

        return $this->executeQuery($query, $params, $types)->fetchAllAssociative();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an associative array with the keys

     * mapped to the first column and the values mapped to the second column.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return array<mixed,mixed>

     *

     * @throws Exception

     */

    public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array

    {

        return $this->executeQuery($query, $params, $types)->fetchAllKeyValue();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped

     * to the first column and the values being an associative array representing the rest of the columns

     * and their values.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return array<mixed,array<string,mixed>>

     *

     * @throws Exception

     */

    public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array

    {

        return $this->executeQuery($query, $params, $types)->fetchAllAssociativeIndexed();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an array of the first column values.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return list<mixed>

     *

     * @throws Exception

     */

    public function fetchFirstColumn(string $query, array $params = [], array $types = []): array

    {

        return $this->executeQuery($query, $params, $types)->fetchFirstColumn();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return Traversable<int,list<mixed>>

     *

     * @throws Exception

     */

    public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable

    {

        return $this->executeQuery($query, $params, $types)->iterateNumeric();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an iterator over rows represented

     * as associative arrays.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return Traversable<int,array<string,mixed>>

     *

     * @throws Exception

     */

    public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable

    {

        return $this->executeQuery($query, $params, $types)->iterateAssociative();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an iterator with the keys

     * mapped to the first column and the values mapped to the second column.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return Traversable<mixed,mixed>

     *

     * @throws Exception

     */

    public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable

    {

        return $this->executeQuery($query, $params, $types)->iterateKeyValue();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped

     * to the first column and the values being an associative array representing the rest of the columns

     * and their values.

     *

     * @param string                                           $query  SQL query

     * @param list<mixed>|array<string, mixed>                 $params Query parameters

     * @param array<int, int|string>|array<string, int|string> $types  Parameter types

     *

     * @return Traversable<mixed,array<string,mixed>>

     *

     * @throws Exception

     */

    public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable

    {

        return $this->executeQuery($query, $params, $types)->iterateAssociativeIndexed();

    }

    /**

     * Prepares and executes an SQL query and returns the result as an iterator over the first column values.

     *

     * @param string                                                               $query  SQL query

     * @param list<mixed>|array<string, mixed>                                     $params Query parameters

     * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types

     *

     * @return Traversable<int,mixed>

     *

     * @throws Exception

     */

    public function iterateColumn(string $query, array $params = [], array $types = []): Traversable

    {