NAME

DBIO::PostgreSQL::EV::Pool - EV::Pg connection pool for DBIO

VERSION

version 0.900007

SYNOPSIS

my $pool = DBIO::PostgreSQL::EV::Pool->new(
    conninfo => 'dbname=myapp',
    size     => 10,
    on_error => sub { warn $_[0] },
);

my $pg    = $pool->acquire;    # get idle connection
my $lease = $pool->_lease($pg);  # the lease of this borrow
$pool->release($pg, $lease);   # return to pool; a stale lease releases nothing
my $pg = $pool->acquire_txn;   # pinned for transaction

DESCRIPTION

Connection pool for DBIO::PostgreSQL::EV::Storage. Manages a pool of EV::Pg connections, dispatching queries to available connections and queuing when all are busy.

The acquire / release / capacity / shutdown mechanics, including the connection-readiness gate and its wiring, are inherited from DBIO::Storage::PoolBase; this class supplies only the EV::Pg seam — see "_create_connection", "_new_connection", "_shutdown_connection" and "_transform_conninfo" — the fork safety its connections need in a forked child ("Fork safety"), and the report that one of them died, so the pool retires it instead of handing it out again ("_new_connection"). That report comes when the EV loop runs; for a connection whose session ended while it sat idle and the loop did not, this class answers core's question before the connection is handed out ("_idle_connection_alive"). It also marks the Future a queued caller waits on ("_new_waiter") and answers whether every connection is held by a callback that is running, or by a spawn that is ("_pg_held_by_callbacks", "_pg_opening"): what "await" in DBIO::PostgreSQL::EV::Future needs to refuse a blocking wait for a connection that cannot come back while it lasts.

EV::Pg is a callback-shaped transport, which is why no readiness override is needed here: EV::Pg::new installs on_error and on_connect and only then starts the connect (connect / connect_params), so the callbacks are armed before any connect event can fire and core's "_create_ready_connection" in DBIO::Storage::PoolBase can express this transport's readiness. A poll-shaped transport — one with no connect callbacks, whose readiness is a probe plus a poll, as in DBIO::Async — must still override the seam; see core's _connection_ready_future POD.

Fork safety

A forked child shares the socket of every connection the pool had opened, and EV::Pg up to 0.07 knew nothing of fork; 0.09 guards its own destruction and finish in a child. Two things went wrong in the child, the first with EV::Pg 0.07 and gone with 0.09, the second measured with 0.09 against PostgreSQL 18:

  • Closing its copy of a connection ended the parent's session (EV::Pg 0.07 and before). EV::Pg's finish and its destructor both called libpq's PQfinish, which sends the server a Terminate message on the shared socket, and the backend exits. The destructor runs on its own when the child exits, so a child that did nothing but exit left the parent with "server closed the connection unexpectedly" on every pooled connection. EV::Pg 0.09 knows the process that opened a connection and does not call PQfinish in any other (a child's exit, undef and finish leave the parent's session as it was); the descriptor redirect below stays as the guard for EV::Pg 0.07.

  • A child that resumed the EV loop read the parent's replies. EV re-arms the default loop in a child and EV::Pg's watchers stay armed on the shared sockets, so the child took the reply to a statement that was in flight when it forked; the parent's statement never completed, and the pool of one it ran on stayed checked out.

Every connection "_new_connection" builds is therefore closed fork-safe -- the pooled ones, and the storage's dedicated LISTEN connection, which "_listen_open" in DBIO::PostgreSQL::EV::Storage builds here too. It remembers the process that opened it, and in any other process its finish and its destructor first point the connection's file descriptor at /dev/null, so PQfinish sends its Terminate nowhere and closes the child's descriptor only; the parent's session is left as it was. That is the counterpart of DBD::Pg's InactiveDestroy, which EV::Pg does not have: a handle cannot be dropped without being closed, so the close is made harmless instead. It covers every way the child lets go of a connection -- exit, dropping the pool, a finish or retirement in the child -- and it is the half of core's fork guard ("_verify_pid" in DBIO::Storage::PoolBase) that core leaves to the transport.

For a child that resumes the loop, the first connection also arms one "fork" in EV watcher. The first thing the child's loop does is run it, and it closes that way every connection opened by another process that is still alive in the child -- idle, checked out for a query or pinned for a transaction alike, and also one the pool no longer counts -- before any of them can read. finish calls back every statement in flight with a "connection finished" error; the callbacks of DBIO::PostgreSQL::EV::Storage return at once outside the process that issued the statement, so no release, no Future and no caller's callback runs in the child. A callback you handed to a connection yourself (through txn_pg, say) does get that error in the child. The watcher never keeps the loop running: an active "fork" in EV watcher alone keeps EV::run from ever returning, so it is armed with keepalive(0).

