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.
- dbkit/__init__.py +77 -0
- dbkit/_async/__init__.py +17 -0
- dbkit/_async/_compat.py +111 -0
- dbkit/_async/connection.py +328 -0
- dbkit/_async/database.py +884 -0
- dbkit/_async/engine.py +232 -0
- dbkit/_async/executor.py +329 -0
- dbkit/_async/health.py +53 -0
- dbkit/_async/resilience.py +148 -0
- dbkit/_async/streaming.py +137 -0
- dbkit/_async/transaction.py +264 -0
- dbkit/_core/__init__.py +1 -0
- dbkit/_core/bulk.py +91 -0
- dbkit/_core/circuit.py +130 -0
- dbkit/_core/config.py +613 -0
- dbkit/_core/errors/__init__.py +74 -0
- dbkit/_core/errors/base.py +344 -0
- dbkit/_core/errors/classifier.py +138 -0
- dbkit/_core/errors/redaction.py +96 -0
- dbkit/_core/errors/sqlstate.py +74 -0
- dbkit/_core/idempotency_lint.py +57 -0
- dbkit/_core/keys.py +29 -0
- dbkit/_core/policies.py +105 -0
- dbkit/_core/query.py +142 -0
- dbkit/_core/result.py +109 -0
- dbkit/_core/routing.py +248 -0
- dbkit/_pool.py +202 -0
- dbkit/_sync/__init__.py +20 -0
- dbkit/_sync/_compat.py +82 -0
- dbkit/_sync/connection.py +331 -0
- dbkit/_sync/database.py +887 -0
- dbkit/_sync/engine.py +235 -0
- dbkit/_sync/executor.py +332 -0
- dbkit/_sync/health.py +56 -0
- dbkit/_sync/resilience.py +151 -0
- dbkit/_sync/streaming.py +140 -0
- dbkit/_sync/transaction.py +267 -0
- dbkit/cli/__init__.py +1 -0
- dbkit/cli/main.py +256 -0
- dbkit/errors.py +6 -0
- dbkit/integrations/__init__.py +21 -0
- dbkit/integrations/batch.py +81 -0
- dbkit/integrations/inbox.py +153 -0
- dbkit/observability/__init__.py +21 -0
- dbkit/observability/logging.py +154 -0
- dbkit/observability/metrics.py +110 -0
- dbkit/observability/otel_metrics.py +69 -0
- dbkit/observability/prometheus.py +78 -0
- dbkit/observability/tracing.py +128 -0
- dbkit/postgres/__init__.py +1 -0
- dbkit/postgres/copy.py +77 -0
- dbkit/postgres/pipeline.py +48 -0
- dbkit/postgres/unnest.py +73 -0
- dbkit/testing/__init__.py +1 -0
- dbkit_sql-0.1.0.dist-info/METADATA +555 -0
- dbkit_sql-0.1.0.dist-info/RECORD +59 -0
- dbkit_sql-0.1.0.dist-info/WHEEL +4 -0
- dbkit_sql-0.1.0.dist-info/entry_points.txt +2 -0
- 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()
|
dbkit/_sync/streaming.py
ADDED
|
@@ -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)."""
|