Deprecate duplicate and ambiguous wrapper connection methods #4163

morozov · 2020-07-11T02:20:48Z

Q	A
Type	improvement
BC Break	no

Deprecation of `Connection::query()` and `::exec()`

Once the wrapper connection has been freed from the responsibilities of the driver connection (#4159), the query() and exec() methods that effectively (and poorly) duplicate executeQuery() and executeUpdate() can be deprecated.

Deprecation of `Connection::executeUpdate()` in favor of `::executeStatement()`

The name of the executeUpdate() method is quote misleading since apart from the UPDATE statements, it should be used for INSERT, DELETE and all sorts of DML, DDL, TCL and other statements. As generic alternative executeStatement() looks more intuitive.

Notes in conjunction with PrimaryReplicaConnection

Note that PrimaryReplicaConnection::query() ensured connection to the primary instance while executeQuery() doesn't.

Depending on the desired behavior:

If the statement doesn't have to be executed on the primary instance, use executeQuery().
If the statement has to be executed on the primary instance and yields rows (e.g. SELECT), prepend executeQuery() with ensureConnectedToPrimary().
Otherwise, use executeStatement().

greg0ire · 2020-07-11T18:52:55Z

tests/Doctrine/Tests/DBAL/Tools/Console/RunSqlCommandTest.php

@@ -79,7 +79,7 @@ public function testSelectStatementsPrintsResult(): void

    public function testUpdateStatementsPrintsAffectedLines(): void
    {
-        $this->expectConnectionExecuteUpdate();
+        $this->expectConnectionexecuteStatement();


Suggested change

$this->expectConnectionexecuteStatement();

$this->expectConnectionExecuteStatement();

greg0ire · 2020-07-11T18:53:04Z

tests/Doctrine/Tests/DBAL/Tools/Console/RunSqlCommandTest.php

@@ -90,11 +90,11 @@ public function testUpdateStatementsPrintsAffectedLines(): void
        self::assertDoesNotMatchRegularExpression('@array.*1.*@', $this->commandTester->getDisplay());
    }

-    private function expectConnectionExecuteUpdate(): void
+    private function expectConnectionexecuteStatement(): void


Suggested change

private function expectConnectionexecuteStatement(): void

private function expectConnectionExecuteStatement(): void

greg0ire · 2020-07-11T18:54:13Z

lib/Doctrine/DBAL/Connection.php

+     *
+     * @param string                 $sql    The statement SQL.
+     * @param array<mixed>           $params The query parameters.
+     * @param array<int|string|null> $types  The parameter types.


Those periods at the end of non-sentences are enforced by our CS, right? I really don't get why we do this…

This looks more like an exception, however, I believe a full stop is enforced in exception messages. Let me see if I can get rid of them here.

I must have been confusing with some other coding standard

…atement()

This PR was merged into the 3.4 branch. Discussion ---------- Fix DBAL deprecation | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | yes | New feature? | no | Deprecations? | no | Tickets | - | License | MIT | Doc PR | - Follows doctrine/dbal#4163 Commits ------- 4273aed Fix DBAL deprecation

…, query APIs.

@gjdanis

Release [2.11.0](https://github.com/doctrine/dbal/milestone/77) 2.11.0 ====== - Total issues resolved: **7** - Total pull requests resolved: **55** - Total contributors: **8** Improvement,Prepared Statements,SQL Server,Types,pdo_sqlsrv,sqlsrv ------------------------------------------------------------------ - [4274: Support ASCII parameter binding](doctrine#4274) thanks to @gjdanis Documentation ------------- - [4271: Add explanation about implicit indexes](doctrine#4271) thanks to @greg0ire Deprecation,Error Handling -------------------------- - [4253: Deprecate DBAL\DBALException in favor of DBAL\Exception](doctrine#4253) thanks to @morozov CI -- - [4251: Setup automatic release workflow](doctrine#4251) thanks to @greg0ire Deprecation,Schema Managers --------------------------- - [4230: Deprecate the functionality of dropping client connections when dropping a database](doctrine#4230) thanks to @morozov Deprecation,Platforms --------------------- - [4229: Deprecate more AbstractPlatform methods](doctrine#4229) thanks to @morozov - [4132: Deprecate AbstractPlatform::fixSchemaElementName()](doctrine#4132) thanks to @morozov Improvement,Test Suite ---------------------- - [4215: Remove test group configuration leftovers](doctrine#4215) thanks to @morozov - [4080: Update PHPUnit to 9.2](doctrine#4080) thanks to @morozov - [4079: Forward compatibility with PHPUnit 9.3](doctrine#4079) thanks to @morozov - [3923: Removed performance tests](doctrine#3923) thanks to @morozov Deprecation,Schema ------------------ - [4213: Deprecate the Synchronizer package](doctrine#4213) thanks to @morozov Blocker,Improvement,PHP,Test Suite ---------------------------------- - [4201: Update PHPUnit to 9.3](doctrine#4201) thanks to @morozov Blocker,PHP,Test Suite ---------------------- - [4196: The test suite uses the deprecated at() matcher](doctrine#4196) thanks to @morozov Connections,Deprecation,Documentation ------------------------------------- - [4175: Additional deprecation note for PrimaryReplicaConnection::query()](doctrine#4175) thanks to @morozov Connections,Deprecation,Prepared Statements ------------------------------------------- - [4165: Deprecated usage of wrapper components as implementations of driver-level interfaces](doctrine#4165) thanks to @morozov - [4020: Deprecated Connection::project(), Statement::errorCode() and errorInfo()](doctrine#4020) thanks to @morozov Connections,Deprecation ----------------------- - [4163: Deprecate duplicate and ambiguous wrapper connection methods](doctrine#4163) thanks to @morozov Error Handling,Improvement,Types -------------------------------- - [4145: Add TypeRegistry constructor](doctrine#4145) thanks to @morozov Deprecation,Drivers,Improvement,pdo_mysql,pdo_oci,pdo_pgsql,pdo_sqlite,pdo_sqlsrv --------------------------------------------------------------------------------- - [4144: Deprecate classes in Driver\PDO* namespaces](doctrine#4144) thanks to @morozov Connections,Documentation,Improvement ------------------------------------- - [4139: Mark connection constructors internal](doctrine#4139) thanks to @morozov Deprecation,Drivers,Error Handling ---------------------------------- - [4137: Deprecate driver exception conversion APIs](doctrine#4137) thanks to @morozov - [4112: Deprecate DriverException::getErrorCode()](doctrine#4112) thanks to @morozov Configuration,Connections,Deprecation,Error Handling ---------------------------------------------------- - [4134: Deprecate some DBALException factory methods](doctrine#4134) thanks to @morozov Code Style,Documentation ------------------------ - [4133: Fix more issues introduced by the deprecation of driver classes](doctrine#4133) thanks to @morozov BC Break,Drivers,Error Handling,pdo_sqlsrv,sqlsrv ------------------------------------------------- - [4131: Restore the PortWithoutHost exception parent class](doctrine#4131) thanks to @morozov Code Style,Improvement,Static Analysis -------------------------------------- - [4123: Remove the no longer needed error suppressions](doctrine#4123) thanks to @morozov Deprecation,Drivers,Error Handling,Improvement ---------------------------------------------- - [4118: Deprecate ExceptionConverterDriver](doctrine#4118) thanks to @morozov Bug,Connections,Improvement,Prepared Statements ----------------------------------------------- - [4117: Fixes for the recently introduced driver-level deprecations](doctrine#4117) thanks to @morozov Connections,Deprecation,Platform Detection ------------------------------------------ - [4114: Deprecate ServerInfoAwareConnection#requiresQueryForServerVersion() as an implementation detail](doctrine#4114) thanks to @morozov Deprecation,Prepared Statements,SQL Parser,oci8 ----------------------------------------------- - [4110: Mark non-interface OCI8 driver methods internal](doctrine#4110) thanks to @morozov Connections,Deprecation,Drivers,Improvement,Prepared Statements --------------------------------------------------------------- - [4100: Deprecate inconsistently and ambiguously named driver-level classes](doctrine#4100) thanks to @morozov Connections,Improvement ----------------------- - [4092: Remove Connection::$isConnected](doctrine#4092) thanks to @morozov Configuration,Connections ------------------------- - [4086: Mark Connection::getParams() internal](doctrine#4086) thanks to @morozov Bug,Drivers,ibm_db2 ------------------- - [4085: The IBM DB2 driver Exception class must implement the DriverException interface](doctrine#4085) thanks to @morozov PHP --- - [4078: Bump PHP requirement to 7.3 as of DBAL 2.11.0](doctrine#4078) thanks to @morozov Connections,Databases,Deprecation,Drivers ----------------------------------------- - [4068: Deprecate Driver::getDatabase()](doctrine#4068) thanks to @morozov Deprecation,Improvement,Portability ----------------------------------- - [4061: Deprecated platform-specific portability mode constants](doctrine#4061) thanks to @morozov - [4054: &doctrine#91;doctrineGH-4052&doctrine#93; Deprecate MasterSlaveConnection and rename to PrimaryReplicaConnection](doctrine#4054) thanks to @beberlei and @albe - [4017: Improve help of dbal:run-sql command](doctrine#4017) thanks to @ostrolucky Code Style,Improvement ---------------------- - [4050: Update doctrine/coding-standard to 8.0](doctrine#4050) thanks to @morozov Cache,Deprecation,Improvement,Prepared Statements ------------------------------------------------- - [4049: Replace forward-compatible ResultStatement interfaces with Result](doctrine#4049) thanks to @morozov Cache,Improvement,Prepared Statements ------------------------------------- - [4048: Make caching layer not rely on closeCursor()](doctrine#4048) thanks to @morozov Deprecation,Improvement,Prepared Statements ------------------------------------------- - [4037: Introduce Statement::fetchFirstColumn()](doctrine#4037) thanks to @morozov - [4019: Deprecated the concept of the fetch mode](doctrine#4019) thanks to @morozov Bug,Documentation,Improvement,Prepared Statements ------------------------------------------------- - [4034: Additional changes based on the discussion in doctrine#4007](doctrine#4034) thanks to @morozov Connections,Console,Improvement ------------------------------- - [3956: allow using multiple connections for CLI commands](doctrine#3956) thanks to @dmaicher Deprecation,Logging ------------------- - [3935: Deprecate EchoSQLLogger](doctrine#3935) thanks to @morozov Improvement,Packaging --------------------- - [3924: Actualize the content of the .gitattributes file](doctrine#3924) thanks to @morozov Azure,Deprecation,Drivers,Drizzle,MariaDB,Platforms,PostgreSQL,SQL Anywhere,SQL Server,Sharding,pdo_ibm ------------------------------------------------------------------------------------------------------- - [3905: Deprecate the usage of the legacy platforms and drivers](doctrine#3905) thanks to @morozov Deprecation,Query ----------------- - [3864: CompositeExpression and()/or() factory methods](doctrine#3864) thanks to @BenMorel - [3853: Deprecate calling QueryBuilder methods with an array argument](doctrine#3853) thanks to @BenMorel and @morozov Deprecation,Tools ----------------- - [3861: Deprecated the usage of the Version class](doctrine#3861) thanks to @morozov Improvement,Query ----------------- - [3852: First parameter of ExpressionBuilder::and/or() mandatory](doctrine#3852) thanks to @BenMorel Deprecation,Improvement,Query ----------------------------- - [3851: Rename andX() / orX() methods](doctrine#3851) thanks to @BenMorel - [3850: Prepare CompositeExpression for immutability](doctrine#3850) thanks to @BenMorel # gpg: Signature made Mon Sep 21 01:47:31 2020 # gpg: using DSA key 1BEDEE0A820BC30D858F9F0C2C3A645671828132 # gpg: Can't check signature: No public key # Conflicts: # README.md # lib/Doctrine/DBAL/Driver/AbstractOracleDriver.php # lib/Doctrine/DBAL/Driver/OCI8/Driver.php # lib/Doctrine/DBAL/Version.php

…, query APIs.

morozov added Connections Deprecation labels Jul 11, 2020

morozov added this to the 2.11.0 milestone Jul 11, 2020

morozov requested a review from greg0ire July 11, 2020 02:34

morozov changed the title ~~Deprecate wrapper query exec~~ Deprecate duplicate and ambiguous wrapper connection methods Jul 11, 2020

greg0ire reviewed Jul 11, 2020

View reviewed changes

morozov added 2 commits July 11, 2020 12:20

Deprecate executeUpdate() in favor of executeStatement()

524a23b

Deprecate query() and exec() in favor of executeQuery() and executeSt…

35e9150

…atement()

morozov force-pushed the deprecate-wrapper-query-exec branch from bff7b76 to 35e9150 Compare July 11, 2020 19:22

greg0ire approved these changes Jul 11, 2020

View reviewed changes

morozov merged commit e24761c into doctrine:2.11.x Jul 11, 2020

morozov deleted the deprecate-wrapper-query-exec branch July 11, 2020 20:25

morozov self-assigned this Jul 11, 2020

nicolas-grekas mentioned this pull request Jul 12, 2020

Fix DBAL deprecation symfony/symfony#37563

Merged

github-actions bot mentioned this pull request Sep 20, 2020

Merge release 2.11.0 into 3.0.x #4277

Merged

beberlei added a commit to beberlei/dbal that referenced this pull request Mar 6, 2021

[doctrineGH-4163] Add deprecation for Connection::exec, executeUpdate…

6abdbb9

…, query APIs.

beberlei added a commit to beberlei/dbal that referenced this pull request Mar 7, 2021

[doctrineGH-4163] Add deprecation for Connection::exec, executeUpdate…

d20b11b

…, query APIs.

beberlei added a commit to beberlei/dbal that referenced this pull request Mar 22, 2021

[doctrineGH-4163] Add deprecation for Connection::exec, executeUpdate…

705d3a2

…, query APIs.

github-actions bot locked as resolved and limited conversation to collaborators Jul 24, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deprecate duplicate and ambiguous wrapper connection methods #4163

Deprecate duplicate and ambiguous wrapper connection methods #4163

morozov commented Jul 11, 2020 •

edited by beberlei

Loading

greg0ire Jul 11, 2020

greg0ire Jul 11, 2020

greg0ire Jul 11, 2020

morozov Jul 11, 2020

greg0ire Jul 11, 2020

	$this->expectConnectionexecuteStatement();
	$this->expectConnectionExecuteStatement();

	private function expectConnectionexecuteStatement(): void
	private function expectConnectionExecuteStatement(): void

Deprecate duplicate and ambiguous wrapper connection methods #4163

Deprecate duplicate and ambiguous wrapper connection methods #4163

Conversation

morozov commented Jul 11, 2020 • edited by beberlei Loading

Deprecation of Connection::query() and ::exec()

Deprecation of Connection::executeUpdate() in favor of ::executeStatement()

Notes in conjunction with PrimaryReplicaConnection

greg0ire Jul 11, 2020

Choose a reason for hiding this comment

greg0ire Jul 11, 2020

Choose a reason for hiding this comment

greg0ire Jul 11, 2020

Choose a reason for hiding this comment

morozov Jul 11, 2020

Choose a reason for hiding this comment

greg0ire Jul 11, 2020

Choose a reason for hiding this comment

morozov commented Jul 11, 2020 •

edited by beberlei

Loading

Deprecation of `Connection::query()` and `::exec()`

Deprecation of `Connection::executeUpdate()` in favor of `::executeStatement()`