Merge branch '3.8.x' into 4.0.x

* 3.8.x:
  Add `QueryBuilder::resetOrderBy()` (#6190)
  Enable establishing exclusive oci8 connections (#6182)

docs/en/reference/configuration.rst

@@ -319,6 +319,9 @@ pdo_oci / oci8
    parameters will no longer be used. Note that when using this parameter, the ``getHost``
    and ``getPort`` methods from ``Doctrine\DBAL\Connection`` will no longer function as expected.
 -  ``persistent`` (boolean): Whether to establish a persistent connection.
+-  ``driverOptions`` (array):
+    -  ``exclusive`` (boolean): Once specified for an ``oci8`` connection, forces the driver to always establish
+       a new connection instead of reusing an existing one from the connection pool.
 
 pdo_sqlsrv / sqlsrv
 ^^^^^^^^^^^^^^^^^^^

src/Driver/OCI8/Driver.php

@@ -6,6 +6,7 @@
 
 use Doctrine\DBAL\Driver\AbstractOracleDriver;
 use Doctrine\DBAL\Driver\OCI8\Exception\ConnectionFailed;
+use Doctrine\DBAL\Driver\OCI8\Exception\InvalidConfiguration;
 use SensitiveParameter;
 
 use function oci_connect;
@@ -32,8 +33,17 @@ public function connect(
 
         $connectionString = $this->getEasyConnectString($params);
 
-        if (! empty($params['persistent'])) {
+        $persistent = ! empty($params['persistent']);
+        $exclusive  = ! empty($params['driverOptions']['exclusive']);
+
+        if ($persistent && $exclusive) {
+            throw InvalidConfiguration::forPersistentAndExclusive();
+        }
+
+        if ($persistent) {
             $connection = @oci_pconnect($username, $password, $connectionString, $charset, $sessionMode);
+        } elseif ($exclusive) {
+            $connection = @oci_new_connect($username, $password, $connectionString, $charset, $sessionMode);
         } else {
             $connection = @oci_connect($username, $password, $connectionString, $charset, $sessionMode);
         }

src/Driver/OCI8/Exception/InvalidConfiguration.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Driver\OCI8\Exception;
+
+use Doctrine\DBAL\Driver\AbstractException;
+
+/**
+ * @internal
+ *
+ * @psalm-immutable
+ */
+final class InvalidConfiguration extends AbstractException
+{
+    public static function forPersistentAndExclusive(): self
+    {
+        return new self('The "persistent" parameter and the "exclusive" driver option are mutually exclusive');
+    }
+}

src/Query/QueryBuilder.php

@@ -1139,6 +1139,19 @@ public function addOrderBy(string $sort, ?string $order = null): self
         return $this;
     }
 
+    /**
+     * Resets the ordering for the query.
+     *
+     * @return $this This QueryBuilder instance.
+     */
+    public function resetOrderBy(): self
+    {
+        $this->orderBy = [];
+        $this->sql = null;
+
+        return $this;
+    }
+
     /** @throws QueryException */
     private function getSQLForSelect(): string
     {

tests/Driver/OCI8/DriverTest.php

@@ -6,10 +6,22 @@
 
 use Doctrine\DBAL\Driver as DriverInterface;
 use Doctrine\DBAL\Driver\OCI8\Driver;
+use Doctrine\DBAL\Driver\OCI8\Exception\InvalidConfiguration;
 use Doctrine\DBAL\Tests\Driver\AbstractOracleDriverTestCase;
 
+/** @requires extension oci8 */
 class DriverTest extends AbstractOracleDriverTestCase
 {
+    public function testPersistentAndExclusiveAreMutuallyExclusive(): void
+    {
+        $this->expectException(InvalidConfiguration::class);
+
+        (new Driver())->connect([
+            'persistent' => true,
+            'driverOptions' => ['exclusive' => true],
+        ]);
+    }
+
     protected function createDriver(): DriverInterface
     {
         return new Driver();

tests/Functional/LockMode/NoneTest.php

@@ -5,6 +5,7 @@
 namespace Doctrine\DBAL\Tests\Functional\LockMode;
 
 use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\DriverManager;
 use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\LockMode;
 use Doctrine\DBAL\Platforms\SQLitePlatform;
@@ -21,11 +22,6 @@ class NoneTest extends FunctionalTestCase
 
     public function setUp(): void
     {
-        if (TestUtil::isDriverOneOf('oci8')) {
-            // https://github.com/doctrine/dbal/issues/4417
-            self::markTestSkipped('This test fails on OCI8 for a currently unknown reason');
-        }
-
         if ($this->connection->getDatabasePlatform() instanceof SQLServerPlatform) {
             // Use row versioning instead of locking on SQL Server (if we don't, the second connection will block when
             // attempting to read the row created by the first connection, instead of reading the previous version);
@@ -43,7 +39,13 @@ public function setUp(): void
 
         $this->dropAndCreateTable($table);
 
-        $this->connection2 = TestUtil::getConnection();
+        $params = TestUtil::getConnectionParams();
+
+        if (TestUtil::isDriverOneOf('oci8')) {
+            $params['driverOptions']['exclusive'] = true;
+        }
+
+        $this->connection2 = DriverManager::getConnection($params);
 
         if ($this->connection2->createSchemaManager()->tableExists('users')) {
             return;

tests/Query/QueryBuilderTest.php

@@ -503,6 +503,17 @@ public function testSetFirstResult(): void
         self::assertEquals(10, $qb->getFirstResult());
     }
 
+    public function testResetOrderBy(): void
+    {
+        $qb = new QueryBuilder($this->conn);
+
+        $qb->select('u.*')->from('users', 'u')->orderBy('u.name', 'ASC');
+
+        self::assertEquals('SELECT u.* FROM users u ORDER BY u.name ASC', (string) $qb);
+        $qb->resetOrderBy();
+        self::assertEquals('SELECT u.* FROM users u', (string) $qb);
+    }
+
     public function testCreateNamedParameter(): void
     {
         $qb = new QueryBuilder($this->conn);