Merge branch '3.6.x' into 4.0.x

* 3.6.x:
  Optimize pgsql queries without parameters
  Raise exception if pg_send_*() calls fail
  Add the PgSQL driver
  Make sure only PDO parameter types are passed
  [Docs] Add IBM DB2 to `configuration.rst`
  Use psalm-assert to get rid of assert() calls
  Introduce the SchemaManagerFactory interface

Author: derrabus

.github/workflows/continuous-integration.yml

@@ -212,11 +212,17 @@ jobs:
           - "8.1"
         postgres-version:
           - "10"
-          - "14"
           - "15"
+        extension:
+          - "pgsql"
+          - "pdo_pgsql"
         include:
           - php-version: "8.2"
             postgres-version: "15"
+            extension: "pgsql"
+          - php-version: "8.2"
+            postgres-version: "15"
+            extension: "pdo_pgsql"
 
     services:
       postgres:
@@ -240,6 +246,7 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
+          extensions: "pgsql pdo_pgsql"
           coverage: "pcov"
           ini-values: "zend.assertions=1"
 
@@ -249,12 +256,12 @@ jobs:
           composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
-        run: "vendor/bin/phpunit -c ci/github/phpunit/pdo_pgsql.xml --coverage-clover=coverage.xml"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage.xml"
 
       - name: "Upload coverage file"
         uses: "actions/upload-artifact@v3"
         with:
-          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}.coverage"
+          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.extension }}-${{ matrix.php-version }}.coverage"
           path: "coverage.xml"
 
   phpunit-mariadb:

UPGRADE.md

@@ -882,6 +882,25 @@ The following methods have been removed.
 
 # Upgrade to 3.6
 
+## Deprecated not setting a schema manager factory
+
+DBAL 4 will change the way the schema manager is created. To opt in to the new
+behavior, please configure the schema manager factory:
+
+```php
+$configuration = new Configuration();
+$configuration->setSchemaManagerFactory(new DefaultSchemaManagerFactory());
+
+$connection = DriverManager::getConnection(
+    [/* your parameters */],
+    $configuration,
+);
+```
+
+If you use a custom platform implementation, please make sure it implements
+the `createSchemaManager()`method . Otherwise, the connection will fail to
+create a schema manager.
+
 ## Deprecated the `url` connection parameter
 
 DBAL ships with a new and configurable DSN parser that can be used to parse a

ci/github/phpunit/pgsql.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         beStrictAboutOutputDuringTests="true"
+         beStrictAboutTodoAnnotatedTests="true"
+         failOnRisky="true"
+         failOnWarning="true"
+         convertDeprecationsToExceptions="true"
+>
+    <php>
+        <ini name="error_reporting" value="-1" />
+
+        <var name="db_driver" value="pgsql"/>
+        <var name="db_host" value="localhost" />
+        <var name="db_user" value="postgres" />
+        <var name="db_password" value="postgres" />
+        <var name="db_dbname" value="doctrine_tests" />
+    </php>
+
+    <testsuites>
+        <testsuite name="Doctrine DBAL Test Suite">
+            <directory>../../../tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <coverage>
+        <include>
+            <directory suffix=".php">../../../src</directory>
+        </include>
+    </coverage>
+</phpunit>

docs/en/reference/configuration.rst

@@ -151,12 +151,15 @@ interfaces to use. It can be configured in one of three ways:
    -  ``sqlite3``: An SQLite driver that uses the sqlite3 extension.
    -  ``pdo_pgsql``: A PostgreSQL driver that uses the pdo_pgsql PDO
       extension.
+   -  ``pgsql``: A PostgreSQL driver that uses the pgsql extension. This driver does support loading BLOBs from file
+      resources yet. It is still considered experimental. Use `pdo_pgsql` if you need a stable driver for Postgres.
    -  ``pdo_oci``: An Oracle driver that uses the pdo_oci PDO
       extension.
       **Note that this driver caused problems in our tests. Prefer the oci8 driver if possible.**
    -  ``pdo_sqlsrv``: A Microsoft SQL Server driver that uses pdo_sqlsrv PDO
    -  ``sqlsrv``: A Microsoft SQL Server driver that uses the sqlsrv PHP extension.
    -  ``oci8``: An Oracle driver that uses the oci8 PHP extension.
