DatabasePool
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
Enable background maintenance after pool initialization succeeds.
Check one idle connection and discard it when unhealthy.
Close the database pool and clear its shared resources.
Get the current number of connections managed by the pool.
Get the number of connections currently available in the pool.
Create a usage policy for this database pool.
Create a new pooled connection.
Return an idle connection without changing its activity timestamps.
Convert seconds to nanoseconds without overflowing integer arithmetic.
Build a monotonic deadline without overflowing at long durations or uptimes.
Ensure that a connection belongs to this pool before destroying it.
Get the shared PDO for in-memory SQLite, or null for other drivers/configurations.
Restore the shared in-memory database retained between tests.
Record the query grammar date format of one of the pool's connections.
Forget the recorded date format, once a connection of the pool has been closed or replaced.
Get the recorded query grammar date format, if a connection recorded one since the last was closed.
Determine whether callers can return the pool's PDO sessions before execution ends.
Determine whether an opted-in driver's endpoints can share a logical connection.
Determine whether a connection that modified records keeps its session.
Determine whether endpoints can share a logical connection without bypassing extensions.
Determine whether the role receiving this pool's writes can select different servers.
Get the role used by every operation on this pool's connections.
Get the merged endpoint configuration of each record a role may select.
Create the shared PDO for in-memory SQLite via the factory.
Check if this pool is for an in-memory SQLite database.
Resolve consistent pool settings without choosing a physical read endpoint.
Ensure a derived read pool does not point at an in-memory SQLite database.
Start the heartbeat timer if configured.
Clear the heartbeat timer.
Run one heartbeat sweep over currently idle connections.
Details
at line 65
__construct(Container $container, string $name)
Create a database connection pool.
in
ConnectionPool at line 61
string
getName()
Get the pool name.
at line 124
void
start()
Enable background maintenance after pool initialization succeeds.
in
ConnectionPool at line 85
Connection
borrow()
Borrow a connection from the pool.
in
ConnectionPool at line 129
void
release(Connection $connection)
Release a connection back to the pool.
in
ConnectionPool at line 146
void
discard(Connection $connection)
Discard a borrowed connection from the pool.
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.
in
ConnectionPool at line 172
void
checkIdleConnection()
Check one idle connection and discard it when unhealthy.
at line 427
void
close()
Close the database pool and clear its shared resources.
in
ConnectionPool at line 254
bool
isClosed()
Determine if the pool is closed.
in
ConnectionPool at line 262
int
getManagedCount()
Get the current number of connections managed by the pool.
in
ConnectionPool at line 270
int
getBorrowedCount()
Return the number of connections borrowed by callers.
in
ConnectionPool at line 278
PoolOptions
getOptions()
Get the pool configuration options.
in
ConnectionPool at line 286
int
getIdleCount()
Get the number of connections currently available in the pool.
in
ConnectionPool at line 294
int
getWaitingCount()
Get the number of coroutines waiting for a connection.
in
ConnectionPool at line 304
array
getStats()
Return the pool's current resource counts and closed state.
at line 360
protected UsageTracker|null
createUsageTracker()
Create a usage policy for this database pool.
at line 325
protected Connection
createConnection()
Create a new pooled connection.
in
ConnectionPool at line 334
protected Connection|false
popIdleConnection()
Pop and validate one idle connection.
in
ConnectionPool at line 358
protected void
requeueConnection(Connection $connection)
Return an idle connection without changing its activity timestamps.
in
ConnectionPool at line 376
protected void
destroyConnection(Connection $connection)
Destroy a managed connection and release its capacity.
in
ConnectionPool at line 400
protected void
report(Throwable|string $error)
Report a pool maintenance or cleanup failure without throwing.
in
ConnectionPool at line 411
protected StdoutLoggerInterface|null
getLogger()
Get the logger instance if available.
in
ConnectionPool at line 498
protected int
nanoseconds(float $seconds)
Convert seconds to nanoseconds without overflowing integer arithmetic.
in
ConnectionPool at line 508
protected int
deadline(float $seconds)
Build a monotonic deadline without overflowing at long durations or uptimes.
in
ConnectionPool at line 521
protected int
ensureManaged(Connection $connection)
Ensure that a connection belongs to this pool before destroying it.
at line 133
PDO|null
getSharedInMemorySqlitePdo()
Get the shared PDO for in-memory SQLite, or null for other drivers/configurations.
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.
at line 162
void
recordDateFormat(Connection $connection)
| internal |
Record the query grammar date format of one of the pool's connections.
at line 172
void
forgetDateFormat()
| internal |
Forget the recorded date format, once a connection of the pool has been closed or replaced.
at line 182
string|null
recordedDateFormat()
| internal |
Get the recorded query grammar date format, if a connection recorded one since the last was closed.
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().
at line 200
bool
supportsDriverSessionLeases()
Determine whether an opted-in driver's endpoints can share a logical connection.
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.
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.
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.
at line 299
protected string
connectionRole(ConnectionFactory $factory, ConnectionName $name, array $config)
Get the role used by every operation on this pool's connections.
at line 310
protected array
roleEndpoints(ConnectionFactory $factory, string $role, array $config)
Get the merged endpoint configuration of each record a role may select.
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.
at line 368
protected bool
isInMemorySqlite(array $config)
Check if this pool is for an in-memory SQLite database.
at line 382
protected array
readPoolConfig(ConnectionFactory $factory, ConnectionName $name, array $config)
Resolve consistent pool settings without choosing a physical read endpoint.
at line 409
protected void
ensureNotDerivedInMemorySqlitePool(ConnectionName $name, array $config)
Ensure a derived read pool does not point at an in-memory SQLite database.
at line 445
protected void
startHeartbeat()
Start the heartbeat timer if configured.
at line 488
protected void
clearHeartbeat()
Clear the heartbeat timer.
at line 502
protected void
heartbeat()
Run one heartbeat sweep over currently idle connections.
at line 521
protected void
heartbeatConnection(PooledConnection $connection)
Heartbeat one idle connection.
at line 556
protected void
discardHeartbeatConnection(PooledConnection $connection)
Discard an idle connection from the pool.