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,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])