Merge remote-tracking branch 'origin/2.11.x' into 3.0.x

.appveyor.yml

@@ -12,7 +12,6 @@ cache:
   - C:\tools\php -> .appveyor.yml
   - C:\tools\cacert -> .appveyor.yml
   - C:\tools\composer -> .appveyor.yml
-  - C:\tools\ocular -> .appveyor.yml
   - '%LOCALAPPDATA%\Composer\files -> composer.json'
 
 ## Build matrix for lowest and highest possible targets
@@ -22,20 +21,17 @@ environment:
     driver: sqlsrv
     db_version: sql2012sp1
     php: 7.3
-    coverage: yes
   - db: mssql
     driver: sqlsrv
     db_version: sql2017
-    coverage: no
     php: 7.3
   - db: mssql
     driver: pdo_sqlsrv
     db_version: sql2017
     php: 7.3
-    coverage: yes
 
 init:
-  - SET PATH=C:\Program Files\OpenSSL;c:\tools\php;C:\tools\composer;C:\tools\ocular;%PATH%
+  - SET PATH=C:\Program Files\OpenSSL;c:\tools\php;C:\tools\composer;%PATH%
   - SET COMPOSER_NO_INTERACTION=1
   - SET ANSICON=121x90 (121x90)
 
@@ -94,15 +90,6 @@ install:
             Set-Content -path 'C:\tools\composer\composer.bat' -Value ('@php C:\tools\composer\composer.phar %*')
           }
 
-          # download Scrutinizer's Ocular
-          if (!(Test-Path C:\tools\ocular)) {
-            New-Item -path c:\tools -name ocular -itemtype directory
-          }
-          if (!(Test-Path c:\tools\ocular\ocular.phar)) {
-            appveyor-retry appveyor DownloadFile https://github.com/scrutinizer-ci/ocular/releases/download/1.5.2/ocular.phar -Filename C:\tools\ocular\ocular.phar
-            Set-Content -path 'C:\tools\ocular\ocular.bat' -Value ('@php C:\tools\ocular\ocular.phar %*')
-          }
-
           # download CA bundle
           if (!(Test-Path C:\tools\cacert)) {
             New-Item -path c:\tools\ -name cacert -itemtype directory
@@ -132,18 +119,8 @@ test_script:
         $env:phpunit_config = "ci\appveyor\$($env:db).$($env:driver).appveyor.xml"
       }
 
-      if ($env:coverage -eq "yes") {
-        vendor\bin\phpunit -c $($env:phpunit_config) --coverage-clover clover.xml
-      } else {
-        vendor\bin\phpunit -c $($env:phpunit_config)
-      }
+      vendor\bin\phpunit -c $($env:phpunit_config)
 
       if ($LastExitCode -ne 0) {
         $host.SetShouldExit($LastExitCode)
       }
-
-after_test:
-  - ps: >-
-      if ($env:coverage -eq "yes") {
-        appveyor-retry ocular code-coverage:upload --format=php-clover clover.xml
-      }

.coveralls.yml

+coverage_clover: clover.xml
+json_path: /tmp/coveralls-upload.json

.gitattributes

@@ -9,7 +9,6 @@
 /phpstan.neon.dist export-ignore
 /phpunit.xml.dist export-ignore
 /run-all.sh export-ignore
-/.scrutinizer.yml export-ignore
 /SECURITY.md export-ignore
 /tests export-ignore
 /.travis.yml export-ignore

.scrutinizer.yml

