NAME

DBIO::PostgreSQL::EV::Storage - Async PostgreSQL storage driver using EV::Pg

VERSION

version 0.900007

DESCRIPTION

The native ev async transport for PostgreSQL (core ADR 0030 / 0031): a thin transport over EV::Pg, a non-blocking libpq client that speaks the async wire protocol directly. No DBI, no DBD::Pg, just raw libpq performance.

It resolves as the ev async mode of DBIO::PostgreSQL::Storage (registered there via register_async_mode( ev => ... )), so a schema connected with { async => 'ev' } answers the six *_async storage methods over EV::Pg while the same schema keeps serving synchronous queries over DBI/DBD::Pg.

Thin transport: shared machinery is inherited

The Model-B orchestration (ADR 0030 §4) is inherited unchanged from DBIO::Storage::Async: the CRUD runner ("_run_crud" in DBIO::Storage::Async with its pooled / pinned runners), the INSERT returned-columns mapping, "txn_do_async" in DBIO::Storage::Async bracketing, the "pipeline" in DBIO::Storage::Async scaffold, the sql_maker plumbing and the sync ->get fallbacks. This class fills only the loop-/wire-specific seams:

Because the extension-composition point is the core resolver, an async storage layer composed onto this transport inherits every CRUD/txn path for free; the transport only has to advertise the wire capabilities it really provides (see "transport_capabilities").

Transport value-add

Beyond the CRUD/txn contract this transport carries two PostgreSQL wire features the abstract future_io transport cannot: COPY ("copy_in") and libpq pipelining. These override the base's croaking defaults and are declared in "transport_capabilities" so a layer that requires them composes cleanly (and core croaks loudly, never silently dropping the feature, when it cannot). LISTEN/NOTIFY is declared too, but it is no longer this transport's own API: it is core's, and this class fills its seams ("LISTEN / NOTIFY").

The session of a pooled connection

Every borrow of a pooled connection has a session of its own. A borrow is a statement, a transaction up to its COMMIT or ROLLBACK, a pipeline or a copy_in. When it ends the connection is reset before anyone else gets it: DISCARD ALL goes out, and then the connect actions run again -- the connection's search_path, extension LOAD, on_connect_do, on_connect_call. Whatever a borrower set on the session -- SET, SET ROLE, set_config(..., false), a temporary table, a prepared statement, a session-level advisory lock, a LISTEN -- ends with its borrow, and the next borrower finds the session a fresh connect gives. The reset is answered before the connection is lent again, also to a caller that is already queued for it ("_reset_pool_connection"). A connection whose reset fails or does not answer within reset_timeout seconds (default 10) is closed, and the next borrower gets a new one.

Within one transaction the settings stay: they belong to that borrow, and a SET LOCAL or set_config(..., true) ends with the transaction as usual. Statements of different calls on the storage are different borrows. The connection of listen is a connection of its own outside the pool.

Cancelling a statement

Cancelling the Future of a statement in flight -- $f->cancel, or losing it in needs_all or wait_any against a timeout -- asks the server to stop it, when the stack can: EV::Pg's cancel_async (libpq 17 and later, LIBPQ_HAS_ASYNC_CANCEL, found with can) is called, once, on the connection the statement runs on. The blocking cancel is never called: it holds the event loop for a network round trip, with no upper bound when the network is the trouble. No request goes out for a statement that is not in flight on a connection of its own: one that waits behind another statement of a transaction's pinned connection, one sent in pipeline mode, and a "copy_in".

The connection is held until both are in: the statement's result -- the server's 57014 canceling statement due to user request, or its normal result when it finished first; the Future is cancelled and discards it -- and the answer to the cancel request. Only then does a pooled connection go back to the pool, and the next statement of a transaction's pinned connection go out. Released earlier, the request would reach the next statement that connection runs, and fail a caller who cancelled nothing (measured: 151 of 185 requests through the pool). The next call on a pool of one waits for that, about ten milliseconds, and not for the end of a statement nobody waits for any more. A request that itself ends with an error retires the connection.

Cancelling the Future of txn_do_async, pipeline or deploy_async -- or only the Future a transaction's coderef returned -- retires the connection in core (ADR 0055 addendum): ROLLBACK best-effort, the connection out of the pool at once, its slot to a fresh connection. A retired connection with a statement in flight is not closed at that moment: closing drops a cancel request that is not through yet, unsent, and the statement would run to its end on the server. The pool ("_shutdown_connection" in DBIO::PostgreSQL::EV::Pool) asks the server to stop it and closes the connection when the request is answered, or lost with the connection.

Without cancel_async -- EV::Pg built against libpq 16 or earlier -- nothing changes: no request is sent, the server runs the statement to its end, and the connection is held, as before, until its result is in. needs_all and wait_any cancel the losers, so with the capability their statements are aborted on the server instead of running to the end.

A statement cancelled while it still waits in the queue of a transaction's pinned connection is skipped: it is not sent, and the server never runs it. The order of the statements behind it is kept; nothing overtakes. The exception is the COMMIT or ROLLBACK of core: a cancelled one is sent all the same -- the queue knows it as the end of the transaction, and skipping it would leave the backend idle in transaction, with its locks. The transaction fails as before with cancelled before it was answered.

What a failed statement's Future fails with

A statement the server refused -- a unique violation, a deadlock, a serialization failure, a statement cancelled by statement_timeout -- fails its Future with one DBIO::Exception::Server (ADR 0062 in core). It answers sqlstate, and constraint, table and detail where the server sent them, and it stringifies to the very text the Future failed with before it was an object -- the server's own words, in its lc_messages:

