feat(database): add closable connection wrapper for PDO connection

src/Tempest/Database/src/Connection.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database;
+
+use PDOStatement;
+
+interface Connection
+{
+    public function beginTransaction(): bool;
+
+    public function commit(): bool;
+
+    public function rollback(): bool;
+
+    public function lastInsertId(): false|string;
+
+    public function prepare(string $sql): false|PDOStatement;
+
+    public function close(): void;
+
+    public function connect(): void;
+}

src/Tempest/Database/src/ConnectionInitializer.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database;
+
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Container\Singleton;
+
+final class ConnectionInitializer implements Initializer
+{
+    private static Connection|null $instance = null;
+
+    #[Singleton]
+    public function initialize(Container $container): Connection
+    {
+        // Reuse same connection instance in unit tests
+        if (self::$instance !== null) {
+            return self::$instance;
+        }
+
+        $databaseConfig = $container->get(DatabaseConfig::class);
+
+        $connection = new PDOConnection($databaseConfig->connection());
+        $connection->connect();
+
+        self::$instance = $connection;
+
+        return $connection;
+    }
+}

src/Tempest/Database/src/DatabaseConnection.php → src/Tempest/Database/src/Connections/DatabaseConnection.php

@@ -2,8 +2,9 @@
 
 declare(strict_types=1);
 
-namespace Tempest\Database;
+namespace Tempest\Database\Connections;
 
+use Tempest\Database\DatabaseDialect;
 use Tempest\Database\Tables\NamingStrategy;
 
 interface DatabaseConnection

src/Tempest/Database/src/DatabaseConnectionInitializer.php → src/Tempest/Database/src/Connections/DatabaseConnectionInitializer.php

@@ -2,11 +2,12 @@
 
 declare(strict_types=1);
 
-namespace Tempest\Database;
+namespace Tempest\Database\Connections;
 
 use Tempest\Container\Container;
 use Tempest\Container\Initializer;
 use Tempest\Container\Singleton;
