Add ConnectionAdapterInterface and PdoConnectionAdapter (#20)

Author: antonkomarev

src/ConnectionAdapterInterface.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cog\DbLocker;
+
+/**
+ * Minimal connection abstraction for PostgreSQL advisory lock operations.
+ *
+ * This interface defines only the operations required by PostgresAdvisoryLocker.
+ * It is NOT a general-purpose database abstraction layer.
+ *
+ * Exception Handling Contract:
+ * - Implementations MUST throw the original database exception unwrapped.
+ * - For PDO: throw \PDOException with SQLSTATE in getCode()
+ * - For ORMs: throw their native exceptions (Doctrine\DBAL\Exception, etc.)
+ * - The locker will inspect exceptions for SQLSTATE '55P03' (lock_not_available)
+ */
+interface ConnectionAdapterInterface
+{
+    /**
+     * Execute a parameterized query and return the first column of the first row.
+     *
+     * Used for lock acquisition functions that return boolean results:
+     * - SELECT PG_TRY_ADVISORY_LOCK(:class_id, :object_id)
+     * - SELECT PG_ADVISORY_UNLOCK(:class_id, :object_id)
+     * - SHOW lock_timeout
+     *
+     * @param string $sql SQL query with named parameters (e.g., :class_id)
+     * @param array<string, mixed> $params Named parameters (e.g., ['class_id' => 1, 'object_id' => 2])
+     * @return mixed The value of the first column (typically bool or string)
+     * @throws \Throwable Database-specific exception on error
+     */
+    public function fetchColumn(string $sql, array $params = []): mixed;
+
+    /**
+     * Execute a statement without returning results.
+     *
+     * Used for:
+     * - Blocking lock acquisition: SELECT PG_ADVISORY_LOCK(:class_id, :object_id)
+     * - Transaction control: SAVEPOINT, RELEASE SAVEPOINT, ROLLBACK TO SAVEPOINT
+     * - Configuration: SET [LOCAL] lock_timeout = '...'
+     * - Cleanup: SELECT PG_ADVISORY_UNLOCK_ALL()
+     *
+     * @param string $sql SQL statement with optional named parameters
+     * @param array<string, mixed> $params Named parameters (e.g., ['class_id' => 1])
+     * @throws \Throwable Database-specific exception on error
+     */
+    public function execute(string $sql, array $params = []): void;
+
+    /**
+     * Check whether a transaction is currently active on this connection.
+     *
+     * Used to validate that transaction-level locks are only acquired within a transaction.
+     *
+     * @return bool True if a transaction is active, false otherwise
+     */
+    public function isTransactionActive(): bool;
+
+    /**
+     * Check if an exception indicates a PostgreSQL lock_not_available error (SQLSTATE 55P03).
+     *
+     * Different database adapters throw different exception types:
+     * - PDO: \PDOException with SQLSTATE in getCode()
+     * - Doctrine DBAL: Doctrine\DBAL\Exception with getSQLState() method
+     * - Cycle ORM: wraps \PDOException in its own exception
+     *
+     * @param \Throwable $exception Exception to inspect
+     * @return bool True if the exception indicates a lock timeout (SQLSTATE 55P03)
+     */
+    public function isLockNotAvailable(\Throwable $exception): bool;
+}

src/DbConnection/PdoConnectionAdapter.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cog\DbLocker\DbConnection;
+
+use Cog\DbLocker\ConnectionAdapterInterface;
+use PDO;
+
+/**
+ * PDO-based implementation of ConnectionAdapterInterface.
+ *
+ * This adapter wraps a PDO connection and provides the minimal interface
+ * required by PostgresAdvisoryLocker.
+ *
+ * Requirements:
+ * - PDO connection MUST use PDO::ERRMODE_EXCEPTION
+ * - Constructor validates this requirement and throws LogicException if violated
+ */
+final class PdoConnectionAdapter implements ConnectionAdapterInterface
+{
+    private const PG_SQLSTATE_LOCK_NOT_AVAILABLE = '55P03';
+
+    public function __construct(
+        private readonly PDO $pdo,
+    ) {
+        if ((int) $this->pdo->getAttribute(PDO::ATTR_ERRMODE) !== PDO::ERRMODE_EXCEPTION) {
+            throw new \LogicException(
+                'PDO connection must use PDO::ERRMODE_EXCEPTION. '
+                . 'Set it via: $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION)',
+            );
+        }
+    }
+
+    public function fetchColumn(string $sql, array $params = []): mixed
+    {
+        $statement = $this->pdo->prepare($sql);
+        $statement->execute($params);
+        return $statement->fetchColumn(0);
+    }
+
+    public function execute(string $sql, array $params = []): void
+    {
+        if ($params === []) {
+            // exec() is more efficient for non-parameterized queries
+            $this->pdo->exec($sql);
+            return;
+        }
+
+        $statement = $this->pdo->prepare($sql);
+        $statement->execute($params);
+    }
+
+    public function isTransactionActive(): bool
+    {
+        return $this->pdo->inTransaction();
+    }
+
+    public function isLockNotAvailable(\Throwable $exception): bool
+    {
+        // PDOException: getCode() returns SQLSTATE string
+        if ($exception instanceof \PDOException) {
+            return $exception->getCode() === self::PG_SQLSTATE_LOCK_NOT_AVAILABLE;
+        }
+
+        return false;
+    }
+}

src/Postgres/LockHandle/SessionLevelLockHandle.php

@@ -13,10 +13,10 @@
 
 namespace Cog\DbLocker\Postgres\LockHandle;
 
+use Cog\DbLocker\ConnectionAdapterInterface;
 use Cog\DbLocker\Postgres\Enum\PostgresLockAccessModeEnum;
 use Cog\DbLocker\Postgres\PostgresAdvisoryLocker;
 use Cog\DbLocker\Postgres\PostgresLockKey;
-use PDO;
 
 /**
  * @internal
@@ -26,7 +26,7 @@ final class SessionLevelLockHandle
     private bool $isReleased = false;
 
     public function __construct(
-        private readonly PDO $dbConnection,
+        private readonly ConnectionAdapterInterface $dbConnection,
         private readonly PostgresAdvisoryLocker $locker,
         public readonly PostgresLockKey $lockKey,
         public readonly PostgresLockAccessModeEnum $accessMode,