1use std::sync::Arc;
4use std::sync::atomic::Ordering;
5use std::time::{Duration, Instant};
6
7use tokio::sync::oneshot;
8use tracing::debug;
9
10use crate::clients;
11use crate::errors::ResolveError;
12use crate::o11y;
13use crate::pool::PoolManager;
14use crate::pool::candidates::ConnectSpec;
15use crate::pool::types::{
16 CandidateResult, CheckoutError, ConnGuard, ConnId, PoolKey, Routing, WaitKey, Waiter,
17 classify_checkout_error,
18};
19
20impl PoolManager {
21 #[tracing::instrument(name = "pool.checkout", skip_all, err(Display), fields(
22 db.namespace = %database,
23 user = %user,
24 halephant.client.id = client.id().as_u64(),
25 read_only,
26 pool.reused,
27 pool.waited,
28 otel.status_code,
29 otel.status_description,
30 ))]
31 pub async fn checkout(
32 self: &Arc<Self>,
33 client: &clients::ClientGuard,
34 database: &str,
35 user: &str,
36 read_only: bool,
37 ) -> anyhow::Result<ConnGuard> {
38 let routing = if read_only {
39 Routing::Replica
40 } else {
41 Routing::Primary
42 };
43 let wait_key = WaitKey {
44 database: database.to_owned(),
45 role: routing,
46 };
47
48 let cfg = self.config.load_full();
49 let checkout_start = Instant::now();
50 let mut queue_start: Option<Instant> = None;
51
52 async {
53 let (cluster_name, idle_timeout, max_lifetime, checkout_timeout) = {
54 let Some((name, _, pool_config)) = cfg.find_pool(database) else {
55 return Err(ResolveError::UnknownDatabase {
56 database: database.to_owned(),
57 }
58 .into());
59 };
60 (
61 name.to_owned(),
62 pool_config.idle_timeout,
63 pool_config.max_lifetime,
64 pool_config
65 .checkout_timeout
66 .unwrap_or(cfg.server.checkout_timeout),
67 )
68 };
69
70 let spec = ConnectSpec::resolve(&cfg, database, user)?;
75
76 loop {
77 let candidates = self.resolve_candidates(&cfg, database, user, routing);
80 let fallback = if routing == Routing::Replica {
81 self.resolve_candidates(&cfg, database, user, Routing::Primary)
82 } else {
83 Vec::new()
84 };
85 if candidates.is_empty() && fallback.is_empty() {
86 return Err(match routing {
87 Routing::Primary => ResolveError::NoPrimary {
88 cluster: cluster_name.clone(),
89 },
90 Routing::Replica => ResolveError::NoReplica {
91 cluster: cluster_name.clone(),
92 },
93 }
94 .into());
95 }
96
97 let mut got = CandidateResult::AllFull;
99 for batch in [&candidates, &fallback] {
100 if batch.is_empty() {
101 continue;
102 }
103 got = self.try_candidates(&cfg, batch, idle_timeout, max_lifetime);
104 if !matches!(got, CandidateResult::AllFull) {
105 break;
106 }
107 }
108
109 match got {
110 CandidateResult::GotIdle { key, conn } => {
111 record_checkout_success(
112 &key,
113 checkout_start,
114 queue_start,
115 database,
116 user,
117 routing,
118 true,
119 );
120 return Ok(ConnGuard {
121 pools: Arc::clone(self),
122 key,
123 id: conn.id,
124 conn: Some(conn.conn),
125 });
126 }
127 CandidateResult::Claimed { key, id } => {
128 match self.connect_with_spec(&key.node, &spec).await {
129 Ok(conn) => {
130 record_checkout_success(
131 &key,
132 checkout_start,
133 queue_start,
134 database,
135 user,
136 routing,
137 false,
138 );
139 return Ok(ConnGuard {
140 pools: Arc::clone(self),
141 key,
142 id,
143 conn: Some(conn),
144 });
145 }
146 Err(e) => {
147 self.discard_internal(&key, id);
148 let total = candidates.len() + fallback.len();
149 if total == 1 {
150 return Err(e);
151 }
152 }
153 }
154 }
155 CandidateResult::AllFull => {}
156 }
157
158 let rx = {
159 let (tx, rx) = oneshot::channel();
160 let mut inner = self.inner.lock();
161 inner
162 .waits
163 .entry(wait_key.clone())
164 .or_default()
165 .waiters
166 .push_back(Waiter {
167 enqueued_at: Instant::now(),
168 user: user.to_owned(),
169 tx,
170 });
171 rx
172 };
173 client.set_waiting_for(Some(clients::WaitTarget {
174 database: database.to_owned(),
175 user: user.to_owned(),
176 role: match routing {
177 Routing::Primary => clients::WaitRole::Primary,
178 Routing::Replica => clients::WaitRole::Replica,
179 },
180 }));
181 client.set_state(clients::ClientState::Waiting);
182 queue_start.get_or_insert_with(Instant::now);
183
184 let timeout_error = || CheckoutError::Timeout {
185 timeout: checkout_timeout,
186 database: database.to_owned(),
187 user: user.to_owned(),
188 };
189 let remaining = checkout_timeout.saturating_sub(checkout_start.elapsed());
190 if remaining.is_zero() {
191 client.set_waiting_for(None);
192 client.set_state(clients::ClientState::Idle);
193 return Err(timeout_error().into());
194 }
195 let wake = tokio::time::timeout(remaining, rx).await;
196 client.set_waiting_for(None);
197 client.set_state(clients::ClientState::Idle);
198
199 if wake.is_err() {
200 return Err(timeout_error().into());
201 }
202 if self.shutting_down.load(Ordering::Acquire) {
203 return Err(CheckoutError::ShuttingDown.into());
204 }
205 }
206 }
207 .await
208 .inspect(|_| {
209 tracing::Span::current().record("otel.status_code", "OK");
210 })
211 .inspect_err(|e| {
212 o11y::metrics::record_checkout_error(database, user, classify_checkout_error(e));
213 let span = tracing::Span::current();
214 span.record("otel.status_code", "ERROR");
215 span.record("otel.status_description", "checkout failed");
216 })
217 }
218
219 fn resolve_candidates(
224 &self,
225 cfg: &crate::config::Config,
226 database: &str,
227 user: &str,
228 routing: Routing,
229 ) -> Vec<PoolKey> {
230 let Some((cluster_name, _, _)) = cfg.find_pool(database) else {
231 return Vec::new();
232 };
233 match routing {
234 Routing::Primary => {
235 let Some(primary) = self.topology.primary(cluster_name) else {
236 return Vec::new();
237 };
238 vec![PoolKey {
239 node: primary,
240 database: database.to_owned(),
241 user: user.to_owned(),
242 }]
243 }
244 Routing::Replica => self
245 .topology
246 .replicas(cluster_name)
247 .iter()
248 .map(|addr| PoolKey {
249 node: addr.clone(),
250 database: database.to_owned(),
251 user: user.to_owned(),
252 })
253 .collect(),
254 }
255 }
256
257 fn try_candidates(
258 &self,
259 cfg: &crate::config::Config,
260 candidates: &[PoolKey],
261 idle_timeout: Duration,
262 max_lifetime: Duration,
263 ) -> CandidateResult {
264 let mut inner = self.inner.lock();
265
266 let mut ranked: Vec<&PoolKey> = candidates.iter().collect();
268 if ranked.len() > 1 {
269 let start = self.replica_rr.fetch_add(1, Ordering::Relaxed) % ranked.len();
270 ranked.rotate_left(start);
271 ranked.sort_by_key(|k| inner.pools.get(*k).map_or(0, |p| p.active.len()));
272 }
273
274 for key in ranked {
275 let limits = self.resolve_limits(cfg, key);
276
277 let idle = {
280 let pool = inner.pools.entry(key.clone()).or_default();
281 let idle = pool.pop_idle(idle_timeout, max_lifetime);
282 if let Some(ref c) = idle {
283 pool.active.insert(c.id);
284 }
285 idle
286 };
287 if let Some(idle) = idle {
288 return CandidateResult::GotIdle {
289 key: key.clone(),
290 conn: Box::new(idle),
291 };
292 }
293
294 let user_total = inner.pools.get(key).map_or(0, super::types::Pool::total);
295 if !limits.user_has_capacity(user_total) {
296 continue;
297 }
298
299 let node_total = inner.node_total(&key.node, &key.database);
300 if !limits.pool_has_capacity(node_total) && !Self::evict_idle_for_node(&mut inner, key)
301 {
302 continue;
303 }
304
305 let id = ConnId::next();
306 inner
307 .pools
308 .entry(key.clone())
309 .or_default()
310 .active
311 .insert(id);
312 return CandidateResult::Claimed {
313 key: key.clone(),
314 id,
315 };
316 }
317
318 CandidateResult::AllFull
319 }
320
321 fn evict_idle_for_node(inner: &mut super::types::Inner, key: &PoolKey) -> bool {
322 let victim = inner
323 .pools
324 .iter()
325 .filter(|(k, p)| k.node == key.node && k.database == key.database && !p.idle.is_empty())
326 .min_by_key(|(_, p)| p.idle.front().map_or(Instant::now(), |i| i.idle_since))
327 .map(|(k, _)| k.clone());
328 if let Some(ref vk) = victim
329 && let Some(pool) = inner.pools.get_mut(vk)
330 {
331 pool.idle.pop_front();
332 }
333 victim.is_some()
334 }
335
336 pub(in crate::pool) fn discard_internal(&self, key: &PoolKey, id: ConnId) {
337 {
338 let mut inner = self.inner.lock();
339 if let Some(pool) = inner.pools.get_mut(key) {
340 pool.active.remove(&id);
341 }
342 }
343 self.wake_one_for_node(key);
344 }
345}
346
347fn record_checkout_success(
348 key: &PoolKey,
349 checkout_start: Instant,
350 queue_start: Option<Instant>,
351 database: &str,
352 user: &str,
353 routing: Routing,
354 reused: bool,
355) {
356 if let Some(queued_at) = queue_start {
357 o11y::metrics::record_wait_duration(queued_at.elapsed(), database, user, routing);
358 }
359 o11y::metrics::record_checkout(checkout_start, database, user, &key.node);
360 let span = tracing::Span::current();
361 span.record("pool.reused", reused);
362 span.record("pool.waited", queue_start.is_some());
363 debug!(database, user, node = %key.node, reused, "checkout complete");
364}