Merge pull request #4163 from morozov/deprecate-wrapper-query-exec

Deprecate duplicate and ambiguous wrapper connection methods

Author: morozov

UPGRADE.md

@@ -1,5 +1,11 @@
 # Upgrade to 2.11
 
+## Deprecations in the wrapper `Connection` class
+
+1. The `executeUpdate()` method has been deprecated in favor of `executeStatement()`. 
+2. The `query()` method has been deprecated in favor of `executeQuery()`. 
+3. The `exec()` method has been deprecated in favor of `executeStatement()`. 
+
 ## PDO-related classes outside of the PDO namespace are deprecated
 
 The following outside of the PDO namespace have been deprecated in favor of their counterparts in the PDO namespace:

docs/en/reference/data-retrieval-and-manipulation.rst

@@ -142,7 +142,7 @@ use prepared statements:
     SQL query, bind the given params with their binding types and execute the query.
     This method returns the executed prepared statement for iteration and is useful
     for SELECT statements.
--   ``executeUpdate($sql, $params, $types)`` - Create a prepared statement for the passed
+-   ``executeStatement($sql, $params, $types)`` - Create a prepared statement for the passed
     SQL query, bind the given params with their binding types and execute the query.
     This method returns the number of affected rows by the executed query and is useful
     for UPDATE, DELETE and INSERT statements.
@@ -170,7 +170,7 @@ of this query using the fetch API of a statement:
 The fetch API of a prepared statement obviously works only for ``SELECT`` queries.
 
 If you find it tedious to write all the prepared statement code you can alternatively use
-the ``Doctrine\DBAL\Connection#executeQuery()`` and ``Doctrine\DBAL\Connection#executeUpdate()``
+the ``Doctrine\DBAL\Connection#executeQuery()`` and ``Doctrine\DBAL\Connection#executeStatement()``
 methods. See the API section below on details how to use them.
 
 Additionally there are lots of convenience methods for data-retrieval and manipulation
@@ -208,7 +208,7 @@ which means this code works independent of the database you are using.
 .. note::
 
     Be aware this type conversion only works with ``Statement#bindValue()``,
-    ``Connection#executeQuery()`` and ``Connection#executeUpdate()``. It
+    ``Connection#executeQuery()`` and ``Connection#executeStatement()``. It
     is not supported to pass a doctrine type name to ``Statement#bindParam()``,
     because this would not work with binding by reference.
 
@@ -286,7 +286,7 @@ This is much more complicated and is ugly to write generically.
 .. note::
 
     The parameter list support only works with ``Doctrine\DBAL\Connection::executeQuery()``
-    and ``Doctrine\DBAL\Connection::executeUpdate()``, NOT with the binding methods of
+    and ``Doctrine\DBAL\Connection::executeStatement()``, NOT with the binding methods of
     a prepared statement.
 
 API
@@ -319,7 +319,7 @@ Prepare a given SQL statement and return the
     )
     */
 
-executeUpdate()
+executeStatement()
 ~~~~~~~~~~~~~~~
 
 Executes a prepared statement with the given SQL and parameters and
@@ -328,7 +328,7 @@ returns the affected rows count:
 .. code-block:: php
 
     <?php
-    $count = $conn->executeUpdate('UPDATE user SET username = ? WHERE id = ?', array('jwage', 1));
+    $count = $conn->executeStatement('UPDATE user SET username = ? WHERE id = ?', array('jwage', 1));
     echo $count; // 1
 
 The ``$types`` variable contains the PDO or Doctrine Type constants

docs/en/reference/security.rst

@@ -135,7 +135,7 @@ are using just the DBAL there are also helper methods which simplify the usage q
     $sql = "SELECT * FROM users WHERE username = ?";
     $stmt = $connection->executeQuery($sql, array($_GET['username']));
 
-There is also ``executeUpdate`` which does not return a statement but the number of affected rows.
+There is also ``executeStatement`` which does not return a statement but the number of affected rows.
 
 Besides binding parameters you can also pass the type of the variable. This allows Doctrine or the underlying
 vendor to not only escape but also cast the value to the correct type. See the docs on querying and DQL in the

