NAME

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

VERSION

version 0.900001

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
$pool->release($pg);           # return to pool
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, are inherited from DBIO::Storage::PoolBase (karr #75); this class supplies only the EV::Pg seam — see "_create_connection", "_connection_ready_future", "_shutdown_connection" and "_transform_conninfo".

METHODS

_connection_ready_future

Overrides "_connection_ready_future" in DBIO::Storage::PoolBase: the resolved Future does not complete until the connection is actually ready for queries.

EV::Pg->new returns before its async connect finishes, so the base's default (immediately-done) seam would hand back a brand-new handle whose on_connect has not fired — the very first query on a cold pool then throws not connected (karr #9). We look up the per-connection readiness Future registered in "_create_connection" via "_connection_ready_lookup" in DBIO::Storage::PoolBase, falling back to the base's immediately-done seam for an already-connected (idle-reused) connection. acquire (inherited, unmodified) chains through this seam for every connection it hands out, so callers (CRUD, pipeline, acquire_txn) Just Work without pre-warming.

_create_connection

Builds one EV::Pg connection from the (already-transformed) connect info. The pool tracks the returned connection — do not push it onto "_connections" yourself.

Wires the connection's readiness Future (see "_connection_ready_future"): on_connect resolves it with the connection; an error before connect fails it, so a dependent query Future fails rather than hanging. After connect it falls through to the pool's on_error.

_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 (karr #75) — this override never has to.

_transform_conninfo

Renders the stored connect info as a libpq conninfo string via "conninfo_string" in DBIO::PostgreSQL::EV::ConnectInfo. Accepts a hashref, arrayref, or string and returns a single conninfo string.

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.