-build:
-    nodes:
-        analysis:
-            environment:
-                php:
-                    version: 7.3
-            cache:
-                disabled: false
-                directories:
-                    - ~/.composer/cache
-
-            project_setup:
-                override: true
-            tests:
-                override:
-                    - php-scrutinizer-run
-
-before_commands:
-    - "composer install --no-dev --prefer-source -a"
-
-tools:
-    external_code_coverage:
-        timeout: 3600
-        runs: 24 # 21x Travis (jobs with COVERAGE=yes) + 2x AppVeyor (jobs with coverage=yes) + 1x ContinuousPHP
-
-filter:
-    excluded_paths:
-        - docs
-
-build_failure_conditions:
-    - 'elements.rating(<= C).new.exists'                        # No new classes/methods with a rating of C or worse allowed
-    - 'issues.severity(>= MAJOR).new.exists'                    # New issues of major or higher severity
-    - 'project.metric_change("scrutinizer.test_coverage", < 0)' # Code Coverage decreased from previous inspection
-    - 'patches.label("Unused Use Statements").new.exists'       # No new unused imports patches allowed

.travis.yml

@@ -11,6 +11,8 @@ before_install:
   - |
     if [ "x$COVERAGE" == "xyes" ]; then
       pecl install pcov-1.0.6
+      wget https://github.com/php-coveralls/php-coveralls/releases/download/v2.2.0/php-coveralls.phar --output-document="${HOME}/bin/coveralls"
+      chmod +x ${HOME}/bin/coveralls
     fi
 
 before_script:
@@ -38,8 +40,7 @@ script:
 after_script:
   - |
     if [ "x$COVERAGE" == "xyes" ]; then
-      travis_retry wget https://github.com/scrutinizer-ci/ocular/releases/download/1.5.2/ocular.phar
-      travis_retry php ocular.phar code-coverage:upload --format=php-clover clover.xml
+      travis_retry coveralls -v
     fi
 
 jobs:

README.md

@@ -4,8 +4,7 @@
 |:----------------:|:----------:|
 | [![Build status][Master image]][Master] | [![Build status][2.10 image]][2.10] |
 | [![Build Status][ContinuousPHP image]][ContinuousPHP] | [![Build Status][ContinuousPHP 2.10 image]][ContinuousPHP] |
-| [![Code Coverage][Coverage image]][Scrutinizer Master] | [![Code Coverage][Coverage 2.10 image]][Scrutinizer 2.10] |
-| [![Code Quality][Quality image]][Scrutinizer Master] | [![Code Quality][Quality 2.10 image]][Scrutinizer 2.10] |
+| [![Code Coverage][Coverage image]][Coveralls Master] | [![Code Coverage][Coverage 2.10 image]][Coveralls 2.10] |
 | [![AppVeyor][AppVeyor master image]][AppVeyor master] | [![AppVeyor][AppVeyor 2.10 image]][AppVeyor 2.10] |
 
 Powerful database abstraction layer with many features for database schema introspection, schema management and PDO abstraction.
