/ 
DBIO-0.900000
/ DBIO::Storage::Async

NAME

DBIO::Storage::Async - Base class for async storage implementations

VERSION

version 0.900000

SYNOPSIS

# Users don't instantiate this directly -- use a concrete driver:
my $schema = MyApp::Schema->connect(
    'DBIO::EV::Pg',
    { host => 'localhost', dbname => 'myapp', pool_size => 10 },
);

# Async queries return Futures
$schema->resultset('Artist')->all_async->then(sub {
    my @artists = @_;
    say $_->name for @artists;
});

DESCRIPTION

Abstract base class for async DBIO storage drivers. Extends DBIO::Storage with async-specific infrastructure: connection pooling, transaction pinning, and Future-based query execution.

Concrete implementations live in separate distributions:

METHODS

future_class

Must be overridden by subclasses to return the event-loop-specific Future class (e.g. 'Future' for Future.pm).

pool

Returns the connection pool object. Must be overridden by subclasses.

_is_access_broker_connect_info

if ($self->_is_access_broker_connect_info($info)) { ... }

True when the supplied connect info is a broker-style invocation: a single-element arrayref whose sole member is a blessed DBIO::AccessBroker instance. Mirrors the same check on the DBI side (DBIO::Storage::DBI::AccessBroker).

_setup_access_broker

$self->_setup_access_broker($info->[0]);

Attach the broker (via the inherited "set_access_broker" in DBIO::Storage) and install the per-spawn conninfo_provider coderef. Call this from a driver's connect_info when "_is_access_broker_connect_info" matched. The coderef closes over $self and, on each invocation, calls the driver's "_async_broker_conninfo" to obtain freshly-refreshed, storage-native connect info for one new pool connection.

_clear_access_broker

$self->_clear_access_broker;

Detach any broker (via the inherited "clear_access_broker" in DBIO::Storage) and tear down the conninfo_provider, so a subsequent non-broker connect uses the static conninfo path. Call from a driver's connect_info on the non-broker branch.

_conninfo_provider

The per-spawn credential coderef installed by "_setup_access_broker", or undef when no broker is attached. Hand this to the pool as its conninfo_provider so every NEW pool connection is built from fresh credentials (see "_spawn_connection" in DBIO::Storage::PoolBase).

_async_broker_conninfo

sub _async_broker_conninfo {
  my ($self, $mode) = @_;
  ...
  return $conninfo;  # one fresh, storage-native conninfo value
}

Required driver seam hook when a broker is in use: return one fresh storage-native connect-info value for a single new pool connection, in the shape the pool's _transform_conninfo expects (e.g. the libpq parameter hashref for the PostgreSQL pool). Invoked once per pool spawn by the "_conninfo_provider" coderef. Defaults to croaking; a driver that consumes the broker must override it.

select_async

my $future = $storage->select_async($source, $select, $where, $attrs);

Must be overridden by subclasses with a non-blocking implementation that returns a Future.

select_single_async

Must be overridden by subclasses.

insert_async

Must be overridden by subclasses.

update_async

Must be overridden by subclasses.

delete_async

Must be overridden by subclasses.

txn_do_async

my $future = $storage->txn_do_async(sub { ... });

Acquires a connection from the pool, issues BEGIN, executes the coderef, and issues COMMIT on success or ROLLBACK on failure. The coderef receives a transaction-bound storage. Must be overridden.

pipeline

my $future = $storage->pipeline(sub {
    my $storage = shift;
    # ... batch multiple queries ...
});

Execute multiple queries in pipeline mode for reduced round-trips. Optional -- not all async drivers support this. Default croaks.

listen

$storage->listen($channel, sub { my ($channel, $payload, $pid) = @_; });

Subscribe to database notifications (e.g. PostgreSQL LISTEN/NOTIFY). Optional -- not all databases support this. Default croaks.

unlisten

$storage->unlisten($channel);

Unsubscribe from a notification channel.

ACCESSBROKER CONSUMPTION

The async storage tier is the second consumer of the DBIO::AccessBroker credential seam (the first being DBIO::Storage::DBI; see CONTEXT.md and the ADRs). The broker-management API itself (set_access_broker, clear_access_broker, current_access_broker_connect_info) lives on the base DBIO::Storage, so it is inherited here unchanged.

What this class adds is the async consumption wiring that was previously re-implemented by every async driver: detecting a broker passed as connect info, building the per-spawn conninfo_provider coderef that pulls fresh credentials, and feeding it to the pool so every NEW pool connection gets freshly-refreshed connect info. Drivers supply only the one storage-native seam hook, "_async_broker_conninfo".

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

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