class DatabasePool extends ConnectionPool

Database connection pool.

For in-memory SQLite, manages a shared PDO behind a single pooled owner. Non-pooled paths (Capsule, SimpleConnectionResolver) bypass this entirely and get isolated connections as expected.

Properties

protected Connection> $channel from  ConnectionPool
protected PoolOptions $options from  ConnectionPool
protected array<int, true> $managedConnections from  ConnectionPool
protected array<int, true> $borrowedConnections from  ConnectionPool
protected int $creatingCount from  ConnectionPool
protected bool $closed from  ConnectionPool
protected UsageTracker|null $usageTracker from  ConnectionPool
protected bool $usageTrackerInitialized from  ConnectionPool
protected IdleConnectionMonitor|null $idleMonitor from  ConnectionPool
protected array $config
protected bool $usesSessionLeases
protected bool|null $supportsDriverSessionLeases
protected bool|null $retainsSessionsAfterWrites
protected Timer|null $heartbeatTimer
protected int|null $heartbeatTimerId
protected bool $heartbeatStarted
protected PDO|null $sharedInMemorySqlitePdo

Shared PDO for in-memory SQLite.

protected string|null $dateFormat

The query grammar date format new borrowers start from, recorded from the pool's physical connections.

Methods

__construct(Container $container, string $name)

Create a database connection pool.

string
getName()

Get the pool name.

void
start()

Enable background maintenance after pool initialization succeeds.

borrow()

Borrow a connection from the pool.

void
release(Connection $connection)

Release a connection back to the pool.

void
discard(Connection $connection)

Discard a borrowed connection from the pool.

void
trimExcessIdle()

Close excess idle connections without checking their age.

void
checkIdleConnection()

Check one idle connection and discard it when unhealthy.

void
close()

Close the database pool and clear its shared resources.

bool
isClosed()

Determine if the pool is closed.

int
getManagedCount()

Get the current number of connections managed by the pool.

int
getBorrowedCount()

Return the number of connections borrowed by callers.

getOptions()

Get the pool configuration options.

int
getIdleCount()

Get the number of connections currently available in the pool.

int
getWaitingCount()

Get the number of coroutines waiting for a connection.

array
getStats()

Return the pool's current resource counts and closed state.

createUsageTracker()

Create a usage policy for this database pool.

createConnection()

Create a new pooled connection.

Connection|false
popIdleConnection()

Pop and validate one idle connection.

void
requeueConnection(Connection $connection)

Return an idle connection without changing its activity timestamps.

void
destroyConnection(Connection $connection)

Destroy a managed connection and release its capacity.

void
report(Throwable|string $error)

Report a pool maintenance or cleanup failure without throwing.

getLogger()

Get the logger instance if available.

int
nanoseconds(float $seconds)

Convert seconds to nanoseconds without overflowing integer arithmetic.

int
deadline(float $seconds)

Build a monotonic deadline without overflowing at long durations or uptimes.

int
ensureManaged(Connection $connection)

Ensure that a connection belongs to this pool before destroying it.

PDO|null
getSharedInMemorySqlitePdo()

Get the shared PDO for in-memory SQLite, or null for other drivers/configurations.

void
restoreSharedInMemorySqlitePdo(PDO $pdo)

Restore the shared in-memory database retained between tests.

void
recordDateFormat(Connection $connection)

Record the query grammar date format of one of the pool's connections.

void
forgetDateFormat()

Forget the recorded date format, once a connection of the pool has been closed or replaced.

string|null
recordedDateFormat()

Get the recorded query grammar date format, if a connection recorded one since the last was closed.

bool
usesSessionLeases()

Determine whether callers can return the pool's PDO sessions before execution ends.

bool
supportsDriverSessionLeases()

Determine whether an opted-in driver's endpoints can share a logical connection.

bool
retainsSessionsAfterWrites()

Determine whether a connection that modified records keeps its session.

bool
supportsSessionLeases(ConnectionFactory $factory, ConnectionName $name, array $config, bool $allowExtensions = false)

Determine whether endpoints can share a logical connection without bypassing extensions.

bool
writesReachDifferentServers(ConnectionFactory $factory, ConnectionName $name, array $config)

Determine whether the role receiving this pool's writes can select different servers.

string
connectionRole(ConnectionFactory $factory, ConnectionName $name, array $config)