@@ -17,20 +16,18 @@ Powerful database abstraction layer with many features for database schema intro
 * [Issue Tracker](https://github.com/doctrine/dbal/issues)
 
   [Master image]: https://img.shields.io/travis/doctrine/dbal/master.svg?style=flat-square
-  [Coverage image]: https://img.shields.io/scrutinizer/coverage/g/doctrine/dbal/master.svg?style=flat-square
-  [Quality image]: https://img.shields.io/scrutinizer/g/doctrine/dbal/master.svg?style=flat-square
+  [Coverage image]: https://coveralls.io/repos/github/doctrine/dbal/badge.svg?branch=master
   [ContinuousPHP image]: https://img.shields.io/continuousphp/git-hub/doctrine/dbal/master.svg?style=flat-square
   [Master]: https://travis-ci.org/doctrine/dbal
-  [Scrutinizer Master]: https://scrutinizer-ci.com/g/doctrine/dbal/
+  [Coveralls Master]: https://coveralls.io/github/doctrine/dbal?branch=master
   [AppVeyor master]: https://ci.appveyor.com/project/doctrine/dbal/branch/master
   [AppVeyor master image]: https://ci.appveyor.com/api/projects/status/i88kitq8qpbm0vie/branch/master?svg=true
   [ContinuousPHP]: https://continuousphp.com/git-hub/doctrine/dbal
 
   [2.10 image]: https://img.shields.io/travis/doctrine/dbal/2.10.x.svg?style=flat-square
-  [Coverage 2.10 image]: https://img.shields.io/scrutinizer/coverage/g/doctrine/dbal/2.10.x.svg?style=flat-square
-  [Quality 2.10 image]: https://img.shields.io/scrutinizer/g/doctrine/dbal/2.10.x.svg?style=flat-square
+  [Coverage 2.10 image]: https://coveralls.io/repos/github/doctrine/dbal/badge.svg?branch=2.10.x
   [ContinuousPHP 2.10 image]: https://img.shields.io/continuousphp/git-hub/doctrine/dbal/2.10.x.svg?style=flat-square
   [2.10]: https://github.com/doctrine/dbal/tree/2.10.x
-  [Scrutinizer 2.10]: https://scrutinizer-ci.com/g/doctrine/dbal/?branch=2.10.x
+  [Coveralls 2.10]: https://coveralls.io/github/doctrine/dbal?branch=2.10.x
   [AppVeyor 2.10]: https://ci.appveyor.com/project/doctrine/dbal/branch/2.10.x
   [AppVeyor 2.10 image]: https://ci.appveyor.com/api/projects/status/i88kitq8qpbm0vie/branch/2.10.x?svg=true

UPGRADE.md

@@ -138,9 +138,17 @@ Please use other database client applications for import, e.g.:
 
 # Upgrade to 2.11
 
+## Deprecated `Connection::project()`
+
+The `Connection::project()` method is deprecated. Implement data transformation outside of DBAL.
+
+## Deprecated `Statement::errorCode()` and `errorInfo()`
+
+The `Statement::errorCode()` and `errorInfo()` methods are deprecated. The error information is available via exceptions.
+
 ## Deprecated `EchoSQLLogger`
 
-The `EchoSQLLogger` is has been deprecated. Implement your logger with the desired logic.
+The `EchoSQLLogger` class is deprecated. Implement your logger with the desired logic.
 
 ## Deprecated database platforms:
 

bin/doctrine-dbal.php

 <?php
 
+use Doctrine\DBAL\Tools\Console\ConnectionProvider;
 use Doctrine\DBAL\Tools\Console\ConsoleRunner;
 use Symfony\Component\Console\Helper\HelperSet;
 
@@ -41,17 +42,17 @@ if (! is_readable($configFile)) {
     exit(1);
 }
 
-$commands  = [];
-$helperSet = require $configFile;
+$commands                      = [];
+$helperSetOrConnectionProvider = require $configFile;
 
-if (! $helperSet instanceof HelperSet) {
-    foreach ($GLOBALS as $helperSetCandidate) {
-        if ($helperSetCandidate instanceof HelperSet) {
-            $helperSet = $helperSetCandidate;
+if (! $helperSetOrConnectionProvider instanceof HelperSet && ! $helperSetOrConnectionProvider instanceof ConnectionProvider) {
+    foreach ($GLOBALS as $candidate) {
+        if ($candidate instanceof HelperSet) {
+            $helperSetOrConnectionProvider = $candidate;
 
             break;
         }
     }
 }
 
-ConsoleRunner::run($helperSet, $commands);
+ConsoleRunner::run($helperSetOrConnectionProvider, $commands);

ci/continuousphp/bootstrap.php

@@ -13,19 +13,4 @@ use Doctrine\DBAL\DriverManager;
         'password' => 'ORACLE',
         'dbname' => 'XE',
     ])->query('ALTER USER ORACLE IDENTIFIED BY ORACLE');
-
-    $pos = array_search('--coverage-clover', $_SERVER['argv'], true);
-
-    if ($pos === false) {
-        return;
-    }
-
-    $file = $_SERVER['argv'][$pos + 1];
-
-    register_shutdown_function(static function () use ($file) : void {
-        $cmd = 'wget https://github.com/scrutinizer-ci/ocular/releases/download/1.5.2/ocular.phar'
-            . ' && php ocular.phar code-coverage:upload --format=php-clover ' . escapeshellarg($file);
-
-        passthru($cmd);
-    });
 })();

