/ 
DBIO-0.900000
/ DBIO::Storage::PoolBase

NAME

DBIO::Storage::PoolBase - Shared connection pool mechanics for async DBIO drivers

VERSION

version 0.900000

SYNOPSIS

package DBIO::PostgreSQL::Async::Pool;
use base 'DBIO::Storage::PoolBase';

sub _create_connection {
  my ($self, $conninfo) = @_;
  return EV::Pg->new(
    conninfo   => $conninfo,
    on_connect => sub {},
    on_error   => $self->{on_error},
  );
}

sub _shutdown_connection { $_[1]->finish }

sub _transform_conninfo { conninfo_string($_[1]) }

DESCRIPTION

Concrete implementation of the DBIO::Storage::Pool contract hosting the pool mechanics shared by all async drivers: idle-pool handling, capacity-bounded connection creation, the waiter queue and shutdown.

Drivers subclass this and supply only the engine seam:

METHODS

new

my $pool = Driver::Pool->new(
    conninfo => 'dbname=myapp',
    size     => 10,
    on_error => sub { warn $_[0] },
);

Requires conninfo or conninfo_provider (a coderef returning fresh connect info per connection). size caps the pool (default 5). future_class overrides the Future implementation per instance.

future_class

The Future implementation backing "acquire". Defaults to Future; override in a subclass or pass future_class to "new".

acquire

Returns an idle connection wrapped in a done Future. Creates a new connection if the pool has capacity. If all connections are busy and the pool is at max size, queues the request and returns a pending Future that resolves on the next "release".

acquire_txn

Acquire a connection pinned for exclusive transaction use. Same as "acquire" but the connection will not be released back to the idle pool until explicitly released.

release

$pool->release($conn);

Return a connection to the idle pool. If waiters are queued, hands the connection straight to the oldest waiter instead.

size

Total connections (active + idle).

available

Number of idle connections.

max_size

Configured maximum pool size.

shutdown

Close all connections via "_shutdown_connection" and clear the pool.

_create_connection

sub _create_connection { my ($self, $conninfo) = @_; ... }

Required driver hook: build and return one connection from the (already transformed) connect info. The pool tracks the connection; do not push it anywhere yourself.

_shutdown_connection

sub _shutdown_connection { my ($self, $conn) = @_; $conn->finish }

Optional driver hook: close one connection during "shutdown". Defaults to a no-op; exceptions are swallowed by the caller.

_transform_conninfo

sub _transform_conninfo { my ($self, $conninfo) = @_; ... }

Optional driver hook: adapt stored connect info into the shape the driver's connection constructor expects (e.g. a libpq conninfo string). Defaults to returning it unchanged.

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.