Connections the child opens itself are its own and are left alone. That a child which queries through the pool gets connections of its own rather than the parent's is core's side of the guard, "_verify_pid" in DBIO::Storage::PoolBase.

METHODS

_create_connection

Builds one EV::Pg connection from the (already-transformed) conninfo string, delegating to "_create_ready_connection" in DBIO::Storage::PoolBase so the per-connection readiness Future is wired to on_connect / on_error and registered for us. The pool tracks the returned connection — do not push it onto _connections yourself.

EV::Pg->new returns before its async connect finishes, so a pool that skipped this gating would hand back a brand-new handle whose on_connect has not fired, and the very first query on a cold pool would throw not connected. Calling _create_ready_connection is how this driver opts in to core's gate; the gate itself is core's.

_new_connection

Constructs the underlying EV::Pg handle from the named arguments "_create_ready_connection" in DBIO::Storage::PoolBase passes (the conninfo plus the on_connect / on_error of the readiness wiring), and makes it one that closes fork-safe ("Fork safety"): the handle is an EV::Pg of a private subclass that remembers the process that opened it. The registration is core's.

Core makes this a named method rather than a coderef precisely so a test can subclass the pool and return a fake connection, exercising the readiness wiring with no event loop and no database (t/04-pool-readiness.t). This driver had cut the same seam by hand as _new_ev_pg before core named it. A fake connection bypasses the fork safety along with EV::Pg.

It is also the constructor of the storage's dedicated LISTEN connection: "_listen_open" in DBIO::PostgreSQL::EV::Storage calls it as a class method with that connection's own handlers and keep_alive, so the LISTEN connection closes fork-safe exactly like a pooled one. It is not registered with any pool.

No message of a handle built here quotes a password. EV::Pg speaks in libpq's words, and libpq quotes what it could not read of a conninfo -- a postgresql:// URI whole, user:password@ included. The constructor croaks with that when libpq refuses the conninfo, which fails the acquire of a pooled statement and the open of the LISTEN connection; this method rethrows it, and hands every on_error its text, with the passwords shown as *** (DBIO::Util::mask_connect_secrets). What it cannot see is a piece of a password libpq quotes on its own: a hand-written conninfo string with an unquoted blank in the password leaves libpq complaining about the word behind the blank.

Called on a pool, it also makes the connection report its own death: its on_error first tells the pool the connection is dead ("_mark_connection_dead" in DBIO::Storage::PoolBase), then runs the on_error core's readiness wiring passed in. EV::Pg calls on_error only when the connection is gone -- the connect failed, or the server closed it, the socket broke, the protocol went out of step -- and always before it fails the statements queued on it, so a statement error the session survives never gets there. An idle connection whose backend dies is retired as soon as the EV loop reads the end of the connection, and the next acquire spawns a fresh one; a checked-out one is retired when it is handed back (see "_dispatch_query" in DBIO::PostgreSQL::EV::Storage). on_error comes from EV::Pg's read watcher, so only while the loop runs: an idle connection whose session ended with nobody running the loop is still listed idle, and is found when it is next borrowed ("_idle_connection_alive"). The handler holds the pool and the connection weakly, so neither is kept alive by it, and it reports nothing in a process other than the one that opened the connection ("Fork safety"). The LISTEN connection gets none of this: it is not the pool's, and core heals it ("_listen_lost" in DBIO::Storage::Async).

_new_waiter

The waiter seam of "acquire" in DBIO::Storage::PoolBase: the pending Future a caller waits on that had to be queued, because no connection is idle and the pool has no room to open one. That is a pool at its size -- or one below it whose remaining slots are taken by a spawn in flight: a spawn holds its slot from before it asks for the conninfo, so a caller that comes in from inside it is queued behind it, in a pool of one with no connection open yet ("acquire" in DBIO::Storage::PoolBase). Core's, of the pool's future_class, and told which pool queued it ("_queued_in" in DBIO::PostgreSQL::EV::Future) -- everything chained off it, the Future a blocking call finally waits on included, carries that along. It is what lets "await" in DBIO::PostgreSQL::EV::Future see that it waits for a queued caller, and refuse the wait when no connection can come back while it lasts ("_pg_held_by_callbacks"). A future_class that is not a DBIO::PostgreSQL::EV::Future is left as core made it.

_pg_held_by_callbacks

my $stuck = $pool->_pg_held_by_callbacks;