docs/en/reference/configuration.rst

@@ -64,12 +64,12 @@ For example, to connect to a "foo" MySQL DB using the ``pdo_mysql``
 driver on localhost port 4486 with the charset set to UTF-8, you
 would use the following URL::
 
-    mysql://localhost:4486/foo?charset=UTF-8
+    mysql://localhost:4486/foo?charset=UTF8
 
 This is identical to the following connection string using the
 full driver name::
 
-    pdo-mysql://localhost:4486/foo?charset=UTF-8
+    pdo-mysql://localhost:4486/foo?charset=UTF8
 
 In the example above, mind the dashes instead of the
 underscores in the URL scheme.

phpcs.xml.dist

@@ -37,10 +37,6 @@
         </properties>
     </rule>
 
-    <rule ref="Squiz.NamingConventions.ValidVariableName.PublicHasUnderscore">
-        <exclude-pattern>*/src/*</exclude-pattern>
-    </rule>
-
     <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint">
         <exclude-pattern>*/src/*</exclude-pattern>
     </rule>
@@ -65,11 +61,6 @@
         <exclude-pattern>tests/Tools/TestAsset/*</exclude-pattern>
     </rule>
 
-    <!-- https://github.com/slevomat/coding-standard/issues/868 -->
-    <rule ref="SlevomatCodingStandard.PHP.UselessParentheses.UselessParentheses">
-        <exclude-pattern>ci/continuousphp/bootstrap.php</exclude-pattern>
-    </rule>
-
     <!-- see https://github.com/squizlabs/PHP_CodeSniffer/issues/2099 -->
     <rule ref="Squiz.Commenting.FunctionComment.InvalidNoReturn">
         <exclude-pattern>src/Platforms/AbstractPlatform.php</exclude-pattern>
@@ -107,11 +98,6 @@
         <exclude-pattern>src/Driver/SQLSrv/SQLSrvStatement.php</exclude-pattern>
     </rule>
 
-    <!-- sqlsrv functions are documented in upper case but reflected in lower case -->
-    <rule ref="Squiz.PHP.LowercasePHPFunctions.CallUppercase">
-        <exclude-pattern>src/Driver/SQLSrv/SQLSrvStatement.php</exclude-pattern>
-    </rule>
-
     <!-- see https://github.com/doctrine/dbal/issues/3377 -->
     <rule ref="SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedNotEqualOperator">
         <exclude-pattern>src/Schema/Comparator.php</exclude-pattern>

src/Connection.php

@@ -962,6 +962,8 @@ class Connection implements DriverConnection
      * Executes an, optionally parametrized, SQL query and returns the result,
      * applying a given projection/transformation function on each row of the result.
      *
+     * @deprecated
+     *
      * @param string  $query    The SQL query to execute.
      * @param mixed[] $params   The parameters, if any.
      * @param Closure $function The transformation function that is applied on each row.
@@ -1092,6 +1094,8 @@ class Connection implements DriverConnection
     /**
      * Fetches the SQLSTATE associated with the last database operation.
      *
+     * @deprecated The error information is available via exceptions.
+     *
      * @return string|null The last error code.
      */
     public function errorCode()
@@ -1101,6 +1105,8 @@ class Connection implements DriverConnection
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/Connection.php

@@ -75,6 +75,8 @@ interface Connection
     /**
      * Returns the error code associated with the last operation on the database handle.
      *
+     * @deprecated The error information is available via exceptions.
+     *
      * @return string|null The error code, or null if no operation has been run on the database handle.
      */
     public function errorCode();
@@ -82,6 +84,8 @@ interface Connection
     /**
      * Returns extended error information associated with the last operation on the database handle.
      *
+     * @deprecated The error information is available via exceptions.
+     *
      * @return mixed[]
      */
     public function errorInfo();

src/Driver/IBMDB2/DB2Connection.php

