dbkit-sql 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. dbkit/__init__.py +77 -0
  2. dbkit/_async/__init__.py +17 -0
  3. dbkit/_async/_compat.py +111 -0
  4. dbkit/_async/connection.py +328 -0
  5. dbkit/_async/database.py +884 -0
  6. dbkit/_async/engine.py +232 -0
  7. dbkit/_async/executor.py +329 -0
  8. dbkit/_async/health.py +53 -0
  9. dbkit/_async/resilience.py +148 -0
  10. dbkit/_async/streaming.py +137 -0
  11. dbkit/_async/transaction.py +264 -0
  12. dbkit/_core/__init__.py +1 -0
  13. dbkit/_core/bulk.py +91 -0
  14. dbkit/_core/circuit.py +130 -0
  15. dbkit/_core/config.py +613 -0
  16. dbkit/_core/errors/__init__.py +74 -0
  17. dbkit/_core/errors/base.py +344 -0
  18. dbkit/_core/errors/classifier.py +138 -0
  19. dbkit/_core/errors/redaction.py +96 -0
  20. dbkit/_core/errors/sqlstate.py +74 -0
  21. dbkit/_core/idempotency_lint.py +57 -0
  22. dbkit/_core/keys.py +29 -0
  23. dbkit/_core/policies.py +105 -0
  24. dbkit/_core/query.py +142 -0
  25. dbkit/_core/result.py +109 -0
  26. dbkit/_core/routing.py +248 -0
  27. dbkit/_pool.py +202 -0
  28. dbkit/_sync/__init__.py +20 -0
  29. dbkit/_sync/_compat.py +82 -0
  30. dbkit/_sync/connection.py +331 -0
  31. dbkit/_sync/database.py +887 -0
  32. dbkit/_sync/engine.py +235 -0
  33. dbkit/_sync/executor.py +332 -0
  34. dbkit/_sync/health.py +56 -0
  35. dbkit/_sync/resilience.py +151 -0
  36. dbkit/_sync/streaming.py +140 -0
  37. dbkit/_sync/transaction.py +267 -0
  38. dbkit/cli/__init__.py +1 -0
  39. dbkit/cli/main.py +256 -0
  40. dbkit/errors.py +6 -0
  41. dbkit/integrations/__init__.py +21 -0
  42. dbkit/integrations/batch.py +81 -0
  43. dbkit/integrations/inbox.py +153 -0
  44. dbkit/observability/__init__.py +21 -0
  45. dbkit/observability/logging.py +154 -0
  46. dbkit/observability/metrics.py +110 -0
  47. dbkit/observability/otel_metrics.py +69 -0
  48. dbkit/observability/prometheus.py +78 -0
  49. dbkit/observability/tracing.py +128 -0
  50. dbkit/postgres/__init__.py +1 -0
  51. dbkit/postgres/copy.py +77 -0
  52. dbkit/postgres/pipeline.py +48 -0
  53. dbkit/postgres/unnest.py +73 -0
  54. dbkit/testing/__init__.py +1 -0
  55. dbkit_sql-0.1.0.dist-info/METADATA +555 -0
  56. dbkit_sql-0.1.0.dist-info/RECORD +59 -0
  57. dbkit_sql-0.1.0.dist-info/WHEEL +4 -0
  58. dbkit_sql-0.1.0.dist-info/entry_points.txt +2 -0
  59. dbkit_sql-0.1.0.dist-info/licenses/LICENSE +21 -0
