Merge branch '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.4
-    coverage: yes
   - db: mssql
     driver: sqlsrv
     db_version: sql2017
-    coverage: no
     php: 7.4
   - db: mssql
     driver: pdo_sqlsrv
     db_version: sql2017
     php: 7.4
-    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

@@ -407,9 +407,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

@@ -2,6 +2,7 @@
 
 declare(strict_types=1);
 
+use Doctrine\DBAL\Tools\Console\ConnectionProvider;
 use Doctrine\DBAL\Tools\Console\ConsoleRunner;
 use Symfony\Component\Console\Helper\HelperSet;
 
@@ -43,17 +44,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,21 +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;
-    }
-
-    assert(is_int($pos));
-
-    $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

@@ -36,10 +36,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>
@@ -68,11 +64,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>
@@ -109,11 +100,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/Driver/IBMDB2/DB2Statement.php

@@ -133,6 +133,8 @@ final class DB2Statement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function execute(?array $params = null) : void
     {

src/Driver/OCI8/OCI8Statement.php

@@ -190,6 +190,8 @@ final class OCI8Statement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function execute(?array $params = null) : void
     {

src/Driver/SQLSrv/SQLSrvStatement.php

@@ -181,6 +181,8 @@ final class SQLSrvStatement implements IteratorAggregate, Statement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function execute(?array $params = null) : void
     {

src/Exception/RetryableException.php

@@ -4,9 +4,13 @@ declare(strict_types=1);
 
 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

@@ -76,6 +76,8 @@ final class Statement implements IteratorAggregate, DriverStatement
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated The error information is available via exceptions.
      */
     public function execute(?array $params = null) : void
     {

src/Tools/Console/Command/ReservedWordsCommand.php

@@ -17,6 +17,8 @@ use Doctrine\DBAL\Platforms\Keywords\ReservedKeywordsValidator;
 use Doctrine\DBAL\Platforms\Keywords\SQLAnywhere16Keywords;
 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;
@@ -26,7 +28,10 @@ use function array_keys;
 use function assert;
 use function count;
 use function implode;
+use function is_string;
 use function sprintf;
+use function trigger_error;
+use const E_USER_DEPRECATED;
 
 class ReservedWordsCommand extends Command
 {
@@ -45,6 +50,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.
      */
@@ -58,12 +77,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
@@ -102,8 +123,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) {
@@ -144,4 +164,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

@@ -4,7 +4,10 @@ declare(strict_types=1);
 
 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;
@@ -17,6 +20,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
@@ -24,18 +29,36 @@ 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);
+    }
+
     protected function configure() : void
     {
         $this
         ->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
         );
     }
@@ -45,7 +68,7 @@ EOT
      */
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $conn = $this->getHelper('db')->getConnection();
+        $conn = $this->getConnection($input);
 
         $sql = $input->getArgument('sql');
 
@@ -74,4 +97,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
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tools\Console;
+
+use OutOfBoundsException;
+
+final class ConnectionNotFound extends OutOfBoundsException
+{
+}

src/Tools/Console/ConnectionProvider.php

+<?php
+
+declare(strict_types=1);
+
+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
+
+declare(strict_types=1);
+
+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

@@ -12,6 +12,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.
@@ -20,6 +24,8 @@ class ConsoleRunner
 {
     /**
      * Create a Symfony Console HelperSet
+     *
+     * @deprecated use a ConnectionProvider instead.
      */
     public static function createHelperSet(Connection $connection) : HelperSet
     {
@@ -29,28 +35,40 @@ class ConsoleRunner
     }
 
     /**
-     * Runs console with the given helperset.
+     * Runs console with the given connection provider or helperset (deprecated).
      *
-     * @param array<int, Command> $commands
+     * @param ConnectionProvider|HelperSet $helperSetOrConnectionProvider
+     * @param array<int, Command>          $commands
      */
-    public static function run(HelperSet $helperSet, array $commands = []) : void
+    public static function run($helperSetOrConnectionProvider, $commands = []) : void
     {
         $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();
     }
 
-    public static function addCommands(Application $cli) : void
+    public static function addCommands(Application $cli, ?ConnectionProvider $connectionProvider = null) : void
     {
         $cli->addCommands([
             new RunSqlCommand(),
             new ReservedWordsCommand(),
+            new ReservedWordsCommand($connectionProvider),
         ]);
     }
 
@@ -65,14 +83,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

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

tests/FunctionalTestCase.php

@@ -48,13 +48,14 @@ abstract class FunctionalTestCase extends TestCase
 
     protected function setUp() : void
     {
+        $this->sqlLoggerStack = new DebugStack();
+
         if (! isset(self::$sharedConnection)) {
             self::$sharedConnection = TestUtil::getConnection();
         }
 
         $this->connection = self::$sharedConnection;
 
-        $this->sqlLoggerStack = new DebugStack();
         $this->connection->getConfiguration()->setSQLLogger($this->sqlLoggerStack);
     }