@@ -169,6 +169,8 @@ class DB2Connection implements ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -177,6 +179,8 @@ class DB2Connection implements ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/IBMDB2/DB2Statement.php

@@ -156,6 +156,8 @@ class DB2Statement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -164,6 +166,8 @@ class DB2Statement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/Mysqli/MysqliConnection.php

@@ -195,6 +195,8 @@ class MysqliConnection implements PingableConnection, ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -203,6 +205,8 @@ class MysqliConnection implements PingableConnection, ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/Mysqli/MysqliStatement.php

@@ -389,6 +389,8 @@ class MysqliStatement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -397,6 +399,8 @@ class MysqliStatement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/OCI8/OCI8Connection.php

@@ -205,6 +205,8 @@ class OCI8Connection implements Connection, ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -218,6 +220,8 @@ class OCI8Connection implements Connection, ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/OCI8/OCI8Statement.php

@@ -356,6 +356,8 @@ class OCI8Statement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -369,6 +371,8 @@ class OCI8Statement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/SQLAnywhere/SQLAnywhereConnection.php

@@ -90,6 +90,8 @@ class SQLAnywhereConnection implements ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -98,6 +100,8 @@ class SQLAnywhereConnection implements ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/SQLAnywhere/SQLAnywhereStatement.php

@@ -137,6 +137,8 @@ class SQLAnywhereStatement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -145,6 +147,8 @@ class SQLAnywhereStatement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/SQLSrv/SQLSrvConnection.php

@@ -171,6 +171,8 @@ class SQLSrvConnection implements ServerInfoAwareConnection
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -184,6 +186,8 @@ class SQLSrvConnection implements ServerInfoAwareConnection
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/SQLSrv/SQLSrvStatement.php

@@ -203,6 +203,8 @@ class SQLSrvStatement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -216,6 +218,8 @@ class SQLSrvStatement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Driver/Statement.php

@@ -60,6 +60,8 @@ interface Statement extends ResultStatement
     /**
      * Fetches the SQLSTATE associated with the last operation on the statement handle.
      *
+     * @deprecated The error information is available via exceptions.
+     *
      * @see Doctrine_Adapter_Interface::errorCode()
      *
      * @return string|int|bool The error code string.
@@ -69,6 +71,8 @@ interface Statement extends ResultStatement
     /**
      * Fetches extended error information associated with the last operation on the statement handle.
      *
+     * @deprecated The error information is available via exceptions.
+     *
      * @return mixed[] The error info array.
      */
     public function errorInfo();

src/Exception/RetryableException.php

@@ -2,9 +2,13 @@
 
 namespace Doctrine\DBAL\Exception;
 
+use Throwable;
+
 /**
  * Marker interface for all exceptions where retrying the transaction makes sense.
+ *
+ * @psalm-immutable
  */
-interface RetryableException
+interface RetryableException extends Throwable
 {
 }

src/Portability/Statement.php