+use Tempest\Database\DatabaseConfig;
 
 final class DatabaseConnectionInitializer implements Initializer
 {

src/Tempest/Database/src/Connections/MySqlConnection.php

@@ -5,7 +5,6 @@
 namespace Tempest\Database\Connections;
 
 use SensitiveParameter;
-use Tempest\Database\DatabaseConnection;
 use Tempest\Database\DatabaseDialect;
 use Tempest\Database\Tables\NamingStrategy;
 use Tempest\Database\Tables\PluralizedSnakeCaseStrategy;

src/Tempest/Database/src/Connections/PostgresConnection.php

@@ -5,7 +5,6 @@
 namespace Tempest\Database\Connections;
 
 use SensitiveParameter;
-use Tempest\Database\DatabaseConnection;
 use Tempest\Database\DatabaseDialect;
 use Tempest\Database\Tables\NamingStrategy;
 use Tempest\Database\Tables\PluralizedSnakeCaseStrategy;

src/Tempest/Database/src/Connections/SQLiteConnection.php

@@ -5,7 +5,6 @@
 namespace Tempest\Database\Connections;
 
 use SensitiveParameter;
-use Tempest\Database\DatabaseConnection;
 use Tempest\Database\DatabaseDialect;
 use Tempest\Database\Tables\NamingStrategy;
 use Tempest\Database\Tables\PluralizedSnakeCaseStrategy;

src/Tempest/Database/src/DatabaseConfig.php

@@ -4,6 +4,8 @@
 
 namespace Tempest\Database;
 
+use Tempest\Database\Connections\DatabaseConnection;
+
 final class DatabaseConfig
 {
     private array $migrations = [];

src/Tempest/Database/src/DatabaseDialectInitializer.php

@@ -6,6 +6,7 @@
 
 use Tempest\Container\Container;
 use Tempest\Container\Initializer;
+use Tempest\Database\Connections\DatabaseConnection;
 
 final readonly class DatabaseDialectInitializer implements Initializer
 {

src/Tempest/Database/src/DatabaseInitializer.php

@@ -4,7 +4,6 @@
 
 namespace Tempest\Database;
 
-use PDO;
 use Tempest\Container\Container;
 use Tempest\Container\Initializer;
 use Tempest\Container\Singleton;
@@ -16,7 +15,7 @@
     public function initialize(Container $container): Database
     {
         return new GenericDatabase(
-            $container->get(PDO::class),
+            $container->get(Connection::class),
             $container->get(TransactionManager::class),
         );
     }

src/Tempest/Database/src/GenericDatabase.php

@@ -12,11 +12,11 @@
 use Tempest\Database\Transactions\TransactionManager;
 use Throwable;
 
-final class GenericDatabase implements Database
+final readonly class GenericDatabase implements Database
 {
     public function __construct(
-        private PDO $pdo,
-        private readonly TransactionManager $transactionManager,
+        private Connection $connection,
+        private TransactionManager $transactionManager,
     ) {
     }
 
@@ -25,7 +25,7 @@ public function execute(Query $query): void
         $bindings = $this->resolveBindings($query);
 
         try {
-            $this->pdo
+            $this->connection
                 ->prepare($query->getSql())
                 ->execute($bindings);
         } catch (PDOException $pdoException) {
@@ -35,12 +35,12 @@ public function execute(Query $query): void
 
     public function getLastInsertId(): Id
     {
-        return new Id($this->pdo->lastInsertId());
+        return new Id($this->connection->lastInsertId());
     }
 
     public function fetch(Query $query): array
     {
-        $pdoQuery = $this->pdo->prepare($query->getSql());
+        $pdoQuery = $this->connection->prepare($query->getSql());
 
         $pdoQuery->execute($this->resolveBindings($query));
 

src/Tempest/Database/src/PDOConnection.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Database;
+
+use PDO;
+use PDOStatement;
+use Tempest\Database\Connections\DatabaseConnection;
+
+final class PDOConnection implements Connection
+{
+    private PDO|null $pdo = null;
+
+    public function __construct(private readonly DatabaseConnection $connection)
+    {
+    }
+
+    public function beginTransaction(): bool
+    {
+        return $this->pdo->beginTransaction();
+    }
+
+    public function commit(): bool
+    {
+        return $this->pdo->commit();
+    }
+
+    public function rollback(): bool
+    {
+        return $this->pdo->rollBack();
+    }
+
+    public function lastInsertId(): false|string
+    {
+        return $this->pdo->lastInsertId();
+    }
+
+    public function prepare(string $sql): false|PDOStatement
+    {
+        return $this->pdo->prepare($sql);
+    }
+
+    public function close(): void
+    {
+        $this->pdo = null;
+    }
+
+    public function connect(): void
+    {
+        if ($this->pdo !== null) {
+            return;
+        }
+
+        $this->pdo = new PDO(
+            $this->connection->getDsn(),
+            $this->connection->getUsername(),
+            $this->connection->getPassword(),
+        );
+    }
+}

src/Tempest/Database/src/Transactions/GenericTransactionManager.php

@@ -4,20 +4,20 @@
 
 namespace Tempest\Database\Transactions;
 
-use PDO;
+use Tempest\Database\Connection;
 use Tempest\Database\Exceptions\CouldNotBeginTransaction;
 use Tempest\Database\Exceptions\CouldNotCommitTransaction;
 use Tempest\Database\Exceptions\CouldNotRollbackTransaction;
 
 final class GenericTransactionManager implements TransactionManager
 {
-    public function __construct(private PDO $pdo)
+    public function __construct(private Connection $connection)
     {
     }
 
     public function begin(): void
     {
-        $transactionBegun = $this->pdo->beginTransaction();
+        $transactionBegun = $this->connection->beginTransaction();
 
         if (! $transactionBegun) {
             throw new CouldNotBeginTransaction();
@@ -26,7 +26,7 @@ public function begin(): void
 
     public function commit(): void
     {
-        $transactionCommitted = $this->pdo->commit();
+        $transactionCommitted = $this->connection->commit();
 
         if (! $transactionCommitted) {
             throw new CouldNotCommitTransaction();
@@ -35,7 +35,7 @@ public function commit(): void
 
     public function rollback(): void
     {
-        $transactionRolledBack = $this->pdo->rollBack();
+        $transactionRolledBack = $this->connection->rollBack();
 
         if (! $transactionRolledBack) {
             throw new CouldNotRollbackTransaction();

src/Tempest/Database/src/Transactions/TransactionManagerInitializer.php

@@ -4,16 +4,16 @@
 
 namespace Tempest\Database\Transactions;
 
-use PDO;
 use Tempest\Container\Container;
 use Tempest\Container\Initializer;
 use Tempest\Container\Singleton;
+use Tempest\Database\Connection;
 
 final readonly class TransactionManagerInitializer implements Initializer
 {
     #[Singleton]
     public function initialize(Container $container): TransactionManager
     {
-        return new GenericTransactionManager($container->get(PDO::class));
+        return new GenericTransactionManager($container->get(Connection::class));
     }
 }

src/Tempest/Database/tests/DatabaseDriverTest.php

@@ -8,10 +8,10 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
+use Tempest\Database\Connections\DatabaseConnection;
 use Tempest\Database\Connections\MySqlConnection;
 use Tempest\Database\Connections\PostgresConnection;
 use Tempest\Database\Connections\SQLiteConnection;
-use Tempest\Database\DatabaseConnection;
 
 /**
  * @internal

src/Tempest/Database/tests/DatabaseQueryStatementTest.php

@@ -8,10 +8,10 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
+use Tempest\Database\Connections\DatabaseConnection;
 use Tempest\Database\Connections\MySqlConnection;
 use Tempest\Database\Connections\PostgresConnection;
 use Tempest\Database\Connections\SQLiteConnection;
-use Tempest\Database\DatabaseConnection;
 use Tempest\Database\QueryStatements\CreateTableStatement;
 use Tempest\Database\QueryStatements\OnDelete;
 use Tempest\Database\QueryStatements\PrimaryKeyStatement;