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
dbkit/_core/circuit.py
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
"""Circuit breaker (§16).
|
|
2
|
+
|
|
3
|
+
One breaker per ``database + shard + role``. It is a pure state machine with the clock
|
|
4
|
+
injected (``now`` is a monotonic timestamp passed in), so it is shared by both frontends and
|
|
5
|
+
fully unit-testable without sleeping.
|
|
6
|
+
|
|
7
|
+
States:
|
|
8
|
+
|
|
9
|
+
* ``CLOSED`` — calls flow; failures inside a rolling window are counted.
|
|
10
|
+
* ``OPEN`` — calls are rejected fast for ``open_seconds`` after the threshold is crossed.
|
|
11
|
+
* ``HALF_OPEN`` — a limited number of trial calls are allowed; a success closes the breaker,
|
|
12
|
+
a failure re-opens it.
|
|
13
|
+
|
|
14
|
+
Only *infrastructure* failures should be reported (connection/pool/availability/timeout) — not
|
|
15
|
+
integrity, programming, or permission errors, which are the caller's fault and would trip the
|
|
16
|
+
breaker for no reason (§16).
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import enum
|
|
22
|
+
from collections import deque
|
|
23
|
+
|
|
24
|
+
from .errors import DatabaseError, ErrorCategory
|
|
25
|
+
|
|
26
|
+
# Categories that indicate the *backend* is unhealthy and should count toward opening (§16).
|
|
27
|
+
TRIPPING_CATEGORIES = frozenset(
|
|
28
|
+
{
|
|
29
|
+
ErrorCategory.AVAILABILITY,
|
|
30
|
+
ErrorCategory.CONNECTION,
|
|
31
|
+
ErrorCategory.POOL,
|
|
32
|
+
ErrorCategory.TIMEOUT,
|
|
33
|
+
}
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def counts_as_failure(error: DatabaseError) -> bool:
|
|
38
|
+
"""Whether an error should count toward opening the breaker."""
|
|
39
|
+
return error.category in TRIPPING_CATEGORIES
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class CircuitState(enum.Enum):
|
|
43
|
+
"""A :class:`CircuitBreaker`'s current state."""
|
|
44
|
+
|
|
45
|
+
CLOSED = "closed"
|
|
46
|
+
OPEN = "open"
|
|
47
|
+
HALF_OPEN = "half_open"
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class CircuitBreaker:
|
|
51
|
+
"""A single breaker. All methods take an explicit monotonic ``now``."""
|
|
52
|
+
|
|
53
|
+
def __init__(
|
|
54
|
+
self,
|
|
55
|
+
*,
|
|
56
|
+
failure_threshold: int = 10,
|
|
57
|
+
window_seconds: float = 30.0,
|
|
58
|
+
open_seconds: float = 10.0,
|
|
59
|
+
half_open_max_calls: int = 2,
|
|
60
|
+
) -> None:
|
|
61
|
+
"""A new breaker, starting ``CLOSED``."""
|
|
62
|
+
self.failure_threshold = failure_threshold
|
|
63
|
+
self.window_seconds = window_seconds
|
|
64
|
+
self.open_seconds = open_seconds
|
|
65
|
+
self.half_open_max_calls = half_open_max_calls
|
|
66
|
+
self._state = CircuitState.CLOSED
|
|
67
|
+
self._failures: deque[float] = deque()
|
|
68
|
+
self._opened_at: float = 0.0
|
|
69
|
+
self._half_open_calls = 0
|
|
70
|
+
|
|
71
|
+
# -- introspection ------------------------------------------------------------ #
|
|
72
|
+
|
|
73
|
+
def state(self, now: float) -> CircuitState:
|
|
74
|
+
"""Current state, advancing OPEN -> HALF_OPEN if the cooldown has elapsed."""
|
|
75
|
+
if self._state == CircuitState.OPEN and now - self._opened_at >= self.open_seconds:
|
|
76
|
+
self._state = CircuitState.HALF_OPEN
|
|
77
|
+
self._half_open_calls = 0
|
|
78
|
+
return self._state
|
|
79
|
+
|
|
80
|
+
# -- gate --------------------------------------------------------------------- #
|
|
81
|
+
|
|
82
|
+
def allow(self, now: float) -> bool:
|
|
83
|
+
"""Whether a call may proceed. In HALF_OPEN, only a limited number of trials pass."""
|
|
84
|
+
state = self.state(now)
|
|
85
|
+
if state == CircuitState.CLOSED:
|
|
86
|
+
return True
|
|
87
|
+
if state == CircuitState.OPEN:
|
|
88
|
+
return False
|
|
89
|
+
# HALF_OPEN: admit up to half_open_max_calls trial calls.
|
|
90
|
+
if self._half_open_calls < self.half_open_max_calls:
|
|
91
|
+
self._half_open_calls += 1
|
|
92
|
+
return True
|
|
93
|
+
return False
|
|
94
|
+
|
|
95
|
+
# -- feedback ----------------------------------------------------------------- #
|
|
96
|
+
|
|
97
|
+
def on_success(self, now: float) -> None:
|
|
98
|
+
"""Record a successful call: closes the breaker from HALF_OPEN, else prunes the window."""
|
|
99
|
+
if self._state == CircuitState.HALF_OPEN:
|
|
100
|
+
self._reset()
|
|
101
|
+
elif self._state == CircuitState.CLOSED:
|
|
102
|
+
self._prune(now)
|
|
103
|
+
|
|
104
|
+
def on_failure(self, now: float) -> None:
|
|
105
|
+
"""Record a failing call: re-opens from HALF_OPEN, or opens once the threshold is hit."""
|
|
106
|
+
if self._state == CircuitState.HALF_OPEN:
|
|
107
|
+
self._open(now)
|
|
108
|
+
return
|
|
109
|
+
self._failures.append(now)
|
|
110
|
+
self._prune(now)
|
|
111
|
+
if len(self._failures) >= self.failure_threshold:
|
|
112
|
+
self._open(now)
|
|
113
|
+
|
|
114
|
+
# -- internals ---------------------------------------------------------------- #
|
|
115
|
+
|
|
116
|
+
def _prune(self, now: float) -> None:
|
|
117
|
+
cutoff = now - self.window_seconds
|
|
118
|
+
while self._failures and self._failures[0] < cutoff:
|
|
119
|
+
self._failures.popleft()
|
|
120
|
+
|
|
121
|
+
def _open(self, now: float) -> None:
|
|
122
|
+
self._state = CircuitState.OPEN
|
|
123
|
+
self._opened_at = now
|
|
124
|
+
self._failures.clear()
|
|
125
|
+
self._half_open_calls = 0
|
|
126
|
+
|
|
127
|
+
def _reset(self) -> None:
|
|
128
|
+
self._state = CircuitState.CLOSED
|
|
129
|
+
self._failures.clear()
|
|
130
|
+
self._half_open_calls = 0
|