@@ -80,6 +80,8 @@ class Statement implements IteratorAggregate, DriverStatement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorCode()
     {
@@ -90,6 +92,8 @@ class Statement implements IteratorAggregate, DriverStatement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Statement.php

@@ -196,6 +196,8 @@ class Statement implements IteratorAggregate, DriverStatement
     /**
      * Fetches the SQLSTATE associated with the last operation on the statement.
      *
+     * @deprecated The error information is available via exceptions.
+     *
      * @return string|int|bool
      */
     public function errorCode()
@@ -205,6 +207,8 @@ class Statement implements IteratorAggregate, DriverStatement
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function errorInfo()
     {

src/Tools/Console/Command/ReservedWordsCommand.php

@@ -15,6 +15,8 @@ use Doctrine\DBAL\Platforms\Keywords\ReservedKeywordsValidator;
 use Doctrine\DBAL\Platforms\Keywords\SQLAnywhereKeywords;
 use Doctrine\DBAL\Platforms\Keywords\SQLiteKeywords;
 use Doctrine\DBAL\Platforms\Keywords\SQLServer2012Keywords;
+use Doctrine\DBAL\Tools\Console\ConnectionProvider;
+use Exception;
 use InvalidArgumentException;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
@@ -24,6 +26,9 @@ use function array_keys;
 use function assert;
 use function count;
 use function implode;
+use function is_string;
+use function trigger_error;
+use const E_USER_DEPRECATED;
 
 class ReservedWordsCommand extends Command
 {
@@ -42,6 +47,20 @@ class ReservedWordsCommand extends Command
         'sqlserver'     => SQLServer2012Keywords::class,
     ];
 
+    /** @var ConnectionProvider|null */
+    private $connectionProvider;
+
+    public function __construct(?ConnectionProvider $connectionProvider = null)
+    {
+        parent::__construct();
+        $this->connectionProvider = $connectionProvider;
+        if ($connectionProvider !== null) {
+            return;
+        }
+
+        @trigger_error('Not passing a connection provider as the first constructor argument is deprecated', E_USER_DEPRECATED);
+    }
+
     /**
      * If you want to add or replace a keywords list use this command.
      *
@@ -61,12 +80,14 @@ class ReservedWordsCommand extends Command
         $this
         ->setName('dbal:reserved-words')
         ->setDescription('Checks if the current database contains identifiers that are reserved.')
-        ->setDefinition([new InputOption(
-            'list',
-            'l',
-            InputOption::VALUE_OPTIONAL | InputOption::VALUE_IS_ARRAY,
-            'Keyword-List name.'
-        ),
+        ->setDefinition([
+            new InputOption('connection', null, InputOption::VALUE_REQUIRED, 'The named database connection'),
+            new InputOption(
+                'list',
+                'l',
+                InputOption::VALUE_OPTIONAL | InputOption::VALUE_IS_ARRAY,
+                'Keyword-List name.'
+            ),
         ])
         ->setHelp(<<<EOT
 Checks if the current database contains tables and columns
@@ -105,8 +126,7 @@ EOT
      */
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $conn = $this->getHelper('db')->getConnection();
-        assert($conn instanceof Connection);
+        $conn = $this->getConnection($input);
 
         $keywordLists = (array) $input->getOption('list');
         if (count($keywordLists) === 0) {
@@ -146,4 +166,24 @@ EOT
 
         return 0;
     }
+
+    private function getConnection(InputInterface $input) : Connection
+    {
+        $connectionName = $input->getOption('connection');
+        assert(is_string($connectionName) || $connectionName === null);
+
+        if ($this->connectionProvider === null) {
+            if ($connectionName !== null) {
+                throw new Exception('Specifying a connection is only supported when a ConnectionProvider is used.');
+            }
+
+            return $this->getHelper('db')->getConnection();
+        }
+
+        if ($connectionName !== null) {
+            return $this->connectionProvider->getConnection($connectionName);
+        }
+
+        return $this->connectionProvider->getDefaultConnection();
+    }
 }

src/Tools/Console/Command/RunSqlCommand.php

@@ -2,7 +2,10 @@
 
 namespace Doctrine\DBAL\Tools\Console\Command;
 
+use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\Tools\Console\ConnectionProvider;
 use Doctrine\DBAL\Tools\Dumper;
+use Exception;
 use LogicException;
 use RuntimeException;
 use Symfony\Component\Console\Command\Command;
@@ -15,6 +18,8 @@ use function is_bool;
 use function is_numeric;
 use function is_string;
 use function stripos;
+use function trigger_error;
+use const E_USER_DEPRECATED;
 
 /**
  * Task for executing arbitrary SQL that can come from a file or directly from
@@ -22,6 +27,20 @@ use function stripos;
  */
 class RunSqlCommand extends Command
 {
+    /** @var ConnectionProvider|null */
+    private $connectionProvider;
+
+    public function __construct(?ConnectionProvider $connectionProvider = null)
+    {
+        parent::__construct();
+        $this->connectionProvider = $connectionProvider;
+        if ($connectionProvider !== null) {
+            return;
+        }
+
+        @trigger_error('Not passing a connection provider as the first constructor argument is deprecated', E_USER_DEPRECATED);
+    }
+
     /** @return void */
     protected function configure()
     {
@@ -29,12 +48,16 @@ class RunSqlCommand extends Command
         ->setName('dbal:run-sql')
         ->setDescription('Executes arbitrary SQL directly from the command line.')
         ->setDefinition([
+            new InputOption('connection', null, InputOption::VALUE_REQUIRED, 'The named database connection'),
             new InputArgument('sql', InputArgument::REQUIRED, 'The SQL statement to execute.'),
             new InputOption('depth', null, InputOption::VALUE_REQUIRED, 'Dumping depth of result set.', 7),
             new InputOption('force-fetch', null, InputOption::VALUE_NONE, 'Forces fetching the result.'),
         ])
         ->setHelp(<<<EOT
-Executes arbitrary SQL directly from the command line.
+The <info>%command.name%</info> command executes the given SQL query and
+outputs the results:
+
+<info>php %command.full_name% "SELECT * FROM users"</info>
 EOT
         );
     }
@@ -44,7 +67,7 @@ EOT
      */
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $conn = $this->getHelper('db')->getConnection();
+        $conn = $this->getConnection($input);
 
         $sql = $input->getArgument('sql');
 
@@ -73,4 +96,24 @@ EOT
 
         return 0;
     }
+
+    private function getConnection(InputInterface $input) : Connection
+    {
+        $connectionName = $input->getOption('connection');
+        assert(is_string($connectionName) || $connectionName === null);
+
+        if ($this->connectionProvider === null) {
+            if ($connectionName !== null) {
+                throw new Exception('Specifying a connection is only supported when a ConnectionProvider is used.');
+            }
+
+            return $this->getHelper('db')->getConnection();
+        }
+
+        if ($connectionName !== null) {
+            return $this->connectionProvider->getConnection($connectionName);
+        }
+
+        return $this->connectionProvider->getDefaultConnection();
+    }
 }