Get the role used by every operation on this pool's connections.

array
roleEndpoints(ConnectionFactory $factory, string $role, array $config)

Get the merged endpoint configuration of each record a role may select.

PDO
createSharedInMemorySqlitePdo()

Create the shared PDO for in-memory SQLite via the factory.

bool
isInMemorySqlite(array $config)

Check if this pool is for an in-memory SQLite database.

array
readPoolConfig(ConnectionFactory $factory, ConnectionName $name, array $config)

Resolve consistent pool settings without choosing a physical read endpoint.

void
ensureNotDerivedInMemorySqlitePool(ConnectionName $name, array $config)

Ensure a derived read pool does not point at an in-memory SQLite database.

void
startHeartbeat()

Start the heartbeat timer if configured.

void
clearHeartbeat()

Clear the heartbeat timer.

void
heartbeat()

Run one heartbeat sweep over currently idle connections.

void
heartbeatConnection(PooledConnection $connection)

Heartbeat one idle connection.

void
discardHeartbeatConnection(PooledConnection $connection)

Discard an idle connection from the pool.

Details

at line 65
__construct(Container $container, string $name)

Create a database connection pool.

Parameters

Container $container
string $name

in ConnectionPool at line 61
string getName()

Get the pool name.

Return Value

string

at line 124
void start()

Enable background maintenance after pool initialization succeeds.

Return Value

void

in ConnectionPool at line 85
Connection borrow()

Borrow a connection from the pool.

Return Value

Connection

in ConnectionPool at line 129
void release(Connection $connection)

Release a connection back to the pool.

Parameters

Connection $connection

Return Value

void

in ConnectionPool at line 146
void discard(Connection $connection)

Discard a borrowed connection from the pool.

Parameters

Connection $connection

Return Value

void

in ConnectionPool at line 157
void trimExcessIdle()

Close excess idle connections without checking their age.

Stop when the managed count reaches the retained minimum or no idle connections remain.

Return Value

void

in ConnectionPool at line 172
void checkIdleConnection()

Check one idle connection and discard it when unhealthy.

Return Value

void

at line 427
void close()

Close the database pool and clear its shared resources.

Return Value

void

in ConnectionPool at line 254
bool isClosed()

Determine if the pool is closed.

Return Value

bool

in ConnectionPool at line 262
int getManagedCount()

Get the current number of connections managed by the pool.

Return Value

int

in ConnectionPool at line 270
int getBorrowedCount()

Return the number of connections borrowed by callers.

Return Value

int

in ConnectionPool at line 278
PoolOptions getOptions()

Get the pool configuration options.

Return Value

PoolOptions

in ConnectionPool at line 286
int getIdleCount()

Get the number of connections currently available in the pool.

Return Value

int

in ConnectionPool at line 294
int getWaitingCount()

Get the number of coroutines waiting for a connection.

Return Value

int

in ConnectionPool at line 304
array getStats()

Return the pool's current resource counts and closed state.

Return Value

array

at line 360
protected UsageTracker|null createUsageTracker()

Create a usage policy for this database pool.

Return Value

UsageTracker|null

at line 325
protected Connection createConnection()

Create a new pooled connection.

Return Value

Connection

in ConnectionPool at line 334
protected Connection|false popIdleConnection()

Pop and validate one idle connection.

Return Value

Connection|false

in ConnectionPool at line 358
protected void requeueConnection(Connection $connection)

Return an idle connection without changing its activity timestamps.

Parameters

Connection $connection

Return Value

void

in ConnectionPool at line 376
protected void destroyConnection(Connection $connection)

Destroy a managed connection and release its capacity.

Parameters

Connection $connection

Return Value

void

in ConnectionPool at line 400
protected void report(Throwable|string $error)

Report a pool maintenance or cleanup failure without throwing.

Parameters

Throwable|string $error

Return Value

void

in ConnectionPool at line 411
protected StdoutLoggerInterface|null getLogger()

Get the logger instance if available.

Return Value

StdoutLoggerInterface|null

in ConnectionPool at line 498
protected int nanoseconds(float $seconds)

Convert seconds to nanoseconds without overflowing integer arithmetic.

Parameters

float $seconds

Return Value

int

in ConnectionPool at line 508
protected int deadline(float $seconds)

