Add retry mechanism when connecting to Oracle

.github/workflows/test-unit.yml

@@ -4,7 +4,7 @@ on:
   pull_request:
   push:
   schedule:
-    - cron: '0 0/2 * * *'
+    - cron: '0 0/8 * * *'
   workflow_dispatch:
 
 jobs:
@@ -120,6 +120,14 @@ jobs:
         image: gvenzl/${{ matrix.type == 'Phpunit Lowest' && 'oracle-free:slim-faststart' || 'oracle-xe:18-slim-faststart' }}
         env:
           ORACLE_PASSWORD: atk4_pass
+          APP_USER: atk4_test_user
+          APP_USER_PASSWORD: atk4_user_pass
+        # Provide healthcheck script options for startup
+        options: >-
+          --health-cmd healthcheck.sh
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -246,9 +254,10 @@ jobs:
       - name: "Run tests: Oracle - PDO (only for coverage or cron)"
         if: (success() || failure()) && (env.LOG_COVERAGE || github.event_name == 'schedule')
         env:
-          DB_DSN: "pdo_oci:dbname=oracle/free"
-          DB_USER: system
-          DB_PASSWORD: atk4_pass
+          # connection to portable database
+          DB_DSN: "pdo_oci:dbname=oracle/${{ matrix.type == 'Phpunit Lowest' && 'freepdb1' || 'xepdb1' }}"
+          DB_USER: atk4_test_user
+          DB_PASSWORD: atk4_user_pass
           NLS_LANG: AMERICAN_AMERICA.AL32UTF8
         run: |
           php -d opcache.enable_cli=1 vendor/bin/phpunit --exclude-group none $(if [ -n "$LOG_COVERAGE" ]; then echo --coverage-text; else echo --no-coverage; fi) --fail-on-warning --fail-on-risky $(if vendor/bin/phpunit --version | grep -q '^PHPUnit 9\.'; then echo -v; else echo --fail-on-notice --fail-on-deprecation --display-notices --display-deprecations --display-warnings --display-errors --display-incomplete --display-skipped; fi)
@@ -257,9 +266,10 @@ jobs:
       - name: "Run tests: Oracle - OCI8"
         if: success() || failure()
         env:
-          DB_DSN: "oci8:dbname=oracle/free"
-          DB_USER: system
-          DB_PASSWORD: atk4_pass
+          # connection to portable database
+          DB_DSN: "oci8:dbname=oracle/${{ matrix.type == 'Phpunit Lowest' && 'freepdb1' || 'xepdb1' }}"
+          DB_USER: atk4_test_user
+          DB_PASSWORD: atk4_user_pass
           NLS_LANG: AMERICAN_AMERICA.AL32UTF8
         run: |
           php -d opcache.enable_cli=1 vendor/bin/phpunit --exclude-group none $(if [ -n "$LOG_COVERAGE" ]; then echo --coverage-text; else echo --no-coverage; fi) --fail-on-warning --fail-on-risky $(if vendor/bin/phpunit --version | grep -q '^PHPUnit 9\.'; then echo -v; else echo --fail-on-notice --fail-on-deprecation --display-notices --display-deprecations --display-warnings --display-errors --display-incomplete --display-skipped; fi)

src/Persistence/Sql/Oracle/Connection.php

@@ -19,6 +19,7 @@ protected static function createDbalConfiguration(): Configuration
 
         $configuration->setMiddlewares([
             ...$configuration->getMiddlewares(),
+            new RetryConnectionMiddleware(),
             new InitializeSessionMiddleware(),
         ]);
 

src/Persistence/Sql/Oracle/RetryConnectionMiddleware.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Atk4\Data\Persistence\Sql\Oracle;
+
+use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\Connection;
+use Doctrine\DBAL\Driver\Middleware;
+use Doctrine\DBAL\Driver\Middleware\AbstractDriverMiddleware;
+use Doctrine\DBAL\Driver\OCI8\Exception\ConnectionFailed;
+
+/**
+ * Retries transient Oracle listener failures during connection establishment.
+ *
+ * Oracle may temporarily return ORA-12516 when the listener has not yet
+ * released a handler after a connection has been closed. Retrying after
+ * a short delay allows the listener to refresh its handler state.
+ */
+class RetryConnectionMiddleware implements Middleware
+{
+    #[\Override]
+    public function wrap(Driver $driver): Driver
+    {
+        return new class($driver) extends AbstractDriverMiddleware {
+            // ORA-12516: TNS:listener could not find available handler with matching protocol stack
+            private const RETRY_ERROR_CODES = [12516];
+            private const RETRY_COUNT = 8;
+            private const RETRY_INTERVAL_BASE_MS = 10;
+            private const RETRY_INTERVAL_MAX_MS = 1000;
+
+            #[\Override]
+            public function connect(
+                #[\SensitiveParameter]
+                array $params
+            ): Connection {
+                for ($attempt = 0;; ++$attempt) {
+                    try {
+                        return parent::connect($params);
+                    } catch (ConnectionFailed $e) { // @phpstan-ignore catch.internalClass
+                        if (
+                            !in_array($e->getCode(), self::RETRY_ERROR_CODES, true)
+                            || $attempt >= self::RETRY_COUNT
+                        ) {
+                            throw $e;
+                        }
+
+                        $timeoutMs = min(
+                            self::RETRY_INTERVAL_BASE_MS * (2 ** $attempt),
+                            self::RETRY_INTERVAL_MAX_MS
+                        );
+
+                        usleep($timeoutMs * 1000);
+                    }
+                }
+            }
+        };
+    }
+}