src/Tools/Console/ConnectionNotFound.php

+<?php
+
+namespace Doctrine\DBAL\Tools\Console;
+
+use OutOfBoundsException;
+
+final class ConnectionNotFound extends OutOfBoundsException
+{
+}

src/Tools/Console/ConnectionProvider.php

+<?php
+
+namespace Doctrine\DBAL\Tools\Console;
+
+use Doctrine\DBAL\Connection;
+
+interface ConnectionProvider
+{
+    public function getDefaultConnection() : Connection;
+
+    /**
+     * @throws ConnectionNotFound in case a connection with the given name does not exist.
+     */
+    public function getConnection(string $name) : Connection;
+}

src/Tools/Console/ConnectionProvider/SingleConnectionProvider.php

+<?php
+
+namespace Doctrine\DBAL\Tools\Console\ConnectionProvider;
+
+use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\Tools\Console\ConnectionNotFound;
+use Doctrine\DBAL\Tools\Console\ConnectionProvider;
+use function sprintf;
+
+class SingleConnectionProvider implements ConnectionProvider
+{
+    /** @var Connection */
+    private $connection;
+
+    /** @var string */
+    private $defaultConnectionName;
+
+    public function __construct(Connection $connection, string $defaultConnectionName = 'default')
+    {
+        $this->connection            = $connection;
+        $this->defaultConnectionName = $defaultConnectionName;
+    }
+
+    public function getDefaultConnection() : Connection
+    {
+        return $this->connection;
+    }
+
+    public function getConnection(string $name) : Connection
+    {
+        if ($name !== $this->defaultConnectionName) {
+            throw new ConnectionNotFound(sprintf('Connection with name "%s" does not exist.', $name));
+        }
+
+        return $this->connection;
+    }
+}

src/Tools/Console/ConsoleRunner.php

