[WyriHaximus]

This PR adds support for transactions by reserving a single connection for a transaction. While keeping connection sharing for other queries on non-reserved connections.

It must be noted that when all connections are in use by transactions, all other queries and new transactions have to wait in the queue until a connection becomes available. This could lead to delays in the starting of queries and is a major change in the behaviour of this package. Follow-up work is in place to see if a single connection can handle multiple transactions. But that is out of scope for this PR.

To achieve the above, the following changes have been made to this package:

• Changed ubuntu-latest to ubuntu-24.04 because ikalnytskyi/action-setup-postgres@v7 errors with sudo: 'apt-key': command not found
• Fixed two deprecations: implicitly nullable types in Client, Connection, ErrorException, and TestCase
• Introduced a new class ConnectionPool to handle all connection pooling and reservations, and moved all the code related to that out of Client
• Added transaction, including an example in example/ to start a transaction and give the user a Transaction to run their queries inside that transaction and commit or rollback in the end
• Hardened Connection against connection issues, ensuring those are handled correctly
• Integration/TestCase added cleanup in the setup method so the new transaction integration tests don't mess up the other integration tests

Example

$client->transaction()->flatMap(function (PgAsync\Transaction $tx) {
    return $tx->executeStatement('INSERT INTO channel(name) VALUES ($1)', ['example'])
        ->concat($tx->query('SELECT COUNT(*) AS c FROM channel'))
        ->concat($tx->commit());
})->subscribe(
    function () {
        echo "Committed.\n";
    },
    function ($e) {
        echo "Failed: " . $e->getMessage() . "\n";
    }
);

[WyriHaximus]

@mbonneau This is now ready for review

[jwage]

Thanks for this, we are building on transaction-support (webhook ingestion on a ReactPHP server) and have been running it hard. I read the diff and ran the integration suite against PostgreSQL. Everything below has a fix with tests in two PRs against the WyriHaximus-labs/PgAsync branch, so you can pull them into this PR:

1. The pool does not respect max_connections while connections are still connecting (tryAcquireQueryConnection() and processConnectionWaiters() subtract the pending reservations from the count, so a burst of transactions opens one connection per waiter). Fix with tests: Count connections that are still connecting against the pool cap WyriHaximus-labs/PgAsync#1 (merged). We saw about 1,500 simultaneous transactions open a connection each.
2. A waiter that unsubscribes while queued stays in the queue (acquire() returns an empty disposable) and is later handed a connection nobody releases.
3. A failed COMMIT (for example a deferred constraint) never releases the connection.

Items 2 and 3 are fixed in WyriHaximus-labs#2 waiters are removed on dispose, and a failed COMMIT/ROLLBACK releases the connection (rolling back first if the server still has the transaction open). Integration tests are in tests/Integration/TransactionConnectionReleaseTest.php.

Smaller things I did not change: Connection::start() became public only so the pool can call it, and the new Integration/TestCase::setUp() spins the loop for three 50 ms waits, which is timing based.