$storage->insert_async($source, \%row)->catch(sub {
  my ($error) = @_;
  if (Scalar::Util::blessed($error)
      && $error->isa('DBIO::Exception::Server')
      && ($error->sqlstate // '') eq '23505') {
    ... # $error->constraint, $error->table
  }
});

eq, =~ and on_fail(sub { my ($message) = @_ }) see the text they saw. It is one object on every path -- pooled, pinned, inside txn_do_async, in a pipeline, a notify, a "copy_in", a LISTEN -- and get dies with it.

What is not the server's stays the plain string it was, with no SQLSTATE:

  • the connection is gone: "connection lost", "connection finished", "pipeline aborted", "empty query", libpq's "server closed the connection unexpectedly" and every other text of EV::Pg's or libpq's own

  • a statement EV::Pg refused to send, "not connected" and "another command is already in progress", and EV::Pg's refusal to enter or leave pipeline mode -- its text and a newline, without the line of this library that called EV::Pg

  • a statement after the COMMIT of its transaction, a blocking wait on the loop, "connecting the listen connection failed: ...", "pool connect statement failed: ..."

  • the error of a copy_in coderef that died, which the Future fails with as the coderef died

  • a cancelled Future, which is cancelled and has no failure at all

The line is drawn by the text, not by the connection. EV::Pg keeps error_fields of the last server error on the connection and sets it only for an error result of a server: a successful statement leaves it, so it still holds the previous error's SQLSTATE; only a lost, reset or finished connection clears it (measured with EV::Pg 0.09). A failure is the server's only when its text begins with the severity and the primary message error_fields holds -- libpq's SEVERITY: primary, the SQLSTATE between them in verbose mode -- which is true in the callback of the very statement that was refused and of nothing else ("_pg_server_error").

Where core puts its own words in front -- BEGIN failed: ..., COMMIT failed: ..., Transaction aborted: ... Rollback failed: ... -- the caller gets a derived copy of the same class and fields with context set (BEGIN, COMMIT or ROLLBACK), stringifying with that prefix (core ADR 0062). Only a failure that is not the server's stays a prefixed string.

Refusals of the transport

What this transport 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"; the future_io transport refuses the same way):

DBIO::PostgreSQL::EV::Storage::_pg_quote_channel(): LISTEN channel name '...' is 64 bytes long; ... at app.pl line 12

These are: no AccessBroker attached to ask; connect info, or a broker's answer, of a form it cannot connect from ("connect_info"); a connection parameter given beside the broker; a listen connection that is closed, not connected or has no connect info; a channel name "quote_channel" in DBIO::PostgreSQL::Util refuses; a statement "number_placeholders" in DBIO::PostgreSQL::Util refuses -- $N beside a ?; and the writer of a "copy_in" called outside its COPY. The words are what they were. The place is the caller's whether the caller called into the transport itself, went through the pool, or ran the EV loop in which the refusal was reached. A refusal reached through the pool fails the statement's Future with the exception; inside core's words -- "LISTEN on channel '...' failed: ...", on_listen_error -- it is a string, as core makes it one.

A refusal of a blocking wait ("await" in DBIO::PostgreSQL::EV::Future) and of a statement after its transaction's COMMIT are not among them: they stay as they were.

LISTEN / NOTIFY

listen, unlisten, notify, listen_alive and listen_reconnect, the hooks on_listen_error and on_listen_reconnect, and the backoff settings listen_backoff_initial / listen_backoff_max are core async API (core ADR 0056) -- one contract on every async transport that declares listen / notify, the PostgreSQL future_io transport included, and documented once in "LISTEN / NOTIFY" in DBIO::Storage::Async. Core owns the channel registry, the one dedicated listen connection, the queue that runs one LISTEN / UNLISTEN at a time on it, reconnect with backoff, LISTENing every channel again on the new connection, and the fork guard. This class fills the listen seams with EV::Pg. They are reached through the async backend of an ev connection:

my $schema = MyApp::Schema->connect($dsn, $user, $pass, { async => 'ev' });
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 LISTENed 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;                               # runs the EV loop until LISTEN is in effect

$async->notify(jobs => 'wake up')->get;   # on a pooled connection
$async->unlisten('jobs')->get;

# an external watchdog, from an EV::timer say
$async->listen_reconnect unless $async->listen_alive;

What is particular to this transport:

  • 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_reconnect is for. $sender_pid is the backend pid of the notifying session. There is no NULL payload: notify($channel) arrives as ''. Notifications are delivered from the EV loop, by EV::Pg's on_notify, in arrival order. Those that arrive while a connection is still being set up -- after its first LISTEN, while core subscribes the other channels one by one -- are held and delivered when watching starts ("_listen_watch"), before the listen Future resolves; none is dropped.

  • Channel names are PostgreSQL identifiers, sent quoted: exact and case-sensitive, any character but NUL, at most 63 bytes in UTF-8. A . is part of the name -- app.events is one channel, not a schema-qualified one. A longer name is refused, not truncated ("_pg_quote_channel"): listen fails its Future and the channel is dropped. The server limits a payload to less than 8000 bytes; notify fails its Future beyond that.

  • Liveness. The EV loop watches the listen connection's socket the whole time, so a server that ends the session (pg_terminate_backend, a restart) is noticed as soon as the loop reads the end of the connection: EV::Pg reports it through on_error, and core closes the connection, reports the error through on_listen_error and reconnects with backoff. listen_alive asks EV::Pg's own view of the connection ("_listen_probe") and never blocks; unlike the future_io transport it sends no ping, so it cannot know more than the loop has read. A peer that vanished without closing the connection is found only by TCP: bound that with libpq parameters in the DSN (keepalives_idle, tcp_user_timeout).

  • Nothing blocks the loop. The connect, each LISTEN / UNLISTEN and the backoff timer are EV watchers. The Futures are "future_class", so get on one runs the EV loop until it is ready.

  • The loop stays up while something is listened to. The listen connection is opened with EV::Pg's keep_alive, so EV::run keeps running for as long as the connection is open -- what a daemon waiting for notifications needs. It closes when the last channel is unlistened.

  • Fork safety. The listen connection is built like a pooled one ("Fork safety" in DBIO::PostgreSQL::EV::Pool): a forked child that exits, or drops its copy of the connection, leaves the parent's LISTEN session alone, and a child that resumes the EV loop closes its copy before it can read a notification meant for the parent. Core never touches the connection outside the process that opened it; a child that wants notifications itself calls listen and gets its own connection.

METHODS

sql_maker_class

The DBIO::PostgreSQL::SQLMaker subclass used to generate SQL. Shared with the sync driver and the future_io transport, so the maker keeps emitting ? placeholders (translated to $N internally by "_transform_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, as the future_io transport does: nothing given quotes with " and separates with ., an explicit quote_char or name_sep is used as given, and where the sync maker writes identifiers unquoted (quote_names => 0, an empty quote_char) so does this one. A backend without an owning sync storage -- constructed on its own, as DBIO::PostgreSQL::EV::Storage->new(undef) plus "connect_info", not through connect(..., { async => 'ev' }) -- quotes with " and ., the defaults of DBIO::PostgreSQL::Storage: core takes the quoting options out of the connect info it hands a backend.

_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).

future_class

Returns 'DBIO::PostgreSQL::EV::Future': a Future subclass whose get on a pending Future runs the EV loop until it is ready (DBIO::PostgreSQL::EV::Future). That is what makes the inherited blocking methods -- select, insert, txn_do, deploy, ... -- work: each is ->get on its *_async sibling, and a plain Future dies there instead of waiting (ADR 0001). The class reaches every Future such a method waits on: "pool" hands it to the pool, every Future this class settles from an EV::Pg callback is built from it, and Future's combinators keep it. A blocking call works from a script and from inside an EV callback. Inside a callback of one of this transport's own connections -- a then on its Futures, a txn_do coderef -- one that would make EV::Pg deliver the next result on that connection to the wrong callback is refused: it dies with "Blocking wait refused: ..." instead of spinning. So is one that is queued for a pooled connection while the callbacks it runs inside hold every connection of the pool -- $storage->select in a then or a txn_do coderef with pool_size => 1: it dies instead of hanging, and does not run later. A blocking call that is queued for a connection and whose wait is given up on any other way -- refused for a result due on the callback's connection, or the loop running dry -- leaves the queue and does not run later either. Use the *_async methods there ("await" in DBIO::PostgreSQL::EV::Future).

Everything else is Future's own. ->then callbacks auto-wrap a non-Future return value into a resolved Future (ADR 0031 §4), so ResultSet/Row *_async callbacks that return plain values resolve without an explicit Future->done(...) wrap.

transport_capabilities

my @caps = DBIO::PostgreSQL::EV::Storage->transport_capabilities;

Class method (see "transport_capabilities" in DBIO::Storage::Async). Declares the wire capabilities this transport really provides, so "_async_storage" in DBIO::Storage::DBI lets an async extension layer that requires any of them compose onto it (and croaks naming the gap otherwise, rather than silently dropping a feature). This transport provides:

  • on_connect_replay -- its pool (DBIO::PostgreSQL::EV::Pool, a DBIO::Storage::PoolBase) drives core's "_setup_pool_connection" in DBIO::Storage::Async on every freshly-spawned connection, and "_run_pool_connect_statement" replays the owning sync storage's on_connect_do/on_connect_call against it.

  • listen / notify -- the capability names core's LISTEN/NOTIFY gate asks for (core ADR 0056 §2): core's listen, unlisten, listen_alive and listen_reconnect need listen, its notify needs notify. This class fills the listen seams behind them ("LISTEN / NOTIFY").

  • copy -- COPY FROM STDIN bulk load ("copy_in").

  • pipeline -- libpq pipeline mode ("_pipeline_enter" / "_pipeline_sync" / "_pipeline_exit" under the inherited scaffold).

  • broker_connect_options -- read by core, not by layers: the connect options given beside an DBIO::AccessBroker, MyApp::Schema->connect($broker, { async => 'ev', pool_size => 3, ... }), are handed on as [ $broker, \%options ] and applied to every connection this transport opens. pool_size sizes the pool. The DBD attributes are treated as the same keys are in DBI-form connect info: this transport has no DBD, so they are dropped and never reach libpq ("connect_info"). A connection parameter there (sslmode, ...) is neither applied nor dropped: the connect info is refused, and so is a capitalised one (Sslmode). Without the declaration core refuses such a connection at first async use.

connect_info

$storage->connect_info([ \%conninfo, \%opts ]);
$storage->connect_info([ 'dbi:Pg:dbname=app;host=db1', $user, $password, \%attrs ]);
$storage->connect_info([ { dsn => 'dbi:Pg:dbname=app;host=db1', user => $user, password => $password } ]);
$storage->connect_info([ $broker ]);

Set what connections are opened from. The owning sync storage hands this transport the connect info it was given itself, and opens its dbh from the same one -- so every form the owner reads as a connection is read here as that connection, and a pooled connection ends up where the dbh does, as the same user. The forms:

  • The DBI form [ 'dbi:Pg:...', $user, $password, \%attrs, \%extra_attributes ], read as DBI and DBD::Pg read it ("dbi_to_conninfo" in DBIO::PostgreSQL::EV::ConnectInfo): the DSN's parameters, the user and the password become libpq parameters. DBI attributes may stand in front of the DSN (dbi:Pg(RaiseError=>1):...), and DBI's Username and Password attributes are the user and password where they are given. The parameters may be a postgresql:// URI (dbi:Pg:postgresql://app@db1/appdb), read as libpq reads it; a user and password beside it win over its own. Of the attributes otherwise only pool_size is read, and a libpq parameter among them (sslmode, host, ...), spelled in any case, is refused, naming the key and never a value: DBI would take it for an attribute, and the pool would connect without it. pool_size among the DSN's parameters (dbi:Pg:dbname=app;pool_size=3) is refused, naming it: libpq refuses it, so the dbh of the same connect info does not open, and it belongs among the attributes. DBI_USER and DBI_PASS stand for an undefined user and password, as for DBI. dbi:Pg: with nothing behind it is read, as the dbh reads it: libpq fills the rest from its environment.

  • A hash with a dsn key, { dsn => 'dbi:Pg:...', user => $user, password => $password, %attrs }: the DBI form written as a hash, every other key an attribute. A connection parameter beside the dsn (host, sslmode, ...) is such an attribute too, to DBI, and is refused here naming the key (before it, dropped without a word, and both halves connected from the DSN alone). It belongs in the DSN. A dbname that is a whole DSN is the dsn where there is none, as for the owner; a host or port beside it is refused, as the owner refuses it.

  • A hash of libpq connection parameters, { dbname => 'app', host => 'db1', user => $user, password => $password, ... }, this transport's own form: every key is handed to libpq, so any libpq parameter works, except pool_size, which sizes the pool, and what is the owner's by its name -- its own options (async, on_connect_do, quote_names, ...) and DBI attributes, told by their names as below for what stands beside a broker. Those are dropped, as the attributes of the DBI form are; no libpq parameter has such a name -- except in another case: Sslmode is an attribute to DBI and sslmode to libpq, so a key that lower-cased is a libpq parameter ("is_libpq_parameter" in DBIO::PostgreSQL::EV::ConnectInfo) is refused, naming it, not dropped. An undefined parameter is left out; a reference for one is refused.

  • A libpq conninfo string ('host=db1 dbname=app', a postgresql:// URI) in the place of that hash.

  • An AccessBroker, [ $broker ] or [ $broker, \%options ], wired to the per-spawn credential provider (the base broker seam). What the broker answers is read as connect info in the forms above, at attach and for every connection ("_async_broker_conninfo").

A hash or a conninfo string may be followed by an options hashref, [ \%conninfo, \%opts ].

Anything else is refused ("Refusals of the transport"), here and not at the first connection, naming the form it was given -- for an array what kind of thing each element is, for a hash its keys, for a DSN the DBI driver -- and never a value. That includes what the owner connects from and this transport cannot: a connection coderef and a hash with a dbh_maker, which make a DBI handle. Through a schema the refusal comes at the first $schema->storage->async. One reader reads static connect info and a broker's answer (_pg_read_connect_info), so a form is read, or refused, the same from both. Static connect info that names nothing to connect to -- an empty hash, an empty or blank conninfo string, an empty array -- is taken, and handed to libpq as it is, to fill from its environment; a broker's answer that renders to the empty conninfo is refused ("_async_broker_conninfo"). A DBI-form dbi:Pg: DSN is the exception: one that names no dbname, host, port, service or hostaddr (dbi:Pg:, dbi:Pg:sslmode=require) is refused, static and as a broker's answer, with the words of the sync storage and of future_io -- libpq would take the target from PGHOST and PGDATABASE ("dsn_names_target" in DBIO::PostgreSQL::Util).

A call that throws leaves nothing of the connect_info before it: the pool and the listen connection are closed first, as for every call, and the conninfo, pool size and options the earlier call stored are dropped before anything is read. A storage whose static connect info was refused has nothing to connect from; one whose broker could not be attached keeps that broker, with what stood beside it, and nothing of the call before.

No conninfo is kept from a broker's answer, as in core's "connect_info" in DBIO::Storage::Async. The answer is read once here -- to refuse one the transport cannot connect from, and for its pool_size -- and every connection asks the broker again, so a stored copy could only be that first answer, password included. A storage whose broker is detached afterwards has nothing to connect from until connect_info is called again: it does not fall back to what the broker once answered. Static connect info is stored, being all a static connection is opened from.

A broker may come with the connect options the owning sync storage was given beside it, [ $broker, \%options ] -- the form core hands a transport declaring broker_connect_options ("transport_capabilities"). They are read through core's "_access_broker_call_options" in DBIO::Storage::Async, after what the owner applies itself (async, the storage and SQL maker options) is stripped:

  • pool_size sizes the pool. So does a pool_size in the broker's answer -- a key of its hash, or among the attributes of a DBI-form answer, in its fourth or fifth element, the later one winning. Given both in the answer and beside the broker, the two must be the same value, or this throws naming pool_size ("_access_broker_pool_size" in DBIO::Storage::Async). Given nowhere, the pool keeps its default of 5.

  • DBD attributes (pg_enable_utf8, AutoCommit, RaiseError, ...) are dropped, exactly as "dbi_to_conninfo" in DBIO::PostgreSQL::EV::ConnectInfo drops them from DBI-form connect info: there is no DBD on this transport to apply them, and libpq refuses a connection parameter it does not know. They change what the owner's DBI connection does and nothing about a pooled one. "_access_broker_call_attributes" in DBIO::Storage::Async answers what was dropped. What counts as one is told by its name, the way core tells it in a broker's hash answer: a first letter in uppercase, or a start of private_, dbi_, dbd_ or DBD::Pg's pg_ -- unless the name lower-cased is a libpq parameter, Sslmode: that is refused as the next item says. An attribute beside a broker whose answer is a code reference (dbh_maker) is named in the refusal of the answer: the code opens the connection, and nothing beside the broker goes to it.

  • A connection parameter -- any other key set to a value: sslmode, connect_timeout, application_name, ... -- is refused. This throws, naming the parameters and never a value, and says where they belong. Every connection of this transport is opened from the broker's answer alone, so the parameter would not reach one, and sslmode => 'require' beside a broker would leave the pool connecting without TLS and without a word. A lowercase name that is no DBI attribute is refused whether libpq knows it or not; a name with a capital is refused when it is a libpq parameter lower-cased, as told by "is_libpq_parameter" in DBIO::PostgreSQL::EV::ConnectInfo. A key set to undef or the empty string names no parameter. Such a parameter is given in the broker's answer ("_async_broker_conninfo").

The options beside the broker are judged first (the order core uses): where a connection parameter stands beside the broker and the answer is also unusable, or its pool_size differs from the one beside the broker, the refusal above is what is said, before the broker is asked, and the answer's problem only once the parameter is gone.

After that refusal nothing is opened through this storage without the parameter. The broker stays attached, no conninfo is stored -- not the one of a static connect_info before it either -- and every pool connection and every open of the listen connection is refused again, naming the parameters, until connect_info is given connect info without them. With the broker detached there is nothing to connect from. This half-configured state is the intended one: it is the only one in which nothing opens without the parameter, and the same holds after a pool_size that disagrees with the broker's answer -- the broker stays attached, the pool has its default of 5 until the call is made again, and every connection is refused again with the same message.

Through a schema, MyApp::Schema->connect($broker, { async => 'ev', sslmode => ... }), the refusal comes when core builds this transport: at the first $schema->storage->async or *_async call, and at every later one. connect itself goes through: this transport is not there yet to refuse anything. The owning sync storage does not open its dbh without the parameter either: core throws where that storage opens a connection of its own -- at the first use of the dbh and at every reconnect, not at connect -- naming the parameters and that they stand beside the broker. So a caller who never uses the async API is told as well, at the first use of the dbh (t/69-access-broker-parameters-beside-live.t holds both, against a server).

This override (rather than the inherited base connect_info) is retained because the EV transport reads connect info itself: it translates the forms above into libpq conninfo, refuses what it cannot connect from, and applies its own rules to what stands beside a broker. Like the base, it reconfigures through the inherited disconnect when a pool or listen state exists, which shuts the pool down and ends listening -- the listen connection was opened with the outgoing connect info.

_async_broker_conninfo

my $conninfo = $storage->_async_broker_conninfo($mode);
# { dbname => 'app', host => 'db1', port => 5432, user => ..., password => ... }

AccessBroker seam (see "ACCESSBROKER CONSUMPTION" in DBIO::Storage::Async): ask the attached broker for its current connect info -- anew each time, so rotated credentials reach the next connection -- and return it as the libpq conninfo the connection is opened from. Called for every new pool connection (through "_conninfo_provider" in DBIO::Storage::Async) and for every open of the listen connection ("_listen_open"), its first and every reconnect. "connect_info" reads the broker's answer the same way when the broker is attached, where a pool_size in it sizes the pool. All three ask core's "_current_async_connect_info" in DBIO::Storage::Async and read what it returns in one place, so an answer refused at attach is refused for every connection after it, and the other way round (before it the pool spawn and the listen open asked "current_access_broker_connect_info" in DBIO::Storage themselves). Connect options given beside the broker change nothing in the conninfo: the DBD attributes among them never reach libpq. A connection parameter among them stops the connection instead -- this refuses it before the broker is asked, as "connect_info" did when it was given them. The 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 ("dbi_to_conninfo" in DBIO::PostgreSQL::EV::ConnectInfo): the DSN's parameters, the user and the password become libpq parameters, and of the attributes -- \%attrs, a fifth element \%extra_attributes, and DBI attributes in front of the DSN -- only pool_size and DBI's Username and Password are read. The rest -- DBD::Pg attributes, and DBIO's own such as async, which a Vault broker selects this transport with -- never reaches libpq; a libpq parameter among them (sslmode, ...) is refused, naming the key, as it is in static connect info.

  • A hashref with a dsn key, { dsn => 'dbi:Pg:...', user => $user, password => $password, %attrs }: that DBI form written as a hash, as the sync storage reads it, and the answer core names for carrying a libpq parameter to both halves of a schema. Read as the DBI form -- the parameter goes inside the DSN; a key beside the dsn is an attribute. So is a hash whose dbname is a whole DSN.

  • A hashref of libpq connection parameters, as DBIO::AccessBroker::Static answers (dbname, host, port, user, password), and DBIO::AccessBroker::HostBound over it. This transport's own shape: every key is handed to libpq, so any libpq parameter works (sslmode, connect_timeout, ...), except pool_size and the keys that are the sync storage's by their names -- its own options and DBI attributes ("connect_info"). A key that lower-cased is a libpq parameter (Sslmode) is refused, naming it. Undefined ones are left out. A value that is a reference is refused, naming the key. A schema's sync storage opens no dbh from a hash carrying a libpq parameter -- see below.

  • An arrayref holding such a hashref, or a libpq conninfo string ('host=db1 dbname=app ...', a postgresql:// URI), optionally followed by an options hashref -- the [ $conninfo, \%opts ] shape of "connect_info". A conninfo string is an answer for this transport alone: through a schema it takes a broker that answers by the storage that asks -- see below.

These are the forms of "connect_info", read by the same reader. Anything else is refused ("Refusals of the transport"), naming the shape it received -- never the values, which carry the password. That includes a DSN for another driver, a dbi:Pg: DSN libpq could not read the parameters of ("dbi_to_conninfo" in DBIO::PostgreSQL::EV::ConnectInfo), a libpq conninfo string followed by a user and password, which would be dropped, and an answer that makes a DBI handle -- a code reference, a hash with a dbh_maker.

So does an answer in one of these shapes that renders to an empty conninfo: a hash that is empty, or holds nothing but pool_size, or only undefined parameters; a blank conninfo string; a dbi:Pg: DSN that names no parameter, with no user and no password beside it. libpq fills an empty conninfo from its environment and defaults (PGHOST, PGUSER, ...), so the connection would be opened wherever the process environment points, as whoever it names -- not where the broker said. One parameter with a value is enough: which ones a connection needs is libpq's to say. A broker that answers nothing at all -- undef, an empty hash or array -- is refused by core before this method reads the answer, naming the broker class ("current_access_broker_connect_info" in DBIO::Storage).

Refuses ("Refusals of the transport") when no AccessBroker is attached -- one detached with "clear_access_broker" in DBIO::Storage while the per-spawn provider is still in place: core's seam answers what "connect_info" stored then, and that is never what a broker connection is opened from. Nothing is stored from a broker's answer, so there is no earlier answer to fall back to; the refusal says that the broker is gone, where reading the seam's answer would report an unusable answer no broker gave.

A libpq parameter in the answer, through a schema. A schema's broker is asked by two storages: this transport, and the owning sync storage for its dbh. The hash of libpq parameters is this transport's shape only: the sync storage builds dbname, host and port into a DSN and applies no other key of it. Answered to every storage alike, a hash carrying another parameter (sslmode, connect_timeout, application_name, ...) connects the schema, and every connection of this transport -- pooled and listen -- is opened with the parameter. The dbh is not opened without it: core throws where the sync storage opens a connection of its own, at the first use of the dbh and at every reconnect, naming the broker class and the parameters. MyApp::Schema->connect does not throw, and a caller who uses only the async API never meets the refusal: this transport opens its own connections, and the sync storage does not connect for them. With two answers the dbh is opened as well:

  • The DBI form with the parameter in the DSN, [ 'dbi:Pg:dbname=app;host=db1;sslmode=verify-full', $user, $password ], or the same written as a hash, { dsn => 'dbi:Pg:...;sslmode=verify-full', user => $user, password => $password }, one answer for every storage: the dbh and every connection of this transport are opened with it.

  • An answer by the storage that asks ("connect_info_for_storage" in DBIO::AccessBroker): the hash with the parameter for a DBIO::PostgreSQL::EV::Storage, an answer the sync storage takes for every other. The parameter then reaches this transport's connections, and the dbh only if the other answer carries it too.

A libpq conninfo string through a schema has the second way only. The sync storage reads an arrayref as the DBI form, its first element as the DSN, and a conninfo string -- 'host=db1 dbname=app ...', a postgresql:// URI -- names no dbi:Driver:. Answered to every storage alike it connects the schema and every connection of this transport, and the dbh fails where it is first used, with DBI's own error (can't work out what driver to use). So a broker answers a conninfo string to a DBIO::PostgreSQL::EV::Storage only, and the DBI form to every other storage ("connect_info_for_storage" in DBIO::AccessBroker).

The transport given the broker directly, $storage->connect_info([ $broker ]), takes the hash with any libpq parameter as before: no sync storage reads the answer then.

pool

Returns the DBIO::PostgreSQL::EV::Pool connection pool, created lazily on first access. The pool is wired with storage => $self so its core-shared spawn path ("_spawn_connection" in DBIO::Storage::PoolBase) replays the owning sync storage's connect actions on each new connection via "_run_pool_connect_statement". Fed the per-spawn conninfo_provider when an AccessBroker is attached, otherwise the static conninfo string. It gets this storage's "future_class" too, so its acquire, waiter and readiness Futures -- the first link of every query chain -- can be waited on with get.

The pool is built in the slot "disconnect" in DBIO::Storage::Async empties, so calling this is for what begins work: "_query_async", "_notify_send" and "copy_in" ask once, as they acquire, and keep what they got. What ends their work -- the release, the report of a dead connection, the retirement of a COPY's connection -- talks to that pool, the one the connection came from, and never calls this again (core's rule, "pool" in DBIO::Storage::Async). See "_dispatch_query" for when work ends on a storage without a pool.

A forked child leaves the pool's sessions to the parent: its copies of the pooled connections close without touching the parent's sessions, when the child exits as when it resumes the EV loop, and no callback of a statement in flight at fork time runs in the child ("Fork safety" in DBIO::PostgreSQL::EV::Pool).

_conninfo_string

my $str = $storage->_conninfo_string;          # what a new connection gets now
my $str = $storage->_conninfo_string(\%conninfo);

The libpq conninfo string of \%conninfo, or else of what a new connection would be opened from at this moment: the broker's current answer, read by "_async_broker_conninfo", when an AccessBroker is attached, the static conninfo otherwise. undef when there is neither -- no connect info was given yet, or a broker and its provider are gone ("_clear_access_broker" in DBIO::Storage::Async): "connect_info" keeps none of a broker's answer.

_txn_context_class

The pinned-connection transaction context the inherited "txn_do_async" in DBIO::Storage::Async hands to its coderef: DBIO::PostgreSQL::EV::TransactionContext.

_txn_conn_accessor

The constructor key the pinned connection is passed under -- txn_conn, the key core's own DBIO::Storage::Async::TransactionContext constructor requires. Since DBIO::PostgreSQL::EV::TransactionContext became a thin subclass of that class the constructor is core's, so this seam names core's key; the driver-native txn_pg survives as a read accessor, not as a constructor key.

_txn_commit_rolled_back

my $rolled_back = $storage->_txn_commit_rolled_back($pg, @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 the transaction was aborted -- a statement core never saw fail: one in a pipeline batch whose coderef dropped its error, or one sent on the pinned connection past the transaction context. Core then fails the transaction with "COMMIT was answered with ROLLBACK: ...".

The tag is $pg->result_meta->{cmd_status}. The COMMIT's Future cannot carry it: it resolves with EV::Pg's row count, which is '' for COMMIT and for its ROLLBACK answer alike. Reading it here gets the COMMIT's own. Core asks from the success callback of the COMMIT's Future, and "_query_async_pinned" settles that Future inside EV::Pg's callback for the COMMIT's result. EV::Pg points result_meta at a result before it calls that result's callback (0.09 builds the hash when asked) and changes it only when the next result is delivered or the connection is torn down -- neither happens between the start of that callback and core's question. Nothing goes out on the connection behind the COMMIT either: a statement issued after it is refused ("_query_async_pinned"), and sending one would not touch result_meta anyway.

A connection without result_meta -- the stand-in of an offline test -- is taken at its word, core's default.

_txn_inner_future

my $future = $storage->_txn_inner_future($txn_ctx, $conn, $inner_future);

Core transport seam ("_txn_inner_future" in DBIO::Storage::Async), asked once the coderef of a txn_do / txn_do_async has returned and before the transaction chains COMMIT onto its Future. The case it exists for: the coderef returned the Future of a call on the STORAGE -- txn_do(sub { $storage->select_async(...) }) instead of one on $ctx. With a pool of one that call is queued for the connection the transaction holds, and the transaction waits for it: nothing is blocking, so "await" in DBIO::PostgreSQL::EV::Future never sees it, and the transaction stayed open with the pool stuck.

Here the Future is asked "_refuse_queued" in DBIO::PostgreSQL::EV::Future: when it waits for a caller queued for a connection of a pool whose every connection is held by a callback on the call stack -- the BEGIN's callback that runs the coderef is one -- the caller is taken out of the pool's queue and failed with the refusal. The Future then takes core's error path: ROLLBACK, txn_do dies with "Blocking wait refused: ...", the connection goes back to the pool, and the refused call never runs. Then core's default runs (next::method): it refuses every other Future the coderef returned that waits in the queue of the transaction's own pool, also one that a busy connection of a larger pool could still serve -- the transaction is not held for it. A Future that is not queued for the pool is answered unchanged: a call on $ctx, a plain value, a Future of another class, a call that has a connection. The rest of the transaction -- txn_timeout, the retirement of a connection whose ROLLBACK failed, the session reset when the connection goes back -- is core's txn_do_async and not this seam.

_transform_sql

my $positional = $storage->_transform_sql($sql);

Transport-internal SQL shaping (ADR 0032): number every ? placeholder as PostgreSQL's positional $N, left to right, so they line up with the bind values. Called first by "_query_async" and "_query_async_pinned", and by "_run_pool_connect_statement" for a connect action that carries binds.

The reading is "number_placeholders" in DBIO::PostgreSQL::Util and nothing else: a ? is a placeholder where PostgreSQL reads SQL, not inside a string, a quoted identifier, a dollar-quoted body or a comment, nor behind the backslashed quote of an E'' string. Everywhere else it is one, behind an operator character as well, for no operator is known here: the ? of <@?, @@? and ~@? is a placeholder, and @? ? is two, sent as @$1 $2 -- as DBD::Pg reads the same statement at the dbh. $N already there passes through. \? outside such text is a literal question mark: the backslash goes and a bare ? stays in the statement, the way to write the operators ?, ?|, ?& and @? in SQL sent through here (and over the dbh, with DBD::Pg 3.7.1 or later). The SQL maker writes the jsonpath operator that way: its @\? ?::jsonpath is sent as @? $1::jsonpath. A statement that mixes $N and ? placeholders is refused, as DBD::Pg refuses it, in the function's words, which name the mix and not the statement -- a refusal of this transport's that names the caller's place ("Refusals of the transport"); a $N in text and a \? are no placeholder of either style, a ? behind an @ is one. Because the backslash goes, a statement is shaped once: the ? a \? left is a placeholder to a second pass. The rule is kept once, in that function, which the future_io transport answers through as well.

_query_async

Transport seam. Execute a query on a freshly-acquired pooled connection, releasing it once the Future is ready -- to the pool it was acquired from, which "pool" is asked for once, here ("_dispatch_query"). Returns a Future of the raw result rows (list of column arrayrefs for a result set, or the affected-row count for plain DML -- ADR 0031 §3), exactly what the inherited _run_crud expects.

Receives SQL in the sql_maker ?-placeholder dialect and shapes it into PostgreSQL's positional $N internally (via "_transform_sql") before it reaches libpq -- the ADR 0032 seam contract.

$bind_attrs is optional (bind attribute hashes parallel to $bind, none for a raw statement) and goes to the statement trace only; the binds stay bare values on the wire. The trace is core's "_debug_query" in DBIO::Storage::Async; the transport has none of its own.

The Future returned holds itself until it is ready: Future.pm holds a then sequence only weakly from the Future waiting on a full pool, so a caller that drops it would take the chain, and the connection it borrows, with it. The same goes for "_notify_send", "copy_in" and "deploy_async".

_dispatch_query

my $future = $storage->_dispatch_query($pg, $sql, $bind, $pool, $lease);

Dispatch a $N-dialect query on the given connection and return a Future completed by libpq's completion callback. Releases the connection back to $pool, the pool it was acquired from, once the Future is ready (the pooled "_query_async" path). Croaks without $pool, before anything is sent.

$lease is the lease of the borrow, $pool->_lease($pg) taken right after the acquire ("_lease" in DBIO::Storage::PoolBase), and every release of $pg here -- the completion's and the refused dispatch's -- passes it. A completion that fires a second time, when $pg has been handed on or borrowed again, then releases nothing instead of taking the connection from its new holder. Without it, the release is what it always was.

The connection goes back to the pool it came from, not to "pool" asked again when the statement ends. The Future is settled before the connection is released, so the caller's callbacks run first, and one of them may disconnect the storage -- a then, on_done or failure handler that calls disconnect, or a connect_info that reconfigures it. EV::Pg does not call the callback it is delivering to again when the connection is finished under it, so the release that follows finds the storage without a pool, and does not ask "pool" to build one: $pool is shut down by then and takes the release, and the report of a dead connection before it, as no-ops; the storage stays without a pool until the next call builds one. The same holds for "_dispatch_notify" and "copy_in". A disconnect from outside, with the statement on the server, never showed this: EV::Pg calls the statement's callback from inside finish, while the pool being shut down is still the storage's (measured against PostgreSQL 18 with EV::Pg 0.09, t/76-completion-same-pool-live.t).

Named sub, deliberately not a closure inside the ->then(sub {...}) acquire chain: the completion callback is created HERE, in a sub whose pad dies when this sub returns, so the bind arrayref lives only until dispatch, not for the whole flight of the query. The ->then closure only calls this and is freed once acquire resolves -- a callback created inside it would be retained by libpq for the flight and would pin that closure's pad (and $bind) alive.

The Future is of "future_class", and the callback marks $pg as delivering for as long as it runs -- the then callbacks on the Future run inside it -- so "await" in DBIO::PostgreSQL::EV::Future can refuse a blocking wait there that would make EV::Pg deliver the next result on $pg to the wrong callback. Every callback this class hands to EV::Pg to settle one of its Futures does the same: "_query_async_pinned", "_pipeline_sync", "_dispatch_notify", "copy_in", and the LISTEN / UNLISTEN of "_listen_subscribe" / "_listen_unsubscribe".

The callback settles the Future before it releases the connection, so the then callbacks run while $pg is still checked out -- a call they make gets another connection, never the one whose result is being delivered ("await" in DBIO::PostgreSQL::EV::Future) -- and the release runs inside the delivery frame. A blocking call there for which the pool has no other connection, and none that can come back while the callback runs, is refused rather than left to wait for $pg; a blocking call that is queued for it and given up on for another reason does not run when $pg is released either. It runs however the settling ends: an on_done, on_ready or on_fail callback on the Future that dies escapes done / fail -- Future catches a die only in then and its siblings -- so the settling runs in eval, the connection is released, and the die is rethrown to EV::Pg, which warns it. The Future keeps its own result or error.

A query EV::Pg refuses at dispatch fails the Future with EV::Pg's own error, and the connection goes back to the pool right there. EV::Pg croaks before it queues the callback -- "not connected" on a connection it has lost, "PQsendQueryParams failed: another command is already in progress" on a busy one -- so the callback never runs and this is the connection's only release.

A connection that failed because it is gone is not reused: it is retired when it is handed back, and the next call gets a freshly spawned connection. Gone means EV::Pg no longer reports it connected after the failure -- see "_pg_report_if_dead" for why that, rather than the error message, is what tells the two apart. A statement error the session survives (a syntax error, a constraint violation, a busy connection's refusal) leaves the connection in the pool. Usually the pool already knows by then: EV::Pg reports a lost connection through its on_error before it fails the statements queued on it ("_new_connection" in DBIO::PostgreSQL::EV::Pool); this covers the connection that went without it -- one a caller closed with finish, or whose on_error a caller replaced.

Every callback this class hands to EV::Pg returns at once in a process other than the one that issued its statement. A forked child that resumes the EV loop closes its copies of the pooled connections ("Fork safety" in DBIO::PostgreSQL::EV::Pool), and EV::Pg calls back every statement in flight with a "connection finished" error; the child must not answer that with a release into the pool, a settled Future or the caller's callbacks -- they all belong to the parent. The Future stays pending in the child.

_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 "Refusals of the transport") -- as a DBIO::Exception, the way core throws its own: Some::method(): $message at FILE line N, where the place is the caller's. 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 EV, 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 callback of the caller's names the line in it that called into the transport; a callback of the transport's own (a LISTEN once the listen connection is up) names where the caller ran the loop -- the ->get of a Future of "future_class", or the caller's EV::run.

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 connect info holds is masked where a frame repeats it, as a password among the arguments of a frame always is.

_pg_server_error

my $error = $storage->_pg_server_error($pg, $text);
my $error = $storage->_pg_server_error($pg, $text, \@values);

What a statement's callback fails its Future with: the DBIO::Exception::Server for $text when the server refused the statement, else $text as it came, masked (below). Called inside the callback of the statement -- only there, where EV::Pg has just set error_fields for an error result and for nothing else. \@values are the plain values bound to the statement (_pg_error_values); the callbacks of "_dispatch_query", "_query_async_pinned" (also in a pipeline) and "_dispatch_notify" hold a copy of them for the statement's flight, no more.

$text is the server's when $pg->error_fields has a severity and a primary and the text begins with them, as libpq renders an error: SEVERITY: primary, with sqlstate: between the two in verbose mode. The text of a lost connection, an aborted pipeline, a finished connection, an empty query or EV::Pg's own croak begins with none of that, and stays a string, although error_fields may still hold the last server error (a successful statement does not clear it).

An error message names keys and columns, never values, whether or not it is the server's and whether or not the connection can answer error_fields: the text passes "_pg_mask_error_text" -- the bound values wherever they stand, then the values the server quotes in the forms of its messages ("mask_error_details" in DBIO::PostgreSQL::Util) -- and the object's message is that text. detail is the server's detail field with the same net and the values of its forms masked ("mask_detail_values" in DBIO::PostgreSQL::Util), so a unique violation reads Key (name)=(***) already exists., as on the synchronous storage and on future_io. A text of no known form is not changed.

The SQLSTATE of $pg->error_fields goes to both maskings when $text is the server's: the forms of the messages are then found in whatever language the server reports in. A text that is not the server's is masked by the English forms alone, as no state belongs to it.

Only a plain string is looked at: an object and undef pass unchanged.

_pg_mask_error_text

my $text = $storage->_pg_mask_error_text($text, \@values);
my $text = $storage->_pg_mask_error_text($text, \@values, $sqlstate);

The text of an error with the values taken out, for every text of the server's or libpq's that reaches an exception or a failed Future: the values bound to the statement (each of four characters or more, wherever it stands -- "mask_bound_values" in DBIO::Util, the net of core's "_mask_error_values" in DBIO::Storage::DBI), then the values the server quotes in the forms of its messages ("mask_error_details" in DBIO::PostgreSQL::Util). \@values is optional. $sqlstate is the SQLSTATE of the server's error, when the caller knows it ("_pg_server_error" reads it from error_fields for a text that is the server's): with it the forms are found in any language the server reports in (lc_messages), without it only the English ones. A text of no known form, undef and a reference come back as they are, a text already masked comes back unchanged, and it never dies. The text of a statement without binds -- the DISCARD ALL of the session reset, a LISTEN -- passes it too.

_pg_report_if_dead

$storage->_pg_report_if_dead($pool, $pg);

Called after a statement on the pooled connection $pg failed, or EV::Pg refused to dispatch it, and before $pg goes back to the pool: when EV::Pg no longer reports $pg connected, tell the pool it is dead ("_mark_connection_dead" in DBIO::Storage::PoolBase), so the release retires it instead of idling it. $pool is the pool $pg was acquired from, the one its release goes to -- not "pool" asked at this moment (see "_dispatch_query").

The error message does not decide, EV::Pg's own view of the connection does. EV::Pg tears a connection down on every connection-level error -- the server ended the session, the socket broke, the protocol went out of step -- before it fails the statements queued on it ("connection lost"); from then on is_connected is false and a dispatch croaks "not connected". A statement error the session survives, and the refusal of a busy connection ("another command is already in progress"), leave it true. finish is the one call that fails the queued statements ("connection finished") before it closes the connection, so a statement in flight on a connection someone finishes is not reported, and the connection goes back to the pool. EV::Pg 0.09 behaves so (measured). Harmless when the pool already knows: the report may be made any number of times.

A connection that sits idle and is not connected any more does not get as far as a dispatch: the pool asks EV::Pg, and looks at the socket, before it hands an idle connection out ("_idle_connection_alive" in DBIO::PostgreSQL::EV::Pool). The dispatch's croak is the only report left where the pool asks nothing: a connection handed straight from a release to a queued caller, and one that is lost after the pool has looked.

_reset_pool_connection

my $future = $storage->_reset_pool_connection($pg);

Core's session-reset seam ("_reset_pool_connection" in DBIO::Storage::Async, ADR 0079), asked by "release" in DBIO::Storage::PoolBase when a borrow ends. Every borrow of a pooled connection has a session of its own: DISCARD ALL goes out on $pg and, once the server has answered it, the connect actions run again ("_setup_pool_connection" in DBIO::Storage::Async: the connection's search_path and extension LOAD, on_connect_do, on_connect_call). The pool hands the connection to the next borrower when the returned Future is done, and retires it when the Future fails.

DISCARD ALL ends what 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. There is no way to switch the reset off, and nothing else in this class resets: a statement, a transaction after its COMMIT or ROLLBACK, a pipeline and a copy_in all end in release, and the reset is the pool's.

The statement is sent bare (Simple Query protocol, no binds) on exactly this connection, outside the transaction queue of the pinned path. It runs in no transaction block, which DISCARD ALL requires: a transaction has ended with its COMMIT or ROLLBACK before the borrow does. The connect actions run from an EV timer once the answer has been delivered, not inside that callback: they drive the EV loop, which EV::Pg does not take inside a callback of the connection they run on. The Future fails with a message that names the step -- the reset or the connect actions -- and carries no statement text, bind or connection parameter.

_query_async_pinned

Transport seam. Like "_query_async" but runs on the supplied pinned connection and does not release it -- used for queries inside a pinned transaction, and by core's DDL runner and pipeline context. Shapes the incoming ?-dialect SQL internally via "_transform_sql" exactly as "_query_async" does. It takes the optional $bind_attrs of "_query_async" and hands it to the trace ("_debug_query" in DBIO::Storage::Async) alone.

One statement at a time. Outside pipeline mode libpq runs one statement at a time on a connection, and EV::Pg refuses a second while the first is in flight -- it croaks "PQsendQueryParams failed: another command is already in progress". A statement issued on a connection while one of this method's statements is in flight there therefore waits in that connection's queue, and is sent once the one before it has its result, in the order they were issued. The next one is sent from the completion callback before that callback settles its Future, so a statement a then callback issues queues behind the ones already waiting.

That is what makes a txn_do coderef roll back cleanly when it dies while one of its statements is in flight -- after $ctx->insert_async(...), or when a blocking $ctx method is refused ("await" in DBIO::PostgreSQL::EV::Future): core's ROLLBACK waits for that statement's result, then runs, the transaction fails with the coderef's own error, and the connection goes back to the pool IDLE. Two *_async calls on the context that are not chained both run, in order (core waits for both before COMMIT, see DBIO::PostgreSQL::EV::TransactionContext).

Nothing after the end. Once core's COMMIT or ROLLBACK has been issued on the connection, a further statement issued on it before that has run is refused: its Future fails at once and it is never sent. Queued behind the COMMIT or ROLLBACK it would be sent from that statement's completion callback, so it would run after the transaction, outside of it -- a write committed on its own after a rollback -- and still be in flight when core hands the connection back to the pool, where the next caller's statement would be refused. Only a statement the coderef did not chain into the Future it returns can get there, from a then on a statement still in flight.

A statement issued on the transaction context does not get this far: core ends the context as it sends COMMIT or ROLLBACK, and the context refuses the statement itself, synchronously ("transaction context is no longer active"). This refusal is left for the connection reached past the context -- $ctx->txn_conn handed to this method directly, the way core's deploy_async runs its DDL -- which core does not see.

Pipeline mode is left alone: between "_pipeline_enter" and "_pipeline_exit" libpq takes any number of statements, and each is sent at once, to be batched. Behind the pipeline's sync point it is not: the server answers a statement sent in pipeline mode only once a sync point follows it, so one sent there would never be answered. That is what a transaction's ROLLBACK is when its coderef ended with $ctx->pipeline still waiting for its sync. Such a statement waits, in order, until "_pipeline_exit" has left pipeline mode, and is sent then like any pinned statement; when the exit is refused it fails with the exit's error.

A statement EV::Pg refuses at dispatch -- "not connected" on a connection it has lost, say -- fails its Future with EV::Pg's own error, whether it was sent at once or from the queue, and the statements queued behind it are still sent. The statement's callback returns at once in a process other than the one that issued it, as every callback of this class does.

_run_pool_connect_statement

$storage->_run_pool_connect_statement($conn, $sql, $attrs, @bind);

Native-backend override of the core connect-action runner seam ("_run_pool_connect_statement" in DBIO::Storage::Async). The base default drives a blocking DBI do and croaks on a non-DBI connection; an EV::Pg handle is neither a { dbh => $dbh } wrapper nor a do-capable DBI handle, so this override drives the statement synchronously to completion on that very connection over the EV loop.

Called once per freshly-spawned pool connection from "_setup_pool_connection" in DBIO::Storage::Async, so the owning sync storage's on_connect_do / on_connect_call (including connect_call_* methods such as an extension's connect_call_load_age) replay on every new EV pool connection, identical to the future_io pool. The freshly-spawned EV::Pg handle may still be mid-connect, so we first drive the loop until it is up, then run the statement and drive the loop until it completes. $attrs (the DBI attribute hashref) has no EV::Pg analogue and is ignored, except for the reserved key dbio_rows: when it is true the method returns the rows of the statement as an array reference of row array references (values as EV::Pg delivers them, SQL NULL as undef; an empty array reference for a statement that answers no rows), as the core default does with selectall_arrayref. Without it the method returns nothing.

Refused inside a delivery. Core spawns a pool connection synchronously, from acquire, whenever the pool has room and no idle connection, so a *_async call made inside a then callback or a txn_do coderef can bring a connection up right there -- and this replay then runs the EV loop inside that callback. Inside a callback of one of this transport's own connections that has more results due -- a txn_do coderef that has already sent a $ctx statement, a then on a statement of a pipeline batch -- EV::Pg would hand the next of those results to the callback that is still running and then spin, exactly the wait "await" in DBIO::PostgreSQL::EV::Future refuses. Measured against PostgreSQL 18.6 with a coderef that sent $ctx->_query_async and then a pool call that spawned: EV::Pg reported "exception in callback: ... is already done and cannot be ->done" and the process spun at 100% CPU until it was killed. So the replay refuses the same wait, on entry and before every iteration, and dies with "Blocking wait refused: ...". The pool retires the half-opened connection, and the call that asked for it fails its Future with an error carrying the refusal (DBIO::Storage::PoolBase turns a spawn that dies into a failed acquire); measured the same way, it fails at once and the pool is left idle. Chain that call with then onto the statement in flight, or run it on the transaction context. An on_disconnect_do / on_disconnect_call run at pool shutdown goes through here too; core runs those best-effort, so a refused one is skipped.

The connection is marked as being opened while this runs ("_replaying" in DBIO::PostgreSQL::EV::Future). The pool counts it by now, it is not idle, and no callback of this transport is being delivered for it -- yet it is handed out only once the spawn has returned, and whatever the loop runs meanwhile runs above the spawn on the call stack. A blocking call on the storage made there, by a timer of the application, say, is queued for that connection in a pool of one and could never be served; the mark is how "_pg_held_by_callbacks" in DBIO::PostgreSQL::EV::Pool knows, and "await" in DBIO::PostgreSQL::EV::Future refuses the wait. Without it the wait hung, or died of a loop that had run dry (measured against PostgreSQL 18.6, t/78-blocking-behind-spawn-live.t).

_pipeline_enter

Open libpq pipeline mode on the connection, and note it: until "_pipeline_exit", "_query_async_pinned" sends every statement on it at once instead of queueing it behind the one in flight.

_pipeline_sync

Flush the batched queries and resolve once the pipeline sync point has been acknowledged. EV::Pg's pipeline_sync takes a completion callback; we adapt it to the Future the inherited scaffold expects.

EV::Pg calls that callback with (1) when the server acknowledged the sync point, and with (undef, $error) when the batch never got there. The Future is done in the first case only; in the second it fails with EV::Pg's own message, and the scaffold fails the whole pipeline with it. The error comes two ways (measured with EV::Pg 0.09):

  • The connection goes with the sync still pending: "connection lost" when EV::Pg loses it, "connection finished" when it is closed. Losing it is what happens when the backend dies during the batch -- its statements fail first, then the sync (measured against PostgreSQL 18.6).

  • An error result arrives while the sync is the next thing EV::Pg waits for, as the server's "FATAL: terminating connection due to administrator command" does on a batch without statements. EV::Pg keeps the sync callback at the head of its queue after that and calls it again with "connection lost" once the connection goes. The Future settles on the first call, and later ones return without touching it.

_pipeline_exit

Close libpq pipeline mode on the connection. When EV::Pg refuses, the connection stays in pipeline mode, and noted as such for "_query_async_pinned" (core retires it).

_listen_open

my $f = $storage->_listen_open;   # done with the listen connection

Core listen seam ("_listen_open" in DBIO::Storage::Async): open the dedicated listen connection -- a new EV::Pg handle, never one from the pool -- and resolve once it is connected; a connect that fails fails the Future with EV::Pg's message. Its conninfo 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 to every reconnect exactly as they do to the pool (ADR 0009), otherwise _conninfo_string. The pool's connect-action replay ("_run_pool_connect_statement") does 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.

The handle is built by "_new_connection" in DBIO::PostgreSQL::EV::Pool, the constructor of every pooled connection, so it closes fork-safe like them ("Fork safety" in DBIO::PostgreSQL::EV::Pool): a forked child that exits or drops its copy leaves the parent's LISTEN session alone, and a child that resumes the EV loop closes its copy before it can read the parent's notifications.

It is opened with keep_alive, so EV::run keeps running while the connection is open, and its on_connect, on_error and on_notify are set at once: a notification that arrives before watching starts is held for "_listen_watch", and a connection-level error after the connect goes to "_listen_lost" in DBIO::Storage::Async. Refuses ("Refusals of the transport") when the storage has no connect info.

_listen_close

$storage->_listen_close($conn);

Core listen seam ("_listen_close" in DBIO::Storage::Async): clear the handle's handlers, so nothing it reports reaches core any more, and finish it. A dead connection is fine -- EV::Pg's finish does not fail on one -- and a connection already closed is left alone. A LISTEN or UNLISTEN still in flight fails its Future with EV::Pg's "connection finished". Core has stopped the watch first whenever it started it ("_listen_unwatch"), and never calls this in a process other than the opener.

_listen_subscribe

my $f = $storage->_listen_subscribe($conn, $channel);

Core listen seam ("_listen_subscribe" in DBIO::Storage::Async): send LISTEN "channel" on the listen connection and resolve once the server has answered; fail with the server's error otherwise. The channel is validated and quoted as one identifier ("_pg_quote_channel"), never interpolated raw (ADR 0017 §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 Future with the reason.

A LISTEN EV::Pg refuses at dispatch -- it croaks before it queues the callback, "not connected" on a connection it has lost, "another command is already in progress" on a busy one -- fails the Future with EV::Pg's own error. Core then probes the connection and heals or reports. Core's queue never has two channel operations in flight on the connection, so the second case does not arise from here.

_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 failure handling as "_listen_subscribe". Core has already dropped the channel from its registry, so a notification for it that is still on its way is not dispatched.

_pg_quote_channel

my $sql_ident = $storage->_pg_quote_channel($channel);   # "jobs"

Validate a channel name and quote it as one PostgreSQL identifier: wrapped in double quotes, embedded " doubled. Quoting makes the name exact -- case included -- which is also how pg_notify ("_notify_send") takes it, so listen('Jobs') and notify('Jobs') meet. A . stays part of the name: app.events becomes "app.events", not "app"."events".

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, the one implementation the future_io transport shares; 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_watch

$storage->_listen_watch($conn);

Core listen seam ("_listen_watch" in DBIO::Storage::Async), socket-driven: the EV loop already watches the connection's socket -- EV::Pg's read watcher -- so starting to watch switches what its handlers do. From now on every notification EV::Pg's on_notify reports goes to "_listen_dispatch" in DBIO::Storage::Async, in arrival order, and a connection-level error its on_error reports (the server closed the connection, a protocol error) goes to "_listen_lost" in DBIO::Storage::Async.

First it delivers the notifications that arrived after the connect and before this call -- while core subscribed the channels one by one -- in the order they arrived. EV::Pg 0.09 discards a notification when no on_notify is set (measured), so on_notify is set from the open on and holds them until here. A channel callback that ends the connection (unlistening the last channel, listen_reconnect) stops that delivery there.

Throws, which core counts as a dead connection, when the handle is gone or EV::Pg does not report it connected.

_listen_unwatch

$storage->_listen_unwatch($conn);

Core listen seam ("_listen_unwatch" in DBIO::Storage::Async): clear the handle's on_notify, on_error and on_connect and drop what is held, so no "_listen_dispatch" in DBIO::Storage::Async or "_listen_lost" in DBIO::Storage::Async for $conn follows. Core closes the connection right after ("_listen_close").

_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 LISTEN / UNLISTEN: EV::Pg's is_connected -- the handle exists, its connect has completed and libpq reports CONNECTION_OK -- and the look the pool takes at an idle connection ("_pg_peer_closed" in DBIO::PostgreSQL::EV::Pool): the server's end of the socket is not closed. Synchronous, without a round trip, nothing sent, nothing read, no loop run. EV::Pg keeps reporting the handle connected until the loop has read the close, so without the second look a program that only blocks was told a session was alive that pg_terminate_backend had ended; the loop reports it through on_error as soon as it runs, as before. Not seen: a peer that vanished without closing, and the milliseconds between a backend's last message and its exit. The future_io transport pings instead; a synchronous ping here would have to run the EV loop from inside listen_alive.

_listen_delay

my $f = $storage->_listen_delay($seconds);

Core listen seam ("_listen_delay" in DBIO::Storage::Async): the reconnect backoff, an "timer" in EV settling a "future_class" Future from the EV loop. The timer lives until it fires or the Future is cancelled, which core does when a wait is cut short (listen_reconnect, disconnect), and which stops it. The wait counts from the call: the loop's cached time is brought up to date first, so work that kept the loop from running does not shorten the delay.

_notify_send

my $f = $storage->_notify_send($channel, $payload);

Core listen seam ("_notify_send" in DBIO::Storage::Async), behind core's notify: acquire a pooled connection -- sending needs no listen connection (ADR 0003) -- and run SELECT pg_notify($1, $2) on it through "_dispatch_notify", channel and payload bound, never interpolated. An undef payload is sent as ''; PostgreSQL has no NULL payload. Resolves void once the server has answered. Core has already refused a missing channel; a channel over 63 bytes or a payload of 8000 bytes or more fails the Future with the server's error.

_dispatch_notify

my $future = $storage->_dispatch_notify($pg, $channel, $payload, $pool, $lease);

Dispatch a pg_notify on the given connection and return a Future completed by libpq's completion callback. Releases the connection back to $pool, the pool it was acquired from, once the Future is ready (the pooled "_notify_send" path behind core's notify) -- never to "pool" asked again, so a then on a notify that disconnects the storage leaves it without a pool (see "_dispatch_query"). Croaks without $pool, before anything is sent. $lease is the lease of the borrow, passed to every release as in "_dispatch_query".

Named sub, deliberately not a closure inside the ->then(sub {...}) acquire chain: the completion callback is created HERE, in a sub whose pad dies when this sub returns, so the freshly-built bind arrayref lives only until dispatch, not for the whole flight of the query -- the same ADR 0044 dispatch pattern as "_dispatch_query". The ->then closure only calls this and is freed once acquire resolves.

Resolves void -- $f->done with no arguments, a pure completion signal. Unlike "_dispatch_query" it deliberately does not pass the pg_notify result row through; the caller of notify only waits for the NOTIFY to be dispatched.

The completion callback settles the Future before it releases the connection, as in "_dispatch_query": a then callback on the Future runs while the connection is still checked out, so a call it makes gets another connection, never the one whose result EV::Pg is still delivering; and an on_done, on_ready or on_fail on it that dies does not keep the connection from going back. A blocking call in such a then never gets that very connection ("await" in DBIO::PostgreSQL::EV::Future).

A NOTIFY EV::Pg refuses at dispatch fails the Future with EV::Pg's own error and releases the connection at once, as in "_dispatch_query". Either way, a connection that failed because it is gone is retired rather than reused, as in "_dispatch_query".

copy_in

$storage->copy_in($table, \@columns, sub {
    my ($put) = @_;
    $put->(['Miles Davis', 'Jazz']);
    $put->(['John Coltrane', 'Jazz']);
});

Bulk load data via PostgreSQL COPY FROM STDIN. The callback receives a writer function that accepts arrayrefs of column values. Transport value-add: overrides the base's croaking default (declared as the copy capability).

Values are given as they are and arrive as they are. The writer writes each by PostgreSQL's COPY text-format rules: a backslash as \\, a TAB as \t, a line feed as \n and a carriage return as \r, so a value never ends its field or its row, and the two characters \N in a value stay those two characters. undef is SQL NULL; the empty string is the empty string. There is no CSV mode, and a value needs no escaping on the caller's side.

Names: $table is a table name, schema.table for a qualified one, and each entry of \@columns one column name, written as identifiers by the server's rule ("quote_ident" in DBIO::PostgreSQL::Util): bare when plain lower case and no key word, double-quoted otherwise, whatever the schema's quote_names says. A dot in $table separates schema and table, each part its own identifier.

The returned Future settles, and the pooled connection is handed back to the pool exactly once, however the COPY ends -- also when EV::Pg refuses the COPY command at dispatch (it croaks before it queues the callback, with "not connected" or "another command is already in progress"), and when it loses the connection during the COPY (it then drops the callback without its second firing, and the writer and put_copy_end croak "not connected"). The Future fails with the callback's own error if the callback died, whatever became of the stream after that; else with what ended the COPY -- the server's error, EV::Pg's ("not connected", "connection lost"), or "put_copy_end failed: " and libpq's reason.

The writer dies when it cannot put its row. EV::Pg croaks "not connected" once it has lost the connection, and the COPY fails whatever the callback does about that. A put_copy_data that answers 0 -- libpq could not make room for the row in its output buffer -- or -1 is the end of the COPY as well, whether the callback lets the writer's die through or catches it: the writer dies for every further row, the COPY is aborted, and the Future fails with the writer's error, "put_copy_data failed: " and libpq's reason, unless the callback goes on to die of something else. A COPY does not complete without a row it was given. The writer is good while the callback runs: called after that it is refused ("Refusals of the transport"), its connection being the pool's again, or in the middle of another caller's COPY.

The callback runs to its end before the EV loop does anything else. What the server has not read by then waits in libpq's output buffer, in this process -- with a server that reads more slowly than the callback writes, most of the stream. libpq lets that buffer grow as long as it can get the memory, and put_copy_data answers 0 once it cannot.

How the COPY ends decides what becomes of its connection. A COPY the server has answered -- done, failed or refused -- leaves the connection ready for the next statement, and it goes back to the pool; one that failed because the connection is gone is retired on the way, as in "_dispatch_query". A COPY that ends with its stream still open is retired in any case ("_mark_connection_dead" in DBIO::Storage::PoolBase), and the next call gets a fresh connection. That is a put_copy_end that

  • answered -1. EV::Pg does no more about it than hand libpq's -1 on (EV::Pg 0.09, Pg.xs). Where libpq could not queue the end of the stream it is still in the COPY, on an open connection, and refuses every statement with "another command is already in progress"; nothing is left to end the COPY with. Where libpq met the end of the connection, EV::Pg has not heard of it.

  • croaked "not connected": EV::Pg lost the connection during the COPY.

  • answered 1 on a connection that is gone. libpq had dropped it in an earlier write, and EV::Pg learns of that in the flush behind put_copy_end, where it drops the callback it is delivering to without calling it again. So is_connected is asked right after put_copy_end, and the COPY ends there with "connection lost" rather than wait for an answer that cannot come.

Wherever the COPY ends inside EV::Pg's callback, the Future is settled before the connection goes back, as in "_dispatch_query": a then callback on the returned Future runs while the connection is still checked out, so a call it makes gets another connection, never the one whose result EV::Pg is still delivering; and an on_done, on_ready or on_fail on it that dies does not keep the connection from going back. A COPY EV::Pg refuses at dispatch -- no callback, so nothing is being delivered on the connection -- goes back before its Future fails, as in "_dispatch_query".

A call of the callback that comes after the COPY has ended returns without touching the Future or the pool, as a late call does in "_pipeline_sync". EV::Pg keeps the callback queued after a put_copy_end that answered -1, to call it again whenever it reads from the connection while libpq has the COPY open, and when the connection goes. Retiring the connection closes it inside the callback's own delivery, and there EV::Pg 0.09 drops the callback instead (measured).

The connection goes back to the pool it was acquired from, however the COPY ends -- released, reported dead or retired there, never at "pool" asked again (see "_dispatch_query"). The callback runs inside the COPY's delivery, and so do the callbacks on the returned Future: when one of them disconnects the storage, the COPY ends on a storage without a pool, and that pool is shut down, where all three are no-ops. A callback that disconnects the storage ends its own COPY: the connection is finished under the stream, the writer and put_copy_end croak "not connected", the Future fails with that, and the server loads nothing. The COPY's end builds no new pool on the disconnected storage.

The connection's lease is taken right after the acquire ("_lease" in DBIO::Storage::PoolBase) and every release of it passes the lease, so a release that arrives once the connection has been handed on takes nothing (see "_dispatch_query").

_ddl_class

The install-DDL generator the inherited "deploy_async" in DBIO::Storage::Async resolves through "_install_ddl" in DBIO::Storage::Async: DBIO::PostgreSQL::DDL -- the same class the sync $schema->pg_install_ddl path uses ("pg_install_ddl" in DBIO::PostgreSQL), so async and sync deploy emit byte-identical DDL.

The DDL batch runs inside a single async transaction, not statement-at-a-time: the sync DBIO::PostgreSQL::Storage declares _use_transactional_ddl(1) (PostgreSQL's DDL is transactional), so the inherited deploy_async probes that capability on the owning sync storage ("_owner_storage" in DBIO::Storage::Async) and takes its txn_do_async branch -- a failure on statement N of M rolls back the preceding N-1, matching today's behaviour. That branch calls $ctx->txn_conn, which DBIO::PostgreSQL::EV::TransactionContext answers because it inherits it from core's generic context; the native txn_pg is the alias on top of it, not the other way round.

deploy_async

my $future = $storage->deploy_async($schema, \%opts);

Core's "deploy_async" in DBIO::Storage::Async, behind one question to the server (as for future_io). 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.

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.