@@ -10,6 +10,10 @@ use PackageVersions\Versions;
 use Symfony\Component\Console\Application;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Helper\HelperSet;
+use TypeError;
+use function sprintf;
+use function trigger_error;
+use const E_USER_DEPRECATED;
 
 /**
  * Handles running the Console Tools inside Symfony Console context.
@@ -19,6 +23,8 @@ class ConsoleRunner
     /**
      * Create a Symfony Console HelperSet
      *
+     * @deprecated use a ConnectionProvider instead.
+     *
      * @return HelperSet
      */
     public static function createHelperSet(Connection $connection)
@@ -29,20 +35,31 @@ class ConsoleRunner
     }
 
     /**
-     * Runs console with the given helperset.
+     * Runs console with the given connection provider or helperset (deprecated).
      *
-     * @param Command[] $commands
+     * @param ConnectionProvider|HelperSet $helperSetOrConnectionProvider
+     * @param Command[]                    $commands
      *
      * @return void
      */
-    public static function run(HelperSet $helperSet, $commands = [])
+    public static function run($helperSetOrConnectionProvider, $commands = [])
     {
         $cli = new Application('Doctrine Command Line Interface', Versions::getVersion('doctrine/dbal'));
 
         $cli->setCatchExceptions(true);
-        $cli->setHelperSet($helperSet);
 
-        self::addCommands($cli);
+        $connectionProvider = null;
+        if ($helperSetOrConnectionProvider instanceof HelperSet) {
+            @trigger_error(sprintf('Passing an instance of "%s" as the first argument is deprecated. Pass an instance of "%s" instead.', HelperSet::class, ConnectionProvider::class), E_USER_DEPRECATED);
+            $connectionProvider = null;
+            $cli->setHelperSet($helperSetOrConnectionProvider);
+        } elseif ($helperSetOrConnectionProvider instanceof ConnectionProvider) {
+            $connectionProvider = $helperSetOrConnectionProvider;
+        } else {
+            throw new TypeError(sprintf('First argument must be an instance of "%s" or "%s"', HelperSet::class, ConnectionProvider::class));
+        }
+
+        self::addCommands($cli, $connectionProvider);
 
         $cli->addCommands($commands);
         $cli->run();
@@ -51,11 +68,12 @@ class ConsoleRunner
     /**
      * @return void
      */
-    public static function addCommands(Application $cli)
+    public static function addCommands(Application $cli, ?ConnectionProvider $connectionProvider = null)
     {
         $cli->addCommands([
             new RunSqlCommand(),
             new ReservedWordsCommand(),
+            new ReservedWordsCommand($connectionProvider),
         ]);
     }
 
@@ -72,14 +90,17 @@ project, which is required to get the Doctrine-DBAL Console working. You can use
 following sample as a template:
 
 <?php
-use Doctrine\DBAL\Tools\Console\ConsoleRunner;
-
-// replace with the mechanism to retrieve DBAL connection in your app
-$connection = getDBALConnection();
+use Doctrine\DBAL\Tools\Console\ConnectionProvider\SingleConnectionProvider;
 
 // You can append new commands to $commands array, if needed
 
-return ConsoleRunner::createHelperSet($connection);
+// replace with the mechanism to retrieve DBAL connection(s) in your app
+// and return a Doctrine\DBAL\Tools\Console\ConnectionProvider instance.
+$connection = getDBALConnection();
+
+// in case you have a single connection you can use SingleConnectionProvider
+// otherwise you need to implement the Doctrine\DBAL\Tools\Console\ConnectionProvider interface with your custom logic
+return new SingleConnectionProvider($connection);
 
 HELP;
     }

src/Tools/Console/Helper/ConnectionHelper.php

@@ -7,6 +7,8 @@ use Symfony\Component\Console\Helper\Helper;
 
 /**
  * Doctrine CLI Connection Helper.
+ *
+ * @deprecated use a ConnectionProvider instead.
  */
 class ConnectionHelper extends Helper
 {