vendor/doctrine/dbal/lib/Doctrine/DBAL/Connection.php line 1276

Open in your IDE?
  1. <?php
  3. namespace Doctrine\DBAL;
  5. use Closure;
  6. use Doctrine\Common\EventManager;
  7. use Doctrine\DBAL\Cache\ArrayStatement;
  8. use Doctrine\DBAL\Cache\CacheException;
  9. use Doctrine\DBAL\Cache\QueryCacheProfile;
  10. use Doctrine\DBAL\Cache\ResultCacheStatement;
  11. use Doctrine\DBAL\Driver\Connection as DriverConnection;
  12. use Doctrine\DBAL\Driver\PingableConnection;
  13. use Doctrine\DBAL\Driver\ResultStatement;
  14. use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
  15. use Doctrine\DBAL\Exception\ConnectionLost;
  16. use Doctrine\DBAL\Exception\InvalidArgumentException;
  17. use Doctrine\DBAL\Exception\NoKeyValue;
  18. use Doctrine\DBAL\Platforms\AbstractPlatform;
  19. use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
  20. use Doctrine\DBAL\Query\QueryBuilder;
  21. use Doctrine\DBAL\Schema\AbstractSchemaManager;
  22. use Doctrine\DBAL\Types\Type;
  23. use Doctrine\Deprecations\Deprecation;
  24. use Throwable;
  25. use Traversable;
  27. use function array_key_exists;
  28. use function array_shift;
  29. use function assert;
  30. use function func_get_args;
  31. use function implode;
  32. use function is_int;
  33. use function is_string;
  34. use function key;
  36. /**
  37.  * A wrapper around a Doctrine\DBAL\Driver\Connection that adds features like
  38.  * events, transaction isolation levels, configuration, emulated transaction nesting,
  39.  * lazy connecting and more.
  40.  *
  41.  * @psalm-import-type Params from DriverManager
  42.  */
  43. class Connection implements DriverConnection
  44. {
  45.     /**
  46.      * Constant for transaction isolation level READ UNCOMMITTED.
  47.      *
  48.      * @deprecated Use TransactionIsolationLevel::READ_UNCOMMITTED.
  49.      */
  50.     public const TRANSACTION_READ_UNCOMMITTED = TransactionIsolationLevel::READ_UNCOMMITTED;
  52.     /**
  53.      * Constant for transaction isolation level READ COMMITTED.
  54.      *
  55.      * @deprecated Use TransactionIsolationLevel::READ_COMMITTED.
  56.      */
  57.     public const TRANSACTION_READ_COMMITTED = TransactionIsolationLevel::READ_COMMITTED;
  59.     /**
  60.      * Constant for transaction isolation level REPEATABLE READ.
  61.      *
  62.      * @deprecated Use TransactionIsolationLevel::REPEATABLE_READ.
  63.      */
  64.     public const TRANSACTION_REPEATABLE_READ = TransactionIsolationLevel::REPEATABLE_READ;
  66.     /**
  67.      * Constant for transaction isolation level SERIALIZABLE.
  68.      *
  69.      * @deprecated Use TransactionIsolationLevel::SERIALIZABLE.
  70.      */
  71.     public const TRANSACTION_SERIALIZABLE = TransactionIsolationLevel::SERIALIZABLE;
  73.     /**
  74.      * Represents an array of ints to be expanded by Doctrine SQL parsing.
  75.      */
  76.     public const PARAM_INT_ARRAY = ParameterType::INTEGER + self::ARRAY_PARAM_OFFSET;
  78.     /**
  79.      * Represents an array of strings to be expanded by Doctrine SQL parsing.
  80.      */
  81.     public const PARAM_STR_ARRAY = ParameterType::STRING + self::ARRAY_PARAM_OFFSET;
  83.     /**
  84.      * Offset by which PARAM_* constants are detected as arrays of the param type.
  85.      */
  86.     public const ARRAY_PARAM_OFFSET = 100;
  88.     /**
  89.      * The wrapped driver connection.
  90.      *
  91.      * @var \Doctrine\DBAL\Driver\Connection|null
  92.      */
  93.     protected $_conn;
  95.     /** @var Configuration */
  96.     protected $_config;
  98.     /** @var EventManager */
  99.     protected $_eventManager;
  101.     /** @var ExpressionBuilder */
  102.     protected $_expr;
  104.     /**
  105.      * The current auto-commit mode of this connection.
  106.      *
  107.      * @var bool
  108.      */
  109.     private $autoCommit = true;
  111.     /**
  112.      * The transaction nesting level.
  113.      *
  114.      * @var int
  115.      */
  116.     private $transactionNestingLevel = 0;
  118.     /**
  119.      * The currently active transaction isolation level or NULL before it has been determined.
  120.      *
  121.      * @var int|null
  122.      */
  123.     private $transactionIsolationLevel;
  125.     /**
  126.      * If nested transactions should use savepoints.
  127.      *
  128.      * @var bool
  129.      */
  130.     private $nestTransactionsWithSavepoints = false;
  132.     /**
  133.      * The parameters used during creation of the Connection instance.
  134.      *
  135.      * @var array<string,mixed>
  136.      * @phpstan-var array<string,mixed>
  137.      * @psalm-var Params
  138.      */
  139.     private $params;
  141.     /**
  142.      * The database platform object used by the connection or NULL before it's initialized.
  143.      *
  144.      * @var AbstractPlatform|null
  145.      */
  146.     private $platform;
  148.     /**
  149.      * The schema manager.
  150.      *
  151.      * @var AbstractSchemaManager|null
  152.      */
  153.     protected $_schemaManager;
  155.     /**
  156.      * The used DBAL driver.
  157.      *
  158.      * @var Driver
  159.      */
  160.     protected $_driver;
  162.     /**
  163.      * Flag that indicates whether the current transaction is marked for rollback only.
  164.      *
  165.      * @var bool
  166.      */
  167.     private $isRollbackOnly = false;
  169.     /** @var int */
  170.     protected $defaultFetchMode = FetchMode::ASSOCIATIVE;
  172.     /**
  173.      * Initializes a new instance of the Connection class.
  174.      *
  175.      * @internal The connection can be only instantiated by the driver manager.
  176.      *
  177.      * @param array<string,mixed> $params       The connection parameters.
  178.      * @param Driver              $driver       The driver to use.
  179.      * @param Configuration|null  $config       The configuration, optional.
  180.      * @param EventManager|null   $eventManager The event manager, optional.
  181.      * @psalm-param Params $params
  182.      * @phpstan-param array<string,mixed> $params
  183.      *
  184.      * @throws Exception
  185.      */
  186.     public function __construct(
  187.         array $params,
  188.         Driver $driver,
  189.         ?Configuration $config = null,
  190.         ?EventManager $eventManager = null
  191.     ) {
  192.         $this->_driver = $driver;
  193.         $this->params  = $params;
  195.         if (isset($params['pdo'])) {
  196.             $this->_conn = $params['pdo'];
  197.             unset($this->params['pdo']);
  198.         }
  200.         if (isset($params['platform'])) {
  201.             if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  202.                 throw Exception::invalidPlatformType($params['platform']);
  203.             }
  205.             $this->platform = $params['platform'];
  206.         }
  208.         // Create default config and event manager if none given
  209.         if (! $config) {
  210.             $config = new Configuration();
  211.         }
  213.         if (! $eventManager) {
  214.             $eventManager = new EventManager();
  215.         }
  217.         $this->_config       = $config;
  218.         $this->_eventManager = $eventManager;
  220.         $this->_expr = new Query\Expression\ExpressionBuilder($this);
  222.         $this->autoCommit = $config->getAutoCommit();
  223.     }
  225.     /**
  226.      * Gets the parameters used during instantiation.
  227.      *
  228.      * @internal
  229.      *
  230.      * @return array<string,mixed>
  231.      * @psalm-return Params
  232.      * @phpstan-return array<string,mixed>
  233.      */
  234.     public function getParams()
  235.     {
  236.         return $this->params;
  237.     }
  239.     /**
  240.      * Gets the name of the database this Connection is connected to.
  241.      *
  242.      * @return string
  243.      */
  244.     public function getDatabase()
  245.     {
  246.         return $this->_driver->getDatabase($this);
  247.     }
  249.     /**
  250.      * Gets the hostname of the currently connected database.
  251.      *
  252.      * @deprecated
  253.      *
  254.      * @return string|null
  255.      */
  256.     public function getHost()
  257.     {
  258.         Deprecation::trigger(
  259.             'doctrine/dbal',
  260.             'https://github.com/doctrine/dbal/issues/3580',
  261.             'Connection::getHost() is deprecated, get the database server host from application config ' .
  262.             'or as a last resort from internal Connection::getParams() API.'
  263.         );
  265.         return $this->params['host'] ?? null;
  266.     }
  268.     /**
  269.      * Gets the port of the currently connected database.
  270.      *
  271.      * @deprecated
  272.      *
  273.      * @return mixed
  274.      */
  275.     public function getPort()
  276.     {
  277.         Deprecation::trigger(
  278.             'doctrine/dbal',
  279.             'https://github.com/doctrine/dbal/issues/3580',
  280.             'Connection::getPort() is deprecated, get the database server port from application config ' .
  281.             'or as a last resort from internal Connection::getParams() API.'
  282.         );
  284.         return $this->params['port'] ?? null;
  285.     }
  287.     /**
  288.      * Gets the username used by this connection.
  289.      *
  290.      * @deprecated
  291.      *
  292.      * @return string|null
  293.      */
  294.     public function getUsername()
  295.     {
  296.         Deprecation::trigger(
  297.             'doctrine/dbal',
  298.             'https://github.com/doctrine/dbal/issues/3580',
  299.             'Connection::getUsername() is deprecated, get the username from application config ' .
  300.             'or as a last resort from internal Connection::getParams() API.'
  301.         );
  303.         return $this->params['user'] ?? null;
  304.     }
  306.     /**
  307.      * Gets the password used by this connection.
  308.      *
  309.      * @deprecated
  310.      *
  311.      * @return string|null
  312.      */
  313.     public function getPassword()
  314.     {
  315.         Deprecation::trigger(
  316.             'doctrine/dbal',
  317.             'https://github.com/doctrine/dbal/issues/3580',
  318.             'Connection::getPassword() is deprecated, get the password from application config ' .
  319.             'or as a last resort from internal Connection::getParams() API.'
  320.         );
  322.         return $this->params['password'] ?? null;
  323.     }
  325.     /**
  326.      * Gets the DBAL driver instance.
  327.      *
  328.      * @return Driver
  329.      */
  330.     public function getDriver()
  331.     {
  332.         return $this->_driver;
  333.     }
  335.     /**
  336.      * Gets the Configuration used by the Connection.
  337.      *
  338.      * @return Configuration
  339.      */
  340.     public function getConfiguration()
  341.     {
  342.         return $this->_config;
  343.     }
  345.     /**
  346.      * Gets the EventManager used by the Connection.
  347.      *
  348.      * @return EventManager
  349.      */
  350.     public function getEventManager()
  351.     {
  352.         return $this->_eventManager;
  353.     }
  355.     /**
  356.      * Gets the DatabasePlatform for the connection.
  357.      *
  358.      * @return AbstractPlatform
  359.      *
  360.      * @throws Exception
  361.      */
  362.     public function getDatabasePlatform()
  363.     {
  364.         if ($this->platform === null) {
  365.             $this->platform = $this->detectDatabasePlatform();
  366.             $this->platform->setEventManager($this->_eventManager);
  367.         }
  369.         return $this->platform;
  370.     }
  372.     /**
  373.      * Gets the ExpressionBuilder for the connection.
  374.      *
  375.      * @return ExpressionBuilder
  376.      */
  377.     public function getExpressionBuilder()
  378.     {
  379.         return $this->_expr;
  380.     }
  382.     /**
  383.      * Establishes the connection with the database.
  384.      *
  385.      * @return bool TRUE if the connection was successfully established, FALSE if
  386.      *              the connection is already open.
  387.      */
  388.     public function connect()
  389.     {
  390.         if ($this->_conn !== null) {
  391.             return false;
  392.         }
  394.         $driverOptions = $this->params['driverOptions'] ?? [];
  395.         $user          = $this->params['user'] ?? null;
  396.         $password      = $this->params['password'] ?? null;
  398.         $this->_conn = $this->_driver->connect($this->params, $user, $password, $driverOptions);
  400.         $this->transactionNestingLevel = 0;
  402.         if ($this->autoCommit === false) {
  403.             $this->beginTransaction();
  404.         }
  406.         if ($this->_eventManager->hasListeners(Events::postConnect)) {
  407.             $eventArgs = new Event\ConnectionEventArgs($this);
  408.             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  409.         }
  411.         return true;
  412.     }
  414.     /**
  415.      * Detects and sets the database platform.
  416.      *
  417.      * Evaluates custom platform class and version in order to set the correct platform.
  418.      *
  419.      * @throws Exception If an invalid platform was specified for this connection.
  420.      */
  421.     private function detectDatabasePlatform(): AbstractPlatform
  422.     {
  423.         $version = $this->getDatabasePlatformVersion();
  425.         if ($version !== null) {
  426.             assert($this->_driver instanceof VersionAwarePlatformDriver);
  428.             return $this->_driver->createDatabasePlatformForVersion($version);
  429.         }
  431.         return $this->_driver->getDatabasePlatform();
  432.     }
  434.     /**
  435.      * Returns the version of the related platform if applicable.
  436.      *
  437.      * Returns null if either the driver is not capable to create version
  438.      * specific platform instances, no explicit server version was specified
  439.      * or the underlying driver connection cannot determine the platform
  440.      * version without having to query it (performance reasons).
  441.      *
  442.      * @return string|null
  443.      *
  444.      * @throws Throwable
  445.      */
  446.     private function getDatabasePlatformVersion()
  447.     {
  448.         // Driver does not support version specific platforms.
  449.         if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  450.             return null;
  451.         }
  453.         // Explicit platform version requested (supersedes auto-detection).
  454.         if (isset($this->params['serverVersion'])) {
  455.             return $this->params['serverVersion'];
  456.         }
  458.         // If not connected, we need to connect now to determine the platform version.
  459.         if ($this->_conn === null) {
  460.             try {
  461.                 $this->connect();
  462.             } catch (Throwable $originalException) {
  463.                 if (empty($this->params['dbname'])) {
  464.                     throw $originalException;
  465.                 }
  467.                 // The database to connect to might not yet exist.
  468.                 // Retry detection without database name connection parameter.
  469.                 $params = $this->params;
  471.                 unset($this->params['dbname']);
  473.                 try {
  474.                     $this->connect();
  475.                 } catch (Throwable $fallbackException) {
  476.                     // Either the platform does not support database-less connections
  477.                     // or something else went wrong.
  478.                     throw $originalException;
  479.                 } finally {
  480.                     $this->params = $params;
  481.                 }
  483.                 $serverVersion = $this->getServerVersion();
  485.                 // Close "temporary" connection to allow connecting to the real database again.
  486.                 $this->close();
  488.                 return $serverVersion;
  489.             }
  490.         }
  492.         return $this->getServerVersion();
  493.     }
  495.     /**
  496.      * Returns the database server version if the underlying driver supports it.
  497.      *
  498.      * @return string|null
  499.      */
  500.     private function getServerVersion()
  501.     {
  502.         $connection = $this->getWrappedConnection();
  504.         // Automatic platform version detection.
  505.         if ($connection instanceof ServerInfoAwareConnection && ! $connection->requiresQueryForServerVersion()) {
  506.             return $connection->getServerVersion();
  507.         }
  509.         // Unable to detect platform version.
  510.         return null;
  511.     }
  513.     /**
  514.      * Returns the current auto-commit mode for this connection.
  515.      *
  516.      * @see    setAutoCommit
  517.      *
  518.      * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.
  519.      */
  520.     public function isAutoCommit()
  521.     {
  522.         return $this->autoCommit === true;
  523.     }
  525.     /**
  526.      * Sets auto-commit mode for this connection.
  527.      *
  528.      * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual
  529.      * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either
  530.      * the method commit or the method rollback. By default, new connections are in auto-commit mode.
  531.      *
  532.      * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is
  533.      * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.
  534.      *
  535.      * @see   isAutoCommit
  536.      *
  537.      * @param bool $autoCommit True to enable auto-commit mode; false to disable it.
  538.      *
  539.      * @return void
  540.      */
  541.     public function setAutoCommit($autoCommit)
  542.     {
  543.         $autoCommit = (bool) $autoCommit;
  545.         // Mode not changed, no-op.
  546.         if ($autoCommit === $this->autoCommit) {
  547.             return;
  548.         }
  550.         $this->autoCommit = $autoCommit;
  552.         // Commit all currently active transactions if any when switching auto-commit mode.
  553.         if ($this->_conn === null || $this->transactionNestingLevel === 0) {
  554.             return;
  555.         }
  557.         $this->commitAll();
  558.     }
  560.     /**
  561.      * Sets the fetch mode.
  562.      *
  563.      * @deprecated Use one of the fetch- or iterate-related methods.
  564.      *
  565.      * @param int $fetchMode
  566.      *
  567.      * @return void
  568.      */
  569.     public function setFetchMode($fetchMode)
  570.     {
  571.         Deprecation::trigger(
  572.             'doctrine/dbal',
  573.             'https://github.com/doctrine/dbal/pull/4019',
  574.             'Default Fetch Mode configuration is deprecated, use explicit Connection::fetch*() APIs instead.'
  575.         );
  577.         $this->defaultFetchMode = $fetchMode;
  578.     }
  580.     /**
  581.      * Prepares and executes an SQL query and returns the first row of the result
  582.      * as an associative array.
  583.      *
  584.      * @deprecated Use fetchAssociative()
  585.      *
  586.      * @param string                                                               $sql    SQL query
  587.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  588.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  589.      *
  590.      * @return array<string, mixed>|false False is returned if no rows are found.
  591.      *
  592.      * @throws Exception
  593.      */
  594.     public function fetchAssoc($sql, array $params = [], array $types = [])
  595.     {
  596.         Deprecation::trigger(
  597.             'doctrine/dbal',
  598.             'https://github.com/doctrine/dbal/pull/4019',
  599.             'Connection::fetchAssoc() is deprecated, use Connection::fetchAssociative() API instead.'
  600.         );
  602.         return $this->executeQuery($sql, $params, $types)->fetch(FetchMode::ASSOCIATIVE);
  603.     }
  605.     /**
  606.      * Prepares and executes an SQL query and returns the first row of the result
  607.      * as a numerically indexed array.
  608.      *
  609.      * @deprecated Use fetchNumeric()
  610.      *
  611.      * @param string                                                               $sql    SQL query
  612.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  613.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  614.      *
  615.      * @return array<int, mixed>|false False is returned if no rows are found.
  616.      */
  617.     public function fetchArray($sql, array $params = [], array $types = [])
  618.     {
  619.         Deprecation::trigger(
  620.             'doctrine/dbal',
  621.             'https://github.com/doctrine/dbal/pull/4019',
  622.             'Connection::fetchArray() is deprecated, use Connection::fetchNumeric() API instead.'
  623.         );
  625.         return $this->executeQuery($sql, $params, $types)->fetch(FetchMode::NUMERIC);
  626.     }
  628.     /**
  629.      * Prepares and executes an SQL query and returns the value of a single column
  630.      * of the first row of the result.
  631.      *
  632.      * @deprecated Use fetchOne() instead.
  633.      *
  634.      * @param string                                                               $sql    SQL query
  635.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  636.      * @param int                                                                  $column 0-indexed column number
  637.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  638.      *
  639.      * @return mixed|false False is returned if no rows are found.
  640.      *
  641.      * @throws Exception
  642.      */
  643.     public function fetchColumn($sql, array $params = [], $column = 0, array $types = [])
  644.     {
  645.         Deprecation::trigger(
  646.             'doctrine/dbal',
  647.             'https://github.com/doctrine/dbal/pull/4019',
  648.             'Connection::fetchColumn() is deprecated, use Connection::fetchOne() API instead.'
  649.         );
  651.         return $this->executeQuery($sql, $params, $types)->fetchColumn($column);
  652.     }
  654.     /**
  655.      * Prepares and executes an SQL query and returns the first row of the result
  656.      * as an associative array.
  657.      *
  658.      * @param string                                                               $query  SQL query
  659.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  660.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  661.      *
  662.      * @return array<string, mixed>|false False is returned if no rows are found.
  663.      *
  664.      * @throws Exception
  665.      */
  666.     public function fetchAssociative(string $query, array $params = [], array $types = [])
  667.     {
  668.         try {
  669.             $stmt = $this->ensureForwardCompatibilityStatement(
  670.                 $this->executeQuery($query, $params, $types)
  671.             );
  673.             return $stmt->fetchAssociative();
  674.         } catch (Throwable $e) {
  675.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  676.         }
  677.     }
  679.     /**
  680.      * Prepares and executes an SQL query and returns the first row of the result
  681.      * as a numerically indexed array.
  682.      *
  683.      * @param string                                                               $query  SQL query
  684.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  685.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  686.      *
  687.      * @return array<int, mixed>|false False is returned if no rows are found.
  688.      *
  689.      * @throws Exception
  690.      */
  691.     public function fetchNumeric(string $query, array $params = [], array $types = [])
  692.     {
  693.         try {
  694.             $stmt = $this->ensureForwardCompatibilityStatement(
  695.                 $this->executeQuery($query, $params, $types)
  696.             );
  698.             return $stmt->fetchNumeric();
  699.         } catch (Throwable $e) {
  700.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  701.         }
  702.     }
  704.     /**
  705.      * Prepares and executes an SQL query and returns the value of a single column
  706.      * of the first row of the result.
  707.      *
  708.      * @param string                                                               $query  SQL query
  709.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  710.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  711.      *
  712.      * @return mixed|false False is returned if no rows are found.
  713.      *
  714.      * @throws Exception
  715.      */
  716.     public function fetchOne(string $query, array $params = [], array $types = [])
  717.     {
  718.         try {
  719.             $stmt = $this->ensureForwardCompatibilityStatement(
  720.                 $this->executeQuery($query, $params, $types)
  721.             );
  723.             return $stmt->fetchOne();
  724.         } catch (Throwable $e) {
  725.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  726.         }
  727.     }
  729.     /**
  730.      * Whether an actual connection to the database is established.
  731.      *
  732.      * @return bool
  733.      */
  734.     public function isConnected()
  735.     {
  736.         return $this->_conn !== null;
  737.     }
  739.     /**
  740.      * Checks whether a transaction is currently active.
  741.      *
  742.      * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  743.      */
  744.     public function isTransactionActive()
  745.     {
  746.         return $this->transactionNestingLevel > 0;
  747.     }
  749.     /**
  750.      * Adds condition based on the criteria to the query components
  751.      *
  752.      * @param array<string,mixed> $criteria   Map of key columns to their values
  753.      * @param string[]            $columns    Column names
  754.      * @param mixed[]             $values     Column values
  755.      * @param string[]            $conditions Key conditions
  756.      *
  757.      * @throws Exception
  758.      */
  759.     private function addCriteriaCondition(
  760.         array $criteria,
  761.         array &$columns,
  762.         array &$values,
  763.         array &$conditions
  764.     ): void {
  765.         $platform = $this->getDatabasePlatform();
  767.         foreach ($criteria as $columnName => $value) {
  768.             if ($value === null) {
  769.                 $conditions[] = $platform->getIsNullExpression($columnName);
  770.                 continue;
  771.             }
  773.             $columns[]    = $columnName;
  774.             $values[]     = $value;
  775.             $conditions[] = $columnName . ' = ?';
  776.         }
  777.     }
  779.     /**
  780.      * Executes an SQL DELETE statement on a table.
  781.      *
  782.      * Table expression and columns are not escaped and are not safe for user-input.
  783.      *
  784.      * @param string                                                               $table    Table name
  785.      * @param array<string, mixed>                                                 $criteria Deletion criteria
  786.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  787.      *
  788.      * @return int The number of affected rows.
  789.      *
  790.      * @throws Exception
  791.      */
  792.     public function delete($table, array $criteria, array $types = [])
  793.     {
  794.         if (empty($criteria)) {
  795.             throw InvalidArgumentException::fromEmptyCriteria();
  796.         }
  798.         $columns = $values = $conditions = [];
  800.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  802.         return $this->executeStatement(
  803.             'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  804.             $values,
  805.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  806.         );
  807.     }
  809.     /**
  810.      * Closes the connection.
  811.      *
  812.      * @return void
  813.      */
  814.     public function close()
  815.     {
  816.         $this->_conn = null;
  817.     }
  819.     /**
  820.      * Sets the transaction isolation level.
  821.      *
  822.      * @param int $level The level to set.
  823.      *
  824.      * @return int
  825.      */
  826.     public function setTransactionIsolation($level)
  827.     {
  828.         $this->transactionIsolationLevel = $level;
  830.         return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  831.     }
  833.     /**
  834.      * Gets the currently active transaction isolation level.
  835.      *
  836.      * @return int The current transaction isolation level.
  837.      */
  838.     public function getTransactionIsolation()
  839.     {
  840.         if ($this->transactionIsolationLevel === null) {
  841.             $this->transactionIsolationLevel = $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  842.         }
  844.         return $this->transactionIsolationLevel;
  845.     }
  847.     /**
  848.      * Executes an SQL UPDATE statement on a table.
  849.      *
  850.      * Table expression and columns are not escaped and are not safe for user-input.
  851.      *
  852.      * @param string                                                               $table    Table name
  853.      * @param array<string, mixed>                                                 $data     Column-value pairs
  854.      * @param array<string, mixed>                                                 $criteria Update criteria
  855.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  856.      *
  857.      * @return int The number of affected rows.
  858.      *
  859.      * @throws Exception
  860.      */
  861.     public function update($table, array $data, array $criteria, array $types = [])
  862.     {
  863.         $columns = $values = $conditions = $set = [];
  865.         foreach ($data as $columnName => $value) {
  866.             $columns[] = $columnName;
  867.             $values[]  = $value;
  868.             $set[]     = $columnName . ' = ?';
  869.         }
  871.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  873.         if (is_string(key($types))) {
  874.             $types = $this->extractTypeValues($columns, $types);
  875.         }
  877.         $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  878.                 . ' WHERE ' . implode(' AND ', $conditions);
  880.         return $this->executeStatement($sql, $values, $types);
  881.     }
  883.     /**
  884.      * Inserts a table row with specified data.
  885.      *
  886.      * Table expression and columns are not escaped and are not safe for user-input.
  887.      *
  888.      * @param string                                                               $table Table name
  889.      * @param array<string, mixed>                                                 $data  Column-value pairs
  890.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  891.      *
  892.      * @return int The number of affected rows.
  893.      *
  894.      * @throws Exception
  895.      */
  896.     public function insert($table, array $data, array $types = [])
  897.     {
  898.         if (empty($data)) {
  899.             return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  900.         }
  902.         $columns = [];
  903.         $values  = [];
  904.         $set     = [];
  906.         foreach ($data as $columnName => $value) {
  907.             $columns[] = $columnName;
  908.             $values[]  = $value;
  909.             $set[]     = '?';
  910.         }
  912.         return $this->executeStatement(
  913.             'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  914.             ' VALUES (' . implode(', ', $set) . ')',
  915.             $values,
  916.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  917.         );
  918.     }
  920.     /**
  921.      * Extract ordered type list from an ordered column list and type map.
  922.      *
  923.      * @param array<int, string>                                                   $columnList
  924.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  925.      *
  926.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  927.      */
  928.     private function extractTypeValues(array $columnList, array $types)
  929.     {
  930.         $typeValues = [];
  932.         foreach ($columnList as $columnIndex => $columnName) {
  933.             $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  934.         }
  936.         return $typeValues;
  937.     }
  939.     /**
  940.      * Quotes a string so it can be safely used as a table or column name, even if
  941.      * it is a reserved name.
  942.      *
  943.      * Delimiting style depends on the underlying database platform that is being used.
  944.      *
  945.      * NOTE: Just because you CAN use quoted identifiers does not mean
  946.      * you SHOULD use them. In general, they end up causing way more
  947.      * problems than they solve.
  948.      *
  949.      * @param string $str The name to be quoted.
  950.      *
  951.      * @return string The quoted name.
  952.      */
  953.     public function quoteIdentifier($str)
  954.     {
  955.         return $this->getDatabasePlatform()->quoteIdentifier($str);
  956.     }
  958.     /**
  959.      * {@inheritDoc}
  960.      *
  961.      * @param mixed                $value
  962.      * @param int|string|Type|null $type
  963.      */
  964.     public function quote($value, $type = ParameterType::STRING)
  965.     {
  966.         $connection = $this->getWrappedConnection();
  968.         [$value, $bindingType] = $this->getBindingInfo($value, $type);
  970.         return $connection->quote($value, $bindingType);
  971.     }
  973.     /**
  974.      * Prepares and executes an SQL query and returns the result as an associative array.
  975.      *
  976.      * @deprecated Use fetchAllAssociative()
  977.      *
  978.      * @param string         $sql    The SQL query.
  979.      * @param mixed[]        $params The query parameters.
  980.      * @param int[]|string[] $types  The query parameter types.
  981.      *
  982.      * @return mixed[]
  983.      */
  984.     public function fetchAll($sql, array $params = [], $types = [])
  985.     {
  986.         return $this->executeQuery($sql, $params, $types)->fetchAll();
  987.     }
  989.     /**
  990.      * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  991.      *
  992.      * @param string                                                               $query  SQL query
  993.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  994.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  995.      *
  996.      * @return array<int,array<int,mixed>>
  997.      *
  998.      * @throws Exception
  999.      */
  1000.     public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  1001.     {
  1002.         try {
  1003.             $stmt = $this->ensureForwardCompatibilityStatement(
  1004.                 $this->executeQuery($query, $params, $types)
  1005.             );
  1007.             return $stmt->fetchAllNumeric();
  1008.         } catch (Throwable $e) {
  1009.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1010.         }
  1011.     }
  1013.     /**
  1014.      * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  1015.      *
  1016.      * @param string                                                               $query  SQL query
  1017.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1018.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1019.      *
  1020.      * @return array<int,array<string,mixed>>
  1021.      *
  1022.      * @throws Exception
  1023.      */
  1024.     public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  1025.     {
  1026.         try {
  1027.             $stmt = $this->ensureForwardCompatibilityStatement(
  1028.                 $this->executeQuery($query, $params, $types)
  1029.             );
  1031.             return $stmt->fetchAllAssociative();
  1032.         } catch (Throwable $e) {
  1033.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1034.         }
  1035.     }
  1037.     /**
  1038.      * Prepares and executes an SQL query and returns the result as an associative array with the keys
  1039.      * mapped to the first column and the values mapped to the second column.
  1040.      *
  1041.      * @param string                                           $query  SQL query
  1042.      * @param array<int, mixed>|array<string, mixed>           $params Query parameters
  1043.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1044.      *
  1045.      * @return array<mixed,mixed>
  1046.      *
  1047.      * @throws Exception
  1048.      */
  1049.     public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  1050.     {
  1051.         $stmt = $this->executeQuery($query, $params, $types);
  1053.         $this->ensureHasKeyValue($stmt);
  1055.         $data = [];
  1057.         foreach ($stmt->fetchAll(FetchMode::NUMERIC) as [$key, $value]) {
  1058.             $data[$key] = $value;
  1059.         }
  1061.         return $data;
  1062.     }
  1064.     /**
  1065.      * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  1066.      * to the first column and the values being an associative array representing the rest of the columns
  1067.      * and their values.
  1068.      *
  1069.      * @param string                                           $query  SQL query
  1070.      * @param array<int, mixed>|array<string, mixed>           $params Query parameters
  1071.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1072.      *
  1073.      * @return array<mixed,array<string,mixed>>
  1074.      *
  1075.      * @throws Exception
  1076.      */
  1077.     public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  1078.     {
  1079.         $stmt = $this->executeQuery($query, $params, $types);
  1081.         $data = [];
  1083.         foreach ($stmt->fetchAll(FetchMode::ASSOCIATIVE) as $row) {
  1084.             $data[array_shift($row)] = $row;
  1085.         }
  1087.         return $data;
  1088.     }
  1090.     /**
  1091.      * Prepares and executes an SQL query and returns the result as an array of the first column values.
  1092.      *
  1093.      * @param string                                                               $query  SQL query
  1094.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1095.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1096.      *
  1097.      * @return array<int,mixed>
  1098.      *
  1099.      * @throws Exception
  1100.      */
  1101.     public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  1102.     {
  1103.         try {
  1104.             $stmt = $this->ensureForwardCompatibilityStatement(
  1105.                 $this->executeQuery($query, $params, $types)
  1106.             );
  1108.             return $stmt->fetchFirstColumn();
  1109.         } catch (Throwable $e) {
  1110.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1111.         }
  1112.     }
  1114.     /**
  1115.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  1116.      *
  1117.      * @param string                                                               $query  SQL query
  1118.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1119.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1120.      *
  1121.      * @return Traversable<int,array<int,mixed>>
  1122.      *
  1123.      * @throws Exception
  1124.      */
  1125.     public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  1126.     {
  1127.         try {
  1128.             $stmt = $this->ensureForwardCompatibilityStatement(
  1129.                 $this->executeQuery($query, $params, $types)
  1130.             );
  1132.             yield from $stmt->iterateNumeric();
  1133.         } catch (Throwable $e) {
  1134.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1135.         }
  1136.     }
  1138.     /**
  1139.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  1140.      * as associative arrays.
  1141.      *
  1142.      * @param string                                                               $query  SQL query
  1143.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1144.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1145.      *
  1146.      * @return Traversable<int,array<string,mixed>>
  1147.      *
  1148.      * @throws Exception
  1149.      */
  1150.     public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  1151.     {
  1152.         try {
  1153.             $stmt = $this->ensureForwardCompatibilityStatement(
  1154.                 $this->executeQuery($query, $params, $types)
  1155.             );
  1157.             yield from $stmt->iterateAssociative();
  1158.         } catch (Throwable $e) {
  1159.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1160.         }
  1161.     }
  1163.     /**
  1164.      * Prepares and executes an SQL query and returns the result as an iterator with the keys
  1165.      * mapped to the first column and the values mapped to the second column.
  1166.      *
  1167.      * @param string                                           $query  SQL query
  1168.      * @param array<int, mixed>|array<string, mixed>           $params Query parameters
  1169.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1170.      *
  1171.      * @return Traversable<mixed,mixed>
  1172.      *
  1173.      * @throws Exception
  1174.      */
  1175.     public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  1176.     {
  1177.         $stmt = $this->executeQuery($query, $params, $types);
  1179.         $this->ensureHasKeyValue($stmt);
  1181.         while (($row = $stmt->fetch(FetchMode::NUMERIC)) !== false) {
  1182.             yield $row[0] => $row[1];
  1183.         }
  1184.     }
  1186.     /**
  1187.      * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  1188.      * to the first column and the values being an associative array representing the rest of the columns
  1189.      * and their values.
  1190.      *
  1191.      * @param string                                           $query  SQL query
  1192.      * @param array<int, mixed>|array<string, mixed>           $params Query parameters
  1193.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1194.      *
  1195.      * @return Traversable<mixed,array<string,mixed>>
  1196.      *
  1197.      * @throws Exception
  1198.      */
  1199.     public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  1200.     {
  1201.         $stmt = $this->executeQuery($query, $params, $types);
  1203.         while (($row = $stmt->fetch(FetchMode::ASSOCIATIVE)) !== false) {
  1204.             yield array_shift($row) => $row;
  1205.         }
  1206.     }
  1208.     /**
  1209.      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  1210.      *
  1211.      * @param string                                                               $query  SQL query
  1212.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1213.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1214.      *
  1215.      * @return Traversable<int,mixed>
  1216.      *
  1217.      * @throws Exception
  1218.      */
  1219.     public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  1220.     {
  1221.         try {
  1222.             $stmt = $this->ensureForwardCompatibilityStatement(
  1223.                 $this->executeQuery($query, $params, $types)
  1224.             );
  1226.             yield from $stmt->iterateColumn();
  1227.         } catch (Throwable $e) {
  1228.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1229.         }
  1230.     }
  1232.     /**
  1233.      * Prepares an SQL statement.
  1234.      *
  1235.      * @param string $sql The SQL statement to prepare.
  1236.      *
  1237.      * @return Statement The prepared statement.
  1238.      *
  1239.      * @throws Exception
  1240.      */
  1241.     public function prepare($sql)
  1242.     {
  1243.         try {
  1244.             $stmt = new Statement($sql, $this);
  1245.         } catch (Throwable $e) {
  1246.             $this->handleExceptionDuringQuery($e, $sql);
  1247.         }
  1249.         $stmt->setFetchMode($this->defaultFetchMode);
  1251.         return $stmt;
  1252.     }
  1254.     /**
  1255.      * Executes an, optionally parametrized, SQL query.
  1256.      *
  1257.      * If the query is parametrized, a prepared statement is used.
  1258.      * If an SQLLogger is configured, the execution is logged.
  1259.      *
  1260.      * @param string                                                               $sql    SQL query
  1261.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1262.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1263.      *
  1264.      * @return ForwardCompatibility\DriverStatement|ForwardCompatibility\DriverResultStatement
  1265.      *
  1266.      * The executed statement or the cached result statement if a query cache profile is used
  1267.      *
  1268.      * @throws Exception
  1269.      */
  1270.     public function executeQuery($sql, array $params = [], $types = [], ?QueryCacheProfile $qcp = null)
  1271.     {
  1272.         if ($qcp !== null) {
  1273.             return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1274.         }
  1276.         $connection = $this->getWrappedConnection();
  1278.         $logger = $this->_config->getSQLLogger();
  1279.         if ($logger) {
  1280.             $logger->startQuery($sql, $params, $types);
  1281.         }
  1283.         try {
  1284.             if ($params) {
  1285.                 [$sql, $params, $types] = SQLParserUtils::expandListParameters($sql, $params, $types);
  1287.                 $stmt = $connection->prepare($sql);
  1288.                 if ($types) {
  1289.                     $this->_bindTypedValues($stmt, $params, $types);
  1290.                     $stmt->execute();
  1291.                 } else {
  1292.                     $stmt->execute($params);
  1293.                 }
  1294.             } else {
  1295.                 $stmt = $connection->query($sql);
  1296.             }
  1297.         } catch (Throwable $e) {
  1298.             $this->handleExceptionDuringQuery(
  1299.                 $e,
  1300.                 $sql,
  1301.                 $params,
  1302.                 $types
  1303.             );
  1304.         }
  1306.         $stmt->setFetchMode($this->defaultFetchMode);
  1308.         if ($logger) {
  1309.             $logger->stopQuery();
  1310.         }
  1312.         return $this->ensureForwardCompatibilityStatement($stmt);
  1313.     }
  1315.     /**
  1316.      * Executes a caching query.
  1317.      *
  1318.      * @param string                                                               $sql    SQL query
  1319.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1320.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1321.      *
  1322.      * @return ForwardCompatibility\DriverResultStatement
  1323.      *
  1324.      * @throws CacheException
  1325.      */
  1326.     public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp)
  1327.     {
  1328.         $resultCache = $qcp->getResultCacheDriver() ?? $this->_config->getResultCacheImpl();
  1330.         if ($resultCache === null) {
  1331.             throw CacheException::noResultDriverConfigured();
  1332.         }
  1334.         $connectionParams = $this->params;
  1335.         unset($connectionParams['platform']);
  1337.         [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1339.         // fetch the row pointers entry
  1340.         $data = $resultCache->fetch($cacheKey);
  1342.         if ($data !== false) {
  1343.             // is the real key part of this row pointers map or is the cache only pointing to other cache keys?
  1344.             if (isset($data[$realKey])) {
  1345.                 $stmt = new ArrayStatement($data[$realKey]);
  1346.             } elseif (array_key_exists($realKey, $data)) {
  1347.                 $stmt = new ArrayStatement([]);
  1348.             }
  1349.         }
  1351.         if (! isset($stmt)) {
  1352.             $stmt = new ResultCacheStatement(
  1353.                 $this->executeQuery($sql, $params, $types),
  1354.                 $resultCache,
  1355.                 $cacheKey,
  1356.                 $realKey,
  1357.                 $qcp->getLifetime()
  1358.             );
  1359.         }
  1361.         $stmt->setFetchMode($this->defaultFetchMode);
  1363.         return $this->ensureForwardCompatibilityStatement($stmt);
  1364.     }
  1366.     /**
  1367.      * @return ForwardCompatibility\Result
  1368.      */
  1369.     private function ensureForwardCompatibilityStatement(ResultStatement $stmt)
  1370.     {
  1371.         return ForwardCompatibility\Result::ensure($stmt);
  1372.     }
  1374.     /**
  1375.      * Executes an, optionally parametrized, SQL query and returns the result,
  1376.      * applying a given projection/transformation function on each row of the result.
  1377.      *
  1378.      * @deprecated
  1379.      *
  1380.      * @param string  $sql      The SQL query to execute.
  1381.      * @param mixed[] $params   The parameters, if any.
  1382.      * @param Closure $function The transformation function that is applied on each row.
  1383.      *                           The function receives a single parameter, an array, that
  1384.      *                           represents a row of the result set.
  1385.      *
  1386.      * @return mixed[] The projected result of the query.
  1387.      */
  1388.     public function project($sql, array $params, Closure $function)
  1389.     {
  1390.         Deprecation::trigger(
  1391.             'doctrine/dbal',
  1392.             'https://github.com/doctrine/dbal/pull/3823',
  1393.             'Connection::project() is deprecated without replacement, implement data projections in your own code.'
  1394.         );
  1396.         $result = [];
  1397.         $stmt   = $this->executeQuery($sql, $params);
  1399.         while ($row = $stmt->fetch()) {
  1400.             $result[] = $function($row);
  1401.         }
  1403.         $stmt->closeCursor();
  1405.         return $result;
  1406.     }
  1408.     /**
  1409.      * Executes an SQL statement, returning a result set as a Statement object.
  1410.      *
  1411.      * @deprecated Use {@link executeQuery()} instead.
  1412.      *
  1413.      * @return \Doctrine\DBAL\Driver\Statement
  1414.      *
  1415.      * @throws Exception
  1416.      */
  1417.     public function query()
  1418.     {
  1419.         Deprecation::trigger(
  1420.             'doctrine/dbal',
  1421.             'https://github.com/doctrine/dbal/pull/4163',
  1422.             'Connection::query() is deprecated, use Connection::executeQuery() instead.'
  1423.         );
  1425.         $connection = $this->getWrappedConnection();
  1427.         $args = func_get_args();
  1429.         $logger = $this->_config->getSQLLogger();
  1430.         if ($logger) {
  1431.             $logger->startQuery($args[0]);
  1432.         }
  1434.         try {
  1435.             $statement = $connection->query(...$args);
  1436.         } catch (Throwable $e) {
  1437.             $this->handleExceptionDuringQuery($e, $args[0]);
  1438.         }
  1440.         $statement->setFetchMode($this->defaultFetchMode);
  1442.         if ($logger) {
  1443.             $logger->stopQuery();
  1444.         }
  1446.         return $statement;
  1447.     }
  1449.     /**
  1450.      * Executes an SQL INSERT/UPDATE/DELETE query with the given parameters
  1451.      * and returns the number of affected rows.
  1452.      *
  1453.      * This method supports PDO binding types as well as DBAL mapping types.
  1454.      *
  1455.      * @deprecated Use {@link executeStatement()} instead.
  1456.      *
  1457.      * @param string                                                               $sql    SQL statement
  1458.      * @param array<int, mixed>|array<string, mixed>                               $params Statement parameters
  1459.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1460.      *
  1461.      * @return int The number of affected rows.
  1462.      *
  1463.      * @throws Exception
  1464.      */
  1465.     public function executeUpdate($sql, array $params = [], array $types = [])
  1466.     {
  1467.         Deprecation::trigger(
  1468.             'doctrine/dbal',
  1469.             'https://github.com/doctrine/dbal/pull/4163',
  1470.             'Connection::executeUpdate() is deprecated, use Connection::executeStatement() instead.'
  1471.         );
  1473.         return $this->executeStatement($sql, $params, $types);
  1474.     }
  1476.     /**
  1477.      * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1478.      *
  1479.      * Could be used for:
  1480.      *  - DML statements: INSERT, UPDATE, DELETE, etc.
  1481.      *  - DDL statements: CREATE, DROP, ALTER, etc.
  1482.      *  - DCL statements: GRANT, REVOKE, etc.
  1483.      *  - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1484.      *  - Other statements that don't yield a row set.
  1485.      *
  1486.      * This method supports PDO binding types as well as DBAL mapping types.
  1487.      *
  1488.      * @param string                                                               $sql    SQL statement
  1489.      * @param array<int, mixed>|array<string, mixed>                               $params Statement parameters
  1490.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1491.      *
  1492.      * @return int The number of affected rows.
  1493.      *
  1494.      * @throws Exception
  1495.      */
  1496.     public function executeStatement($sql, array $params = [], array $types = [])
  1497.     {
  1498.         $connection = $this->getWrappedConnection();
  1500.         $logger = $this->_config->getSQLLogger();
  1501.         if ($logger) {
  1502.             $logger->startQuery($sql, $params, $types);
  1503.         }
  1505.         try {
  1506.             if ($params) {
  1507.                 [$sql, $params, $types] = SQLParserUtils::expandListParameters($sql, $params, $types);
  1509.                 $stmt = $connection->prepare($sql);
  1511.                 if ($types) {
  1512.                     $this->_bindTypedValues($stmt, $params, $types);
  1513.                     $stmt->execute();
  1514.                 } else {
  1515.                     $stmt->execute($params);
  1516.                 }
  1518.                 $result = $stmt->rowCount();
  1519.             } else {
  1520.                 $result = $connection->exec($sql);
  1521.             }
  1522.         } catch (Throwable $e) {
  1523.             $this->handleExceptionDuringQuery(
  1524.                 $e,
  1525.                 $sql,
  1526.                 $params,
  1527.                 $types
  1528.             );
  1529.         }
  1531.         if ($logger) {
  1532.             $logger->stopQuery();
  1533.         }
  1535.         return $result;
  1536.     }
  1538.     /**
  1539.      * Executes an SQL statement and return the number of affected rows.
  1540.      *
  1541.      * @deprecated Use {@link executeStatement()} instead.
  1542.      *
  1543.      * @param string $sql
  1544.      *
  1545.      * @return int The number of affected rows.
  1546.      *
  1547.      * @throws Exception
  1548.      */
  1549.     public function exec($sql)
  1550.     {
  1551.         Deprecation::trigger(
  1552.             'doctrine/dbal',
  1553.             'https://github.com/doctrine/dbal/pull/4163',
  1554.             'Connection::exec() is deprecated, use Connection::executeStatement() instead.'
  1555.         );
  1557.         $connection = $this->getWrappedConnection();
  1559.         $logger = $this->_config->getSQLLogger();
  1560.         if ($logger) {
  1561.             $logger->startQuery($sql);
  1562.         }
  1564.         try {
  1565.             $result = $connection->exec($sql);
  1566.         } catch (Throwable $e) {
  1567.             $this->handleExceptionDuringQuery($e, $sql);
  1568.         }
  1570.         if ($logger) {
  1571.             $logger->stopQuery();
  1572.         }
  1574.         return $result;
  1575.     }
  1577.     /**
  1578.      * Returns the current transaction nesting level.
  1579.      *
  1580.      * @return int The nesting level. A value of 0 means there's no active transaction.
  1581.      */
  1582.     public function getTransactionNestingLevel()
  1583.     {
  1584.         return $this->transactionNestingLevel;
  1585.     }
  1587.     /**
  1588.      * Fetches the SQLSTATE associated with the last database operation.
  1589.      *
  1590.      * @deprecated The error information is available via exceptions.
  1591.      *
  1592.      * @return string|null The last error code.
  1593.      */
  1594.     public function errorCode()
  1595.     {
  1596.         Deprecation::trigger(
  1597.             'doctrine/dbal',
  1598.             'https://github.com/doctrine/dbal/pull/3507',
  1599.             'Connection::errorCode() is deprecated, use getCode() or getSQLState() on Exception instead.'
  1600.         );
  1602.         return $this->getWrappedConnection()->errorCode();
  1603.     }
  1605.     /**
  1606.      * {@inheritDoc}
  1607.      *
  1608.      * @deprecated The error information is available via exceptions.
  1609.      */
  1610.     public function errorInfo()
  1611.     {
  1612.         Deprecation::trigger(
  1613.             'doctrine/dbal',
  1614.             'https://github.com/doctrine/dbal/pull/3507',
  1615.             'Connection::errorInfo() is deprecated, use getCode() or getSQLState() on Exception instead.'
  1616.         );
  1618.         return $this->getWrappedConnection()->errorInfo();
  1619.     }
  1621.     /**
  1622.      * Returns the ID of the last inserted row, or the last value from a sequence object,
  1623.      * depending on the underlying driver.
  1624.      *
  1625.      * Note: This method may not return a meaningful or consistent result across different drivers,
  1626.      * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1627.      * columns or sequences.
  1628.      *
  1629.      * @param string|null $name Name of the sequence object from which the ID should be returned.
  1630.      *
  1631.      * @return string A string representation of the last inserted ID.
  1632.      */
  1633.     public function lastInsertId($name = null)
  1634.     {
  1635.         return $this->getWrappedConnection()->lastInsertId($name);
  1636.     }
  1638.     /**
  1639.      * Executes a function in a transaction.
  1640.      *
  1641.      * The function gets passed this Connection instance as an (optional) parameter.
  1642.      *
  1643.      * If an exception occurs during execution of the function or transaction commit,
  1644.      * the transaction is rolled back and the exception re-thrown.
  1645.      *
  1646.      * @param Closure $func The function to execute transactionally.
  1647.      *
  1648.      * @return mixed The value returned by $func
  1649.      *
  1650.      * @throws Throwable
  1651.      */
  1652.     public function transactional(Closure $func)
  1653.     {
  1654.         $this->beginTransaction();
  1655.         try {
  1656.             $res = $func($this);
  1657.             $this->commit();
  1659.             return $res;
  1660.         } catch (Throwable $e) {
  1661.             $this->rollBack();
  1663.             throw $e;
  1664.         }
  1665.     }
  1667.     /**
  1668.      * Sets if nested transactions should use savepoints.
  1669.      *
  1670.      * @param bool $nestTransactionsWithSavepoints
  1671.      *
  1672.      * @return void
  1673.      *
  1674.      * @throws ConnectionException
  1675.      */
  1676.     public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1677.     {
  1678.         if ($this->transactionNestingLevel > 0) {
  1679.             throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1680.         }
  1682.         if (! $this->getDatabasePlatform()->supportsSavepoints()) {
  1683.             throw ConnectionException::savepointsNotSupported();
  1684.         }
  1686.         $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1687.     }
  1689.     /**
  1690.      * Gets if nested transactions should use savepoints.
  1691.      *
  1692.      * @return bool
  1693.      */
  1694.     public function getNestTransactionsWithSavepoints()
  1695.     {
  1696.         return $this->nestTransactionsWithSavepoints;
  1697.     }
  1699.     /**
  1700.      * Returns the savepoint name to use for nested transactions are false if they are not supported
  1701.      * "savepointFormat" parameter is not set
  1702.      *
  1703.      * @return mixed A string with the savepoint name or false.
  1704.      */
  1705.     protected function _getNestedTransactionSavePointName()
  1706.     {
  1707.         return 'DOCTRINE2_SAVEPOINT_' . $this->transactionNestingLevel;
  1708.     }
  1710.     /**
  1711.      * {@inheritDoc}
  1712.      */
  1713.     public function beginTransaction()
  1714.     {
  1715.         $connection = $this->getWrappedConnection();
  1717.         ++$this->transactionNestingLevel;
  1719.         $logger = $this->_config->getSQLLogger();
  1721.         if ($this->transactionNestingLevel === 1) {
  1722.             if ($logger) {
  1723.                 $logger->startQuery('"START TRANSACTION"');
  1724.             }
  1726.             $connection->beginTransaction();
  1728.             if ($logger) {
  1729.                 $logger->stopQuery();
  1730.             }
  1731.         } elseif ($this->nestTransactionsWithSavepoints) {
  1732.             if ($logger) {
  1733.                 $logger->startQuery('"SAVEPOINT"');
  1734.             }
  1736.             $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1737.             if ($logger) {
  1738.                 $logger->stopQuery();
  1739.             }
  1740.         }
  1742.         return true;
  1743.     }
  1745.     /**
  1746.      * {@inheritDoc}
  1747.      *
  1748.      * @throws ConnectionException If the commit failed due to no active transaction or
  1749.      *                                            because the transaction was marked for rollback only.
  1750.      */
  1751.     public function commit()
  1752.     {
  1753.         if ($this->transactionNestingLevel === 0) {
  1754.             throw ConnectionException::noActiveTransaction();
  1755.         }
  1757.         if ($this->isRollbackOnly) {
  1758.             throw ConnectionException::commitFailedRollbackOnly();
  1759.         }
  1761.         $result = true;
  1763.         $connection = $this->getWrappedConnection();
  1765.         $logger = $this->_config->getSQLLogger();
  1767.         if ($this->transactionNestingLevel === 1) {
  1768.             if ($logger) {
  1769.                 $logger->startQuery('"COMMIT"');
  1770.             }
  1772.             $result = $connection->commit();
  1774.             if ($logger) {
  1775.                 $logger->stopQuery();
  1776.             }
  1777.         } elseif ($this->nestTransactionsWithSavepoints) {
  1778.             if ($logger) {
  1779.                 $logger->startQuery('"RELEASE SAVEPOINT"');
  1780.             }
  1782.             $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1783.             if ($logger) {
  1784.                 $logger->stopQuery();
  1785.             }
  1786.         }
  1788.         --$this->transactionNestingLevel;
  1790.         if ($this->autoCommit !== false || $this->transactionNestingLevel !== 0) {
  1791.             return $result;
  1792.         }
  1794.         $this->beginTransaction();
  1796.         return $result;
  1797.     }
  1799.     /**
  1800.      * Commits all current nesting transactions.
  1801.      */
  1802.     private function commitAll(): void
  1803.     {
  1804.         while ($this->transactionNestingLevel !== 0) {
  1805.             if ($this->autoCommit === false && $this->transactionNestingLevel === 1) {
  1806.                 // When in no auto-commit mode, the last nesting commit immediately starts a new transaction.
  1807.                 // Therefore we need to do the final commit here and then leave to avoid an infinite loop.
  1808.                 $this->commit();
  1810.                 return;
  1811.             }
  1813.             $this->commit();
  1814.         }
  1815.     }
  1817.     /**
  1818.      * Cancels any database changes done during the current transaction.
  1819.      *
  1820.      * @return bool
  1821.      *
  1822.      * @throws ConnectionException If the rollback operation failed.
  1823.      */
  1824.     public function rollBack()
  1825.     {
  1826.         if ($this->transactionNestingLevel === 0) {
  1827.             throw ConnectionException::noActiveTransaction();
  1828.         }
  1830.         $connection = $this->getWrappedConnection();
  1832.         $logger = $this->_config->getSQLLogger();
  1834.         if ($this->transactionNestingLevel === 1) {
  1835.             if ($logger) {
  1836.                 $logger->startQuery('"ROLLBACK"');
  1837.             }
  1839.             $this->transactionNestingLevel = 0;
  1840.             $connection->rollBack();
  1841.             $this->isRollbackOnly = false;
  1842.             if ($logger) {
  1843.                 $logger->stopQuery();
  1844.             }
  1846.             if ($this->autoCommit === false) {
  1847.                 $this->beginTransaction();
  1848.             }
  1849.         } elseif ($this->nestTransactionsWithSavepoints) {
  1850.             if ($logger) {
  1851.                 $logger->startQuery('"ROLLBACK TO SAVEPOINT"');
  1852.             }
  1854.             $this->rollbackSavepoint($this->_getNestedTransactionSavePointName());
  1855.             --$this->transactionNestingLevel;
  1856.             if ($logger) {
  1857.                 $logger->stopQuery();
  1858.             }
  1859.         } else {
  1860.             $this->isRollbackOnly = true;
  1861.             --$this->transactionNestingLevel;
  1862.         }
  1864.         return true;
  1865.     }
  1867.     /**
  1868.      * Creates a new savepoint.
  1869.      *
  1870.      * @param string $savepoint The name of the savepoint to create.
  1871.      *
  1872.      * @return void
  1873.      *
  1874.      * @throws ConnectionException
  1875.      */
  1876.     public function createSavepoint($savepoint)
  1877.     {
  1878.         $platform = $this->getDatabasePlatform();
  1880.         if (! $platform->supportsSavepoints()) {
  1881.             throw ConnectionException::savepointsNotSupported();
  1882.         }
  1884.         $this->getWrappedConnection()->exec($platform->createSavePoint($savepoint));
  1885.     }
  1887.     /**
  1888.      * Releases the given savepoint.
  1889.      *
  1890.      * @param string $savepoint The name of the savepoint to release.
  1891.      *
  1892.      * @return void
  1893.      *
  1894.      * @throws ConnectionException
  1895.      */
  1896.     public function releaseSavepoint($savepoint)
  1897.     {
  1898.         $platform = $this->getDatabasePlatform();
  1900.         if (! $platform->supportsSavepoints()) {
  1901.             throw ConnectionException::savepointsNotSupported();
  1902.         }
  1904.         if (! $platform->supportsReleaseSavepoints()) {
  1905.             return;
  1906.         }
  1908.         $this->getWrappedConnection()->exec($platform->releaseSavePoint($savepoint));
  1909.     }
  1911.     /**
  1912.      * Rolls back to the given savepoint.
  1913.      *
  1914.      * @param string $savepoint The name of the savepoint to rollback to.
  1915.      *
  1916.      * @return void
  1917.      *
  1918.      * @throws ConnectionException
  1919.      */
  1920.     public function rollbackSavepoint($savepoint)
  1921.     {
  1922.         $platform = $this->getDatabasePlatform();
  1924.         if (! $platform->supportsSavepoints()) {
  1925.             throw ConnectionException::savepointsNotSupported();
  1926.         }
  1928.         $this->getWrappedConnection()->exec($platform->rollbackSavePoint($savepoint));
  1929.     }
  1931.     /**
  1932.      * Gets the wrapped driver connection.
  1933.      *
  1934.      * @return DriverConnection
  1935.      */
  1936.     public function getWrappedConnection()
  1937.     {
  1938.         $this->connect();
  1940.         assert($this->_conn !== null);
  1942.         return $this->_conn;
  1943.     }
  1945.     /**
  1946.      * Gets the SchemaManager that can be used to inspect or change the
  1947.      * database schema through the connection.
  1948.      *
  1949.      * @return AbstractSchemaManager
  1950.      */
  1951.     public function getSchemaManager()
  1952.     {
  1953.         if ($this->_schemaManager === null) {
  1954.             $this->_schemaManager = $this->_driver->getSchemaManager($this);
  1955.         }
  1957.         return $this->_schemaManager;
  1958.     }
  1960.     /**
  1961.      * Marks the current transaction so that the only possible
  1962.      * outcome for the transaction to be rolled back.
  1963.      *
  1964.      * @return void
  1965.      *
  1966.      * @throws ConnectionException If no transaction is active.
  1967.      */
  1968.     public function setRollbackOnly()
  1969.     {
  1970.         if ($this->transactionNestingLevel === 0) {
  1971.             throw ConnectionException::noActiveTransaction();
  1972.         }
  1974.         $this->isRollbackOnly = true;
  1975.     }
  1977.     /**
  1978.      * Checks whether the current transaction is marked for rollback only.
  1979.      *
  1980.      * @return bool
  1981.      *
  1982.      * @throws ConnectionException If no transaction is active.
  1983.      */
  1984.     public function isRollbackOnly()
  1985.     {
  1986.         if ($this->transactionNestingLevel === 0) {
  1987.             throw ConnectionException::noActiveTransaction();
  1988.         }
  1990.         return $this->isRollbackOnly;
  1991.     }
  1993.     /**
  1994.      * Converts a given value to its database representation according to the conversion
  1995.      * rules of a specific DBAL mapping type.
  1996.      *
  1997.      * @param mixed  $value The value to convert.
  1998.      * @param string $type  The name of the DBAL mapping type.
  1999.      *
  2000.      * @return mixed The converted value.
  2001.      */
  2002.     public function convertToDatabaseValue($value, $type)
  2003.     {
  2004.         return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  2005.     }
  2007.     /**
  2008.      * Converts a given value to its PHP representation according to the conversion
  2009.      * rules of a specific DBAL mapping type.
  2010.      *
  2011.      * @param mixed  $value The value to convert.
  2012.      * @param string $type  The name of the DBAL mapping type.
  2013.      *
  2014.      * @return mixed The converted type.
  2015.      */
  2016.     public function convertToPHPValue($value, $type)
  2017.     {
  2018.         return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  2019.     }
  2021.     /**
  2022.      * Binds a set of parameters, some or all of which are typed with a PDO binding type
  2023.      * or DBAL mapping type, to a given statement.
  2024.      *
  2025.      * @internal Duck-typing used on the $stmt parameter to support driver statements as well as
  2026.      *           raw PDOStatement instances.
  2027.      *
  2028.      * @param \Doctrine\DBAL\Driver\Statement                                      $stmt   Prepared statement
  2029.      * @param array<int, mixed>|array<string, mixed>                               $params Statement parameters
  2030.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  2031.      *
  2032.      * @return void
  2033.      */
  2034.     private function _bindTypedValues($stmt, array $params, array $types)
  2035.     {
  2036.         // Check whether parameters are positional or named. Mixing is not allowed, just like in PDO.
  2037.         if (is_int(key($params))) {
  2038.             // Positional parameters
  2039.             $typeOffset = array_key_exists(0, $types) ? -1 : 0;
  2040.             $bindIndex  = 1;
  2041.             foreach ($params as $value) {
  2042.                 $typeIndex = $bindIndex + $typeOffset;
  2043.                 if (isset($types[$typeIndex])) {
  2044.                     $type                  = $types[$typeIndex];
  2045.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  2046.                     $stmt->bindValue($bindIndex, $value, $bindingType);
  2047.                 } else {
  2048.                     $stmt->bindValue($bindIndex, $value);
  2049.                 }
  2051.                 ++$bindIndex;
  2052.             }
  2053.         } else {
  2054.             // Named parameters
  2055.             foreach ($params as $name => $value) {
  2056.                 if (isset($types[$name])) {
  2057.                     $type                  = $types[$name];
  2058.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  2059.                     $stmt->bindValue($name, $value, $bindingType);
  2060.                 } else {
  2061.                     $stmt->bindValue($name, $value);
  2062.                 }
  2063.             }
  2064.         }
  2065.     }
  2067.     /**
  2068.      * Gets the binding type of a given type. The given type can be a PDO or DBAL mapping type.
  2069.      *
  2070.      * @param mixed                $value The value to bind.
  2071.      * @param int|string|Type|null $type  The type to bind (PDO or DBAL).
  2072.      *
  2073.      * @return mixed[] [0] => the (escaped) value, [1] => the binding type.
  2074.      */
  2075.     private function getBindingInfo($value, $type)
  2076.     {
  2077.         if (is_string($type)) {
  2078.             $type = Type::getType($type);
  2079.         }
  2081.         if ($type instanceof Type) {
  2082.             $value       = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  2083.             $bindingType = $type->getBindingType();
  2084.         } else {
  2085.             $bindingType = $type;
  2086.         }
  2088.         return [$value, $bindingType];
  2089.     }
  2091.     /**
  2092.      * Resolves the parameters to a format which can be displayed.
  2093.      *
  2094.      * @internal This is a purely internal method. If you rely on this method, you are advised to
  2095.      *           copy/paste the code as this method may change, or be removed without prior notice.
  2096.      *
  2097.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  2098.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  2099.      *
  2100.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  2101.      */
  2102.     public function resolveParams(array $params, array $types)
  2103.     {
  2104.         $resolvedParams = [];
  2106.         // Check whether parameters are positional or named. Mixing is not allowed, just like in PDO.
  2107.         if (is_int(key($params))) {
  2108.             // Positional parameters
  2109.             $typeOffset = array_key_exists(0, $types) ? -1 : 0;
  2110.             $bindIndex  = 1;
  2111.             foreach ($params as $value) {
  2112.                 $typeIndex = $bindIndex + $typeOffset;
  2113.                 if (isset($types[$typeIndex])) {
  2114.                     $type                       = $types[$typeIndex];
  2115.                     [$value]                    = $this->getBindingInfo($value, $type);
  2116.                     $resolvedParams[$bindIndex] = $value;
  2117.                 } else {
  2118.                     $resolvedParams[$bindIndex] = $value;
  2119.                 }
  2121.                 ++$bindIndex;
  2122.             }
  2123.         } else {
  2124.             // Named parameters
  2125.             foreach ($params as $name => $value) {
  2126.                 if (isset($types[$name])) {
  2127.                     $type                  = $types[$name];
  2128.                     [$value]               = $this->getBindingInfo($value, $type);
  2129.                     $resolvedParams[$name] = $value;
  2130.                 } else {
  2131.                     $resolvedParams[$name] = $value;
  2132.                 }
  2133.             }
  2134.         }
  2136.         return $resolvedParams;
  2137.     }
  2139.     /**
  2140.      * Creates a new instance of a SQL query builder.
  2141.      *
  2142.      * @return QueryBuilder
  2143.      */
  2144.     public function createQueryBuilder()
  2145.     {
  2146.         return new Query\QueryBuilder($this);
  2147.     }
  2149.     /**
  2150.      * Ping the server
  2151.      *
  2152.      * When the server is not available the method returns FALSE.
  2153.      * It is responsibility of the developer to handle this case
  2154.      * and abort the request or reconnect manually:
  2155.      *
  2156.      * @deprecated
  2157.      *
  2158.      * @return bool
  2159.      *
  2160.      * @example
  2161.      *
  2162.      *   if ($conn->ping() === false) {
  2163.      *      $conn->close();
  2164.      *      $conn->connect();
  2165.      *   }
  2166.      *
  2167.      * It is undefined if the underlying driver attempts to reconnect
  2168.      * or disconnect when the connection is not available anymore
  2169.      * as long it returns TRUE when a reconnect succeeded and
  2170.      * FALSE when the connection was dropped.
  2171.      */
  2172.     public function ping()
  2173.     {
  2174.         Deprecation::trigger(
  2175.             'doctrine/dbal',
  2176.             'https://github.com/doctrine/dbal/pull/4119',
  2177.             'Retry and reconnecting lost connections now happens automatically, ping() will be removed in DBAL 3.'
  2178.         );
  2180.         $connection = $this->getWrappedConnection();
  2182.         if ($connection instanceof PingableConnection) {
  2183.             return $connection->ping();
  2184.         }
  2186.         try {
  2187.             $this->query($this->getDatabasePlatform()->getDummySelectSQL());
  2189.             return true;
  2190.         } catch (DBALException $e) {
  2191.             return false;
  2192.         }
  2193.     }
  2195.     /**
  2196.      * @internal
  2197.      *
  2198.      * @param array<int, mixed>|array<string, mixed>                               $params
  2199.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  2200.      *
  2201.      * @psalm-return never-return
  2202.      *
  2203.      * @throws Exception
  2204.      */
  2205.     public function handleExceptionDuringQuery(Throwable $e, string $sql, array $params = [], array $types = []): void
  2206.     {
  2207.         $this->throw(
  2208.             Exception::driverExceptionDuringQuery(
  2209.                 $this->_driver,
  2210.                 $e,
  2211.                 $sql,
  2212.                 $this->resolveParams($params, $types)
  2213.             )
  2214.         );
  2215.     }
  2217.     /**
  2218.      * @internal
  2219.      *
  2220.      * @psalm-return never-return
  2221.      *
  2222.      * @throws Exception
  2223.      */
  2224.     public function handleDriverException(Throwable $e): void
  2225.     {
  2226.         $this->throw(
  2227.             Exception::driverException(
  2228.                 $this->_driver,
  2229.                 $e
  2230.             )
  2231.         );
  2232.     }
  2234.     /**
  2235.      * @internal
  2236.      *
  2237.      * @psalm-return never-return
  2238.      *
  2239.      * @throws Exception
  2240.      */
  2241.     private function throw(Exception $e): void
  2242.     {
  2243.         if ($e instanceof ConnectionLost) {
  2244.             $this->close();
  2245.         }
  2247.         throw $e;
  2248.     }
  2250.     private function ensureHasKeyValue(ResultStatement $stmt): void
  2251.     {
  2252.         $columnCount = $stmt->columnCount();
  2254.         if ($columnCount < 2) {
  2255.             throw NoKeyValue::fromColumnCount($columnCount);
  2256.         }
  2257.     }
  2258. }