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,344 @@
|
|
|
1
|
+
"""Normalized error hierarchy (§13).
|
|
2
|
+
|
|
3
|
+
Every failure dbkit surfaces — from SQLAlchemy, the DBAPI driver, the network, timeouts,
|
|
4
|
+
routing, or configuration — is normalized into a :class:`DatabaseError` subclass with a
|
|
5
|
+
stable ``code``, a :class:`ErrorCategory`, retryability, and connection/transaction
|
|
6
|
+
outcome certainty. Messages are sanitized so secrets never leak (§13.4, §29).
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import enum
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class ErrorCategory(enum.Enum):
|
|
16
|
+
"""Coarse grouping used for metrics labels and retry/circuit-breaker decisions."""
|
|
17
|
+
|
|
18
|
+
CONFIGURATION = "configuration"
|
|
19
|
+
ROUTING = "routing"
|
|
20
|
+
AVAILABILITY = "availability"
|
|
21
|
+
CONNECTION = "connection"
|
|
22
|
+
POOL = "pool"
|
|
23
|
+
TIMEOUT = "timeout"
|
|
24
|
+
LOCK = "lock"
|
|
25
|
+
CONCURRENCY = "concurrency"
|
|
26
|
+
INTEGRITY = "integrity"
|
|
27
|
+
PROGRAMMING = "programming"
|
|
28
|
+
PERMISSION = "permission"
|
|
29
|
+
TRANSACTION = "transaction"
|
|
30
|
+
CANCELLED = "cancelled"
|
|
31
|
+
RESULT = "result"
|
|
32
|
+
RESILIENCE = "resilience"
|
|
33
|
+
UNSUPPORTED = "unsupported"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class DatabaseError(Exception):
|
|
37
|
+
"""Base class for every error dbkit raises (§13.1).
|
|
38
|
+
|
|
39
|
+
Attributes are populated by the classifier or by the raising call site. ``original``
|
|
40
|
+
holds the underlying exception for internal inspection; it is never rendered into the
|
|
41
|
+
user-facing message.
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
#: Stable internal code, e.g. ``"unique_violation"``. Subclasses set a default.
|
|
45
|
+
code: str = "database_error"
|
|
46
|
+
#: Coarse category. Subclasses set a default.
|
|
47
|
+
category: ErrorCategory = ErrorCategory.AVAILABILITY
|
|
48
|
+
#: Whether an operation raising this error is *potentially* retryable (policy still
|
|
49
|
+
#: applies idempotency gating on top of this).
|
|
50
|
+
retryable: bool = False
|
|
51
|
+
|
|
52
|
+
def __init__(
|
|
53
|
+
self,
|
|
54
|
+
message: str = "",
|
|
55
|
+
*,
|
|
56
|
+
code: str | None = None,
|
|
57
|
+
category: ErrorCategory | None = None,
|
|
58
|
+
retryable: bool | None = None,
|
|
59
|
+
connection_invalidated: bool = False,
|
|
60
|
+
transaction_state_unknown: bool = False,
|
|
61
|
+
database_name: str | None = None,
|
|
62
|
+
shard_id: str | None = None,
|
|
63
|
+
role: str | None = None,
|
|
64
|
+
query_name: str | None = None,
|
|
65
|
+
sqlstate: str | None = None,
|
|
66
|
+
original: BaseException | None = None,
|
|
67
|
+
) -> None:
|
|
68
|
+
"""Any keyword left ``None`` falls back to the subclass default or is left unset.
|
|
69
|
+
|
|
70
|
+
``original`` and the routing/query context fields are for internal inspection and
|
|
71
|
+
logging — never interpolated into the exception message itself (§13.4, §29).
|
|
72
|
+
"""
|
|
73
|
+
self.code = code or type(self).code
|
|
74
|
+
self.category = category or type(self).category
|
|
75
|
+
self.retryable = type(self).retryable if retryable is None else retryable
|
|
76
|
+
self.connection_invalidated = connection_invalidated
|
|
77
|
+
self.transaction_state_unknown = transaction_state_unknown
|
|
78
|
+
self.database_name = database_name
|
|
79
|
+
self.shard_id = shard_id
|
|
80
|
+
self.role = role
|
|
81
|
+
self.query_name = query_name
|
|
82
|
+
self.sqlstate = sqlstate
|
|
83
|
+
self.original = original
|
|
84
|
+
super().__init__(message or self._default_message())
|
|
85
|
+
|
|
86
|
+
def _default_message(self) -> str:
|
|
87
|
+
parts = [self.code]
|
|
88
|
+
if self.query_name:
|
|
89
|
+
parts.append(f"query={self.query_name}")
|
|
90
|
+
if self.database_name:
|
|
91
|
+
parts.append(f"database={self.database_name}")
|
|
92
|
+
if self.sqlstate:
|
|
93
|
+
parts.append(f"sqlstate={self.sqlstate}")
|
|
94
|
+
return " ".join(parts)
|
|
95
|
+
|
|
96
|
+
def with_context(
|
|
97
|
+
self,
|
|
98
|
+
*,
|
|
99
|
+
database_name: str | None = None,
|
|
100
|
+
shard_id: str | None = None,
|
|
101
|
+
role: str | None = None,
|
|
102
|
+
query_name: str | None = None,
|
|
103
|
+
) -> DatabaseError:
|
|
104
|
+
"""Attach routing/query context discovered by an outer layer. Returns self."""
|
|
105
|
+
if database_name is not None:
|
|
106
|
+
self.database_name = database_name
|
|
107
|
+
if shard_id is not None:
|
|
108
|
+
self.shard_id = shard_id
|
|
109
|
+
if role is not None:
|
|
110
|
+
self.role = role
|
|
111
|
+
if query_name is not None:
|
|
112
|
+
self.query_name = query_name
|
|
113
|
+
return self
|
|
114
|
+
|
|
115
|
+
def to_dict(self) -> dict[str, Any]:
|
|
116
|
+
"""Safe, secret-free representation for logs/traces (§13.4)."""
|
|
117
|
+
return {
|
|
118
|
+
"code": self.code,
|
|
119
|
+
"category": self.category.value,
|
|
120
|
+
"retryable": self.retryable,
|
|
121
|
+
"connection_invalidated": self.connection_invalidated,
|
|
122
|
+
"transaction_state_unknown": self.transaction_state_unknown,
|
|
123
|
+
"database": self.database_name,
|
|
124
|
+
"shard": self.shard_id,
|
|
125
|
+
"role": self.role,
|
|
126
|
+
"query_name": self.query_name,
|
|
127
|
+
"sqlstate": self.sqlstate,
|
|
128
|
+
"message": str(self),
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
# --- Configuration & routing -------------------------------------------------------- #
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
class DatabaseConfigurationError(DatabaseError):
|
|
136
|
+
"""Invalid or missing configuration, raised at startup before any connection is made."""
|
|
137
|
+
|
|
138
|
+
code = "configuration_error"
|
|
139
|
+
category = ErrorCategory.CONFIGURATION
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
class DatabaseRoutingError(DatabaseError):
|
|
143
|
+
"""A shard/replica/target could not be resolved (e.g. an unmapped shard key)."""
|
|
144
|
+
|
|
145
|
+
code = "routing_error"
|
|
146
|
+
category = ErrorCategory.ROUTING
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
# --- Availability & connectivity ---------------------------------------------------- #
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
class DatabaseUnavailableError(DatabaseError):
|
|
153
|
+
"""The database is reachable but not currently able to serve requests."""
|
|
154
|
+
|
|
155
|
+
code = "unavailable"
|
|
156
|
+
category = ErrorCategory.AVAILABILITY
|
|
157
|
+
retryable = True
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
class DatabaseConnectionError(DatabaseError):
|
|
161
|
+
"""The connection could not be established or was lost mid-operation."""
|
|
162
|
+
|
|
163
|
+
code = "connection_error"
|
|
164
|
+
category = ErrorCategory.CONNECTION
|
|
165
|
+
retryable = True
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
class DatabasePoolTimeoutError(DatabaseError):
|
|
169
|
+
"""No pooled connection became available before the pool checkout timeout elapsed."""
|
|
170
|
+
|
|
171
|
+
code = "pool_timeout"
|
|
172
|
+
category = ErrorCategory.POOL
|
|
173
|
+
retryable = True
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
# --- Timeouts & locking ------------------------------------------------------------- #
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
class DatabaseQueryTimeoutError(DatabaseError):
|
|
180
|
+
"""A single statement exceeded its query timeout."""
|
|
181
|
+
|
|
182
|
+
code = "query_timeout"
|
|
183
|
+
category = ErrorCategory.TIMEOUT
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
class DatabaseLockTimeoutError(DatabaseError):
|
|
187
|
+
"""A statement gave up waiting on a row/table lock (PostgreSQL ``lock_timeout``)."""
|
|
188
|
+
|
|
189
|
+
code = "lock_timeout"
|
|
190
|
+
category = ErrorCategory.LOCK
|
|
191
|
+
retryable = True
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
class DatabaseDeadlockError(DatabaseError):
|
|
195
|
+
"""PostgreSQL detected and broke a deadlock by aborting this transaction."""
|
|
196
|
+
|
|
197
|
+
code = "deadlock"
|
|
198
|
+
category = ErrorCategory.LOCK
|
|
199
|
+
retryable = True
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
class DatabaseSerializationError(DatabaseError):
|
|
203
|
+
"""A ``SERIALIZABLE``/``REPEATABLE READ`` transaction failed to serialize; safe to retry."""
|
|
204
|
+
|
|
205
|
+
code = "serialization_failure"
|
|
206
|
+
category = ErrorCategory.CONCURRENCY
|
|
207
|
+
retryable = True
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
# --- Integrity ---------------------------------------------------------------------- #
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
class DatabaseIntegrityError(DatabaseError):
|
|
214
|
+
"""Base class for constraint violations (SQLSTATE class 23)."""
|
|
215
|
+
|
|
216
|
+
code = "integrity_error"
|
|
217
|
+
category = ErrorCategory.INTEGRITY
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
class DatabaseUniqueViolationError(DatabaseIntegrityError):
|
|
221
|
+
"""A unique/primary-key constraint rejected the row."""
|
|
222
|
+
|
|
223
|
+
code = "unique_violation"
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
class DatabaseForeignKeyViolationError(DatabaseIntegrityError):
|
|
227
|
+
"""A foreign-key constraint rejected the row."""
|
|
228
|
+
|
|
229
|
+
code = "foreign_key_violation"
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
class DatabaseNotNullViolationError(DatabaseIntegrityError):
|
|
233
|
+
"""A ``NOT NULL`` column was given a null value."""
|
|
234
|
+
|
|
235
|
+
code = "not_null_violation"
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
class DatabaseCheckViolationError(DatabaseIntegrityError):
|
|
239
|
+
"""A ``CHECK`` constraint rejected the row."""
|
|
240
|
+
|
|
241
|
+
code = "check_violation"
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
# --- Programming / permission ------------------------------------------------------- #
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
class DatabaseProgrammingError(DatabaseError):
|
|
248
|
+
"""The statement itself is invalid (bad SQL, wrong types, undefined objects)."""
|
|
249
|
+
|
|
250
|
+
code = "programming_error"
|
|
251
|
+
category = ErrorCategory.PROGRAMMING
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
class DatabaseSyntaxError(DatabaseProgrammingError):
|
|
255
|
+
"""The statement failed to parse."""
|
|
256
|
+
|
|
257
|
+
code = "syntax_error"
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
class DatabasePermissionError(DatabaseError):
|
|
261
|
+
"""The connected role lacks the privilege required for this operation."""
|
|
262
|
+
|
|
263
|
+
code = "permission_denied"
|
|
264
|
+
category = ErrorCategory.PERMISSION
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
class DatabaseReadOnlyError(DatabaseError):
|
|
268
|
+
"""A write was attempted against a read-only transaction or replica target."""
|
|
269
|
+
|
|
270
|
+
code = "read_only_transaction"
|
|
271
|
+
category = ErrorCategory.PERMISSION
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
# --- Transactions ------------------------------------------------------------------- #
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
class DatabaseTransactionError(DatabaseError):
|
|
278
|
+
"""A transaction-lifecycle operation (begin/commit/rollback/savepoint) failed."""
|
|
279
|
+
|
|
280
|
+
code = "transaction_error"
|
|
281
|
+
category = ErrorCategory.TRANSACTION
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
class DatabaseCommitUnknownError(DatabaseError):
|
|
285
|
+
"""Commit outcome is genuinely unknown — do not retry unless idempotent (§15)."""
|
|
286
|
+
|
|
287
|
+
code = "commit_unknown"
|
|
288
|
+
category = ErrorCategory.TRANSACTION
|
|
289
|
+
|
|
290
|
+
def __init__(self, message: str = "", **kwargs: Any) -> None:
|
|
291
|
+
"""Always marks ``transaction_state_unknown``/``connection_invalidated`` (§15)."""
|
|
292
|
+
kwargs.setdefault("transaction_state_unknown", True)
|
|
293
|
+
kwargs.setdefault("connection_invalidated", True)
|
|
294
|
+
super().__init__(message, **kwargs)
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
class DatabaseCancellationError(DatabaseError):
|
|
298
|
+
"""The operation was cancelled (e.g. by ``asyncio`` task cancellation or a client timeout)."""
|
|
299
|
+
|
|
300
|
+
code = "cancelled"
|
|
301
|
+
category = ErrorCategory.CANCELLED
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
# --- Results & mapping -------------------------------------------------------------- #
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
class DatabaseResultError(DatabaseError):
|
|
308
|
+
"""A cardinality expectation (exactly-one / at-most-one / scalar) was violated."""
|
|
309
|
+
|
|
310
|
+
code = "result_error"
|
|
311
|
+
category = ErrorCategory.RESULT
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
class DatabaseMappingError(DatabaseError):
|
|
315
|
+
"""A row could not be mapped to the requested ``map_to`` type."""
|
|
316
|
+
|
|
317
|
+
code = "mapping_error"
|
|
318
|
+
category = ErrorCategory.RESULT
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
# --- Resilience --------------------------------------------------------------------- #
|
|
322
|
+
|
|
323
|
+
|
|
324
|
+
class DatabaseCircuitOpenError(DatabaseError):
|
|
325
|
+
"""The circuit breaker for this database/shard/role is open; the call was short-circuited."""
|
|
326
|
+
|
|
327
|
+
code = "circuit_open"
|
|
328
|
+
category = ErrorCategory.RESILIENCE
|
|
329
|
+
retryable = True
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
class DatabaseOverloadedError(DatabaseError):
|
|
333
|
+
"""A concurrency limiter rejected the call because its semaphore was exhausted."""
|
|
334
|
+
|
|
335
|
+
code = "overloaded"
|
|
336
|
+
category = ErrorCategory.CONCURRENCY
|
|
337
|
+
retryable = True
|
|
338
|
+
|
|
339
|
+
|
|
340
|
+
class DatabaseUnsupportedOperationError(DatabaseError):
|
|
341
|
+
"""The requested operation isn't supported by the current dialect/driver/configuration."""
|
|
342
|
+
|
|
343
|
+
code = "unsupported_operation"
|
|
344
|
+
category = ErrorCategory.UNSUPPORTED
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""Translate SQLAlchemy / driver / network / timeout exceptions into dbkit errors (§13).
|
|
2
|
+
|
|
3
|
+
Order of precedence (SQLSTATE-first, message-matching only as a last resort):
|
|
4
|
+
|
|
5
|
+
1. Already a :class:`DatabaseError` — return unchanged.
|
|
6
|
+
2. ``asyncio.TimeoutError`` / ``TimeoutError`` — client-side deadline.
|
|
7
|
+
3. Extract a SQLSTATE from the DBAPI ``orig`` and map it (``sqlstate.py``).
|
|
8
|
+
4. Fall back to the SQLAlchemy exception *type* (OperationalError, IntegrityError, ...).
|
|
9
|
+
5. Fall back to plain OS/connection errors.
|
|
10
|
+
6. Anything else -> generic :class:`DatabaseError`.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import asyncio
|
|
16
|
+
from typing import Any
|
|
17
|
+
|
|
18
|
+
from . import base as e
|
|
19
|
+
from .redaction import sanitize_message
|
|
20
|
+
from .sqlstate import error_class_for_sqlstate
|
|
21
|
+
|
|
22
|
+
try: # SQLAlchemy is a hard dependency, but keep the import defensive for pure-core tests.
|
|
23
|
+
from sqlalchemy import exc as sa_exc
|
|
24
|
+
except Exception: # pragma: no cover
|
|
25
|
+
sa_exc = None # type: ignore[assignment]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _extract_sqlstate(orig: BaseException | None) -> str | None:
|
|
29
|
+
"""Pull a 5-char SQLSTATE from a DBAPI exception (psycopg3, asyncpg, generic)."""
|
|
30
|
+
if orig is None:
|
|
31
|
+
return None
|
|
32
|
+
# psycopg3: exc.sqlstate ; also .diag.sqlstate
|
|
33
|
+
for attr in ("sqlstate", "pgcode"):
|
|
34
|
+
code = getattr(orig, attr, None)
|
|
35
|
+
if isinstance(code, str) and len(code) == 5:
|
|
36
|
+
return code
|
|
37
|
+
diag = getattr(orig, "diag", None)
|
|
38
|
+
if diag is not None:
|
|
39
|
+
code = getattr(diag, "sqlstate", None)
|
|
40
|
+
if isinstance(code, str) and len(code) == 5:
|
|
41
|
+
return code
|
|
42
|
+
return None
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _from_sqlalchemy_type(exc: Any) -> type[e.DatabaseError] | None:
|
|
46
|
+
"""Map by SQLAlchemy exception class when no SQLSTATE is available."""
|
|
47
|
+
if sa_exc is None:
|
|
48
|
+
return None
|
|
49
|
+
if isinstance(exc, sa_exc.IntegrityError):
|
|
50
|
+
return e.DatabaseIntegrityError
|
|
51
|
+
if isinstance(exc, sa_exc.ProgrammingError):
|
|
52
|
+
return e.DatabaseProgrammingError
|
|
53
|
+
if isinstance(exc, sa_exc.OperationalError):
|
|
54
|
+
# Operational errors are typically transient connectivity/availability issues.
|
|
55
|
+
return e.DatabaseConnectionError
|
|
56
|
+
if isinstance(exc, sa_exc.DisconnectionError):
|
|
57
|
+
return e.DatabaseConnectionError
|
|
58
|
+
if isinstance(exc, sa_exc.TimeoutError):
|
|
59
|
+
# SQLAlchemy raises this on pool checkout timeout.
|
|
60
|
+
return e.DatabasePoolTimeoutError
|
|
61
|
+
if isinstance(exc, sa_exc.DBAPIError):
|
|
62
|
+
return e.DatabaseError
|
|
63
|
+
return None
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def classify(
|
|
67
|
+
exc: BaseException,
|
|
68
|
+
*,
|
|
69
|
+
query_name: str | None = None,
|
|
70
|
+
database_name: str | None = None,
|
|
71
|
+
shard_id: str | None = None,
|
|
72
|
+
role: str | None = None,
|
|
73
|
+
) -> e.DatabaseError:
|
|
74
|
+
"""Normalize any exception into a :class:`DatabaseError` with context attached."""
|
|
75
|
+
if isinstance(exc, e.DatabaseError):
|
|
76
|
+
return exc.with_context(
|
|
77
|
+
query_name=query_name,
|
|
78
|
+
database_name=database_name,
|
|
79
|
+
shard_id=shard_id,
|
|
80
|
+
role=role,
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
# Client-side deadline (asyncio.timeout / wait_for).
|
|
84
|
+
if isinstance(exc, (asyncio.TimeoutError, TimeoutError)):
|
|
85
|
+
return e.DatabaseQueryTimeoutError(
|
|
86
|
+
"operation exceeded its client-side deadline",
|
|
87
|
+
original=exc,
|
|
88
|
+
query_name=query_name,
|
|
89
|
+
database_name=database_name,
|
|
90
|
+
shard_id=shard_id,
|
|
91
|
+
role=role,
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
orig = getattr(exc, "orig", None) or (exc if _looks_like_dbapi(exc) else None)
|
|
95
|
+
sqlstate = _extract_sqlstate(orig) or _extract_sqlstate(exc)
|
|
96
|
+
|
|
97
|
+
cls = error_class_for_sqlstate(sqlstate)
|
|
98
|
+
if cls is None:
|
|
99
|
+
cls = _from_sqlalchemy_type(exc)
|
|
100
|
+
if cls is None and isinstance(exc, (ConnectionError, OSError)):
|
|
101
|
+
cls = e.DatabaseConnectionError
|
|
102
|
+
if cls is None:
|
|
103
|
+
cls = e.DatabaseError
|
|
104
|
+
|
|
105
|
+
connection_invalidated = bool(getattr(exc, "connection_invalidated", False))
|
|
106
|
+
message = sanitize_message(str(exc)) or cls.code
|
|
107
|
+
|
|
108
|
+
err = cls(
|
|
109
|
+
message,
|
|
110
|
+
sqlstate=sqlstate,
|
|
111
|
+
original=exc,
|
|
112
|
+
query_name=query_name,
|
|
113
|
+
database_name=database_name,
|
|
114
|
+
shard_id=shard_id,
|
|
115
|
+
role=role,
|
|
116
|
+
)
|
|
117
|
+
if connection_invalidated:
|
|
118
|
+
err.connection_invalidated = True
|
|
119
|
+
return err
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _looks_like_dbapi(exc: BaseException) -> bool:
|
|
123
|
+
return hasattr(exc, "sqlstate") or hasattr(exc, "pgcode") or hasattr(exc, "diag")
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def is_connection_error(exc: BaseException) -> bool:
|
|
127
|
+
"""Whether ``exc`` indicates the connection itself is broken, not just a query failure (§15).
|
|
128
|
+
|
|
129
|
+
Used to decide whether a failure during COMMIT means the outcome is genuinely unknown
|
|
130
|
+
(§15) — prefers SQLAlchemy's own per-dialect disconnect detection
|
|
131
|
+
(``connection_invalidated``, computed by each dialect's ``is_disconnect()`` when it wraps
|
|
132
|
+
the driver exception) over a blanket ``OperationalError`` check — ``OperationalError`` also
|
|
133
|
+
covers many transient-but-not-disconnected conditions (e.g. some lock/resource errors),
|
|
134
|
+
which would otherwise over-classify ordinary failures as commit-unknown.
|
|
135
|
+
"""
|
|
136
|
+
if sa_exc is not None and isinstance(exc, sa_exc.DBAPIError):
|
|
137
|
+
return bool(exc.connection_invalidated)
|
|
138
|
+
return isinstance(exc, (ConnectionError, OSError))
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"""Secret redaction for messages, DSNs, and parameters (§13.4, §29).
|
|
2
|
+
|
|
3
|
+
Nothing that could carry credentials, tokens, or personal data may reach a log, trace,
|
|
4
|
+
metric, or error message unredacted. These helpers are intentionally conservative: when in
|
|
5
|
+
doubt, redact.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import re
|
|
11
|
+
from collections.abc import Mapping
|
|
12
|
+
from typing import Any
|
|
13
|
+
from urllib.parse import urlsplit, urlunsplit
|
|
14
|
+
|
|
15
|
+
REDACTED = "***"
|
|
16
|
+
|
|
17
|
+
# postgresql+psycopg://user:secret@host:5432/db -> redact the password component.
|
|
18
|
+
_DSN_RE = re.compile(r"(?P<pre>[a-z0-9+]+://[^:/\s]+:)(?P<pw>[^@/\s]+)(?P<post>@)", re.IGNORECASE)
|
|
19
|
+
|
|
20
|
+
# Common secret-ish/PII key fragments; redacted from parameter maps unless caller opts out.
|
|
21
|
+
# This list is deliberately conservative and documented (not just here — see
|
|
22
|
+
# docs/troubleshooting.md's redaction section): it substring-matches credential and
|
|
23
|
+
# unambiguous-PII fragments, but cannot know an application's full schema. Anything outside
|
|
24
|
+
# this list — including context-dependent fields like email/phone that aren't always secret —
|
|
25
|
+
# must be declared via ``Query.sensitive_parameters``. See
|
|
26
|
+
# ``tests/property/test_invariants.py::test_hint_list_boundary_is_documented_and_tested`` for
|
|
27
|
+
# the exact, tested catch/miss boundary.
|
|
28
|
+
_SENSITIVE_KEY_HINTS = (
|
|
29
|
+
"password",
|
|
30
|
+
"passwd",
|
|
31
|
+
"secret",
|
|
32
|
+
"token",
|
|
33
|
+
"api_key",
|
|
34
|
+
"apikey",
|
|
35
|
+
"authorization",
|
|
36
|
+
"auth",
|
|
37
|
+
"credential",
|
|
38
|
+
"private_key",
|
|
39
|
+
"access_key",
|
|
40
|
+
"ssn",
|
|
41
|
+
"national_id",
|
|
42
|
+
"credit_card",
|
|
43
|
+
"card_number",
|
|
44
|
+
"cvv",
|
|
45
|
+
"iban",
|
|
46
|
+
"dob",
|
|
47
|
+
"date_of_birth",
|
|
48
|
+
"pin",
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def redact_dsn(value: str) -> str:
|
|
53
|
+
"""Redact the password in a URL/DSN while keeping it recognizable for debugging."""
|
|
54
|
+
redacted = _DSN_RE.sub(rf"\g<pre>{REDACTED}\g<post>", value)
|
|
55
|
+
# If urlsplit disagrees (e.g. odd formatting), fall back to a full rebuild.
|
|
56
|
+
try:
|
|
57
|
+
parts = urlsplit(redacted)
|
|
58
|
+
if parts.password:
|
|
59
|
+
netloc = parts.netloc.replace(f":{parts.password}@", f":{REDACTED}@")
|
|
60
|
+
redacted = urlunsplit(parts._replace(netloc=netloc))
|
|
61
|
+
except ValueError:
|
|
62
|
+
pass
|
|
63
|
+
return redacted
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def is_sensitive_key(key: str) -> bool:
|
|
67
|
+
"""Whether ``key``'s name suggests it holds a secret (password, token, etc.), by substring."""
|
|
68
|
+
lowered = key.lower()
|
|
69
|
+
return any(hint in lowered for hint in _SENSITIVE_KEY_HINTS)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def redact_params(
|
|
73
|
+
params: Mapping[str, Any] | None,
|
|
74
|
+
*,
|
|
75
|
+
sensitive: set[str] | None = None,
|
|
76
|
+
) -> dict[str, Any]:
|
|
77
|
+
"""Return a copy of ``params`` with sensitive values replaced by ``***``.
|
|
78
|
+
|
|
79
|
+
A key is redacted if it is named in ``sensitive`` (from ``Query.sensitive_parameters``)
|
|
80
|
+
or if it matches a built-in secret-ish hint.
|
|
81
|
+
"""
|
|
82
|
+
if not params:
|
|
83
|
+
return {}
|
|
84
|
+
sensitive = sensitive or set()
|
|
85
|
+
out: dict[str, Any] = {}
|
|
86
|
+
for key, value in params.items():
|
|
87
|
+
if key in sensitive or is_sensitive_key(key):
|
|
88
|
+
out[key] = REDACTED
|
|
89
|
+
else:
|
|
90
|
+
out[key] = value
|
|
91
|
+
return out
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def sanitize_message(message: str) -> str:
|
|
95
|
+
"""Strip DSN passwords out of a free-form error/driver message."""
|
|
96
|
+
return redact_dsn(message)
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""PostgreSQL SQLSTATE → dbkit error class mapping (§13.3).
|
|
2
|
+
|
|
3
|
+
The classifier prefers SQLSTATE codes over matching driver message strings. Phase 1 covers
|
|
4
|
+
the core set (integrity, timeout/cancel, connectivity, concurrency, read-only). The table is
|
|
5
|
+
structured so Phase 2 can extend it without touching the classifier.
|
|
6
|
+
|
|
7
|
+
Reference: https://www.postgresql.org/docs/current/errcodes-appendix.html
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from . import base as e
|
|
13
|
+
|
|
14
|
+
# Exact SQLSTATE code -> error class.
|
|
15
|
+
SQLSTATE_MAP: dict[str, type[e.DatabaseError]] = {
|
|
16
|
+
# Class 23 — integrity constraint violation
|
|
17
|
+
"23505": e.DatabaseUniqueViolationError,
|
|
18
|
+
"23503": e.DatabaseForeignKeyViolationError,
|
|
19
|
+
"23502": e.DatabaseNotNullViolationError,
|
|
20
|
+
"23514": e.DatabaseCheckViolationError,
|
|
21
|
+
"23000": e.DatabaseIntegrityError,
|
|
22
|
+
# Class 40 — transaction rollback
|
|
23
|
+
"40001": e.DatabaseSerializationError,
|
|
24
|
+
"40P01": e.DatabaseDeadlockError,
|
|
25
|
+
"40000": e.DatabaseTransactionError,
|
|
26
|
+
"40002": e.DatabaseIntegrityError, # transaction integrity constraint violation
|
|
27
|
+
"40003": e.DatabaseCommitUnknownError, # statement completion unknown
|
|
28
|
+
# Class 55 — object not in prerequisite state
|
|
29
|
+
"55P03": e.DatabaseLockTimeoutError, # lock_not_available
|
|
30
|
+
# Class 57 — operator intervention
|
|
31
|
+
"57014": e.DatabaseQueryTimeoutError, # query_canceled (statement_timeout)
|
|
32
|
+
"57P01": e.DatabaseConnectionError, # admin_shutdown
|
|
33
|
+
"57P02": e.DatabaseConnectionError, # crash_shutdown
|
|
34
|
+
"57P03": e.DatabaseUnavailableError, # cannot_connect_now
|
|
35
|
+
# Class 53 — insufficient resources
|
|
36
|
+
"53300": e.DatabaseUnavailableError, # too_many_connections
|
|
37
|
+
"53400": e.DatabaseUnavailableError, # configuration_limit_exceeded
|
|
38
|
+
# Class 25 — invalid transaction state
|
|
39
|
+
"25006": e.DatabaseReadOnlyError, # read_only_sql_transaction
|
|
40
|
+
"25P02": e.DatabaseTransactionError, # in_failed_sql_transaction
|
|
41
|
+
# Class 08 — connection exception
|
|
42
|
+
"08000": e.DatabaseConnectionError,
|
|
43
|
+
"08003": e.DatabaseConnectionError,
|
|
44
|
+
"08006": e.DatabaseConnectionError,
|
|
45
|
+
"08001": e.DatabaseConnectionError,
|
|
46
|
+
"08004": e.DatabaseConnectionError,
|
|
47
|
+
# Class 42 — syntax error or access rule violation
|
|
48
|
+
"42601": e.DatabaseSyntaxError,
|
|
49
|
+
"42501": e.DatabasePermissionError, # insufficient_privilege
|
|
50
|
+
"42P01": e.DatabaseProgrammingError, # undefined_table
|
|
51
|
+
"42703": e.DatabaseProgrammingError, # undefined_column
|
|
52
|
+
"42883": e.DatabaseProgrammingError, # undefined_function
|
|
53
|
+
# Class 22 — data exception (caller/data problem, not retryable)
|
|
54
|
+
"22P02": e.DatabaseProgrammingError, # invalid_text_representation
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
# Two-character SQLSTATE class -> fallback error class when the exact code is unknown.
|
|
58
|
+
SQLSTATE_CLASS_MAP: dict[str, type[e.DatabaseError]] = {
|
|
59
|
+
"08": e.DatabaseConnectionError,
|
|
60
|
+
"23": e.DatabaseIntegrityError,
|
|
61
|
+
"42": e.DatabaseProgrammingError,
|
|
62
|
+
"40": e.DatabaseTransactionError,
|
|
63
|
+
"53": e.DatabaseUnavailableError,
|
|
64
|
+
"22": e.DatabaseProgrammingError,
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def error_class_for_sqlstate(sqlstate: str | None) -> type[e.DatabaseError] | None:
|
|
69
|
+
"""Return the dbkit error class for a SQLSTATE, or ``None`` if unrecognized."""
|
|
70
|
+
if not sqlstate:
|
|
71
|
+
return None
|
|
72
|
+
if sqlstate in SQLSTATE_MAP:
|
|
73
|
+
return SQLSTATE_MAP[sqlstate]
|
|
74
|
+
return SQLSTATE_CLASS_MAP.get(sqlstate[:2])
|