Is every connection of the pool held by something on the call stack right now -- a callback that is running, or a spawn that is -- so that none of them can come back before that has returned? Asked about a caller that is queued ("_new_waiter"). True when no connection is idle and each slot the pool has taken is held in one of two ways:

  • by a callback: the connection has a callback of this transport on the call stack and nothing but that callback's statement pending ("_held_by_callback" in DBIO::PostgreSQL::EV::Future). That is a pooled statement whose Future is being settled -- its then callbacks run before the connection is handed back -- or a transaction whose coderef, or a then on one of its statements, is running: it gives its connection back only after COMMIT or ROLLBACK, and the answer to either cannot be delivered before the callback has returned.

  • by a spawn ("_pg_opening"): the pool is opening the connection, synchronously, inside the acquire that found room for it, and that acquire has not returned. Whatever asks this question while it lasts runs above the spawn on the call stack -- in the AccessBroker's answer, or in a callback the EV loop ran while the broker's client, or the replay of a connect statement, waited -- and the connection is handed out only after the spawn has returned.

A caller queued for a connection is not served while that lasts, and a blocking wait for it would never end ("await" in DBIO::PostgreSQL::EV::Future). A spawn is looked at: a pool with nothing but a spawn in flight -- no connection yet, in a pool of one -- counts as held, so the wait is refused instead of hanging or dying of a loop that has run dry (t/77-blocking-behind-spawn-mock.t, t/78-blocking-behind-spawn-live.t).

False as soon as one connection could still come back: one that is idle or still connecting for a caller whose acquire has returned, one checked out by a statement that is in flight -- its answer releases it -- and one none of whose callbacks is running, whatever holds it. False too for a pool that holds nothing at all, neither a connection nor a spawn. Room to open another connection is not looked at: a caller is queued only when the pool has none.

_pg_opening

my $count = $pool->_pg_opening;

How many of the pool's slots are held by a spawn that is running: a connection the pool is opening inside an acquire that has not returned. A spawn holds its slot in two stretches, and both are counted:

Every spawn it counts is a frame on the call stack below whoever asks, since a spawn is synchronous through both stretches. Not counted: a connection whose spawn has returned and that is still connecting -- the loop brings that one up --, and a connect action that runs the loop by a way of its own, not through the connect statement seam.

_idle_connection_alive

my $alive = $pool->_idle_connection_alive($pg);

The borrow-time liveness seam of "acquire" in DBIO::Storage::PoolBase: asked about every idle connection the pool is about to hand out. One it does not vouch for is retired by core, which then takes the next idle connection, or opens one. So a session that ended while its connection sat idle -- pg_terminate_backend, idle_session_timeout, a server restart -- costs no caller a failed statement, also in a program that only ever blocks and so never runs the EV loop between two calls. Before that the pool learned of such an end from EV::Pg's on_error alone ("_new_connection"), which reaches as far as the loop does: the first call after it was handed the dead connection, and failed.

A connection is taken for dead only where that is certain, in this order:

1. "is_connected" in EV::Pg is false: dead. The handle has no connection any more and nobody told the pool -- a caller called finish on it, or EV::Pg lost it with a caller's on_error in place of the pool's.
2. A statement is queued or in flight on it ("pending_count" in EV::Pg): vouched for, without a look at the socket. A statement of this transport's own is answered before its connection goes back to the pool, but a caller that kept the handle can leave one on an idle connection ("txn_pg" in DBIO::PostgreSQL::EV::TransactionContext). Retiring the connection would call that statement's callback from inside acquire; its own read reports a lost connection instead.
3. The server's end of the socket is closed ("_pg_peer_closed"): dead.

Everything else is vouched for. That the socket has something to read says nothing here, and is not asked: a PostgreSQL server writes to a live idle session too -- a notification on a channel the session listens on, a notice, a parameter change, a TLS session ticket -- and such a session keeps its connection; what was sent stays on the socket for the loop to read.

It answers and does nothing else. Nothing is sent, nothing is read, no callback runs, the EV loop is not run, and it does not wait: what it costs a borrow is three accessors of the handle and one poll with a zero timeout. The pool is not told either -- core retires the connection it asked about, quietly: its on_error does not hear of a session found ended here, and the server's last words ("FATAL: terminating connection due to administrator command") are never read.

It narrows the window; it does not close it. Not seen:

  • a session that ends after the look -- its statement fails, and the connection is retired on the way back ("_pg_report_if_dead" in DBIO::PostgreSQL::EV::Storage);

  • a session that is ending. A backend sends its last message and then exits, and its end of the socket closes when the process is gone: 5 to 7 milliseconds after pg_terminate_backend had returned, measured against PostgreSQL 18.6. A borrow in between finds a readable, open socket and vouches;

  • a peer that went without closing -- a partition, a host that is gone. The kernel reports that only once it has given up on the connection (TCP keepalive, which libpq turns on);

  • anything, on a platform whose poll has no flag for a closed peer ("_pg_peer_closed"): there step 3 vouches for every connection, as the pool did before.