+   -  ``ibm_db2``: An IBM DB2 driver that uses the ibm_db2 PHP extension.
 
 -  ``driverClass``: Specifies a custom driver implementation if no
    'driver' is specified. This allows the use of custom drivers that
@@ -235,8 +238,8 @@ mysqli
 -  ``ssl_cipher`` (string): A list of allowable ciphers to use for SSL encryption.
 -  ``driverOptions`` Any supported flags for mysqli found on `http://www.php.net/manual/en/mysqli.real-connect.php`
 
-pdo_pgsql
-^^^^^^^^^
+pdo_pgsql / pgsql
+^^^^^^^^^^^^^^^^^
 
 -  ``user`` (string): Username to use when connecting to the
    database.
@@ -315,6 +318,18 @@ pdo_sqlsrv / sqlsrv
 -  ``port`` (integer): Port of the database to connect to.
 -  ``dbname`` (string): Name of the database/schema to connect to.
 
+ibm_db2
+^^^^^^^
+
+-  ``dbname`` (string): Name of the database/schema to connect to or a complete connection string in
+   the format "DATABASE=dbname;HOSTNAME=host;PORT=port;PROTOCOL=TCPIP;UID=user;PWD=password;".
+-  ``user`` (string): Username to use when connecting to the database.
+-  ``password`` (string): Password to use when connecting to the database.
+-  ``host`` (string): Hostname of the database to connect to.
+-  ``port`` (integer): Port of the database to connect to.
+-  ``persistent`` (boolean): Whether to establish a persistent connection.
+-  ``driverOptions`` (array): Any supported options found on `https://www.php.net/manual/en/function.db2-connect.php#refsect1-function.db2-connect-parameters`
+
 Automatic platform version detection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/en/reference/schema-manager.rst

@@ -36,7 +36,7 @@ Retrieve an array of databases on the configured connection:
     $databases = $sm->listDatabases();
 
 listSequences()
--------------------------------
+---------------
 
 Retrieve an array of ``Doctrine\DBAL\Schema\Sequence`` instances
 that exist for a database:
@@ -63,7 +63,7 @@ Now you can loop over the array inspecting each sequence object:
     }
 
 listTableColumns()
-----------------------------
+------------------
 
 Retrieve an array of ``Doctrine\DBAL\Schema\Column`` instances that
 exist for the given table:
@@ -102,7 +102,7 @@ schema for that table. For example we can add a new column:
     $table->addColumn('email_address', 'string');
 
 listTableForeignKeys()
---------------------------------
+----------------------
 
 Retrieve an array of ``Doctrine\DBAL\Schema\ForeignKeyConstraint``
 instances that exist for the given table:
@@ -123,7 +123,7 @@ object:
     }
 
 listTableIndexes()
-----------------------------
+------------------
 
 Retrieve an array of ``Doctrine\DBAL\Schema\Index`` instances that
 exist for the given table:
@@ -232,3 +232,50 @@ table:
       0 => 'DROP TABLE user'
     )
     */
+
+Overriding the schema manager
+-----------------------------
+
+All schema manager classes can be overridden, for instance if your application needs to modify SQL statements emitted
+by the schema manager or the comparator. If you want your own schema manager to be returned by
+``Connection::createSchemaManager()`` you need to configure a factory for it.
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\DBAL\Configuration;
+    use Doctrine\DBAL\DriverManager;
+    use Doctrine\DBAL\Platforms\AbstractMySQLPlatform;
+    use Doctrine\DBAL\Schema\DefaultSchemaManagerFactory;
+    use Doctrine\DBAL\Schema\MySQLSchemaManager;
+    use Doctrine\DBAL\Schema\SchemaManagerFactory;
+
+    class MyCustomMySQLSchemaManager extends MySQLSchemaManager
+    {
+        // .. your custom logic.
+    }
+
+    final class MySchemaManagerFactory implements SchemaManagerFactory
+    {
+        private readonly SchemaManagerFactory $defaultFactory;
+
+        public function __construct()
+        {
+            $this->defaultFactory = new DefaultSchemaManagerFactory();
+        }
+
+        public function createSchemaManager(Connection $connection): AbstractSchemaManager
+        {
+            $platform = $connection->getDatabasePlatform();
+            if ($platform instanceof AbstractMySQLPlatform) {
+                return new MyCustomMySQLSchemaManager($connection, $platform);
+            }
+
+            return $this->defaultFactory->createSchemaManager($connection);
+        }
+    }
+
+    $configuration = new Configuration();
+    $configuration->setSchemaManagerFactory(new MySchemaManagerFactory());
+
+    $connection = DriverManager::getConnection([/* your connection parameters */], $configuration);

