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
@@ -0,0 +1,151 @@
1
+ # This file is GENERATED from ../_async/resilience.py by tools/run_unasync.py.
2
+ # Do not edit by hand. Run `make unasync` after changing the async source.
3
+
4
+ """Retry executor and concurrency limiter (§14, §17).
5
+
6
+ The retry *decisions* (idempotency gating, backoff shape) live in the pure ``_core.policies``
7
+ module; this is the async loop that applies them, respects the caller deadline, and drives the
8
+ circuit breaker. The concurrency limiter bounds how many operations may use the database at
9
+ once, independently of pool size — and is acquired *before* pool checkout so queueing happens
10
+ in cheap asyncio waiters, not held connections (§17).
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import contextlib
16
+ import random
17
+ import time
18
+ from collections.abc import Iterator, Awaitable, Callable
19
+ from typing import TypeVar
20
+
21
+ from .._core.circuit import CircuitBreaker, CircuitState, counts_as_failure
22
+ from .._core.config import RetryConfig
23
+ from .._core.errors import DatabaseCircuitOpenError, DatabaseError, DatabaseOverloadedError
24
+ from .._core.policies import backoff_delay_ms, should_retry
25
+ from .._core.query import Query
26
+ from ..observability import metrics as m
27
+ from ..observability.metrics import MetricsSink
28
+ from ._compat import semaphore_acquire, sleep
29
+
30
+ T = TypeVar("T")
31
+
32
+ #: Numeric value of each circuit-breaker state, for the ``CIRCUIT_STATE`` gauge (§16).
33
+ _CIRCUIT_STATE_VALUE = {
34
+ CircuitState.CLOSED: 0.0,
35
+ CircuitState.HALF_OPEN: 1.0,
36
+ CircuitState.OPEN: 2.0,
37
+ }
38
+
39
+
40
+ def _emit_circuit_state(
41
+ breaker: CircuitBreaker, now: float, metrics: MetricsSink, labels: dict[str, str]
42
+ ) -> None:
43
+ metrics.gauge(m.CIRCUIT_STATE, _CIRCUIT_STATE_VALUE[breaker.state(now)], labels=labels)
44
+
45
+
46
+ def run_with_retries(
47
+ operation: Callable[[], Awaitable[T]],
48
+ *,
49
+ query: Query | None,
50
+ retry: RetryConfig,
51
+ breaker: CircuitBreaker | None,
52
+ metrics: MetricsSink,
53
+ labels: dict[str, str],
54
+ idempotent_override: bool | None = None,
55
+ deadline: float | None = None,
56
+ ) -> T:
57
+ """Run ``operation`` with conservative, idempotency-gated retries (§14).
58
+
59
+ Each attempt runs a *fresh* operation (new connection/transaction) — the caller supplies a
60
+ thunk that re-does the work. Non-retryable errors, exhausted budgets, unknown-commit
61
+ outcomes, and non-idempotent writes propagate immediately.
62
+
63
+ Total time spent retrying (backoff delays only, not attempt execution time) is bounded by
64
+ ``retry.maximum_total_ms`` regardless of ``attempts``/``deadline`` — without this, a caller
65
+ with a generous ``attempts`` count and no explicit ``deadline`` has no bound on how long a
66
+ single logical call can spend retrying (performance review §5/§7).
67
+ """
68
+ attempt = 0
69
+ started = time.monotonic()
70
+ while True:
71
+ attempt += 1
72
+ now = time.monotonic()
73
+ if breaker is not None:
74
+ allowed = breaker.allow(now)
75
+ _emit_circuit_state(breaker, now, metrics, labels)
76
+ if not allowed:
77
+ raise DatabaseCircuitOpenError(
78
+ "circuit is open for this target",
79
+ database_name=labels.get("database"),
80
+ role=labels.get("role"),
81
+ query_name=labels.get("query_name"),
82
+ )
83
+ try:
84
+ result = operation()
85
+ except DatabaseError as err:
86
+ if breaker is not None:
87
+ if counts_as_failure(err):
88
+ breaker.on_failure(time.monotonic())
89
+ _emit_circuit_state(breaker, time.monotonic(), metrics, labels)
90
+ if not should_retry(
91
+ err,
92
+ query=query,
93
+ config=retry,
94
+ attempt=attempt,
95
+ idempotent_override=idempotent_override,
96
+ ):
97
+ raise
98
+ delay = backoff_delay_ms(attempt, retry, rand=random.random()) / 1000.0
99
+ # never sleep past the caller deadline
100
+ if deadline is not None and time.monotonic() + delay >= deadline:
101
+ raise
102
+ # never sleep past the retry budget, independent of any caller deadline
103
+ elapsed_ms = (time.monotonic() - started) * 1000.0
104
+ if elapsed_ms + delay * 1000.0 >= retry.maximum_total_ms:
105
+ raise
106
+ metrics.incr(m.OP_RETRIES, labels={**labels, "retry_attempt": str(attempt)})
107
+ sleep(delay)
108
+ continue
109
+ else:
110
+ if breaker is not None:
111
+ breaker.on_success(time.monotonic())
112
+ _emit_circuit_state(breaker, time.monotonic(), metrics, labels)
113
+ return result
114
+
115
+
116
+ class ConcurrencyLimiter:
117
+ """Per-tier semaphores bounding concurrent database use (§17).
118
+
119
+ Tiers: ``"database"`` (overall), ``"reads"``, ``"writes"``, ``"bulk"``. A tier with no
120
+ configured limit is unbounded (a no-op context).
121
+ """
122
+
123
+ def __init__(self, limits: dict[str, int | None]) -> None:
124
+ """``limits`` maps tier name to its cap; a missing/``None``/``<=0`` limit is unbounded."""
125
+ # threading.Semaphore in the async build; threading.Semaphore after unasync.
126
+ import threading
127
+
128
+ self._sems: dict[str, threading.Semaphore] = {
129
+ tier: threading.Semaphore(n) for tier, n in limits.items() if n and n > 0
130
+ }
131
+
132
+ @contextlib.contextmanager
133
+ def acquire(self, tier: str, *, timeout: float | None = None) -> Iterator[None]:
134
+ """Hold one slot of ``tier`` for the block's duration (no-op if unbounded).
135
+
136
+ Raises :class:`DatabaseOverloadedError` if no slot frees up within ``timeout`` —
137
+ without this bound, a saturated tier would queue callers indefinitely, invisibly to
138
+ dbkit's own timeout/deadline machinery (§17).
139
+ """
140
+ sem = self._sems.get(tier)
141
+ if sem is None:
142
+ yield
143
+ return
144
+ if not semaphore_acquire(sem, timeout):
145
+ raise DatabaseOverloadedError(
146
+ f"concurrency limit reached for tier {tier!r}; no slot freed up within {timeout}s"
147
+ )
148
+ try:
149
+ yield
150
+ finally:
151
+ sem.release()
@@ -0,0 +1,140 @@
1
+ # This file is GENERATED from ../_async/streaming.py by tools/run_unasync.py.
2
+ # Do not edit by hand. Run `make unasync` after changing the async source.
3
+
4
+ """Streaming large result sets without loading them into memory (§20).
5
+
6
+ ``ResultStream`` holds one connection for the lifetime of the stream and pulls rows from a
7
+ server-side cursor in bounded batches. It is both an async context manager (guaranteeing the
8
+ connection is released) and an async iterator. Because a stream holds its connection across
9
+ many yields, it deliberately bypasses the retry wrapper — a partially consumed stream cannot be
10
+ transparently restarted.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import contextlib
16
+ import time
17
+ from typing import Any
18
+
19
+ from sqlalchemy import Connection, Engine
20
+
21
+ from .._core import result as result_mod
22
+ from .._core.errors import DatabaseQueryTimeoutError, classify
23
+ from .._core.query import Statement
24
+ from ..observability import metrics as m
25
+ from ..observability.metrics import MetricsSink
26
+ from ..observability.tracing import Tracer
27
+ from ._compat import stream_mappings
28
+
29
+
30
+ class ResultStream:
31
+ """A bounded, connection-owning async row stream."""
32
+
33
+ def __init__(
34
+ self,
35
+ engine: Engine,
36
+ statement: Statement,
37
+ params: Any,
38
+ *,
39
+ batch_size: int,
40
+ map_to: Any,
41
+ database: str,
42
+ role: str,
43
+ query_name: str,
44
+ metrics: MetricsSink,
45
+ labels: dict[str, str],
46
+ max_duration: float | None = None,
47
+ tracer: Tracer | None = None,
48
+ shard_id: str | None = None,
49
+ ) -> None:
50
+ """Constructed by ``Database.stream(...)``; not intended to be built directly."""
51
+ self._engine = engine
52
+ self._statement = statement
53
+ self._params = params
54
+ self._batch_size = batch_size
55
+ self._mapper = result_mod.build_mapper(map_to)
56
+ self._database = database
57
+ self._role = role
58
+ self._query_name = query_name
59
+ self._metrics = metrics
60
+ self._labels = labels
61
+ self._max_duration = max_duration
62
+ self._tracer = tracer
63
+ self._shard_id = shard_id
64
+ self._conn: Connection | None = None
65
+ self._gen: Any = None
66
+ self._count = 0
67
+ self._started_at = 0.0
68
+ self._span_cm: Any = None
69
+ self._span: Any = None
70
+
71
+ def __enter__(self) -> ResultStream:
72
+ """Open the underlying connection and server-side cursor."""
73
+ if self._tracer is not None:
74
+ self._span_cm = self._tracer.span(
75
+ "dbkit.stream",
76
+ operation_type="stream",
77
+ query_name=self._query_name,
78
+ database=self._database,
79
+ shard=self._shard_id,
80
+ role=self._role,
81
+ )
82
+ self._span = self._span_cm.__enter__()
83
+ try:
84
+ self._conn = self._engine.connect()
85
+ self._gen = stream_mappings(self._conn, self._statement, self._params, self._batch_size)
86
+ except Exception as exc:
87
+ self._cleanup()
88
+ raise classify(
89
+ exc, query_name=self._query_name, database_name=self._database, role=self._role
90
+ ) from exc
91
+ self._started_at = time.monotonic()
92
+ return self
93
+
94
+ def __iter__(self) -> ResultStream:
95
+ """Returns ``self`` — the stream is its own iterator."""
96
+ return self
97
+
98
+ def __next__(self) -> Any:
99
+ """The next mapped row, or raise :class:`StopIteration`/a timeout error."""
100
+ assert self._gen is not None
101
+ if (
102
+ self._max_duration is not None
103
+ and time.monotonic() - self._started_at > self._max_duration
104
+ ):
105
+ raise DatabaseQueryTimeoutError(
106
+ f"stream {self._query_name!r} exceeded max duration {self._max_duration}s",
107
+ query_name=self._query_name,
108
+ database_name=self._database,
109
+ role=self._role,
110
+ )
111
+ try:
112
+ row = self._gen.__next__()
113
+ except StopIteration:
114
+ self._metrics.observe(m.STREAM_ROWS, self._count, labels=self._labels)
115
+ raise
116
+ except Exception as exc:
117
+ raise classify(
118
+ exc, query_name=self._query_name, database_name=self._database, role=self._role
119
+ ) from exc
120
+ self._count += 1
121
+ return self._mapper(row)
122
+
123
+ def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
124
+ """Release the connection/cursor unconditionally; never suppresses the exception."""
125
+ self._cleanup()
126
+ if self._span_cm is not None:
127
+ if self._span is not None:
128
+ self._span.set_attribute("db.rows_affected", self._count)
129
+ self._span_cm.__exit__(exc_type, exc_val, exc_tb)
130
+ return False
131
+
132
+ def _cleanup(self) -> None:
133
+ if self._gen is not None:
134
+ with contextlib.suppress(Exception):
135
+ self._gen.close()
136
+ self._gen = None
137
+ if self._conn is not None:
138
+ with contextlib.suppress(Exception):
139
+ self._conn.close()
140
+ self._conn = None
@@ -0,0 +1,267 @@
1
+ # This file is GENERATED from ../_async/transaction.py by tools/run_unasync.py.
2
+ # Do not edit by hand. Run `make unasync` after changing the async source.
3
+
4
+ """Explicit transactions, savepoints, commit-unknown, and cancellation cleanup (§11.3-11.6, §15).
5
+
6
+ A transaction owns a single connection for its lifetime. Commit failures where the outcome is
7
+ uncertain surface as :class:`DatabaseCommitUnknownError` (§15). On cancellation the transaction
8
+ is rolled back, the connection invalidated, and the cancellation re-raised — never swallowed
9
+ (§12.3).
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import contextlib
15
+ import time
16
+ from collections.abc import Iterator
17
+ from typing import Any
18
+
19
+ from sqlalchemy import text
20
+ from sqlalchemy import Connection, Engine
21
+
22
+ from .._core.errors import (
23
+ DatabaseCommitUnknownError,
24
+ classify,
25
+ is_connection_error,
26
+ )
27
+ from ..observability import logging as obslog
28
+ from ..observability import metrics as m
29
+ from ..observability.metrics import MetricsSink, NoopMetrics
30
+ from ._compat import is_cancellation, shield_from_cancellation
31
+ from .connection import ConnectionScope, apply_statement_timeout_sql
32
+
33
+
34
+ class TransactionScope(ConnectionScope):
35
+ """A connection scope wrapped in an explicit transaction, with savepoint support."""
36
+
37
+ def __init__(
38
+ self,
39
+ conn: Connection,
40
+ *,
41
+ is_postgres: bool,
42
+ default_timeout: float | None,
43
+ database: str,
44
+ shard_id: str,
45
+ role: str,
46
+ ) -> None:
47
+ """Wrap an already-``BEGIN``'d connection; not constructed directly by applications."""
48
+ super().__init__(
49
+ conn,
50
+ is_postgres=is_postgres,
51
+ default_timeout=default_timeout,
52
+ database=database,
53
+ shard_id=shard_id,
54
+ role=role,
55
+ )
56
+
57
+ @contextlib.contextmanager
58
+ def savepoint(self) -> Iterator[TransactionScope]:
59
+ """A nested transaction (SAVEPOINT). Rolls back to the savepoint on error (§11.4)."""
60
+ nested = self._conn.begin_nested()
61
+ try:
62
+ yield self
63
+ except BaseException:
64
+ nested.rollback()
65
+ raise
66
+ else:
67
+ nested.commit()
68
+
69
+
70
+ class _TransactionManager:
71
+ """Async context manager implementing the transaction lifecycle (§11.1, §11.3)."""
72
+
73
+ def __init__(
74
+ self,
75
+ engine: Engine,
76
+ *,
77
+ is_postgres: bool,
78
+ default_timeout: float | None,
79
+ database: str,
80
+ shard_id: str,
81
+ role: str,
82
+ isolation: str | None,
83
+ read_only: bool,
84
+ timeout: float | None,
85
+ lock_timeout: float | None,
86
+ query_name: str,
87
+ metrics: MetricsSink | None = None,
88
+ labels: dict[str, str] | None = None,
89
+ long_transaction_warning_seconds: float = 5.0,
90
+ span: Any = None,
91
+ deferrable: bool = False,
92
+ ) -> None:
93
+ """Constructed by ``Database.transaction(...)``; not built directly by applications."""
94
+ self._engine = engine
95
+ self._is_postgres = is_postgres
96
+ self._default_timeout = default_timeout
97
+ self._database = database
98
+ self._shard_id = shard_id
99
+ self._role = role
100
+ self._isolation = isolation
101
+ self._read_only = read_only
102
+ self._deferrable = deferrable
103
+ self._timeout = timeout if timeout is not None else default_timeout
104
+ self._lock_timeout = lock_timeout
105
+ self._query_name = query_name
106
+ self._metrics = metrics or NoopMetrics()
107
+ self._labels = labels or {"database": database, "shard": shard_id, "role": role}
108
+ self._long_transaction_warning = long_transaction_warning_seconds
109
+ self._span = span
110
+ self._conn: Connection | None = None
111
+ self._trans: Any = None
112
+ self._scope: TransactionScope | None = None
113
+ self._started_at: float = 0.0
114
+
115
+ def __enter__(self) -> TransactionScope:
116
+ """Acquire a connection, apply isolation/read-only/timeout settings, and ``BEGIN``."""
117
+ try:
118
+ self._conn = self._engine.connect()
119
+ # Isolation level / read-only / deferrable must be set *before* BEGIN — SQLAlchemy's
120
+ # execution_options() applies them via the driver's native connection attributes
121
+ # where possible (e.g. psycopg's own .isolation_level/.read_only), not raw SQL
122
+ # (§11.5). isolation_level is dialect-portable; the postgresql_* options are PG-only.
123
+ opts = self._execution_options()
124
+ if opts:
125
+ self._conn = self._conn.execution_options(**opts)
126
+ self._trans = self._conn.begin()
127
+ self._apply_settings(self._conn)
128
+ except BaseException as exc:
129
+ self._cleanup_on_enter_failure()
130
+ if is_cancellation(exc):
131
+ raise
132
+ raise classify(
133
+ exc, query_name=self._query_name, database_name=self._database, role=self._role
134
+ ) from exc
135
+ self._started_at = time.monotonic()
136
+ self._scope = TransactionScope(
137
+ self._conn,
138
+ is_postgres=self._is_postgres,
139
+ default_timeout=self._timeout,
140
+ database=self._database,
141
+ shard_id=self._shard_id,
142
+ role=self._role,
143
+ )
144
+ return self._scope
145
+
146
+ def _execution_options(self) -> dict[str, Any]:
147
+ opts: dict[str, Any] = {}
148
+ if self._isolation:
149
+ opts["isolation_level"] = self._isolation.upper().replace("_", " ")
150
+ if self._is_postgres:
151
+ if self._read_only:
152
+ opts["postgresql_readonly"] = True
153
+ if self._deferrable:
154
+ opts["postgresql_deferrable"] = True
155
+ return opts
156
+
157
+ def _apply_settings(self, conn: Connection) -> None:
158
+ # Statement/lock timeout are PostgreSQL GUCs with no portable execution_option — they
159
+ # have no driver-native equivalent, so SET LOCAL is the only option (§10, §12.1). Must
160
+ # run after BEGIN: SET LOCAL only takes effect inside an open transaction.
161
+ if not self._is_postgres:
162
+ return
163
+ stmt = apply_statement_timeout_sql(self._timeout)
164
+ if stmt is not None:
165
+ conn.execute(text(stmt))
166
+ if self._lock_timeout is not None and self._lock_timeout > 0:
167
+ ms = max(int(self._lock_timeout * 1000), 1)
168
+ conn.execute(text(f"SET LOCAL lock_timeout = {ms}"))
169
+
170
+ def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
171
+ """Commit on clean exit, else roll back; records metrics/logs/span for the outcome."""
172
+ assert self._conn is not None
173
+ outcome = "commit"
174
+ try:
175
+ if exc is not None:
176
+ outcome = "cancelled" if is_cancellation(exc) else "rollback"
177
+ self._rollback(cancelled=is_cancellation(exc))
178
+ return False # propagate the original exception
179
+ try:
180
+ self._commit()
181
+ except DatabaseCommitUnknownError:
182
+ outcome = "commit_unknown"
183
+ raise
184
+ except BaseException:
185
+ outcome = "rollback" # _commit() already attempted an internal rollback
186
+ raise
187
+ return False
188
+ finally:
189
+ duration = time.monotonic() - self._started_at
190
+ self._metrics.incr(m.TX_TOTAL, labels=self._labels)
191
+ self._metrics.observe(m.TX_DURATION, duration, labels=self._labels)
192
+ if outcome in ("rollback", "cancelled"):
193
+ self._metrics.incr(m.TX_ROLLBACK, labels=self._labels)
194
+ elif outcome == "commit_unknown":
195
+ self._metrics.incr(m.COMMIT_UNKNOWN, labels=self._labels)
196
+ if self._span is not None:
197
+ self._span.set_attribute("db.transaction.duration_ms", round(duration * 1000, 3))
198
+ if duration >= self._long_transaction_warning:
199
+ obslog.long_transaction_warning(
200
+ duration_ms=duration * 1000,
201
+ threshold_ms=self._long_transaction_warning * 1000,
202
+ database=self._database,
203
+ role=self._role,
204
+ outcome=outcome,
205
+ )
206
+ self._release()
207
+
208
+ def _commit(self) -> None:
209
+ assert self._trans is not None
210
+ try:
211
+ self._trans.commit()
212
+ except BaseException as commit_exc:
213
+ # A failure during COMMIT may mean the transaction committed anyway (§15).
214
+ if is_connection_error(commit_exc):
215
+ raise DatabaseCommitUnknownError(
216
+ "connection failed during COMMIT; transaction outcome is unknown",
217
+ original=commit_exc,
218
+ database_name=self._database,
219
+ shard_id=self._shard_id,
220
+ role=self._role,
221
+ query_name=self._query_name,
222
+ ) from commit_exc
223
+ # Otherwise attempt rollback and classify normally.
224
+ with contextlib.suppress(Exception):
225
+ self._trans.rollback()
226
+ raise classify(
227
+ commit_exc,
228
+ query_name=self._query_name,
229
+ database_name=self._database,
230
+ role=self._role,
231
+ ) from commit_exc
232
+
233
+ def _rollback(self, *, cancelled: bool) -> None:
234
+ if self._trans is None:
235
+ return
236
+
237
+ def _do_rollback() -> None:
238
+ try:
239
+ self._trans.rollback()
240
+ except Exception:
241
+ # Rollback failed — the connection state is uncertain; invalidate it.
242
+ with contextlib.suppress(Exception):
243
+ self._conn.invalidate() # type: ignore[union-attr]
244
+
245
+ shield_from_cancellation(_do_rollback())
246
+ if cancelled:
247
+ # State after cancellation is uncertain; drop the connection from the pool.
248
+ with contextlib.suppress(Exception):
249
+ self._conn.invalidate() # type: ignore[union-attr]
250
+
251
+ def _release(self) -> None:
252
+ if self._conn is None:
253
+ return
254
+
255
+ def _do_release() -> None:
256
+ with contextlib.suppress(Exception):
257
+ self._conn.close() # type: ignore[union-attr]
258
+
259
+ shield_from_cancellation(_do_release())
260
+ self._conn = None
261
+ self._trans = None
262
+
263
+ def _cleanup_on_enter_failure(self) -> None:
264
+ if self._trans is not None:
265
+ with contextlib.suppress(Exception):
266
+ self._trans.rollback()
267
+ self._release()
dbkit/cli/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """dbkit cli — see docs/roadmap.md (later phases)."""