docs/en/reference/sharding_azure_tutorial.rst

@@ -263,7 +263,7 @@ operation for us:
         'LastName' => 'Brehm',
     ));
 
-    $conn->executeUpdate("DECLARE @orderId INT
+    $conn->executeStatement("DECLARE @orderId INT
 
         DECLARE @customerId INT
 

docs/examples/sharding/insert_data.php

@@ -90,7 +90,7 @@
     'LastName' => 'Brehm',
 ));
 
-$conn->executeUpdate("
+$conn->executeStatement("
     DECLARE @orderId INT
 
     DECLARE @customerId INT

lib/Doctrine/DBAL/Connection.php

@@ -749,7 +749,7 @@ public function delete($tableExpression, array $identifier, array $types = [])
 
         $this->addIdentifierCondition($identifier, $columns, $values, $conditions);
 
-        return $this->executeUpdate(
+        return $this->executeStatement(
             'DELETE FROM ' . $tableExpression . ' WHERE ' . implode(' AND ', $conditions),
             $values,
             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
@@ -777,7 +777,7 @@ public function setTransactionIsolation($level)
     {
         $this->transactionIsolationLevel = $level;
 
-        return $this->executeUpdate($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
+        return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
     }
 
     /**
@@ -827,7 +827,7 @@ public function update($tableExpression, array $data, array $identifier, array $
         $sql = 'UPDATE ' . $tableExpression . ' SET ' . implode(', ', $set)
                 . ' WHERE ' . implode(' AND ', $conditions);
 
-        return $this->executeUpdate($sql, $values, $types);
+        return $this->executeStatement($sql, $values, $types);
     }
 
     /**
@@ -846,7 +846,7 @@ public function update($tableExpression, array $data, array $identifier, array $
     public function insert($tableExpression, array $data, array $types = [])
     {
         if (empty($data)) {
-            return $this->executeUpdate('INSERT INTO ' . $tableExpression . ' () VALUES ()');
+            return $this->executeStatement('INSERT INTO ' . $tableExpression . ' () VALUES ()');
         }
 
         $columns = [];
@@ -859,7 +859,7 @@ public function insert($tableExpression, array $data, array $types = [])
             $set[]     = '?';
         }
 
-        return $this->executeUpdate(
+        return $this->executeStatement(
             'INSERT INTO ' . $tableExpression . ' (' . implode(', ', $columns) . ')' .
             ' VALUES (' . implode(', ', $set) . ')',
             $values,
@@ -1249,6 +1249,8 @@ public function project($query, array $params, Closure $function)
     /**
      * Executes an SQL statement, returning a result set as a Statement object.
      *
+     * @deprecated Use {@link executeQuery()} instead.
+     *
      * @return \Doctrine\DBAL\Driver\Statement
      *
      * @throws DBALException
@@ -1285,6 +1287,8 @@ public function query()
      *
      * This method supports PDO binding types as well as DBAL mapping types.
      *
+     * @deprecated Use {@link executeStatement()} instead.
+     *
      * @param string                 $query  The SQL query.
      * @param array<mixed>           $params The query parameters.
      * @param array<int|string|null> $types  The parameter types.
@@ -1294,19 +1298,44 @@ public function query()
      * @throws DBALException
      */
     public function executeUpdate($query, array $params = [], array $types = [])
+    {
+        return $this->executeStatement($query, $params, $types);
+    }
+
+    /**
+     * Executes an SQL statement with the given parameters and returns the number of affected rows.
+     *
+     * Could be used for:
+     *  - DML statements: INSERT, UPDATE, DELETE, etc.
+     *  - DDL statements: CREATE, DROP, ALTER, etc.
+     *  - DCL statements: GRANT, REVOKE, etc.
+     *  - Session control statements: ALTER SESSION, SET, DECLARE, etc.
+     *  - Other statements that don't yield a row set.
+     *
+     * This method supports PDO binding types as well as DBAL mapping types.
+     *
+     * @param string                 $sql    The statement SQL
+     * @param array<mixed>           $params The query parameters
+     * @param array<int|string|null> $types  The parameter types
+     *
+     * @return int The number of affected rows.
+     *
+     * @throws DBALException
+     */
+    public function executeStatement($sql, array $params = [], array $types = [])
     {
         $connection = $this->getWrappedConnection();
 
         $logger = $this->_config->getSQLLogger();
         if ($logger) {
-            $logger->startQuery($query, $params, $types);
+            $logger->startQuery($sql, $params, $types);
         }
 
         try {
             if ($params) {
-                [$query, $params, $types] = SQLParserUtils::expandListParameters($query, $params, $types);
+                [$sql, $params, $types] = SQLParserUtils::expandListParameters($sql, $params, $types);
 
-                $stmt = $connection->prepare($query);
+                $stmt = $connection->prepare($sql);
 
                 if ($types) {
                     $this->_bindTypedValues($stmt, $params, $types);
@@ -1317,10 +1346,10 @@ public function executeUpdate($query, array $params = [], array $types = [])
 
                 $result = $stmt->rowCount();
             } else {
-                $result = $connection->exec($query);
+                $result = $connection->exec($sql);
             }
         } catch (Throwable $e) {
-            $this->handleExceptionDuringQuery($e, $query, $params, $types);
+            $this->handleExceptionDuringQuery($e, $sql, $params, $types);
         }
 
         if ($logger) {
@@ -1333,6 +1362,8 @@ public function executeUpdate($query, array $params = [], array $types = [])
     /**
      * Executes an SQL statement and return the number of affected rows.
      *
+     * @deprecated Use {@link executeStatement()} instead.
+     *
      * @param string $statement
      *
      * @return int The number of affected rows.

lib/Doctrine/DBAL/Connections/PrimaryReadReplicaConnection.php

@@ -26,7 +26,7 @@
  *
  * 1. Replica if primary was never picked before and ONLY if 'getWrappedConnection'
  *    or 'executeQuery' is used.
- * 2. Primary picked when 'exec', 'executeUpdate', 'insert', 'delete', 'update', 'createSavepoint',
+ * 2. Primary picked when 'exec', 'executeUpdate', 'executeStatement', 'insert', 'delete', 'update', 'createSavepoint',
  *    'releaseSavepoint', 'beginTransaction', 'rollback', 'commit', 'query' or
  *    'prepare' is called.
  * 3. If Primary was picked once during the lifetime of the connection it will always get picked afterwards.
@@ -41,7 +41,7 @@
  * Be aware that Connection#executeQuery is a method specifically for READ
  * operations only.
  *
- * Use Connection#executeUpdate for any SQL statement that changes/updates
+ * Use Connection#executeStatement for any SQL statement that changes/updates
  * state in the database (UPDATE, INSERT, DELETE or DDL statements).
  *
  * This connection is limited to replica operations using the
@@ -256,6 +256,8 @@ protected function chooseConnectionConfiguration($connectionName, $params)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use {@link executeStatement()} instead.
      */
     public function executeUpdate($query, array $params = [], array $types = [])
     {
@@ -264,6 +266,16 @@ public function executeUpdate($query, array $params = [], array $types = [])
         return parent::executeUpdate($query, $params, $types);
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public function executeStatement($query, array $params = [], array $types = [])
+    {
+        $this->ensureConnectedToPrimary();
+
+        return parent::executeStatement($query, $params, $types);
+    }
+
     /**
      * {@inheritDoc}
      */

lib/Doctrine/DBAL/Event/Listeners/MysqlSessionInit.php

@@ -45,7 +45,7 @@ public function __construct($charset = 'utf8', $collation = false)
     public function postConnect(ConnectionEventArgs $args)
     {
         $collation = $this->collation ? ' COLLATE ' . $this->collation : '';
-        $args->getConnection()->executeUpdate('SET NAMES ' . $this->charset . $collation);
+        $args->getConnection()->executeStatement('SET NAMES ' . $this->charset . $collation);
     }
 
     /**

lib/Doctrine/DBAL/Event/Listeners/OracleSessionInit.php

@@ -61,7 +61,7 @@ public function postConnect(ConnectionEventArgs $args)
         }
 
         $sql = 'ALTER SESSION SET ' . implode(' ', $vars);
-        $args->getConnection()->executeUpdate($sql);
+        $args->getConnection()->executeStatement($sql);
     }
 
     /**

lib/Doctrine/DBAL/Id/TableGenerator.php

@@ -131,7 +131,7 @@ public function nextValue($sequenceName)
                 $sql  = 'UPDATE ' . $this->generatorTableName . ' ' .
                        'SET sequence_value = sequence_value + sequence_increment_by ' .
                        'WHERE sequence_name = ? AND sequence_value = ?';
-                $rows = $this->conn->executeUpdate($sql, [$sequenceName, $row['sequence_value']]);
+                $rows = $this->conn->executeStatement($sql, [$sequenceName, $row['sequence_value']]);
 
                 if ($rows !== 1) {
                     throw new DBALException('Race-condition detected while updating sequence. Aborting generation');

lib/Doctrine/DBAL/Query/QueryBuilder.php

@@ -196,9 +196,6 @@ public function getState()
     /**
      * Executes this query using the bound parameters and their types.
      *
-     * Uses {@see Connection::executeQuery} for select statements and {@see Connection::executeUpdate}
-     * for insert, update and delete statements.
-     *
      * @return ResultStatement|int
      */
     public function execute()
@@ -207,7 +204,7 @@ public function execute()
             return $this->connection->executeQuery($this->getSQL(), $this->params, $this->paramTypes);
         }
 
-        return $this->connection->executeUpdate($this->getSQL(), $this->params, $this->paramTypes);
+        return $this->connection->executeStatement($this->getSQL(), $this->params, $this->paramTypes);
     }
 
     /**

lib/Doctrine/DBAL/Schema/AbstractSchemaManager.php

@@ -1033,7 +1033,7 @@ protected function _getPortableTableForeignKeyDefinition($tableForeignKey)
     protected function _execSql($sql)
     {
         foreach ((array) $sql as $query) {
-            $this->_conn->executeUpdate($query);
+            $this->_conn->executeStatement($query);
         }
     }
 

lib/Doctrine/DBAL/Schema/OracleSchemaManager.php

@@ -307,10 +307,10 @@ public function createDatabase($database = null)
         $password = $params['password'];
 
         $query = 'CREATE USER ' . $username . ' IDENTIFIED BY ' . $password;
-        $this->_conn->executeUpdate($query);
+        $this->_conn->executeStatement($query);
 
         $query = 'GRANT DBA TO ' . $username;
-        $this->_conn->executeUpdate($query);
+        $this->_conn->executeStatement($query);
     }
 
     /**
@@ -324,7 +324,7 @@ public function dropAutoincrement($table)
 
         $sql = $this->_platform->getDropAutoincrementSql($table);
         foreach ($sql as $query) {
-            $this->_conn->executeUpdate($query);
+            $this->_conn->executeStatement($query);
         }
 
         return true;

lib/Doctrine/DBAL/Tools/Console/Command/RunSqlCommand.php

@@ -87,7 +87,7 @@ protected function execute(InputInterface $input, OutputInterface $output)
         if (stripos($sql, 'select') === 0 || $input->getOption('force-fetch')) {
             $resultSet = $conn->fetchAllAssociative($sql);
         } else {
-            $resultSet = $conn->executeUpdate($sql);
+            $resultSet = $conn->executeStatement($sql);
         }
 
         $output->write(Dumper::dump($resultSet, (int) $depth));

tests/Doctrine/Tests/DBAL/Connection/LoggingTest.php

@@ -22,13 +22,13 @@ public function testLogExecuteQuery(): void
             ->executeQuery('SELECT * FROM table');
     }
 
-    public function testLogExecuteUpdate(): void
+    public function testLogExecuteStatement(): void
     {
         $this->createConnection(
             $this->createStub(DriverConnection::class),
             'UPDATE table SET foo = ?'
         )
-            ->executeUpdate('UPDATE table SET foo = ?');
+            ->executeStatement('UPDATE table SET foo = ?');
     }
 
     public function testLogPrepareExecute(): void