NAME
DBIO::PostgreSQL::Storage::Async - future_io async PostgreSQL transport over DBD::Pg's pg_async binding
VERSION
version 0.900007
DESCRIPTION
The concrete future_io transport adapter for PostgreSQL (core ADR 0030 / 0031). It is resolved by convention off the sync driver storage: a connection opened with
MyApp::Schema->connect($dsn, $user, $pass, { async => 'future_io' });
on a DBIO::PostgreSQL::Storage instance derives ref($storage) . '::Async' == DBIO::PostgreSQL::Storage::Async. No register_async_mode call is needed; the name itself is the registration.
Storage extensions ride on top by composition
Under the storage-layer composition model, a PostgreSQL extension (AGE, PostGIS, ...) is not a storage_type subclass and does not ship a shadow register_async_mode / ::Storage::Async of its own. It ships a plain storage layer registered with $schema->register_storage_layer('DBIO::PostgreSQL::Ext::Storage') and, for async behaviour, a sibling async mirror DBIO::PostgreSQL::Ext::Storage::Async (a plain method package, not a transport). When a layered schema connects { async => 'future_io' }, core resolves this transport by convention off the composition base (the driver, not the layers -- see "_async_resolution_class" in DBIO::Storage::DBI) and then DBIO::Storage::Composed->composes each registered layer's async mirror on top of it. So this class stays the single per-driver future_io transport BASE; extensions add behaviour above it via C3, exactly as their sync layers ride the sync driver storage.
The Model-B orchestration -- the CRUD runner ("_run_crud" in DBIO::Storage::Async with its pooled / pinned runners), INSERT returned-columns mapping, "txn_do_async" in DBIO::Storage::Async bracketing, the pipeline scaffold, and the sync ->get fallbacks -- is inherited unchanged from DBIO::Storage::Async. The Future::IO transport (query execution over the socket-readable watcher, the Future class and the DBIO::Async::Pool) is inherited from DBIO::Async::Storage. This class fills only the DB-specific transport seams over DBD::Pg's own asynchronous binding ({pg_async => PG_ASYNC} + pg_ready / pg_result / pg_socket):
"sql_maker_class" / "_sql_maker_args" -- the PostgreSQL SQLMaker
"_transform_sql" --
?to positional$Nplaceholders"_post_insert_sql" --
RETURNING *for the returned-columns hashref"_normalize_conninfo" -- DBI-form connect info into the pool's shape
"_async_broker_conninfo" -- an AccessBroker's connect info into the same shape, fresh for every new connection ("AccessBroker")
"_create_pool_connection" / "_shutdown_pool_connection" -- DBD::Pg handle lifecycle
"_conn_ready" / "_conn_fileno" -- readiness + the
pg_socketfd for the Future::IO watcher"_submit_query" / "_collect_result" -- send non-blocking, then gather once the wire is readable
"_conn_error_is_fatal" -- whether a failed statement took its connection with it, so the pool retires it
"_idle_connection_alive" -- whether an idle pool connection's session is still there before the pool hands it out, so one whose backend ended while it sat idle is retired instead
"_txn_commit_rolled_back" -- whether PostgreSQL answered a transaction's
COMMITwithROLLBACK"_reset_pool_connection" --
DISCARD ALLand the connect actions again when a borrow ends, so the session of one borrow is its own"_ddl_class" -- the DDL generator "deploy_async" in DBIO::Storage::Async installs from
The transaction-context seams are not among them: _txn_context_class and _txn_conn_accessor answer with the future_io transport's own defaults (DBIO::Async::Storage) -- the DBIO::Async::TransactionContext under the key txn_conn, which is exactly what this transport wants -- so it names them nowhere and would only do so for a different context class or constructor key.
A connection is represented as a small hashref { dbh => $dbh, sth => $sth }: the DBD::Pg database handle plus the statement handle of the in-flight async query. There is at most one per connection at a time: the pool lends a connection to one borrower, and on a pinned connection (a transaction's) the base sends a statement only once the one before it has settled ("THE PINNED STATEMENT QUEUE" in DBIO::Async::Storage). Pinning alone does not give that -- two statements issued on a transaction context without awaiting the first would otherwise share the connection.
For LISTEN/NOTIFY this class fills the PostgreSQL half of the listen seams (see "LISTEN / NOTIFY"):
"_listen_open" / "_listen_close" -- the dedicated listen connection
"_listen_subscribe" / "_listen_unsubscribe" -- quoted
LISTEN/UNLISTEN, each followed by a drain of what libpq buffered"_listen_drain" --
pg_notifies, in contract order, never blocking"_listen_probe" -- the liveness ping
"_notify_sql" --
SELECT pg_notify(?, ?)
The session of a borrow
A pool connection serves one borrow at a time -- a statement, a transaction or a pipeline -- and the session of a borrow is its own. When a borrow ends, "_reset_pool_connection" runs DISCARD ALL on the connection and then the connect actions again (search_path and LOAD of the connection's schema and extensions, on_connect_do, on_connect_call); only then is the connection given to the next borrower. A reset that fails, or takes longer than reset_timeout, retires the connection and the next borrower gets a fresh one.
The reset covers settings of the session (set_config(..., false), SET, SET ROLE, SET SESSION AUTHORIZATION), temporary tables, prepared statements, cursors, LISTEN registrations and the session-level advisory locks, which DISCARD ALL releases. Inside a transaction, set_config(..., true) and SET LOCAL end with it as before.
Transport capabilities
"transport_capabilities" declares what DBIO::Async::Storage declares -- on_connect_replay: the pool replays the owning sync storage's on_connect_do / on_connect_call on every freshly-spawned connection -- plus listen and notify ("LISTEN / NOTIFY"), the names the native ev transport uses for the same contract, and broker_connect_options: the connect options given beside an AccessBroker reach every connection this transport opens ("AccessBroker").
Two PostgreSQL wire features stay on the native ev backend (DBIO::PostgreSQL::EV::Storage, dist dbio-postgresql-ev) and are not declared here:
pipelining ("pipeline" in DBIO::Storage::Async) -- DBD::Pg's async binding exposes no libpq pipeline mode, so the pipeline seams stay core's croaking defaults.
COPY -- asynchronous
COPYisev-only. (COPYon the sync driver is a separate matter.)
An async storage layer that declares required_transport_capabilities for either of them fails loud (core capability gate) when composed over this future_io transport, naming the missing capability -- never a silent feature loss.
AccessBroker
Every built-in DBIO::AccessBroker works on this transport: DBIO::AccessBroker::Static, DBIO::AccessBroker::Vault and a DBIO::AccessBroker::HostBound view over either. The broker is asked for its current connect info whenever a connection is opened -- each new pool connection, and the listen connection at its first listen and at every reconnect -- so rotated credentials apply from the next connection on. What it answers is turned into a DBI->connect by "_async_broker_conninfo", which lists the shapes it takes.
# on the future_io backend ($schema->storage->async) directly
$async->connect_info([ DBIO::AccessBroker::Static->new(
host => 'db1', dbname => 'app', username => 'app', password => $pw,
) ]);
# or through the schema: a Vault broker carries the mode in its DBI attributes
my $schema = MyApp::Schema->connect(DBIO::AccessBroker::Vault->new(
vault => $vault,
dsn => 'dbi:Pg:dbname=app;host=db1',
cred_path => 'database/creds/app',
dbi_attrs => { async => 'future_io' },
));
# or through the schema, with the connect options beside the broker
my $schema = MyApp::Schema->connect($static_broker, {
async => 'future_io',
pool_size => 10,
pg_server_prepare => 0,
});
The options beside the broker (core ADR 0030 addendum) are taken here because this transport declares broker_connect_options ("transport_capabilities"). pool_size sizes the pool -- core's "connect_info" in DBIO::Storage::Async does that, with "_access_broker_pool_size" in DBIO::Storage::Async -- and every other DBD attribute is merged into the attributes of each connection opened from the broker's answer, pool and listen connection alike ("_async_broker_conninfo"). A setting given both beside the broker and in its answer must have the same value in both, or the connection is refused, naming the setting. What the owning sync storage applies itself -- async, on_connect_do, the SQL maker options -- never reaches DBI->connect.
LISTEN / NOTIFY
listen, unlisten, notify, listen_alive and listen_reconnect are core async API (core ADR 0056), the same contract on every async transport that declares listen / notify, and documented once in "LISTEN / NOTIFY" in DBIO::Storage::Async. Core owns the channel registry, the one dedicated listen connection, reconnect with backoff, re-subscribing every channel and the fork guard; DBIO::Async::Storage owns the Future::IO watch loop, the backoff timer and the pooled notify. This class supplies the PostgreSQL seams listed above. They are reached through the async backend of a future_io connection:
my $schema = MyApp::Schema->connect($dsn, $user, $pass, { async => 'future_io' });
my $async = $schema->storage->async;
$async->on_listen_error(sub {
my ($storage, $error) = @_; # every error; without a hook it is warned
$log->warn("listen: $error");
});
$async->on_listen_reconnect(sub {
my ($storage) = @_; # rebuilt, every channel subscribed again
$log->info('listen connection rebuilt -- re-read what may have been missed');
});
$async->listen_backoff_initial(0.5); # reconnect backoff, seconds
$async->listen_backoff_max(30); # (defaults 1 and 30)
$async->listen(jobs => sub {
my ($channel, $payload, $sender_pid) = @_;
...
})->get; # resolves once LISTEN is in effect
$async->notify(jobs => 'wake up')->get; # on a pooled connection
$async->unlisten('jobs')->get;
# an external watchdog
$async->listen_reconnect->get unless $async->listen_alive;
$sender_pid is the PostgreSQL backend pid of the notifying session. listen_alive is true while the listen connection is set up and answers a ping; a failed ping starts self-healing at once. on_listen_reconnect fires after a rebuild, not for the first connection.
Delivery is PostgreSQL's: a notification arrives when the sending transaction commits, and it is not durable -- whatever was sent while the listen connection was down is gone, which is what
on_listen_reconnectis for. There is no NULL payload:notify($channel)arrives as''. The listen connection's socket is watched from the event loop, and notifications are delivered from there. libpq also buffers notifications that arrive while the listen connection runs a synchronous statement -- its ownLISTEN/UNLISTENor the ping behindlisten_alive-- and those are delivered right after that statement, so a callback can run from insidelisten,unlistenorlisten_alivetoo.Channel names are PostgreSQL identifiers, sent quoted: exact and case-sensitive, any character but NUL, at most 63 bytes in UTF-8. A longer name is refused, not truncated ("_pg_quote_channel"):
listenfails its Future and the channel is dropped. The server limits a payload to less than 8000 bytes;notifyfails its Future beyond that.The listen connection blocks briefly. It is a synchronous DBD::Pg handle, opened with a blocking
DBI->connectlike every pool connection: its connect (at the firstlistenand on each reconnect), eachLISTEN/UNLISTENand thelisten_aliveping hold the event loop for one round trip. Against a host that stops answering without closing the connection, a round trip lasts until the TCP timeout; bound it with libpq parameters in the DSN (connect_timeout,keepalives_idle,tcp_user_timeout).Fork safety. Every connection of this transport -- the listen connection, and the pooled ones
notifyruns on -- is opened withAutoInactiveDestroy => 1("_create_pool_connection"), and core never touches them outside the process that opened them. A child that forks off a listening parent and exits -- global destruction and all -- leaves the parent's LISTEN session and its pooled sessions intact. A child that wants notifications itself callslistenand gets its own connection.
The IO::Async loop. With Future::IO::Impl::IOAsync, Future::IO watches the listen socket on the loop IO::Async::Loop->new returns -- the process-wide magic singleton -- which the implementation fetches the first time it needs a loop and keeps. A program that builds its loop with a subclass constructor, IO::Async::Loop::EV->new say, holds that same loop only if it built it before anything asked for the singleton; otherwise it runs a second loop while the socket is watched on the first, which nothing runs, and notifications silently never arrive. Build the program's loop through IO::Async::Loop->new and choose the implementation with IO_ASYNC_LOOP=EV in the environment (or $IO::Async::Loop::LOOP = 'EV' before the first construction).
METHODS
transport_capabilities
my @caps = DBIO::PostgreSQL::Storage::Async->transport_capabilities;
# ('on_connect_replay', 'listen', 'notify', 'broker_connect_options')
Class method ("transport_capabilities" in DBIO::Storage::Async): the inherited list plus listen and notify, the capability names core's LISTEN/NOTIFY gate asks for (core ADR 0056 section 2), and broker_connect_options, the promise core asks for before it hands this transport the connect options given beside an AccessBroker ("AccessBroker"). Not copy, not pipeline -- see "Transport capabilities".
sql_maker_class
The DBIO::PostgreSQL::SQLMaker subclass used to generate SQL.
_sql_maker_args
PostgreSQL SQLMaker construction args: the identifier quoting of the connection, and the LIMIT/OFFSET dialect.
The quoting is not decided here. quote_char and name_sep are taken from the SQL maker of the owning sync storage ("sql_maker" in DBIO::PostgreSQL::Storage, which is core's rule), so both paths of one connection quote alike: nothing given quotes with " and separates with ., quote_names => 0 alone or an empty quote_char alone writes identifiers unquoted, and an explicit quote_char or name_sep is used as given. A backend without an owning sync storage -- constructed on its own, not through connect(..., { async => 'future_io' }) -- quotes with " and ., the defaults of DBIO::PostgreSQL::Storage: core takes the quoting options out of the connect info it hands a backend.
_transform_sql
my $positional = $storage->_transform_sql($sql);
Transport-internal SQL shaping ("_transform_sql" in DBIO::Storage::Async, ADR 0032): number every ? placeholder as PostgreSQL's positional $N, left to right, so they line up with the bind values. The inherited query seams call it first ("_query_async" in DBIO::Async::Storage, "_query_async_pinned" in DBIO::Async::Storage); a caller of those hands over SQL in the ? dialect and never shapes it itself.
It delegates to "number_placeholders" in DBIO::PostgreSQL::Util, where the rule lives and is documented in full. In short: a ? is a placeholder where PostgreSQL reads SQL. A ? inside a string or quoted identifier, an escape string E'...' with its backslashed quotes, a dollar-quoted body ($$...$$, $tag$...$tag$) or a comment (-- ..., /* ... */, nested ones too) is text and stays as it is, so literal SQL that runs over the schema's dbh runs over this transport with the same binds. Everywhere else a ? is a placeholder, behind an operator character too (<@?, @@?, @?). This is the server's reading, which the sync driver's DBD::Pg does not match in four forms (a nested comment, a lower case e'...', a carriage return ending a -- comment, a $ inside an identifier); a statement with one of them can be read differently on the two ways, see "Where DBD::Pg reads less than the server" in DBIO::PostgreSQL::Util. \? is a literal question mark and the backslash goes: the jsonpath operator, which the SQL maker writes @\?, reaches the server as @?. $N already in the statement passes through, and a $N beside a ? placeholder is refused, as is an undefined statement or a reference: in the function's words, as a refusal of this transport's that names the caller's place ("_pg_refuse", "ERRORS"). A statement is shaped once: shaping it again changes nothing as long as it holds no \?, whose ? is a placeholder to a second pass.
A ? inside '...', "...", a dollar-quoted body, a comment or an E'...' string (behind its backslashed quote too) is passed over, not numbered. Numbered, a dollar-quoted body without a bind would reach the server changed -- $1 where its ? had been -- and with a bind DBD::Pg would refuse the statement: it looks for no placeholder in a body or a comment, so the first one it saw would be the statement's own, numbered $2 ("Invalid placeholders: must start at $1 and increment one at a time"), or it would count none at all ("called with 1 bind variables when 0 are needed").
DBD::Pg reads the numbered statement once more. This transport does not hand it to the server itself: "_submit_query" prepares it with pg_placeholder_dollaronly, and DBD::Pg then looks for the $N by a scanner of its own, which in places reads less than the server does. Measured with DBD::Pg 3.20.2 against PostgreSQL 18.6: it does not nest /* ... */, takes neither a lowercase e'...' nor the continuation of an E'...' string on the next line for an escape string, does not end a -- comment at a carriage return, and takes a $ inside an identifier (a$b$) for the start of a dollar quote. The numbering holds the server's reading all the same. Where the difference hides a $N from DBD::Pg, or shows it one that is text, DBD::Pg refuses the statement before it is sent, with one of the two messages above; it passes a $N on as it finds it, so such a statement never runs with other binds. The schema's dbh refuses or misreads the same statements. The native ev transport hands the statement to libpq and has no second reading.
_post_insert_sql
Returns RETURNING * so an INSERT yields every populated column (autoinc PK + retrieve-on-insert defaults); the inherited runner folds the row onto the supplied data to build the returned-columns hashref (ADR 0031 §3).
_normalize_conninfo
my $info = $storage->_normalize_conninfo([ 'dbi:Pg:...', $user, $pass, \%attrs, \%extra ]);
Convert the sync storage's DBI-form connect info into the [ \%conninfo, \%opts ] pair the pool consumes, carrying the DSN / user / password / attrs straight through for "_create_pool_connection" to hand to DBI->connect. The attributes are \%attrs and the optional fifth element \%extra_attributes merged, the later winning -- as the sync storage merges them ("connect_info" in DBIO::Storage::DBI), so an attribute given in either reaches every pooled connection. The DBIO-private keys of both are gone by then: core strips them before this seam ("connect_info" in DBIO::Storage::Async). A pool_size attribute, if present, is lifted into the conninfo hash (the inherited normaliser strips it back out to size the pool). Broker-style or already-normalised info is passed through untouched; what a broker answers is read by "_async_broker_conninfo".
_async_broker_conninfo
my $conninfo = $storage->_async_broker_conninfo($mode);
# { dsn => 'dbi:Pg:dbname=app;host=db1', user => ..., password => ..., attrs => {...} }
AccessBroker seam ("_async_broker_conninfo" in DBIO::Storage::Async), called for every new pool connection and for every open of the listen connection ("_listen_open"): ask the attached broker for its current connect info -- anew each time, so rotated credentials reach the next connection -- and turn it into the conninfo hash "_create_pool_connection" connects from. The broker's answer may come in any of these shapes:
A DBI-form arrayref
[ 'dbi:Pg:...', $user, $password, \%attrs ], as DBIO::AccessBroker::Vault answers, and DBIO::AccessBroker::HostBound over it. Read exactly like DBI-form connect info ("_normalize_conninfo"), after the DBIO-private attributes --async,quote_charand the rest -- are stripped from\%attrsthe way core strips them from a direct connect. That matters here: a Vault broker gets onto this transport throughMyApp::Schema->connect($vault)withdbi_attrs => { async => 'future_io' }, andasyncis no DBD::Pg attribute.A hashref of libpq connection parameters, as DBIO::AccessBroker::Static answers (
dbname,host,port,user,password), and DBIO::AccessBroker::HostBound over it.userandpasswordbecome theDBI->connectuser and password; every other key with a value becomes akey=valuepart of adbi:Pg:DSN, which DBD::Pg hands to libpq as it is -- so any libpq parameter works (sslmode,connect_timeout, ...). Parts without a value are left out, and the parts are sorted by name (dbname,host,port). The keys this transport's own shape uses (attrs,pool_size) keep their meaning.A key is a libpq parameter name: lower case letters, digits and underscores, beginning with a letter or an underscore. Any other key is refused, naming it.
Without
sslmodelibpq connects withprefer, and a server that does not offer TLS is then connected to in the clear. For a connection over a network answersslmode => 'verify-full'withsslrootcertnaming the certificate authority;verify-fullchecks the certificate and the host name.At least one of
dbname,host,port,hostaddrandservicemust be given: without one the DSN would bedbi:Pg:and libpq would take the target from its environment (PGHOST,PGDATABASE), so the credentials would go where the environment says.serviceandhostaddrname a target themselves and are enough. Anything else is refused, naming the parameters and never a value; the sync storage, which writes onlydbname,hostandport, refuses the same.A value is a value, whatever is in it: libpq reads back what the broker answered. Each one is written by "quote_dsn_value" in DBIO::PostgreSQL::Util, where the rule is kept and explained: a value containing whitespace,
;,',\,=or"goes in single-quoted, with',\and=escaped by a backslash; any other goes in as it is. So a database name given in double quotes keeps them --dbname => '"app"'is the database"app", notapp; the DBD::Pg way of quoting a name belongs into a DSN, not into a value. The sync storage writesdbname,hostandportthrough the same function ("_connect_params_dsn" in DBIO::PostgreSQL::Storage), so for a broker that answers these three both halves of a schema hold the same DSN. One difference is core's: it refuses a;in a value before the sync storage is asked for the DSN (core ADR 0057), where this transport writes it quoted. A value with a NUL character is refused, naming the parameter and never the value: no connection string can carry it, and written out it would end the DSN there, the parameters behind it lost.A
dbnamethat starts withdbi:is the DSN, taken as it is -- the way DBIO::AccessBroker::Static is given a whole DSN, and the way the sync storage reads it (core ADR 0057), so a schema's sync storage and itsfuture_iobackend open the same database. Nothing set beside it can be put into it:hostandport, which core refuses there, and every other parameter that would otherwise become a part of the DSN (sslmode, ...) croak in core's words, naming the keys and never a value. A parameter without a value is as none given, anduser,password,attrsandpool_sizekeep their meaning.A hashref in this transport's own shape -- with a
dsn, plususer,passwordandattrs-- taken as it is. A broker written for this transport answers in it.Either hashref as the first half of a
[ \%conninfo, \%opts ]pair.
The DBD attributes given beside the broker ("_access_broker_call_attributes" in DBIO::Storage::Async, see "AccessBroker") are then merged into the connection's attributes, whichever shape the answer came in -- the attributes of every shape are DBD attributes here -- with _merge_access_broker_settings (DBIO::Storage): a setting given in both places must have the same value, or this throws naming the setting, and nothing is connected.
The answer is read through "_current_async_connect_info" in DBIO::Storage::Async, so a broker that answers nothing -- undef, an empty hash or array, a false value -- is refused there, naming the broker class and the shape: an empty hash would otherwise become the DSN dbi:Pg:, and libpq would connect with its environment defaults. Anything else this transport cannot connect from is refused, naming the shape it received -- never the values, which carry the password.
Without a broker attached it is refused saying so ("ERRORS"), as "_async_broker_conninfo" in DBIO::Async::Storage does. The provider core installs outlives a broker detached through "clear_access_broker" in DBIO::Storage -- on the storage, where "_listen_open" asks it, and in a pool built with it -- and what is stored in the broker's place then is no broker's answer: no connection is opened from it, and it is not reported as one.
_create_pool_connection
my $conn = $storage->_create_pool_connection(\%conninfo);
Open one DBD::Pg handle via DBI->connect and wrap it as { dbh => $dbh }. AutoCommit is on: the inherited orchestration drives transactions with explicit BEGIN / COMMIT / ROLLBACK on the pinned connection, so DBD::Pg's own transaction tracking stays out of the way.
The handle is opened with AutoInactiveDestroy => 1, whatever the connect attributes say: a forked child that drops its copy of the handle -- at its exit, say -- must not send PostgreSQL the terminate message that would end the parent's pooled session. The pool itself never touches its connections outside the process that opened them ("_verify_pid" in DBIO::Storage::PoolBase); the handle's own DESTROY is this transport's half.
A connect that fails is reported without its password: the message goes through core's DBIO::Util::mask_connect_secrets with the connect info it is about, as core's own connect does (DBIO::Storage::DBI). Otherwise it is DBI's message -- DBI connect('...','user',...) failed: and libpq's reason -- or, when DBI->connect answered false because a HandleError among the connect attributes took the error, DBD::Pg connect failed: and libpq's reason. The listen connection ("_listen_open") is opened the same way, so the same holds for what its failed connect hands the listen Future and on_listen_error, on every reconnect attempt again.
The handle raises its errors through "_pg_raise", and so does the connect itself: what a failed connect or statement says is its text, without a file and a line of this library (see "ERRORS").
_pg_raise
_pg_raise($message);
_pg_raise($message, $dbh);
Die with $message and a newline -- the one place an error of DBI's, of DBD::Pg's or of the server's is raised on this transport (see "ERRORS"): a failed statement, a failed connect, a statement the server cancelled. A function, not a method. The transport's own refusals are raised by "_pg_refuse".
With the database handle the statement failed on, the text first loses the values bound to that statement (core's DBIO::Util/mask_bound_values: each value whole, also as $dbh->quote writes it), then the forms of the server's text ("mask_error_details" in DBIO::PostgreSQL::Util) -- the order of the sync storage's _mask_error_values. The SQLSTATE of the error, read from $dbh ("error_sqlstate" in DBIO::PostgreSQL::Util), goes with the text, so the values are masked by the SQLSTATE and the quoting marks in any language of the server (lc_messages), not by the English words alone; without a handle, only the English forms are read. The values are those "_submit_query" put on the handle for the statement in flight; a handle without any (a statement without binds, a connect) leaves the text to the forms alone.
Under Carp's verbose mode ($Carp::Verbose, perl -MCarp=verbose) it dies with the message and a stack trace instead, as croak does: whoever asks for the frames gets them. The trace is core's "masked_longmess" in DBIO::Util, so a password among the arguments of a frame (a DSN, the connect info) is shown as ***.
_pg_refuse
_pg_refuse($message);
_pg_refuse($message, [ $dsn, $user, $password, \%attrs ]);
Throw a refusal of this transport's own -- what it refuses to do with what the caller gave it (see "ERRORS") -- as a DBIO::Exception, the way core throws its own: Some::method(): $message at FILE line N, where the place is the caller's (maintainer's decision 2026-10-16). A function, not a method.
The place is found as "throw" in DBIO::Exception finds it, through DBIO::Carp: the first frame outside DBIO -- and outside Future and IO::Async, whose frames stand between the caller and a refusal reached in a callback of the event loop. So it is the caller's line whether the caller called into the transport itself, went through the pool, or ran the loop in which the refusal was reached. A loop of another library names the frame of that library that ran the callback.
Under Carp's verbose mode the exception carries a stack trace instead, the one "throw" in DBIO::Exception writes with core's "masked_longmess" in DBIO::Util. The connect info given is handed to it, so a password the refused answer holds is masked where a frame repeats it, as a password among the arguments of a frame always is.
_reset_pool_connection
my $future = $storage->_reset_pool_connection($conn);
The reset of a pool connection at the end of a borrow (core's seam, "_reset_pool_connection" in DBIO::Storage::Async, ADR 0079): DISCARD ALL, then the connect actions again ("_setup_pool_connection" in DBIO::Storage::Async: the connection's search_path and extension LOAD, on_connect_do, on_connect_call). The connection goes to the next borrower only after both, and a failure of either retires it. There is no way to switch it off.
DISCARD ALL ends everything the session of one borrow holds: settings (set_config(..., false), SET, SET ROLE, SET SESSION AUTHORIZATION, the session's isolation level), temporary tables, prepared statements, cursors, LISTEN registrations, sequence state (currval, lastval) and the session-level advisory locks, which it releases. The connect actions then set the session up as a fresh connect does.
_shutdown_pool_connection
Disconnect the DBD::Pg handle held by $conn.
_conn_ready
True once the connection can accept queries. DBI->connect is a blocking connect, so a handed-out connection is ready immediately. The check is only that $conn holds a handle DBI still counts as Active, i.e. one nobody has disconnected. It does not tell whether the server connection is still there: DBD::Pg leaves Active true on a lost connection. Whether an idle connection's session is still there is "_idle_connection_alive"'s question, asked before this one; a connection that died past that check is found out by the next statement sent on it, which fails and retires it ("_conn_error_is_fatal").
_conn_fileno
The connection socket fd for the Future::IO readable watcher, exposed by DBD::Pg as $dbh->{pg_socket}. The transport base ("_await_readable" in DBIO::Async::Storage) dups this integer fd into a filehandle for Future::IO->poll.
_submit_query
$storage->_submit_query($conn, $sql, $bind);
Send $sql non-blocking via DBD::Pg's async binding: prepare with {pg_async => PG_ASYNC} and execute the bind values. execute returns immediately; the result is gathered later by "_collect_result". The statement handle is stashed on $conn so the collector can fetch its rows.
pg_placeholder_dollaronly is set so DBD::Pg treats only the $N placeholders "_transform_sql" produced as bind parameters, leaving any literal ? (the one of the JSONB @? operator, written @\? before the numbering) alone.
A failure here -- DBD::Pg refusing the statement, or the send failing -- dies with DBI's message and nothing behind it ("ERRORS"), and the query Future fails with it ("_await_query_result" in DBIO::Async::Storage runs this inside Future->call). The base then asks "_conn_error_is_fatal", so a connection that turns out to be gone is retired rather than reused.
_collect_result
my $future = $storage->_collect_result($conn);
Called once the socket is readable. Takes the connection and nothing else: the SQL and the bind arrayref were consumed by "_submit_query" at dispatch and must not outlive it (ADR 0044), which is why "_collect_on_readable" in DBIO::Async::Storage forwards only $conn and why the re-poll below recurses the same way.
If the async result has not fully arrived ($dbh->pg_ready is false) it waits for the socket again -- through "_await_readable" in DBIO::Async::Storage, the one seam that touches Future::IO -- and re-checks, so a large result spanning several reads is handled correctly. The in-flight statement handle it needs is on $conn, put there by "_submit_query"; carrying the SQL and the binds into that re-poll callback instead would pin the caller's bind arrayref alive for as long as the result keeps arriving. Once ready it finalises with $dbh->pg_result and resolves:
a query that produced a result set (SELECT, or INSERT/UPDATE/DELETE
... RETURNING) -> the list of raw row arrayrefs, exactly the shape the sync cursor's->allyields (ADR 0031 §3);a statement with no result set (plain UPDATE/DELETE, BEGIN/COMMIT/...) -> the affected-row count from
pg_result.
The full list is carried in an explicit future_class->done(@rows) so it survives the surrounding ->then chain (a bare list return would collapse to its last element).
pg_ready and pg_result die on a failed statement, and on a lost connection, with DBI's message and the server's text ("ERRORS"); the die fails the query Future, and the base then asks "_conn_error_is_fatal", so a connection that is gone is retired rather than reused.
One failure pg_result does not die on: a statement PostgreSQL cancelled -- statement_timeout, pg_cancel_backend, a cancel request -- which fails with SQLSTATE 57014 (query_canceled). DBD::Pg answers that one with 0E0, sets no err and no errstr, and leaves only $dbh->state at 57014; the server's message is dropped. This is DBD::Pg's documented contract for its own pg_send_cancel, and it applies to every cancellation alike (pg_db_result in dbdimp.c; measured on PostgreSQL 18.6 / DBD::Pg 3.20.2). The sync path is not affected -- a blocking execute raises. So after pg_result the state is read, and 57014 fails the statement with an error naming the SQLSTATE; before, a cancelled statement resolved as a success with no rows. pg_result sets the state from every result it reads, a successful one included, so it is this statement's own and never left over from an earlier one. A cancelled statement leaves the connection usable -- its socket stays open, so "_conn_error_is_fatal" answers false -- and it goes back to the pool.
_txn_commit_rolled_back
my $rolled_back = $storage->_txn_commit_rolled_back($conn, @commit_result);
Core transport seam ("_txn_commit_rolled_back" in DBIO::Storage::Async): true when PostgreSQL answered the transaction's COMMIT with the command tag ROLLBACK. That is its answer, not an error, when a statement in the transaction failed and aborted it -- a statement core never saw fail, because it was sent on the pinned connection past the transaction context. Core then fails the transaction with "COMMIT was answered with ROLLBACK: ...".
The tag is the pg_cmd_status attribute of the COMMIT's statement handle, which "_submit_query" left on $conn. @commit_result cannot carry it: it is pg_result's row count, 0E0 for COMMIT and for its ROLLBACK answer alike, and the database handle's pg_cmd_status stays undef on an async statement (both measured on PostgreSQL 18.6 / DBD::Pg 3.20.2). Core asks from the success callback of the COMMIT's Future, and the base's statement queue sends the next statement on the connection only after that callback has run -- nothing is sent on the connection in between, so the handle on $conn is the COMMIT's own. A connection without a statement handle is taken at its word, core's default.
_conn_error_is_fatal
my $dead = $storage->_conn_error_is_fatal($conn, $error);
Driver seam of "_conn_error_is_fatal" in DBIO::Async::Storage: did the statement that just failed on the connection $conn take the connection with it? The base asks it for every failed query Future of "_query_async" in DBIO::Async::Storage and "_query_async_pinned" in DBIO::Async::Storage -- whether "_submit_query", pg_ready or pg_result died, or "_collect_result" failed a cancelled statement -- and on a true answer reports $conn to the pool ("_mark_connection_dead" in DBIO::Storage::PoolBase), so the release that follows retires it instead of putting it back. The pool cannot see a connection die by itself: without the report a dead handle goes back to the idle list and every caller it is handed to fails the same way. A transaction's pinned connection is covered alike, since core hands it back through the same release once the transaction has ended.
Dead means libpq has no server connection open any more: DBD::Pg's pg_socket (libpq's PQsocket) is -1, or $conn holds no handle at all. libpq drops the socket on every path where it concludes the connection is lost -- end of file (a terminated backend, a server restart), a read or write error, lost protocol sync -- and never on a statement error the session survives. That is the verdict of the library that owns the connection; $error is not read, and nothing is sent: no round trip, so the event loop is never held. $dbh->{Active} does not tell -- DBD::Pg leaves it true on a lost connection -- and pg_ping would, but costs a blocking round trip on every ordinary statement error. Measured on PostgreSQL 18.6 / DBD::Pg 3.20.2: pg_socket is -1 after pg_terminate_backend (idle or in flight), on a handle that is already dead and on a disconnected one, and unchanged after a syntax error, a division by zero, a bind error, an error inside a transaction and a cancellation (statement_timeout, pg_cancel_backend: SQLSTATE 57014) -- so a cancelled statement keeps its connection.
A connection whose backend died while it sat idle in the pool still shows an open pg_socket: libpq learns of the death only when it next reads from the socket. That read is "_idle_connection_alive"'s, before the pool hands the connection out, so such a connection is normally retired without a statement failing on it. What this seam still sees is a connection that died after that check, or without the server saying so (a network partition): its statement fails, the connection is retired with it, and the call after it gets a fresh one.
The listen connection never reaches this seam: its statements run synchronously ("_listen_subscribe", "_listen_probe", "_listen_drain"), not through the query path, and core heals it on its own.
_idle_connection_alive
my $alive = $storage->_idle_connection_alive($conn);
Driver seam of "_idle_connection_alive" in DBIO::Async::Storage: is the server session behind the idle pool connection $conn still there? Core's pool asks it every time it is about to hand out an idle connection ("acquire" in DBIO::Storage::PoolBase); on a false answer it retires $conn and takes the next idle connection or a fresh one, so a backend that ended while its connection sat idle -- pg_terminate_backend, a server restart, idle_session_timeout -- no longer costs a caller a failed statement first.
pg_socket alone cannot tell. libpq notices a lost connection only when it reads from the socket, and nothing reads from an idle pool connection: after pg_terminate_backend on an idle backend, pg_socket stays open and Active stays true until the next read. What the server does leave is on the socket. Ending a session, it sends a FATAL error message and closes, so the socket turns readable -- and an idle connection has no statement in flight, so nothing else is due on it. So the check is:
- 1.
pg_socketbelow zero, or no handle: dead (the verdict of "_conn_error_is_fatal"). - 2. The socket is not readable, by a
selectwith a zero timeout: alive. The common case, and all it costs. - 3. Readable: let libpq read what arrived -- one
pg_notifies, which runsPQconsumeInput-- and give the verdict of step 1 again. Repeated while the socket stays readable, at most four reads.
Why read instead of taking readable as dead: a PostgreSQL server also writes to a live idle session. A notification on a channel the session LISTENs to arrives at once, and it leaves the socket readable exactly like a dying session's last message; taking readable as dead would throw such a connection away on every borrow. Reading tells the two apart. Measured on PostgreSQL 18.6 / libpq 17 / DBD::Pg 3.20.2, idle backend terminated with pg_terminate_backend and gone from pg_stat_activity: pg_socket unchanged, socket readable; the first read takes the FATAL message -- libpq handles an error that arrives while idle as a notice -- and answers nothing, the socket is still readable (the end of file behind it); the second read dies with "server closed the connection unexpectedly", and pg_socket is -1. Over TLS the same two reads, the second dying with "SSL connection has been closed unexpectedly": the verdict is the socket's, never the wording's. A connection that received a notification: readable, one read consumes it, not readable any more, socket open -- alive. Two reads are what a session the server ended takes; the bound of four only keeps a connection that goes on receiving, which is a live one, from holding the acquire.
It never blocks and never sends. The zero-timeout select does not wait; PQconsumeInput sends nothing and reads only what the socket holds, with the socket in O_NONBLOCK mode for the read ("_pg_nonblocking") -- the same guarantee the listen drain relies on ("_listen_drain"). No ping, no pg_ping: both are round trips.
A read that dies because the connection is gone is the answer, not a failed check: false, and core retires the connection quietly. A read that dies while the socket stays open is not understood here, and is rethrown; core then retires the connection all the same and reports the error to the pool's on_error.
Two side effects of the read, both of which the next statement's read would have had anyway:
The dying session's
FATALmessage reaches DBD::Pg as a notice, which it warns (unless the handle'sPrintWarnis off) -- now from the acquire, as the one trace of why the connection was retired.A notification a pool connection received is taken off libpq's queue and dropped. A pool connection is not a listen connection: this transport runs
LISTENonly on the dedicated listen connection ("_listen_open") and never reads a notification from a pool connection, so one there -- possible only if the application ranLISTENon pool connections itself, inon_connect_dosay -- was never going to be delivered.
It narrows the window; it does not close it. A backend can die after the check, or without the server saying so (a network partition, a host gone); the statement sent on it fails, and "_conn_error_is_fatal" retires the connection as before.
_listen_open
my $f = $storage->_listen_open; # done with { dbh => $dbh }
Core listen seam ("_listen_open" in DBIO::Storage::Async): open the dedicated listen connection -- a new DBD::Pg handle, never one from the pool. Its connect info is what a pool spawn would get at this moment: fresh credentials through "_conninfo_provider" in DBIO::Storage::Async when an AccessBroker is attached (so rotated credentials apply exactly as they do to the pool), otherwise the static conninfo. A provider whose broker has been detached opens nothing: "_async_broker_conninfo" throws. The connect shape is the pool's ("_create_pool_connection": AutoCommit, RaiseError, no PrintError, AutoInactiveDestroy => 1). The last one, set at connect time, matters most here: a forked child that exits, and so destroys its inherited copy of the handle, must never send PostgreSQL the terminate message that would end the parent's LISTEN session.
The handle is synchronous (no pg_async): it only ever runs LISTEN, UNLISTEN and the probe's ping, and is otherwise watched for readability. The pool's on_connect_do / on_connect_call replay is not run on it -- none of those statements concern listening, and a session-setup statement with side effects should not run once more per reconnect.
Resolves with { dbh => $dbh }, the shape of a pool connection, so the inherited "_conn_fileno", "_conn_poll_fh" in DBIO::Async::Storage and "_await_readable" in DBIO::Async::Storage work on it unchanged. A failed connect throws, which core reports and heals from.
_listen_close
$storage->_listen_close($conn);
Core listen seam ("_listen_close" in DBIO::Storage::Async): disconnect the listen handle and take it off $conn. A dead connection is fine -- DBD::Pg's disconnect does not fail on one -- and a connection already closed is left alone. Core has stopped the watch ("_listen_unwatch" in DBIO::Async::Storage) first, and never calls this in a process other than the one that opened the connection.
_listen_subscribe
my $f = $storage->_listen_subscribe($conn, $channel);
Core listen seam ("_listen_subscribe" in DBIO::Storage::Async): run LISTEN "channel" on the listen connection. The channel is validated and quoted as an identifier (see "_pg_quote_channel"), never interpolated raw (ADR 0017 section 3, as restated by core ADR 0056). A channel it refuses makes the seam throw; core then finds the connection alive, drops the channel and fails its "listen" in DBIO::Storage::Async Future with the reason.
Right after the statement it drains and dispatches what libpq buffered during the round trip (see "_pg_dispatch_buffered"): a notification that arrived while the synchronous LISTEN waited for its reply sits in libpq's buffer, and the socket never becomes readable for it again.
_listen_unsubscribe
my $f = $storage->_listen_unsubscribe($conn, $channel);
Core listen seam ("_listen_unsubscribe" in DBIO::Storage::Async): UNLISTEN, with the same validation, quoting and drain as "_listen_subscribe". Core has already dropped the channel from its registry, so a notification for it that the drain turns up is discarded; the other channels' are delivered.
_pg_quote_channel
my $sql_ident = $storage->_pg_quote_channel($channel); # "jobs"
Validate a channel name and quote it as a PostgreSQL identifier: wrapped in double quotes, embedded " doubled. Quoting makes the name exact -- case included -- which is also how pg_notify (the "_notify_sql" statement) takes it, so listen('Jobs') and notify('Jobs') meet.
Refused, by throwing: an undefined, empty or reference channel, one containing a NUL byte, and one longer than 63 bytes in UTF-8 (PostgreSQL's NAMEDATALEN - 1). The length limit is a refusal, not a truncation, because a longer name can never deliver: LISTEN would silently truncate it and then report notifications under the truncated name, which matches no registered channel, and pg_notify rejects it outright ("channel name too long").
The rule itself lives in "quote_channel" in DBIO::PostgreSQL::Util, a public helper the native ev transport can load as well; this method delegates to it. The helper croaks, which blames its caller -- this file. A refusal is raised again in the helper's words as a refusal of this transport's, naming the caller's place ("_pg_refuse").
_listen_drain
my $notifications = $storage->_listen_drain($conn);
# [ [ $channel, $payload, $sender_pid ], ... ]
Driver seam of the DBIO::Async::Storage watch loop ("_listen_drain" in DBIO::Async::Storage): every notification pending on the listen connection, in arrival order, as [$channel, $payload, $sender_pid] -- DBD::Pg's pg_notifies answers [$channel, $sender_pid, $payload], and the tuple is reordered into the contract's order here. An empty arrayref when nothing is pending.
Each pg_notifies call runs libpq's PQconsumeInput, which reads what the socket holds without waiting for more, then PQnotifies. It dies:
on a dead connection, and at end of file --
PQconsumeInputfails ("server closed the connection unexpectedly", over TLS "SSL connection has been closed unexpectedly", then "connection not open") and DBD::Pg raises it under the handle'sRaiseError. A server that terminates the backend first sends itsFATALmessage, which one drain consumes as a notice and answers[]for; the end of file behind it keeps the socket readable, so the next drain dies. Either way the loop never spins on a closed socket.on an error DBD::Pg recorded without raising it (a caller-supplied
HandleErrorthat swallowed it), as a second line of defence.on a connection "_listen_close" already closed.
It never blocks. libpq's socket must be in O_NONBLOCK mode for PQconsumeInput to return when the socket runs dry -- libpq reads a second time on its own once more than 32 kB are buffered -- and O_NONBLOCK lives on the open file description that the watch loop's dup of the socket shares. Future::IO's built-in implementation clears it on that dup while its poll callbacks run, which is exactly when a drain happens. So every libpq read on the listen connection runs with O_NONBLOCK set and the previous mode restored afterwards ("_pg_nonblocking").
_listen_probe
my $alive = $storage->_listen_probe($conn);
Core listen seam ("_listen_probe" in DBIO::Storage::Async), asked by "listen_alive" in DBIO::Storage::Async and after a failed channel operation: DBD::Pg's ping, a synchronous empty-query round trip, false on a dead connection. Like "_listen_subscribe" it drains and dispatches afterwards what libpq buffered during that round trip, so a callback may run from inside listen_alive.
_pg_dispatch_buffered
$storage->_pg_dispatch_buffered($conn);
Deliver what a synchronous statement on the listen connection left in libpq's buffer: "_listen_drain", then "_listen_dispatch" in DBIO::Storage::Async for each notification, in order. A channel callback that ends the connection (unlistening the last channel, listen_reconnect) stops the batch there -- nothing is dispatched for a connection core has closed, just as the watch loop stops.
_pg_nonblocking
my $r = $storage->_pg_nonblocking($conn, sub { $dbh->ping });
Run the code with the connection's socket in O_NONBLOCK mode -- the mode libpq assumes -- and put the previous mode back afterwards, whether the code returned or died. Used for every libpq read on the listen connection, and for the read "_idle_connection_alive" makes on an idle pool connection. The flag is set through the watch loop's cached dup of the socket ("_conn_poll_fh" in DBIO::Async::Storage), which shares it with libpq's own descriptor; see "_listen_drain" for why. A connection whose socket is already gone (pg_socket is -1) is left as it is: libpq fails on it at once instead of blocking.
_notify_sql
my ($sql, $bind) = $storage->_notify_sql($channel, $payload);
# ('SELECT pg_notify(?, ?)', [ $channel, $payload ])
Driver seam of "_notify_send" in DBIO::Async::Storage, which runs the statement on a pooled connection through "_query_async" in DBIO::Async::Storage -- where "_transform_sql" turns the ?s into $1, $2. Channel and payload travel only as bind values, never in the SQL (ADR 0017 section 3). PostgreSQL has no NULL payload: pg_notify sends an undef payload as the empty string, and a listener receives ''. The server refuses a channel over 63 bytes and a payload of 8000 bytes or more; the Future of "notify" in DBIO::Storage::Async fails with its message.
_ddl_class
The class "deploy_async" in DBIO::Storage::Async asks for the install DDL, via _ddl_class->install_ddl($schema) -- DBIO::PostgreSQL::DDL, the very class the sync DBIO::PostgreSQL::Deploy and the native ev backend (DBIO::PostgreSQL::EV::Storage) name. One generator for all three paths, so $storage->deploy_async($schema) and $deploy->install put byte-identical DDL on the wire; a second generator here could only drift.
Without it the inherited deploy_async croaks (core leaves the seam abstract, because a backend that cannot deploy must say so rather than deploy something else).
deploy_async
my $future = $storage->deploy_async($schema, \%opts);
Core's "deploy_async" in DBIO::Storage::Async, behind one question to the server. The schema of a CREATE EXTENSION is, as in DBIO::PostgreSQL::Deploy, the declared one, else the one the control file of the extension fixes, else public -- and the control file is the server's to tell. So before the DDL is built, a pooled connection is asked (asynchronously, no second blocking connection) for the schemas the control files of the extensions the schema class declares fix ("control_schemas_sql" in DBIO::PostgreSQL::DDL), a declared schema other than a fixed one is refused with the Future failed, before any statement of the DDL ("check_control_schemas" in DBIO::PostgreSQL::DDL), and the answer reaches "_install_ddl" as extension_control_schemas. An extension with a fixed schema (age, postgis_topology, ...) is thus written without the WITH SCHEMA clause the server would refuse. A schema that declares no extension, or no schema class with the PostgreSQL component, asks nothing.
_install_ddl
The install script (core's _install_ddl, which asks the generator without options), with the control schemas "deploy_async" read from the server passed to "install_ddl" in DBIO::PostgreSQL::DDL as extension_control_schemas.
ERRORS
An error of the database's is a plain string: its text and a newline. A refusal of this transport's own is a DBIO::Exception that names the caller's place. Either reaches the caller as the failure of the Future -- of a statement, of txn_do_async, of listen or notify -- or as what a direct call dies with, and as the argument of on_listen_error, unchanged or behind core's words for where it happened (opening the listen connection failed: ...; core's words make a string of the exception).
A statement the server refuses fails with DBI's message: the method that collected it,
failed:, and the server's text as libpq gives it,DETAIL,HINT, theLINEand its position marker included.DBD::Pg::db pg_result failed: ERROR: duplicate key value violates unique constraint "users_pkey" DETAIL: Key (id)=(1) already exists.A statement DBD::Pg refuses before it is sent reads
DBD::Pg::st execute failed: ..., and so does one on a connection that is gone.The text names no value the statement was run with. Of a statement with bound values every value of four characters or more is replaced by
***whole, also where the server reads it as a name (relation "***" does not exist), and then the forms of the server's text are masked, in whatever language the server reports ("mask_error_details" in DBIO::PostgreSQL::Util), for a statement of the pool, of a transaction's pinned connection and of_query_asyncalike. The values are at the connection's database handle (private_dbio_binds) from "_submit_query" until the statement is over; a result, an error and a failed send take them, and the statement handle that holds them, off again (ADR 0044).The SQLSTATE is not in that text and never was. It is on the DBD::Pg handle the statement ran on (
state), which a caller holds only for a pinned connection -- a transaction context'stxn_conn. The one failure that names its SQLSTATE is a statement the server cancelled (57014, "_collect_result"), because that is all DBD::Pg passes on of it.A connection that cannot be opened fails with DBI's
DBI connect('...','user',...) failed:and libpq's reason, its password masked ("_create_pool_connection").A refusal of the transport -- what it refuses to do with what the caller gave it -- is a DBIO::Exception, the way core throws its own: the transport's method that refused, one sentence saying what was refused, and the caller's file and line ("_pg_refuse", maintainer's decision 2026-10-16).
DBIO::PostgreSQL::Storage::Async::_pg_quote_channel(): LISTEN channel name '...' is 64 bytes long; ... at app.pl line 12These are: no AccessBroker attached to ask; a broker answer of a shape it cannot connect from, with an empty
dbname, with parameters beside adbnamethat is a whole DSN, or with a parameter that is a reference or holds a NUL character; connect info that is no hash with adsn; a channel name "quote_channel" in DBIO::PostgreSQL::Util refuses; a listen connection that is closed; and a statement "number_placeholders" in DBIO::PostgreSQL::Util refuses -- none at all, or$Nbeside a?. The place is the caller's whether the caller called into the transport itself, went through the pool, or ran the event loop in which the refusal was reached.
None of the errors of the database's names a file and a line. Under RaiseError DBI raises an error itself and adds the place that called it, and every call into DBI is made from this file, so a statement would fail with ... at <where DBIO is installed>/DBIO/PostgreSQL/Storage/Async.pm line 946. -- a path that says where the library lives and a line that moves with every release, neither of them about the statement. So every handle this transport opens carries a HandleError that raises the error instead (the one DBI->connect in _pg_connect; it covers the connect itself, the pool connections and the listen connection), through "_pg_raise". A HandleError among the caller's connect attributes is not replaced: it is asked first and keeps what DBI gives one -- answering true it has taken the error, dying it has replaced it. This transport depends on its statements raising, so a HandleError that takes errors is the caller's risk, as it was.
Whoever asks Carp for stack traces ($Carp::Verbose, perl -MCarp=verbose) gets the text followed by the trace, for every one of these -- a refusal as a DBIO::Exception still. A failed connect and the transport's refusals always did; an error DBI raised on an open handle did not, because DBI raises those from C. The frames are written by DBIO::Util::masked_longmess: a password in the arguments of a frame is not shown, nor, for a refusal, the password of the connect info it refused.
Not raised here, and in the form of who raises it: what core says about a transaction or the listen machinery (DBIO::Exception objects -- COMMIT was answered with ROLLBACK, an unsupported capability), what DBIO::Async::Storage says about a statement abandoned in flight, and what DBD::Pg croaks directly while it reads a statement (Invalid placeholders: must start at $1 ..., which names no place either).
AUTHOR
DBIO & DBIx::Class Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.