phpcs.xml.dist

@@ -53,6 +53,11 @@
         <exclude-pattern>*/tests/*</exclude-pattern>
     </rule>
 
+    <rule ref="SlevomatCodingStandard.Classes.RequireConstructorPropertyPromotion.RequiredConstructorPropertyPromotion">
+        <!-- CPP breaks static analysis here. -->
+        <exclude-pattern>src/Driver/PgSQL/Result.php</exclude-pattern>
+    </rule>
+
     <rule ref="SlevomatCodingStandard.PHP.RequireExplicitAssertion.RequiredExplicitAssertion">
         <exclude-pattern>tests/*</exclude-pattern>
     </rule>

phpstan.neon.dist

@@ -64,9 +64,6 @@ parameters:
                 - src/Driver/Mysqli/Exception/StatementError.php
 
         # We're testing with invalid input.
-        -
-            message: '~^Unable to resolve the template type T in call to method static method Doctrine\\DBAL\\DriverManager::getConnection\(\)~'
-            path: tests/DriverManagerTest.php
         -
             message: '~array{driver: ''invalid_driver''} given\.$~'
             path: tests/DriverManagerTest.php
@@ -96,6 +93,25 @@ parameters:
             paths:
                 - src/Schema/PostgreSQLSchemaManager.php
 
+        # We don't need to declare the return type *that* fine-grained.
+        - '~^Method Doctrine\\DBAL\\Driver\\PDO\\Statement\:\:convertParamType\(\) never returns \d+ so it can be removed from the return type\.$~'
+
+        # PgSql objects are represented as resources in PHP 7.4
+        - '~ expects PgSql\\Connection(:?\|(?:string|null))?, PgSql\\Connection\|resource given\.$~'
+        - '~ expects PgSql\\Result, PgSql\\Result\|resource given\.$~'
+
+        # PHPStan does not understand the array shapes returned by pg_fetch_*() methods.
+        - '~^Parameter #1 \$row of method Doctrine\\DBAL\\Driver\\PgSQL\\Result\:\:mapAssociativeRow\(\) expects array<string, string\|null>, array<int\|string, string\|null> given\.$~'
+        - '~^Parameter #1 \$row of method Doctrine\\DBAL\\Driver\\PgSQL\\Result\:\:mapNumericRow\(\) expects array<int, string\|null>, array<int\|string, string\|null> given\.$~'
+
+        # Ignore isset() checks in destructors.
+        - '~^Property Doctrine\\DBAL\\Driver\\PgSQL\\Connection\:\:\$connection \(PgSql\\Connection\|resource\) in isset\(\) is not nullable\.$~'
+
+        # On PHP 7.4, pg_fetch_all() might return false for empty result sets.
+        -
+            message: '~^Strict comparison using === between array<int, array> and false will always evaluate to false\.$~'
+            paths:
+                - src/Driver/PgSQL/Result.php
 includes:
     - vendor/phpstan/phpstan-phpunit/extension.neon
     - vendor/phpstan/phpstan-phpunit/rules.neon

psalm.xml.dist

@@ -19,7 +19,6 @@
         <file name="vendor/jetbrains/phpstorm-stubs/ibm_db2/ibm_db2.php" />
         <file name="vendor/jetbrains/phpstorm-stubs/mysqli/mysqli.php" />
         <file name="vendor/jetbrains/phpstorm-stubs/oci8/oci8.php" />
-        <file name="vendor/jetbrains/phpstorm-stubs/pgsql/pgsql.php" />
         <file name="vendor/jetbrains/phpstorm-stubs/sqlsrv/sqlsrv.php" />
     </stubs>
     <issueHandlers>
@@ -50,6 +49,7 @@
                 -->
                 <file name="src/Connection.php"/>
                 <file name="src/Driver/IBMDB2/Statement.php"/>
+                <directory name="src/Driver/PgSQL"/>
                 <!--
                     Requires a release of https://github.com/JetBrains/phpstorm-stubs/pull/1255
                 -->
@@ -115,6 +115,30 @@
                 <file name="src/Driver/AbstractSQLiteDriver.php"/>
             </errorLevel>
         </NullableReturnStatement>
+        <PossiblyInvalidArgument>
+            <errorLevel type="suppress">
+                <!-- PgSql objects are represented as resources in PHP 7.4 -->
+                <referencedFunction name="pg_affected_rows"/>
+                <referencedFunction name="pg_close"/>
+                <referencedFunction name="pg_escape_bytea"/>
+                <referencedFunction name="pg_escape_literal"/>
+                <referencedFunction name="pg_fetch_all"/>
+                <referencedFunction name="pg_fetch_all_columns"/>
+                <referencedFunction name="pg_fetch_assoc"/>
+                <referencedFunction name="pg_fetch_row"/>
+                <referencedFunction name="pg_field_name"/>
+                <referencedFunction name="pg_field_type"/>
+                <referencedFunction name="pg_free_result"/>
+                <referencedFunction name="pg_get_result"/>
+                <referencedFunction name="pg_last_error"/>
+                <referencedFunction name="pg_num_fields"/>
+                <referencedFunction name="pg_result_error_field"/>
+                <referencedFunction name="pg_send_execute"/>
+                <referencedFunction name="pg_send_prepare"/>
+                <referencedFunction name="pg_send_query"/>
+                <referencedFunction name="pg_version"/>
+            </errorLevel>
+        </PossiblyInvalidArgument>
         <PossiblyInvalidArrayOffset>
             <errorLevel type="suppress">
                 <!-- $array[key($array)] is safe. -->
@@ -168,11 +192,14 @@
                 <file name="src/Platforms/AbstractMySQLPlatform.php"/>
                 <file name="tests/Functional/Driver/AbstractDriverTest.php"/>
 
+                <!-- We're checking for invalid input. -->
+                <directory name="src/Driver/PgSQL"/>
+
                 <!-- We're testing invalid input. -->
                 <file name="tests/Types/DateImmutableTypeTest.php"/>
                 <file name="tests/Types/DateTimeImmutableTypeTest.php"/>
                 <file name="tests/Types/TimeImmutableTypeTest.php"/>
-                
+
                 <!-- False positive: "mixed is never string" -->
                 <file name="src/Platforms/PostgreSQLPlatform.php" />
             </errorLevel>
@@ -189,6 +216,12 @@
                 <file name="tests/Functional/Schema/SchemaManagerFunctionalTestCase.php"/>
             </errorLevel>
         </TypeDoesNotContainNull>
+        <TypeDoesNotContainType>
+            <errorLevel type="suppress">
+                <!-- On PHP 7.4, pg_fetch_all() might return false for empty result sets. -->
+                <file name="src/Driver/PgSQL/Result.php"/>
+            </errorLevel>
+        </TypeDoesNotContainType>
         <UndefinedDocblockClass>
             <errorLevel type="suppress">
                 <!-- See https://github.com/vimeo/psalm/issues/5472 -->

src/Configuration.php

@@ -5,6 +5,7 @@
 namespace Doctrine\DBAL;
 
 use Doctrine\DBAL\Driver\Middleware;
+use Doctrine\DBAL\Schema\SchemaManagerFactory;
 use Psr\Cache\CacheItemPoolInterface;
 
 /**
@@ -32,6 +33,8 @@ class Configuration
      */
     protected bool $autoCommit = true;
 
+    private ?SchemaManagerFactory $schemaManagerFactory = null;
+
     public function __construct()
     {
         $this->schemaAssetsFilter = static function (): bool {
@@ -116,4 +119,17 @@ public function getMiddlewares(): array
     {
         return $this->middlewares;
     }
+
+    public function getSchemaManagerFactory(): ?SchemaManagerFactory
+    {
+        return $this->schemaManagerFactory;
+    }
+
+    /** @return $this */
+    public function setSchemaManagerFactory(SchemaManagerFactory $schemaManagerFactory): self
+    {
+        $this->schemaManagerFactory = $schemaManagerFactory;
+
+        return $this;
+    }
 }