pub struct PoolManager { /* private fields */ }Expand description
Manages connection pools keyed by (node, database, user). Each upstream node gets its own pool, enabling per-node failover and separate primary/replica connection limits.
Implementations§
Source§impl PoolManager
impl PoolManager
Sourcepub async fn checkout(
self: &Arc<Self>,
client: &ClientGuard,
database: &str,
user: &str,
read_only: bool,
) -> Result<ConnGuard>
pub async fn checkout( self: &Arc<Self>, client: &ClientGuard, database: &str, user: &str, read_only: bool, ) -> Result<ConnGuard>
Check out a server connection.
When read_only is true, routes to a replica. When false, routes
to the primary. Returns an RAII guard that auto-discards on drop;
call checkin to return the connection for reuse.
If every candidate node for the resolved role is at its per-node
max_connections, the checkout enqueues on a shared
(database, user, role) wait queue and blocks until either:
- a connection is released on any candidate node and this waiter is the next in the FIFO queue, or
server.checkout_timeoutelapses since the first enqueue, in which case the checkout fails with a classifiedcheckout_timeouterror.
The ClientGuard is flipped to ClientState::Waiting for the
duration of any blocked wait and back to ClientState::Idle on
success, timeout, or spurious wakeup.
Source§impl PoolManager
impl PoolManager
Sourcepub async fn warm_up(self: &Arc<Self>)
pub async fn warm_up(self: &Arc<Self>)
Open idle connections at startup based on min_connections config.
Sourcepub fn scavenge_idle(&self) -> u32
pub fn scavenge_idle(&self) -> u32
Remove idle connections that exceed max_lifetime or whose socket is
dead, then apply idle_timeout only to connections in excess of
min_connections for that pool entry.
max_lifetime and dead-socket detection always apply because those
represent unhealthy connections. idle_timeout represents excess
capacity that can be released — so it must respect the floor set by
min_connections, otherwise warm-up connections decay away even when
the user explicitly asked for a minimum.
Returns the number of connections removed across all pool entries.
Normally invoked from PoolManager::run_scavenger; exposed so tests
can drive it directly without spinning up the full background task.
Sourcepub async fn run_scavenger(self: &Arc<Self>)
pub async fn run_scavenger(self: &Arc<Self>)
Run the idle scavenger and refill loop at a fixed interval.
Each tick prunes expired idle connections (preserving the
min_connections floor), then refills any pool entry below its
floor by fanning every spawn_connections call into a
JoinSet and awaiting them concurrently — matching
PoolManager::warm_up. Running them in series here would
let a single slow node blow most of the 30-second budget and
leave unrelated pools under their min_connections floor.
The per-tick state is logged at debug level so the loop is
visible without needing trace-level filters.
Source§impl PoolManager
impl PoolManager
pub fn new( config: Arc<ArcSwap<Config>>, topology: Arc<TopologyManager>, pgpass: Arc<Pgpass>, ) -> Self
Sourcepub fn config(&self) -> &Arc<ArcSwap<Config>>
pub fn config(&self) -> &Arc<ArcSwap<Config>>
Access the shared config handle. Used by the reload path to
atomically swap in a new Config via store; callers that just
want to read the current config should use load_full() on the
returned handle for intra-operation consistency.
Sourcepub fn shutdown(&self)
pub fn shutdown(&self)
Signal that halephant is shutting down: set the shutdown flag
and wake every queued waiter so they return a classified error
immediately instead of sitting on the queue until checkout_timeout
expires or they get force-aborted.
Called from the graceful shutdown path in main right after the
accept loop exits, before draining client tasks.
Sourcepub fn resolve(
&self,
database: &str,
routing: Routing,
) -> Result<String, ResolveError>
pub fn resolve( &self, database: &str, routing: Routing, ) -> Result<String, ResolveError>
Resolve a routing target for a database. Returns the upstream address as an owned string.
Returns a specific ResolveError if the database is unknown, the
primary has not been discovered, or no healthy replica is available.
Sourcepub fn drain_node(&self, node: &str)
pub fn drain_node(&self, node: &str)
Drain idle connections for a specific node across all databases/users. Called when topology detects a node role change or unreachability.
Sourcepub fn pool_stats(&self) -> Vec<(PoolKeyInfo, PoolStats)>
pub fn pool_stats(&self) -> Vec<(PoolKeyInfo, PoolStats)>
Returns a snapshot of all pool states for metrics reporting.
Sourcepub fn queue_stats(&self) -> Vec<QueueInfo>
pub fn queue_stats(&self) -> Vec<QueueInfo>
Returns a snapshot of every non-empty wait queue.
Sourcepub fn pool_limits(&self) -> Vec<PoolLimits>
pub fn pool_limits(&self) -> Vec<PoolLimits>
Returns the configured connection limits for each pool.