feature: first version of postgresql client

Author: norberttech

src/lib/postgresql/src/Flow/PostgreSql/Client/Client.php

@@ -0,0 +1,234 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\PostgreSql\Client;
+
+use Flow\PostgreSql\Client\Exception\{QueryException, TransactionException};
+use Flow\PostgreSql\QueryBuilder\SqlQuery;
+
+interface Client
+{
+    /**
+     * Begin a transaction.
+     * Supports nesting via SAVEPOINTs.
+     *
+     * @throws TransactionException
+     */
+    public function beginTransaction() : void;
+
+    /**
+     * Close the connection.
+     */
+    public function close() : void;
+
+    /**
+     * Commit the current transaction.
+     * If nested, releases the savepoint.
+     *
+     * @throws TransactionException
+     */
+    public function commit() : void;
+
+    /**
+     * Get a cursor for lazy iteration over large result sets.
+     * Memory efficient - rows are fetched one at a time.
+     * Use cursor->map() to map rows to objects.
+     *
+     * @param SqlQuery|string $sql SQL query or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     *
+     * @throws QueryException
+     */
+    public function cursor(SqlQuery|string $sql, array $parameters = []) : Cursor;
+
+    /**
+     * Execute a statement that modifies data (INSERT, UPDATE, DELETE).
+     * Returns the number of affected rows.
+     *
+     * @param SqlQuery|string $sql SQL statement or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     *
+     * @throws QueryException
+     */
+    public function execute(SqlQuery|string $sql, array $parameters = []) : int;
+
+    /**
+     * Fetch the first row from query result.
+     * Returns null if no rows found.
+     *
+     * @param SqlQuery|string $sql SQL query or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     *
+     * @throws QueryException
+     *
+     * @return null|array<string, mixed>
+     */
+    public function fetch(SqlQuery|string $sql, array $parameters = []) : ?array;
+
+    /**
+     * Fetch all rows from query result.
+     *
+     * @param SqlQuery|string $sql SQL query or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     *
+     * @throws QueryException
+     *
+     * @return array<int, array<string, mixed>>
+     */
+    public function fetchAll(SqlQuery|string $sql, array $parameters = []) : array;
+
+    /**
+     * Fetch all rows and map to objects.
+     *
+     * @template T of object
+     *
+     * @param class-string<T> $class Target class for mapping
+     * @param SqlQuery|string $sql SQL query or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     * @param null|RowMapper $mapper Override default mapper for this call
+     *
+     * @throws QueryException
+     *
+     * @return array<int, T>
+     */
+    public function fetchAllInto(
+        string $class,
+        SqlQuery|string $sql,
+        array $parameters = [],
+        ?RowMapper $mapper = null,
+    ) : array;
+
+    /**
+     * Fetch the first row and map to object.
+     * Returns null if no rows found.
+     *
+     * @template T of object
+     *
+     * @param class-string<T> $class Target class for mapping
+     * @param SqlQuery|string $sql SQL query or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     * @param null|RowMapper $mapper Override default mapper for this call
+     *
+     * @throws QueryException
+     *
+     * @return null|T
+     */
+    public function fetchInto(
+        string $class,
+        SqlQuery|string $sql,
+        array $parameters = [],
+        ?RowMapper $mapper = null,
+    ) : ?object;
+
+    /**
+     * Fetch exactly one row. Throws if result has 0 or more than 1 row.
+     * Use when you expect precisely one result (e.g., SELECT by primary key).
+     *
+     * @param SqlQuery|string $sql SQL query or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     *
+     * @throws QueryException When row count is not exactly 1
+     *
+     * @return array<string, mixed>
+     */
+    public function fetchOne(SqlQuery|string $sql, array $parameters = []) : array;
+
+    /**
+     * Fetch exactly one row and map to object.
+     * Throws if result has 0 or more than 1 row.
+     *
+     * @template T of object
+     *
+     * @param class-string<T> $class Target class for mapping
+     * @param SqlQuery|string $sql SQL query or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     * @param null|RowMapper $mapper Override default mapper for this call
+     *
+     * @throws QueryException When row count is not exactly 1
+     *
+     * @return T
+     */
+    public function fetchOneInto(
+        string $class,
+        SqlQuery|string $sql,
+        array $parameters = [],
+        ?RowMapper $mapper = null,
+    ) : object;
+
+    /**
+     * Fetch a single scalar value from the first column of first row.
+     * Ideal for COUNT(*), MAX(), MIN(), etc.
+     *
+     * @param SqlQuery|string $sql SQL query or query builder with $1, $2, ... placeholders
+     * @param array<int, mixed> $parameters Positional parameters
+     *
+     * @throws QueryException
+     */
+    public function fetchScalar(SqlQuery|string $sql, array $parameters = []) : mixed;
+
+    /**
+     * Get the current transaction nesting level.
+     * 0 = no active transaction, 1 = top-level, 2+ = nested.
+     */
+    public function getTransactionNestingLevel() : int;
+
+    /**
+     * Check if auto-commit mode is enabled.
+     * When enabled (default), each query is executed in its own transaction.
+     * When disabled, a transaction is implicitly started and remains open until
+     * commit() or rollBack() is called.
+     */
+    public function isAutoCommit() : bool;
+
+    /**
+     * Check if the connection is alive.
+     */
+    public function isConnected() : bool;
+
+    /**
+     * Get the last inserted ID from a sequence.
+     * PostgreSQL requires a sequence name - there's no concept of "last insert ID" without it.
+     *
+     * Preferred alternative: Use RETURNING clause in INSERT statements:
+     * $row = $client->fetch('INSERT INTO users (name) VALUES ($1) RETURNING id', ['John']);
+     *
+     * @param string $sequenceName The name of the sequence (e.g., 'users_id_seq')
+     *
+     * @throws QueryException
+     */
+    public function lastInsertId(string $sequenceName) : int|string;
+
+    /**
+     * Roll back the current transaction.
+     * If nested, rolls back to the savepoint.
+     *
+     * @throws TransactionException
+     */
+    public function rollBack() : void;
+
+    /**
+     * Set auto-commit mode.
+     * When enabled (default), each query is executed in its own transaction.
+     * When disabled, a transaction is implicitly started and remains open until
+     * commit() or rollBack() is called.
+     *
+     * @throws TransactionException
+     */
+    public function setAutoCommit(bool $autoCommit) : void;
+
+    /**
+     * Execute a callback within a transaction.
+     * Auto-commits on success, auto-rollbacks on exception.
+     * Supports nesting via SAVEPOINTs.
+     *
+     * @template T
+     *
+     * @param callable(Client): T $callback
+     *
+     * @throws TransactionException
+     *
+     * @return T
+     */
+    public function transaction(callable $callback) : mixed;
+}

