DbConnectionPool

in package

• ZealPHP

Per-worker pool of database connections — the DB counterpart to {@see \ZealPHP\Store\RedisConnectionPool}.

$pool = DbConnectionPool::pdo('mysql:host=127.0.0.1;dbname=app', 'user', 'pass',
    size: 16, validationQuery: 'SELECT 1');
// or mysqli (WordPress $wpdb-style code):
$pool = DbConnectionPool::mysqli('127.0.0.1', 'user', 'pass', 'app', size: 16);

$rows = $pool->with(fn (\PDO $db) =>
    $db->query('SELECT * FROM users LIMIT 10')->fetchAll());

$pool->transaction(function (\PDO $db): void {
    $db->exec('UPDATE accounts SET balance = balance - 10 WHERE id = 1');
    $db->exec('UPDATE accounts SET balance = balance + 10 WHERE id = 2');
});

Tags

template

Table of Contents

Properties

$buildLock  : Channel|null

Size-1 channel used as a coroutine mutex around channel construction.

$ch  : Channel|null

The coroutine channel holding available connections. Created lazily on the first acquire() inside a coroutine (Channel::push() throws outside the scheduler).

$closed  : bool

Set by close() — a closed pool refuses acquire() rather than silently rebuilding a fresh (never-drained) channel.

$driver  : PoolDriver<string|int, TConn>

$size  : int

Configured pool capacity (minimum 1).

$stats  : Stats

Per-worker counters: pool_acquires_total, pool_acquire_timeouts_total, pool_clients_created_total, pool_clients_discarded_total (poison-pill discards of a connection whose with() body threw), and pool_validation_replacements_total (connections replaced because they failed the on-acquire liveness probe).

$syncClient  : TConn|null

Single connection used in sync (non-coroutine) mode.

$validationQuery  : string|null

Optional liveness probe run on acquire (null = no check).

Methods

__construct()  : mixed

acquire()  : TConn

Pop a connection from the pool. In coroutine context, yields up to $timeout seconds for one to become available; throws DbException on timeout. In sync context, returns a shared single connection.

close()  : void

Tear down the pool. Drains every channel connection (driver disconnect() + reference drop) and marks the pool closed so a later acquire() throws instead of rebuilding a fresh channel that would never be drained.

mysqli()  : mysqli>

Pool of \mysqli connections. $charset defaults to utf8mb4. For SSL / custom init, build a {@see MysqliDriver} from your own factory and pass it to the constructor instead.

pdo()  : PDO>

Pool of \PDO connections from a DSN. ERRMODE_EXCEPTION + FETCH_ASSOC are applied unless overridden in $options.

release()  : void

Return a connection to the pool. Rolls back any transaction the borrower left open first (driver-dependent). A connection that can't even be inspected is discarded + replaced. No-op for the sync-mode singleton.

size()  : int

Return the configured pool capacity.

stats()  : Stats

Per-worker stats — acquires, timeouts, clients created/discarded, validation replacements.

transaction()  : T

Run $fn inside a transaction on a pooled connection: BEGIN, then COMMIT on success or ROLLBACK on throw. The connection returns to the pool afterward (cleaned either way).

with()  : T

Acquire + use + release in one call. On success the connection returns to the pool (transaction-cleaned); if $fn throws, the connection is discarded and the pool refilled, then the exception re-thrown.

aliveEnough()  : bool

True if no validation is configured, or the connection answers the validation probe. A connection that fails is counted as a validation replacement so the caller rebuilds.

build()  : TConn

Build a fresh connection via the driver and count it.

buildChannelLocked()  : Channel

The serialized half of {@see ensureChannel()} — runs under $buildLock.

discard()  : void

Discard a connection (broken / poisoned) and preserve pool capacity by refilling with a fresh one. For the sync singleton, just null it so the next acquire rebuilds.

ensureChannel()  : Channel

Lazily initialise the channel and pre-fill it with $size connections.