NAME
DBIO::PostgreSQL::EV - Async PostgreSQL storage for DBIO via EV::Pg
VERSION
version 0.900007
SYNOPSIS
package MyApp::Schema::Result::Artist;
use base 'DBIO::Core';
__PACKAGE__->table('artist');
__PACKAGE__->add_columns(
id => { data_type => 'integer', is_auto_increment => 1 },
name => { data_type => 'text' },
);
__PACKAGE__->set_primary_key('id');
package MyApp::Schema;
use DBIO 'Schema', -pg; # the schema declares its driver
__PACKAGE__->register_class(Artist => 'MyApp::Schema::Result::Artist');
package main;
# A dbi:Pg: DSN for the PostgreSQL driver, { async => 'ev' } this
# distribution's transport for everything async.
my $schema = MyApp::Schema->connect(
'dbi:Pg:dbname=myapp;host=localhost', $user, $pass,
{ async => 'ev' },
);
my $artists = $schema->resultset('Artist');
# Sync calls run over DBI / DBD::Pg, as on any other connection
my @all = $artists->all;
# *_async calls run over EV::Pg and return Futures
my @nina = $artists->create_async({ name => 'Nina Simone' })
->then(sub { $artists->search({ name => 'Nina Simone' })->all_async })
->get; # get waits by running the EV loop
# LISTEN/NOTIFY, COPY and pipeline mode are called on the transport
my $async = $schema->storage->async; # the DBIO::PostgreSQL::EV::Storage
$async->listen(artists => sub {
my ($channel, $payload, $sender_pid) = @_;
...
})->get;
$async->notify(artists => 'changed')->get;
$async->copy_in('artist', [qw( name )], sub {
my ($put) = @_;
$put->([ $_ ]) for 'Miles Davis', 'John Coltrane'; # values as they are;
})->get; # undef is NULL
my $source = $schema->source('Artist');
my @rows = $async->pipeline(sub {
my ($batch) = @_; # a batch context, not the storage
$batch->future_class->needs_all(
map { $batch->insert_async($source, { name => $_ }) }
'Billie Holiday', 'Ella Fitzgerald'
);
})->get; # one returned-columns hashref each
DESCRIPTION
This distribution is the native ev async transport for PostgreSQL. It speaks libpq's asynchronous protocol through EV::Pg -- no DBI, no DBD::Pg -- and answers every async call with a Future. This page is its map: "OVERVIEW" says in a few lines what each part does and links to the module that documents it.
Activating the ev mode
Async is chosen per connection (core ADR 0030): a schema that declares the PostgreSQL driver connects with an ordinary dbi:Pg: DSN and { async => 'ev' }, as in the "SYNOPSIS". The schema declares its driver (core ADR 0067) with use DBIO 'Schema', -pg or the DBIO::PostgreSQL component; both pin DBIO::PostgreSQL::Storage, the sync driver, and that driver registers the ev mode with register_async_mode( ev => 'DBIO::PostgreSQL::EV::Storage' ). Core resolves the mode on the storage, so nothing else in the schema class takes part in choosing the transport, and no component of this distribution is loaded. A schema that declares no driver is refused at connect.
$schema->storage stays the sync storage, with the transport embedded in it. Sync calls run over DBI / DBD::Pg; the *_async methods of the storage, of ResultSets and of rows run over EV::Pg against the same connection info, which the transport translates into libpq conninfo (DBIO::PostgreSQL::EV::ConnectInfo). What only this transport offers -- LISTEN/NOTIFY, COPY, pipeline mode -- is called on $schema->storage->async. The pool_size connect attribute sizes its connection pool (default 5), and the on_connect_do / on_connect_call actions are replayed on every pooled connection.
Nothing degrades. Without the option the connection is sync and every *_async call croaks (not an async connection -- connect with { async => ... }); a requested mode whose backend is not installed croaks as well (core ADR 0030 §3). No compile-time dependency on EV is added to the sync driver.
OVERVIEW
The transport
DBIO::PostgreSQL::EV::Storage is the ev async storage, a thin transport over EV::Pg: core's DBIO::Storage::Async brings the CRUD, transaction, pipeline and LISTEN/NOTIFY machinery, and this class fills its seams with EV::Pg. The storage-level *_async calls resolve in the shapes core defines (core ADR 0031): select_async with raw row arrayrefs, insert_async with the returned-columns hashref, read back with RETURNING *. SQL comes from the shared DBIO::PostgreSQL::SQLMaker, whose ? placeholders the transport rewrites to $N itself. It declares the capabilities on_connect_replay, listen, notify, copy and pipeline, so an extension's async storage layer that needs them composes onto it, and broker_connect_options, so a connection made from an DBIO::AccessBroker takes connect options beside the broker -- connect($broker, { async => 'ev', pool_size => 3 }) ("transport_capabilities" in DBIO::PostgreSQL::EV::Storage).
Futures
Every Future the transport hands out is a DBIO::PostgreSQL::EV::Future, whose get runs the EV loop until the Future is ready. That is what makes ->get work from a plain script, and with it the transport's blocking methods -- select, insert, txn_do, ... -- each a *_async call waited on (ADR 0001). Inside a callback of one of the transport's own connections, a wait that would make EV::Pg hand a result to the wrong callback is refused with "Blocking wait refused", and so is a blocking call queued for a pooled connection while those callbacks hold every one of them -- with pool_size => 1, any blocking call on the storage in a then or a txn_do coderef; chain with then there ("await" in DBIO::PostgreSQL::EV::Future). The same goes for a blocking call made while the pool is opening the connection it would have to wait for: in an AccessBroker's answer, or in a callback the loop runs while the broker fetches or on_connect_do is replayed.
A statement the server refused fails its Future with a DBIO::Exception::Server: sqlstate, constraint, table and detail beside the server's text, which is what it stringifies to. A failure that is not the server's -- connection lost, a statement refused at dispatch -- is a plain string without a SQLSTATE ("What a failed statement's Future fails with" in DBIO::PostgreSQL::EV::Storage). What the transport refuses to do with what it was given -- connect info or an AccessBroker answer it cannot connect from, a channel name, a statement that mixes $N and ?, a listen connection that is closed -- is a DBIO::Exception naming the caller's file and line ("Refusals of the transport" in DBIO::PostgreSQL::EV::Storage).
Connection pool
DBIO::PostgreSQL::EV::Pool holds the EV::Pg connections, spawned as needed up to pool_size, and replays the connect actions on each new one. It is fork-safe: a forked child leaves the parent's sessions alone, whether it exits or resumes the EV loop ("Fork safety" in DBIO::PostgreSQL::EV::Pool). A connection EV::Pg reports dead is retired instead of being handed out again; one whose session ended while it sat idle is found when it is next borrowed, also when nothing ran the EV loop in between ("_idle_connection_alive" in DBIO::PostgreSQL::EV::Pool). Every connection goes back to the pool exactly once, also when EV::Pg refuses a statement or a Future callback dies ("_dispatch_query" in DBIO::PostgreSQL::EV::Storage).
Every borrow of a pooled connection has a session of its own. When a statement, a transaction, a pipeline or a copy_in ends, the connection is reset (DISCARD ALL, then the connect actions again) before it is lent to the next caller; a SET ROLE or a set_config(..., false) of one borrow is not there in the next ("The session of a pooled connection" in DBIO::PostgreSQL::EV::Storage).
Transactions
$schema->storage->txn_do_async ("txn_do_async" in DBIO::Storage::Async) pins one pooled connection from BEGIN to COMMIT or ROLLBACK and hands the coderef a DBIO::PostgreSQL::EV::TransactionContext; the transaction's statements go through that context's *_async methods. The pinned connection runs them one at a time, in the order they were issued, so a coderef that dies while one of them is still running rolls back cleanly, and the connection goes back to the pool idle ("_query_async_pinned" in DBIO::PostgreSQL::EV::Storage).
Pipeline mode
pipeline brackets one pooled connection with libpq's pipeline mode and hands the block a DBIO::Storage::Async::PipelineContext pinned to it; the calls made on that context travel in one round trip ("pipeline" in DBIO::Storage::Async, ADR 0007). A call on the storage inside the block takes another connection and is not batched.
LISTEN / NOTIFY
listen, unlisten, notify, listen_alive, listen_reconnect and the hooks on_listen_error and on_listen_reconnect are core's contract, the same on every transport that declares it ("LISTEN / NOTIFY" in DBIO::Storage::Async). This transport fills it with EV::Pg: LISTEN runs on one dedicated connection, NOTIFY on a pooled one as SELECT pg_notify($1, $2). The listen connection heals itself -- when the server drops it, it is reopened after a backoff and every channel is LISTENed again -- and it is fork-safe like a pooled one. Delivery, channel names and liveness on PostgreSQL: "LISTEN / NOTIFY" in DBIO::PostgreSQL::EV::Storage.
COPY
copy_in bulk-loads rows with COPY ... FROM STDIN in PostgreSQL's text format; its callback gets a writer that takes one arrayref per row ("copy_in" in DBIO::PostgreSQL::EV::Storage). The writer escapes each value by the text-format rules (backslash, TAB, line feed and carriage return), so a value arrives in the table exactly as given and undef is NULL.
AccessBroker credential rotation
The transport accepts an DBIO::AccessBroker as its connect info ($storage->connect_info([ $broker ])): DBIO::AccessBroker::Static, DBIO::AccessBroker::Vault and a DBIO::AccessBroker::HostBound view over either. It asks the broker for its current connect info for every new pooled connection, and for the listen connection at every open, so rotated credentials reach new connections without a pool teardown, and turns the answer into libpq connection parameters ("_async_broker_conninfo" in DBIO::PostgreSQL::EV::Storage, "ACCESSBROKER CONSUMPTION" in DBIO::Storage::Async, ADR 0009).
A schema picks the ev mode for a broker in the broker's own DBI attributes -- dbi_attrs => { async => 'ev' } on a Vault broker -- or, with a core that takes the connect options beside the broker, as connect($broker, { async => 'ev' }). Without either it stays sync.
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 => 'ev' },
));
my $async = $schema->storage->async; # DBIO::PostgreSQL::EV::Storage
A libpq parameter for the connections (sslmode, connect_timeout, ...) belongs in the broker's answer. A hash of libpq parameters is this transport's shape: answered to every storage, it connects the schema, and every pooled connection and the listen connection are opened with the parameter. The dbh of the schema's sync storage is not opened without it: of a hash that storage applies only dbname, host and port, so core throws where it would connect -- at the first use of the dbh and at every reconnect, not at connect. For the parameter on the dbh too, the broker answers the DBI form with the parameter in the DSN, which the dbh and the pool are both opened from, or each storage its own ("connect_info_for_storage" in DBIO::AccessBroker). Given beside the broker, connect($broker, { async => 'ev', sslmode => ... }), such a parameter is not applied to any connection: the transport refuses to be built with it rather than connect without it, and the sync storage refuses the same way where it would open its dbh ("connect_info" in DBIO::PostgreSQL::EV::Storage, "_async_broker_conninfo" in DBIO::PostgreSQL::EV::Storage).
Connection security and timeouts
Set sslmode=verify-full and sslrootcert in the DSN (dbi:Pg:dbname=app;host=db1;sslmode=verify-full;sslrootcert=/etc/ssl/db-ca.pem) for every connection that leaves the machine: libpq's default, prefer, falls back to plain text and checks no certificate, while verify-full encrypts, checks the server's certificate against sslrootcert and checks that the certificate names the host. The transport sets neither on its own.
Every connection this transport opens has a connect_timeout. A conninfo that sets none gets connect_timeout=10 (seconds); a value the connect info gives, 0 included, is used as it is. libpq's own default waits for ever.
Statement trace
The transport has no trace of its own. Every statement, BEGIN and COMMIT included, goes through the one rule of core, shared by every async transport: "_debug_query" in DBIO::Storage::Async. It is on with DBIO_TRACE (or $storage->debug(1)) and writes to the debug object of the schema's storage; bind values, their redaction and their cut are that method's.
Test harness
DBIO::PostgreSQL::EV::TestHarness is an installable live-test harness on core's DBIO::Test::AsyncHarness. It connects an { async => 'ev' } schema from DBIO_TEST_PG_DSN, skips the test file cleanly without one, drives the EV loop, and runs a statement on each of several pooled connections -- the check that connect actions replay. Extension distributions such as dbio-postgresql-age build their live suites on it.
EVENT LOOP COMPATIBILITY
EV::Pg uses the EV event loop. This works with:
SEE ALSO
DBIO::PostgreSQL, DBIO::Storage::Async, EV::Pg. The ADRs cited above are in this distribution's docs/adr/; the core ADRs (0030 async modes, 0031 resolution shapes, 0056 LISTEN/NOTIFY) are in DBIO's.
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.