src/lib/postgresql/src/Flow/PostgreSql/Client/ConnectionParameters.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\PostgreSql\Client;
+
+final readonly class ConnectionParameters
+{
+    private function __construct(
+        public string $connectionString,
+    ) {
+    }
+
+    /**
+     * Create from individual parameters.
+     *
+     * @param array<string, string> $options Additional connection options (e.g., sslmode, connect_timeout)
+     */
+    public static function fromParams(
+        string $database,
+        string $host = 'localhost',
+        int $port = 5432,
+        ?string $user = null,
+        ?string $password = null,
+        array $options = [],
+    ) : self {
+        $parts = [
+            \sprintf('host=%s', $host),
+            \sprintf('port=%d', $port),
+            \sprintf('dbname=%s', $database),
+        ];
+
+        if ($user !== null) {
+            $parts[] = \sprintf('user=%s', $user);
+        }
+
+        if ($password !== null) {
+            $parts[] = \sprintf('password=%s', $password);
+        }
+
+        foreach ($options as $key => $value) {
+            $parts[] = \sprintf('%s=%s', $key, $value);
+        }
+
+        return new self(\implode(' ', $parts));
+    }
+
+    /**
+     * Create from a PostgreSQL connection string.
+     */
+    public static function fromString(string $connectionString) : self
+    {
+        return new self($connectionString);
+    }
+}

src/lib/postgresql/src/Flow/PostgreSql/Client/Cursor.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\PostgreSql\Client;
+
+/**
+ * Cursor for lazy iteration over large result sets.
+ * Use Client::cursor() to obtain a cursor.
+ *
+ * Supports both raw array iteration and object mapping via RowMapper.
+ *
+ * @extends \IteratorAggregate<int, array<string, mixed>>
+ */
+interface Cursor extends \Countable, \IteratorAggregate
+{
+    /**
+     * Get the number of rows in the result set.
+     */
+    public function count() : int;
+
+    /**
+     * Free the cursor resources.
+     * Called automatically when iteration completes.
+     */
+    public function free() : void;
+
+    /**
+     * Iterate all remaining rows lazily as arrays.
+     * Memory efficient - one row at a time.
+     *
+     * @return \Generator<int, array<string, mixed>>
+     */
+    public function iterate() : \Generator;
+
+    /**
+     * Iterate all remaining rows, mapping each to an object.
+     * Memory efficient - one object at a time.
+     *
+     * Uses the client's default mapper unless overridden.
+     *
+     * @template T of object
+     *
+     * @param class-string<T> $class Target class for mapping
+     * @param null|RowMapper $mapper Override default mapper for this iteration
+     *
+     * @return \Generator<int, T>
+     */
+    public function map(string $class, ?RowMapper $mapper = null) : \Generator;
+
+    /**
+     * Fetch the next row. Returns null when exhausted.
+     *
+     * @return null|array<string, mixed>
+     */
+    public function next() : ?array;
+}