dbkit/_async/engine.py ADDED
@@ -0,0 +1,232 @@
1
+ """Async engine registry (§9).
2
+
3
+ One :class:`~sqlalchemy.ext.asyncio.AsyncEngine` per unique
4
+ ``environment:database:shard:role:driver`` key, created lazily and disposed on shutdown.
5
+ SQLAlchemy owns pooling and dialects; this module just keys, builds, instruments, and caps
6
+ engines.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import asyncio
12
+ import time
13
+ from dataclasses import dataclass, field
14
+ from typing import Any
15
+
16
+ from sqlalchemy import NullPool
17
+ from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
18
+
19
+ from .._core.config import DbkitConfig, PoolConfig, TargetConfig
20
+ from .._core.errors import DatabaseConfigurationError, DatabaseRoutingError
21
+ from .._core.keys import EngineKey
22
+ from .._core.routing import ResolvedRoute
23
+ from .._pool import PoolInstrumentation, PoolSnapshot
24
+ from ..observability import metrics as m
25
+ from ..observability.metrics import MetricsSink, NoopMetrics
26
+ from ._compat import sync_engine_of
27
+
28
+
29
+ @dataclass
30
+ class EngineEntry:
31
+ """One cached engine plus the bookkeeping :class:`AsyncEngineRegistry` needs for it."""
32
+
33
+ key: EngineKey
34
+ engine: AsyncEngine
35
+ target: TargetConfig
36
+ instrumentation: PoolInstrumentation
37
+ labels: dict[str, str]
38
+ last_used: float = field(default_factory=time.monotonic)
39
+
40
+ def snapshot(self) -> PoolSnapshot:
41
+ """This engine's current connection-pool snapshot."""
42
+ return self.instrumentation.snapshot(sync_engine_of(self.engine).pool)
43
+
44
+
45
+ def _connect_args(target: TargetConfig, pool: PoolConfig) -> dict[str, Any]:
46
+ driver = target.driver
47
+ if driver in ("psycopg", "psycopg2"):
48
+ args: dict[str, Any] = {"connect_timeout": int(max(pool.connect_timeout_seconds, 1))}
49
+ if pool.pgbouncer_compatible:
50
+ # Disable server-side prepared-statement autoprep — required under PgBouncer
51
+ # transaction pooling, where a connection may hit a different backend each
52
+ # transaction (§ pgbouncer_compatible docstring on PoolConfig).
53
+ args["prepare_threshold"] = None
54
+ return args
55
+ if driver == "asyncpg":
56
+ # asyncpg names its connection establishment timeout "timeout".
57
+ args = {"timeout": pool.connect_timeout_seconds}
58
+ if pool.pgbouncer_compatible:
59
+ args["statement_cache_size"] = 0
60
+ return args
61
+ return {}
62
+
63
+
64
+ class AsyncEngineRegistry:
65
+ """Creates and caches engines; enforces a maximum engine count (§9, §22.4).
66
+
67
+ When ``max_engines`` is set and ``evict_lru`` is True, reaching the cap evicts (disposes)
68
+ the least-recently-used engine instead of failing — the pattern for dynamic per-tenant
69
+ databases where the number of distinct tenants ever seen may be unbounded, but only a
70
+ bounded number should have live connections at once. The default (``evict_lru=False``)
71
+ is a hard cap: exceeding it is a configuration error, not a silent eviction.
72
+ """
73
+
74
+ def __init__(
75
+ self,
76
+ config: DbkitConfig,
77
+ *,
78
+ metrics: MetricsSink | None = None,
79
+ max_engines: int | None = None,
80
+ evict_lru: bool = False,
81
+ ) -> None:
82
+ """A registry backed by ``config``, empty until :meth:`get` creates engines lazily."""
83
+ self._config = config
84
+ self._metrics = metrics or NoopMetrics()
85
+ self._max_engines = max_engines
86
+ self._evict_lru = evict_lru
87
+ self._entries: dict[str, EngineEntry] = {}
88
+ self._lock = asyncio.Lock()
89
+
90
+ @property
91
+ def count(self) -> int:
92
+ """Number of currently live engines."""
93
+ return len(self._entries)
94
+
95
+ def _target_for(self, route: ResolvedRoute) -> TargetConfig:
96
+ db = self._config.databases.get(route.database)
97
+ if db is None:
98
+ raise DatabaseRoutingError(f"unknown database {route.database!r}")
99
+ if route.role == "replica":
100
+ for r in db.replicas:
101
+ if r.name == route.replica_name:
102
+ return r
103
+ raise DatabaseRoutingError(
104
+ f"unknown replica {route.replica_name!r} for database {route.database!r}"
105
+ )
106
+ return db.primary
107
+
108
+ def _key_for(self, route: ResolvedRoute, target: TargetConfig) -> EngineKey:
109
+ role = "primary" if route.role == "primary" else f"replica:{route.replica_name}"
110
+ return EngineKey(
111
+ environment=self._config.environment,
112
+ database=route.database,
113
+ shard_id=route.shard_id,
114
+ role=role,
115
+ driver=target.driver,
116
+ )
117
+
118
+ def _build_engine(self, target: TargetConfig) -> AsyncEngine:
119
+ pool = target.resolved_pool(self._config.defaults)
120
+ kwargs: dict[str, Any] = {
121
+ "connect_args": _connect_args(target, pool),
122
+ "pool_pre_ping": pool.pre_ping,
123
+ }
124
+ if pool.disable_pooling:
125
+ kwargs["poolclass"] = NullPool
126
+ else:
127
+ reset = None if pool.reset_on_return in (None, "none") else pool.reset_on_return
128
+ kwargs.update(
129
+ pool_size=pool.size,
130
+ max_overflow=pool.max_overflow,
131
+ pool_timeout=pool.timeout_seconds,
132
+ pool_recycle=pool.recycle_seconds,
133
+ pool_use_lifo=pool.use_lifo,
134
+ pool_reset_on_return=reset,
135
+ )
136
+ try:
137
+ return create_async_engine(target.url, **kwargs)
138
+ except Exception as exc:
139
+ raise DatabaseConfigurationError(
140
+ f"failed to create engine for {target.name!r}: {exc}"
141
+ ) from exc
142
+
143
+ async def get(self, route: ResolvedRoute) -> EngineEntry:
144
+ """The cached engine for ``route``, creating (and, if needed, evicting) one lazily."""
145
+ target = self._target_for(route)
146
+ key = self._key_for(route, target)
147
+ key_str = str(key)
148
+ entry = self._entries.get(key_str)
149
+ if entry is not None:
150
+ entry.last_used = time.monotonic()
151
+ return entry
152
+ victim: EngineEntry | None = None
153
+ async with self._lock:
154
+ entry = self._entries.get(key_str) # double-checked
155
+ if entry is None:
156
+ if self._max_engines is not None and len(self._entries) >= self._max_engines:
157
+ if not self._evict_lru:
158
+ raise DatabaseConfigurationError(
159
+ f"engine limit reached ({self._max_engines}); cannot create {key_str!r}"
160
+ )
161
+ # Pop the victim under the lock, but dispose it *after* releasing the lock
162
+ # (below) — disposing while holding the lock would block every concurrent
163
+ # get() that only misses the fast path on I/O it has nothing to do with
164
+ # (performance review §2 Finding #4).
165
+ victim = self._pop_lru_locked()
166
+ labels = {
167
+ "environment": key.environment,
168
+ "database": key.database,
169
+ "shard": key.shard_id,
170
+ "role": key.role,
171
+ }
172
+ engine = self._build_engine(target)
173
+ pool = target.resolved_pool(self._config.defaults)
174
+ instrumentation = PoolInstrumentation(
175
+ key=key_str,
176
+ labels=labels,
177
+ long_hold_warning_seconds=pool.long_hold_warning_seconds,
178
+ metrics=self._metrics,
179
+ )
180
+ instrumentation.attach(sync_engine_of(engine))
181
+ entry = EngineEntry(
182
+ key=key,
183
+ engine=engine,
184
+ target=target,
185
+ instrumentation=instrumentation,
186
+ labels=labels,
187
+ )
188
+ self._entries[key_str] = entry
189
+ entry.last_used = time.monotonic()
190
+ if victim is not None:
191
+ await victim.engine.dispose()
192
+ self._metrics.incr(m.CONN_CLOSED, labels=victim.labels)
193
+ return entry
194
+
195
+ def _pop_lru_locked(self) -> EngineEntry | None:
196
+ """Pop (but don't dispose) the least-recently-used engine. Caller must hold
197
+ ``self._lock``; the caller is responsible for disposing the popped engine after
198
+ releasing the lock."""
199
+ if not self._entries:
200
+ return None
201
+ oldest_key = min(self._entries, key=lambda k: self._entries[k].last_used)
202
+ return self._entries.pop(oldest_key)
203
+
204
+ def snapshots(self) -> list[PoolSnapshot]:
205
+ """A pool snapshot for every currently live engine."""
206
+ return [entry.snapshot() for entry in self._entries.values()]
207
+
208
+ async def dispose_all(self) -> None:
209
+ """Dispose every engine and clear the registry (called by ``AsyncDatabase.close``)."""
210
+ async with self._lock:
211
+ entries = list(self._entries.values())
212
+ self._entries.clear()
213
+ for entry in entries:
214
+ await entry.engine.dispose()
215
+
216
+ async def dispose_one(self, key: str) -> bool:
217
+ """Dispose one engine by its snapshot key (e.g. ``"env:database:shard:role:driver"``, as
218
+ printed by :meth:`snapshots`/``dbkit pools``), forcing subsequent calls to rebuild it
219
+ with fresh connections. Returns ``False`` if no live engine has that key.
220
+
221
+ Only closes idle pooled connections, exactly like the LRU-eviction path
222
+ (:meth:`_pop_lru_locked`) — a connection already checked out by another in-flight
223
+ coroutine keeps working until the caller releases it (verified by the same regression
224
+ test covering LRU eviction under concurrent use).
225
+ """
226
+ async with self._lock:
227
+ entry = self._entries.pop(key, None)
228
+ if entry is None:
229
+ return False
230
+ await entry.engine.dispose()
231
+ self._metrics.incr(m.CONN_CLOSED, labels=entry.labels)
232
+ return True
@@ -0,0 +1,329 @@
1
+ """Resilience-orchestration collaborator for :class:`~dbkit._async.database.AsyncDatabase`
2
+ (§11.1, §14, §16, §17).
3
+
4
+ Extracted from the facade so it stays a thin dispatcher over fetch/execute/bulk/stream/
5
+ transaction methods, each delegating the actual "acquire a connection and run one statement,
6
+ with concurrency limits + circuit breaker + retries" mechanics to one focused collaborator —
7
+ mirroring how bulk writes, streaming, and transactions already live in their own modules. This
8
+ module owns exactly what the facade's own ``# -- resilience --`` / ``# -- acquisition --``
9
+ section comments already called out as one boundary; nothing here changes behavior, only where
10
+ the code lives.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import contextlib
16
+ import time
17
+ from collections.abc import AsyncIterator, Awaitable, Callable
18
+ from typing import Any
19
+
20
+ from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
21
+
22
+ from .._core.circuit import CircuitBreaker
23
+ from .._core.config import DbkitConfig
24
+ from .._core.errors import (
25
+ DatabaseCommitUnknownError,
26
+ DatabaseError,
27
+ classify,
28
+ is_connection_error,
29
+ )
30
+ from .._core.policies import effective_timeout
31
+ from .._core.query import Query
32
+ from .._core.routing import DatabaseTarget, ResolvedRoute
33
+ from ..observability import logging as obslog
34
+ from ..observability import metrics as m
35
+ from ..observability.metrics import MetricsSink
36
+ from ..observability.tracing import Tracer
37
+ from ._compat import API_LABEL
38
+ from .connection import AsyncConnectionScope
39
+ from .engine import AsyncEngineRegistry, EngineEntry
40
+ from .resilience import ConcurrencyLimiter, run_with_retries
41
+
42
+
43
+ class ResilientExecutor:
44
+ """Resolves a target to an engine, acquires a connection, and runs one statement under
45
+ the configured concurrency limits, circuit breaker, and retry policy.
46
+
47
+ ``resolve`` is injected (rather than this class doing its own routing) because routing
48
+ (shard/replica selection, the read-your-writes override) is a facade concern, not a
49
+ resilience one — this collaborator only needs "given a target, which route/engine."
50
+ """
51
+
52
+ def __init__(
53
+ self,
54
+ config: DbkitConfig,
55
+ *,
56
+ registry: AsyncEngineRegistry,
57
+ resolve: Callable[[DatabaseTarget], ResolvedRoute],
58
+ metrics: MetricsSink,
59
+ tracer: Tracer,
60
+ ) -> None:
61
+ self._config = config
62
+ self._registry = registry
63
+ self._resolve = resolve
64
+ self._metrics = metrics
65
+ self._tracer = tracer
66
+ self._breakers: dict[str, CircuitBreaker] = {}
67
+ self._limiters: dict[str, ConcurrencyLimiter] = {}
68
+
69
+ # -- routing lookup ------------------------------------------------------------- #
70
+
71
+ async def entry(self, target: DatabaseTarget) -> tuple[EngineEntry, ResolvedRoute]:
72
+ """The engine entry and resolved route for ``target``, creating the engine if needed."""
73
+ route = self._resolve(target)
74
+ entry = await self._registry.get(route)
75
+ return entry, route
76
+
77
+ def labels(self, entry: EngineEntry, query_name: str, operation: str) -> dict[str, str]:
78
+ """The metrics/tracing label set for one operation against ``entry``."""
79
+ return {
80
+ "environment": entry.key.environment,
81
+ "database": entry.key.database,
82
+ "shard": entry.key.shard_id,
83
+ "role": entry.key.role,
84
+ "query_name": query_name,
85
+ "operation": operation,
86
+ "api": API_LABEL,
87
+ }
88
+
89
+ @staticmethod
90
+ def is_postgres(entry: EngineEntry) -> bool:
91
+ """Whether ``entry``'s target dialect is PostgreSQL."""
92
+ return entry.target.dialect == "postgresql"
93
+
94
+ @staticmethod
95
+ def query_meta(query: object) -> tuple[str, str, Query | None]:
96
+ """``(query_name, operation, Query | None)`` for a caller-supplied query object."""
97
+ if isinstance(query, Query):
98
+ return query.name, query.operation, query
99
+ return "adhoc", "read", None
100
+
101
+ # -- resilience ------------------------------------------------------------------ #
102
+
103
+ def breaker_for(self, entry: EngineEntry) -> CircuitBreaker | None:
104
+ """One circuit breaker per db+shard+role, created lazily if enabled (§16)."""
105
+ cb = self._config.defaults.circuit_breaker
106
+ if not cb.enabled:
107
+ return None
108
+ key = str(entry.key)
109
+ breaker = self._breakers.get(key)
110
+ if breaker is None:
111
+ breaker = CircuitBreaker(
112
+ failure_threshold=cb.failure_threshold,
113
+ window_seconds=cb.window_seconds,
114
+ open_seconds=cb.open_seconds,
115
+ half_open_max_calls=cb.half_open_max_calls,
116
+ )
117
+ self._breakers[key] = breaker
118
+ return breaker
119
+
120
+ def limiter_for(self, database: str) -> ConcurrencyLimiter:
121
+ """One concurrency limiter per named database, from its concurrency config (§17)."""
122
+ limiter = self._limiters.get(database)
123
+ if limiter is None:
124
+ cc = self._config.databases[database].concurrency
125
+ limiter = ConcurrencyLimiter(
126
+ {
127
+ "database": cc.database,
128
+ "reads": cc.reads,
129
+ "writes": cc.writes,
130
+ "bulk": cc.bulk_writes,
131
+ "expensive": cc.expensive_queries,
132
+ }
133
+ )
134
+ self._limiters[database] = limiter
135
+ return limiter
136
+
137
+ async def execute_with_resilience(
138
+ self,
139
+ target: DatabaseTarget,
140
+ query: object,
141
+ op: Callable[[AsyncConnectionScope], Awaitable[Any]],
142
+ *,
143
+ commit: bool,
144
+ timeout: float | None,
145
+ deadline: float | None,
146
+ ) -> Any:
147
+ """Run ``op`` under concurrency limiting, circuit breaking, and retries (§14, §16, §17).
148
+
149
+ Concurrency is acquired *inside* each attempt (before pool checkout) so queueing
150
+ happens in cheap waiters and a retry backoff does not hold a slot.
151
+ """
152
+ entry, _route = await self.entry(target)
153
+ query_name, operation, q = self.query_meta(query)
154
+ labels = self.labels(entry, query_name, operation)
155
+ breaker = self.breaker_for(entry)
156
+ limiter = self.limiter_for(entry.key.database)
157
+ tier = "writes" if (q and q.is_write) else "reads"
158
+
159
+ async def attempt() -> Any:
160
+ # Bound the concurrency-limiter wait by the same effective timeout the query
161
+ # itself would get, so a saturated tier fails with a classified error instead of
162
+ # queueing invisibly forever (§17).
163
+ limiter_timeout = effective_timeout(
164
+ timeout, q, self._config.defaults.query_timeout_seconds, deadline, time.monotonic()
165
+ )
166
+ async with contextlib.AsyncExitStack() as stack:
167
+ await stack.enter_async_context(
168
+ limiter.acquire("database", timeout=limiter_timeout)
169
+ )
170
+ await stack.enter_async_context(limiter.acquire(tier, timeout=limiter_timeout))
171
+ if q is not None and q.expensive:
172
+ # A separate, additional tier for a small number of known-heavy queries
173
+ # (§17) — acquired on top of the normal reads/writes tier, not instead of
174
+ # it, so an expensive query still counts against ordinary capacity too.
175
+ await stack.enter_async_context(
176
+ limiter.acquire("expensive", timeout=limiter_timeout)
177
+ )
178
+ scope = await stack.enter_async_context(
179
+ self.scope(
180
+ target,
181
+ query,
182
+ call_timeout=timeout,
183
+ deadline=deadline,
184
+ commit=commit,
185
+ entry=entry,
186
+ labels=labels,
187
+ )
188
+ )
189
+ return await op(scope)
190
+
191
+ return await run_with_retries(
192
+ attempt,
193
+ query=q,
194
+ retry=self._config.defaults.retry,
195
+ breaker=breaker,
196
+ metrics=self._metrics,
197
+ labels=labels,
198
+ deadline=deadline,
199
+ )
200
+
201
+ # -- acquisition ------------------------------------------------------------------ #
202
+
203
+ @contextlib.asynccontextmanager
204
+ async def scope(
205
+ self,
206
+ target: DatabaseTarget,
207
+ query: object,
208
+ *,
209
+ call_timeout: float | None,
210
+ deadline: float | None,
211
+ commit: bool,
212
+ entry: EngineEntry | None = None,
213
+ labels: dict[str, str] | None = None,
214
+ ) -> AsyncIterator[AsyncConnectionScope]:
215
+ """Acquire a short-lived connection scope, measure pool wait, emit metrics (§11.1).
216
+
217
+ ``entry``/``labels`` let a caller that already resolved them (``execute_with_resilience``,
218
+ which needs them itself for the breaker/limiter/retry-labels) pass them straight through
219
+ instead of this method redoing the registry lookup and rebuilding an identical labels
220
+ dict a second time per operation (performance review §4/§11 Finding #5). Callers that
221
+ invoke ``scope()`` directly (``db.connection()``, ``db.transaction()``, bulk executemany)
222
+ don't have them yet, so both remain optional and are resolved here when omitted.
223
+ """
224
+ if entry is None:
225
+ entry, _route = await self.entry(target)
226
+ query_name, operation, q = self.query_meta(query)
227
+ if labels is None:
228
+ labels = self.labels(entry, query_name, operation)
229
+ timeout = effective_timeout(
230
+ call_timeout,
231
+ q,
232
+ self._config.defaults.query_timeout_seconds,
233
+ deadline,
234
+ time.monotonic(),
235
+ )
236
+
237
+ with self._tracer.span(
238
+ f"dbkit.{operation}",
239
+ operation_type=operation,
240
+ query_name=query_name,
241
+ database=entry.key.database,
242
+ shard=entry.key.shard_id,
243
+ role=entry.key.role,
244
+ ) as span:
245
+ wait_start = time.monotonic()
246
+ conn = await self.acquire(entry.engine, labels, query_name)
247
+ pool_wait = time.monotonic() - wait_start
248
+ self._metrics.observe(m.POOL_WAIT_SECONDS, pool_wait, labels=labels)
249
+ span.set_attribute("db.pool.wait_ms", pool_wait * 1000)
250
+
251
+ scope = AsyncConnectionScope(
252
+ conn,
253
+ is_postgres=self.is_postgres(entry),
254
+ default_timeout=timeout,
255
+ database=entry.key.database,
256
+ shard_id=entry.key.shard_id,
257
+ role=entry.key.role,
258
+ )
259
+ op_start = time.monotonic()
260
+ try:
261
+ yield scope
262
+ except BaseException as exc:
263
+ with contextlib.suppress(Exception):
264
+ await conn.rollback()
265
+ if isinstance(exc, DatabaseError):
266
+ self._metrics.incr(
267
+ m.OP_ERRORS, labels={**labels, "error_category": exc.category.value}
268
+ )
269
+ raise
270
+ else:
271
+ if commit:
272
+ try:
273
+ await conn.commit()
274
+ except BaseException as commit_exc:
275
+ # Mirror _AsyncTransactionManager._commit(): a failure during COMMIT
276
+ # may mean the write committed anyway (§15) — never silently swallow
277
+ # that ambiguity, and never leave the exception unclassified either
278
+ # (both would previously happen only on this auto-commit write path).
279
+ if is_connection_error(commit_exc):
280
+ err: DatabaseError = DatabaseCommitUnknownError(
281
+ "connection failed during COMMIT; transaction outcome is unknown",
282
+ original=commit_exc,
283
+ database_name=entry.key.database,
284
+ shard_id=entry.key.shard_id,
285
+ role=entry.key.role,
286
+ query_name=query_name,
287
+ )
288
+ else:
289
+ with contextlib.suppress(Exception):
290
+ await conn.rollback()
291
+ err = classify(
292
+ commit_exc,
293
+ query_name=query_name,
294
+ database_name=entry.key.database,
295
+ role=entry.key.role,
296
+ )
297
+ self._metrics.incr(
298
+ m.OP_ERRORS, labels={**labels, "error_category": err.category.value}
299
+ )
300
+ raise err from commit_exc
301
+ finally:
302
+ duration = time.monotonic() - op_start
303
+ with contextlib.suppress(Exception):
304
+ await conn.close()
305
+ self._metrics.incr(m.OP_TOTAL, labels=labels)
306
+ self._metrics.observe(m.OP_DURATION, duration, labels=labels)
307
+ if duration * 1000 >= self._config.defaults.observability.slow_query_ms:
308
+ obslog.slow_query_warning(
309
+ query_name=query_name,
310
+ duration_ms=duration * 1000,
311
+ threshold_ms=self._config.defaults.observability.slow_query_ms,
312
+ database=entry.key.database,
313
+ pool_wait_ms=pool_wait * 1000,
314
+ )
315
+
316
+ async def acquire(
317
+ self, engine: AsyncEngine, labels: dict[str, str], query_name: str
318
+ ) -> AsyncConnection:
319
+ """Check out a connection, classifying any failure; tags it for leak diagnostics."""
320
+ try:
321
+ conn = await engine.connect()
322
+ except Exception as exc:
323
+ err = classify(exc, query_name=query_name, database_name=labels.get("database"))
324
+ self._metrics.incr(m.OP_ERRORS, labels={**labels, "error_category": err.category.value})
325
+ raise err from exc
326
+ # Best-effort context tag for leak diagnostics (§10.5).
327
+ with contextlib.suppress(Exception):
328
+ conn.info["dbkit_context"] = query_name
329
+ return conn
dbkit/_async/health.py ADDED
@@ -0,0 +1,53 @@
1
+ """Liveness and readiness checks (§26).
2
+
3
+ Liveness verifies the process/event loop is functioning and must not require any database.
4
+ Readiness verifies that *required* database targets answer a trivial ``SELECT 1`` within a
5
+ strict, short timeout.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass, field
11
+
12
+ from sqlalchemy import text
13
+ from sqlalchemy.ext.asyncio import AsyncEngine
14
+
15
+ from .._core.errors import classify
16
+ from ._compat import timeout_scope
17
+
18
+
19
+ @dataclass
20
+ class TargetHealth:
21
+ """Readiness result for one required target."""
22
+
23
+ key: str
24
+ healthy: bool
25
+ error: str | None = None
26
+
27
+
28
+ @dataclass
29
+ class HealthReport:
30
+ """The overall result of :meth:`~dbkit.AsyncDatabase.health`."""
31
+
32
+ live: bool
33
+ ready: bool
34
+ targets: list[TargetHealth] = field(default_factory=list)
35
+
36
+ def to_dict(self) -> dict[str, object]:
37
+ """A JSON-serializable representation, e.g. for the CLI/HTTP health endpoint."""
38
+ return {
39
+ "live": self.live,
40
+ "ready": self.ready,
41
+ "targets": [
42
+ {"key": t.key, "healthy": t.healthy, "error": t.error} for t in self.targets
43
+ ],
44
+ }
45
+
46
+
47
+ async def ping(engine: AsyncEngine, *, timeout: float) -> None:
48
+ """Run ``SELECT 1`` with a strict timeout; raises a classified error on failure (§26.3)."""
49
+ try:
50
+ async with timeout_scope(timeout), engine.connect() as conn:
51
+ await conn.execute(text("SELECT 1"))
52
+ except Exception as exc:
53
+ raise classify(exc) from exc