Measured against PostgreSQL 18 with EV::Pg 0.09 on libpq 17, over plain TCP (t/63-idle-liveness-live.t): the idle session terminated and its backend gone, or ended by idle_session_timeout -- the next call completes on a new session, without the loop having run; a live idle session with notifications waiting, with the unread answer of a statement, a notice among it, or 4 MB of one -- vouched for every time, and nothing of it lost. The look took 6 microseconds asked back to back, 15 to 20 as part of a borrow, where a statement's round trip took 2100 (those times taken with EV::Pg 0.07). Not measured: TLS (the server at hand had ssl = off; the look is at the TCP connection underneath, where a TLS record is data like any other and the close is the same close), a server restart (its backends exit as a terminated one does), and a Unix-domain socket to a server (the kernel answers the same for a socket pair of that kind, t/57-idle-liveness-mock.t).

It is asked only about connections of the process that owns the pool: a forked child's first acquire drops the connections it inherited before any of them is looked at ("Fork safety").

_pg_peer_closed

my $closed = $pool->_pg_peer_closed($pg);

Has the other end of $pg's socket been closed? One poll with a zero timeout on "socket" in EV::Pg, asking for the one thing the kernel knows without anything being read: that the peer has closed, or shut down its sending side (POLLRDHUP), that the connection is broken (POLLERR, POLLHUP), or that the descriptor is not open (POLLNVAL). POLLRDHUP is reported for a socket with unread data in front of the close as well -- a backend's last message, a TLS alert -- which is what tells a session that ended from one that was merely sent something: POLLIN is not asked for.

False -- not known to be closed -- for a handle without a socket, when poll fails, and on a platform where a closed peer cannot be asked for. Perl has no name for POLLRDHUP and its value is the platform's, so the bit (Linux: 0x2000) is not taken on trust: "_pg_rdhup" measures it. Where there is none, nothing is polled.

_pg_rdhup

my $bit = DBIO::PostgreSQL::EV::Pool::_pg_rdhup();

The poll event bit that says the peer of a stream socket has closed (POLLRDHUP), or 0 where this platform's poll has none that behaves so. A function, measured once per process on a socket pair of its own: the bit counts only if poll reports it for a peer that closed behind unread data, and does not report it for an open socket that has something to read.

_shutdown_connection

Closes one EV::Pg connection during "shutdown" in DBIO::Storage::PoolBase. Errors are swallowed by the caller. The base class clears the connection's readiness Future from its side table — this override never has to.

A connection with a statement in flight that is retired is closed only once the server has answered a cancel request for it: a core that retires the connection of a cancelled transaction, pipeline or deploy would otherwise have EV::Pg drop the request unsent, and the statement would run to its end. Not so during shutdown, nor in pipeline mode (a request stops the one statement the server is on, and the batch runs on), which close at once. See "Cancelling a statement" in DBIO::PostgreSQL::EV::Storage.

_transform_conninfo

my $string = $pool->_transform_conninfo($conninfo);

The libpq conninfo string one new connection is opened with -- this driver's side of "_transform_conninfo" in DBIO::Storage::PoolBase, which core calls for every spawn with the pool's conninfo or with what its conninfo_provider answered. Rendered by "conninfo_string" in DBIO::PostgreSQL::EV::ConnectInfo, it takes the two things "pool" in DBIO::PostgreSQL::EV::Storage gives the pool:

  • a hashref of libpq connection parameters -- what "_async_broker_conninfo" in DBIO::PostgreSQL::EV::Storage makes of an AccessBroker's answer -- becomes keyword=value pairs, quoted where libpq needs it, an undefined value left out;

  • a libpq conninfo string -- the static conninfo, or a broker's answer that was one -- comes back unchanged.

An arrayref is not taken: it dies, with Perl's own complaint about the reference, which holds nothing of what was in it. An arrayref here would be connect info nobody has read -- the DBI form [ $dsn, $user, $password, \%attrs ], or a [ \%conninfo, \%opts ] pair -- and reading those is the storage's ("connect_info" in DBIO::PostgreSQL::EV::Storage, "_async_broker_conninfo" in DBIO::PostgreSQL::EV::Storage), where the rules about them are kept; the storage never hands the pool one. A spawn that dies here fails its acquire, and no connection is constructed.

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.