Build a monotonic deadline without overflowing at long durations or uptimes.

Parameters

float $seconds

Return Value

int

in ConnectionPool at line 521
protected int ensureManaged(Connection $connection)

Ensure that a connection belongs to this pool before destroying it.

Parameters

Connection $connection

Return Value

int

at line 133
PDO|null getSharedInMemorySqlitePdo()

Get the shared PDO for in-memory SQLite, or null for other drivers/configurations.

Return Value

PDO|null

at line 143
void restoreSharedInMemorySqlitePdo(PDO $pdo)

Restore the shared in-memory database retained between tests.

Replaces the database used by every subsequent pool borrower.

Parameters

PDO $pdo

Return Value

void

at line 162
void recordDateFormat(Connection $connection)

internal  
 

Record the query grammar date format of one of the pool's connections.

Parameters

Connection $connection

Return Value

void

at line 172
void forgetDateFormat()

internal  
 

Forget the recorded date format, once a connection of the pool has been closed or replaced.

Return Value

void

at line 182
string|null recordedDateFormat()

internal  
 

Get the recorded query grammar date format, if a connection recorded one since the last was closed.

Return Value

string|null

at line 192
bool usesSessionLeases()

Determine whether callers can return the pool's PDO sessions before execution ends.

Opted-in extension drivers are checked separately by supportsDriverSessionLeases().

Return Value

bool

at line 200
bool supportsDriverSessionLeases()

Determine whether an opted-in driver's endpoints can share a logical connection.

Return Value

bool

at line 218
bool retainsSessionsAfterWrites()

Determine whether a connection that modified records keeps its session.

Sticky and write-routed reads must reach the server that took the connection's writes, which a later borrow may not when writes can reach different servers.

Return Value

bool

at line 230
protected bool supportsSessionLeases(ConnectionFactory $factory, ConnectionName $name, array $config, bool $allowExtensions = false)

Determine whether endpoints can share a logical connection without bypassing extensions.

Parameters

ConnectionFactory $factory
ConnectionName $name
array $config
bool $allowExtensions

Return Value

bool

at line 264
protected bool writesReachDifferentServers(ConnectionFactory $factory, ConnectionName $name, array $config)

Determine whether the role receiving this pool's writes can select different servers.

Parameters

ConnectionFactory $factory
ConnectionName $name
array $config

Return Value

bool

at line 299
protected string connectionRole(ConnectionFactory $factory, ConnectionName $name, array $config)

Get the role used by every operation on this pool's connections.

Parameters

ConnectionFactory $factory
ConnectionName $name
array $config

Return Value

string

at line 310
protected array roleEndpoints(ConnectionFactory $factory, string $role, array $config)

Get the merged endpoint configuration of each record a role may select.

Parameters

ConnectionFactory $factory
string $role
array $config

Return Value

array

at line 344
protected PDO createSharedInMemorySqlitePdo()

Create the shared PDO for in-memory SQLite via the factory.

Uses the normal PDO resolver pipeline so initial construction and refresh produce the same connection subclass.

Return Value

PDO

at line 368
protected bool isInMemorySqlite(array $config)

Check if this pool is for an in-memory SQLite database.

Parameters

array $config

Return Value

bool

at line 382
protected array readPoolConfig(ConnectionFactory $factory, ConnectionName $name, array $config)

Resolve consistent pool settings without choosing a physical read endpoint.

Parameters

ConnectionFactory $factory
ConnectionName $name
array $config

Return Value

array

at line 409
protected void ensureNotDerivedInMemorySqlitePool(ConnectionName $name, array $config)

Ensure a derived read pool does not point at an in-memory SQLite database.

Parameters

ConnectionName $name
array $config

Return Value

void

at line 445
protected void startHeartbeat()

Start the heartbeat timer if configured.

Return Value

void

at line 488
protected void clearHeartbeat()

Clear the heartbeat timer.

Return Value

void

at line 502
protected void heartbeat()

Run one heartbeat sweep over currently idle connections.

Return Value

void

at line 521
protected void heartbeatConnection(PooledConnection $connection)

Heartbeat one idle connection.

Parameters

PooledConnection $connection

Return Value

void

at line 556
protected void discardHeartbeatConnection(PooledConnection $connection)

Discard an idle connection from the pool.

Parameters

PooledConnection $connection

Return Value

void