Deprecate the Doctrine DBAL binary

UPGRADE.md

@@ -8,6 +8,13 @@ awareness about deprecated code.
 
 # Upgrade to 3.3
 
+## Deprecated the `doctrine-dbal` binary.
+
+The documentation explains how the console tools can be bootstrapped for standalone usage.
+
+The method `ConsoleRunner::printCliConfigTemplate()` is deprecated because it was only useful in the context of the
+`doctrine-dbal` binary.
+
 ## Deprecated the `Graphviz` visitor.
 
 This class is not part of the database abstraction provided by the library and will be removed in DBAL 4.

bin/doctrine-dbal.php

@@ -2,6 +2,15 @@
 
 use Doctrine\DBAL\Tools\Console\ConsoleRunner;
 
+fwrite(
+    STDERR,
+    '[Warning] The use of this script is discouraged.'
+        . ' You find instructions on how to boostrap the console runner in our documentation.'
+        . PHP_EOL
+);
+
+echo PHP_EOL . PHP_EOL;
+
 $files       = [__DIR__ . '/../vendor/autoload.php', __DIR__ . '/../../../autoload.php'];
 $loader      = null;
 $cwd         = getcwd();

docs/en/reference/cli-tools.rst

@@ -0,0 +1,37 @@
+CLI Tools
+=========
+
+Doctrine DBAL bundles commands that can be integrated into a Symfony console application.
+
+When you use DBAL inside a full-stack Symfony application, DoctrineBundle already integrates those into your
+application's console.
+
+There is also a standalone console runner available. To use it, make sure that Symfony console is installed::
+
+    composer require symfony/console
+
+With a small PHP script, you can bootstrap the console tools:
+
+.. code-block:: php
+
+    #!/usr/bin/env php
+    <?php
+
+    use Doctrine\DBAL\DriverManager;
+    use Doctrine\DBAL\Tools\Console\ConnectionProvider\SingleConnectionProvider;
+    use Doctrine\DBAL\Tools\Console\ConsoleRunner;
+
+    // The path to Composer's autoloader
+    // Adjust it according to your project's structure
+    require __DIR__ . '/vendor/autoload.php';
+
+    $connection = DriverManager::getConnection([
+        // Configure your DBAL connection here.
+    ]);
+
+    ConsoleRunner::run(
+        new SingleConnectionProvider($connection)
+    );
+
+If your application uses more than one connection, write your own implementation of ``ConnectionProvider`` and use it
+instead of the ``SingleConnectionProvider`` class.

src/Tools/Console/ConsoleRunner.php

@@ -52,6 +52,8 @@ public static function addCommands(Application $cli, ConnectionProvider $connect
     /**
      * Prints the instructions to create a configuration file
      *
+     * @deprecated This method will be removed without replacement.
+     *
      * @return void
      */
     public static function printCliConfigTemplate()