/ 
DBIO-0.900004
/ DBIO::Storage::Pool

NAME

DBIO::Storage::Pool - Abstract connection pool interface for async storage

VERSION

version 0.900004

SYNOPSIS

# Implemented by async distributions, e.g.:
package DBIO::PostgreSQL::EV::Pool;
use base 'DBIO::Storage::Pool';

sub acquire  { ... }   # return Future resolving to a connection
sub release  { ... }   # return connection to pool
sub shutdown { ... }   # terminal, idempotent teardown

See t/storage/pool_base.t for a runnable example.

DESCRIPTION

Defines the interface contract for connection pools used by DBIO::Storage::Async drivers. This is an abstract base -- concrete implementations live in async driver distributions.

Sync storage (DBIO::Storage::DBI) does not use a pool -- it manages a single connection directly. This interface is only relevant for async storage drivers that need to multiplex queries across multiple connections.

METHODS

acquire

my $future = $pool->acquire;

Acquire a connection from the pool. Returns a Future that resolves to a connection handle. If no connections are available, the Future waits until one is released.

An implementation must report failure through that Future too -- a connection that cannot be created, or whose connect actions the server refuses, fails the Future rather than throwing. A caller holds a Future and reaches errors with ->on_fail; an exception raised instead arrives nowhere. After "shutdown", acquire and "acquire_txn" keep that contract by returning a failed Future rather than throwing or starting new work.

release

$pool->release($connection);
$pool->release($connection, $lease);

Return a connection to the pool, making it available for other queries. Once "shutdown" starts, a late release has no effect.

An implementation may take a second argument, the lease of the borrow the release ends, and ignore a release whose lease is not the connection's current one ("_lease" in DBIO::Storage::PoolBase). A caller that has no lease passes none.

acquire_txn

my $future = $pool->acquire_txn;

Acquire a connection pinned for exclusive transaction use. The connection will not be returned to the general pool until the transaction completes (COMMIT or ROLLBACK).

size

my $n = $pool->size;

Returns the total number of connections in the pool (active + idle).

available

my $n = $pool->available;

Returns the number of idle connections ready for use.

max_size

my $n = $pool->max_size;

Returns the configured maximum pool size.

shutdown

$pool->shutdown;

Permanently shut down this pool instance. Implementations must make this transition terminal and idempotent: fail queued and readiness-pending acquire Futures, refuse later acquires through failed Futures, ignore late releases, and close each connection at most once. Reconnection is owned above the pool and creates a new pool instance.

This is the existing teardown contract consumed by "disconnect" in DBIO::Storage::Async.

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.