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,57 @@
1
+ """Best-effort static heuristic flagging writes marked ``idempotent=True`` whose SQL text has
2
+ no visible guard against duplicate execution (§14, §18.3).
3
+
4
+ ``Query.idempotent`` only tells dbkit's retry executor it's *allowed* to retry a write — it is
5
+ a self-declared flag, not a verified property. Marking a plain ``INSERT`` idempotent without an
6
+ ``ON CONFLICT``/uniqueness guard is the single most common way to turn a transient network blip
7
+ into a duplicate row. This module is a *lint*, not a gate: it recognizes common textual patterns
8
+ that make a write self-evidently safe to repeat, so ``dbkit query-list`` can nudge a reviewer
9
+ toward double-checking, not enforce anything (dbkit cannot know the schema's unique constraints
10
+ from SQL text alone).
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import re
16
+
17
+ from .query import Query
18
+
19
+ # Patterns that make a write's own SQL text self-evidently safe to run twice: an explicit
20
+ # conflict/idempotency guard.
21
+ _GUARD_PATTERNS = (
22
+ re.compile(r"\bON\s+CONFLICT\b", re.IGNORECASE),
23
+ re.compile(r"\bWHERE\s+NOT\s+EXISTS\b", re.IGNORECASE),
24
+ re.compile(r"\bMERGE\b", re.IGNORECASE),
25
+ re.compile(r"\bINSERT\s+IGNORE\b", re.IGNORECASE), # MySQL-style; harmless to recognize
26
+ )
27
+
28
+ # INSERT is the operation most likely to duplicate rows on a naive retry. UPDATE/DELETE/etc.
29
+ # targeting a specific row via WHERE are typically naturally idempotent (repeating them leaves
30
+ # the same end state), so they're not flagged even without an explicit guard.
31
+ _INSERT_RE = re.compile(r"^\s*INSERT\b", re.IGNORECASE)
32
+
33
+
34
+ def statement_text(query: Query) -> str | None:
35
+ """Best-effort plain SQL text for ``query.statement``, or ``None`` if unavailable (e.g. a
36
+ SQLAlchemy Core construct rather than a ``sql()``/``text()`` clause)."""
37
+ text_attr = getattr(query.statement, "text", None)
38
+ return text_attr if isinstance(text_attr, str) else None
39
+
40
+
41
+ def looks_unsafe_to_retry(query: Query) -> bool:
42
+ """Whether ``query`` is marked ``idempotent=True`` for a write but its SQL text has no
43
+ visible guard against duplication on retry.
44
+
45
+ This is a heuristic, not a guarantee either way: a false positive (flagging a genuinely-safe
46
+ query) just means an extra line in ``dbkit query-list``; a false negative is expected and
47
+ unavoidable — recognizing that a write is *actually* safe to repeat requires knowing the
48
+ schema's unique constraints, which isn't visible from SQL text alone.
49
+ """
50
+ if not (query.is_write and query.idempotent):
51
+ return False
52
+ text_ = statement_text(query)
53
+ if text_ is None:
54
+ return False # can't inspect a bare Core construct's text; nothing to flag
55
+ if not _INSERT_RE.match(text_):
56
+ return False # UPDATE/DELETE/etc. are typically naturally idempotent
57
+ return not any(p.search(text_) for p in _GUARD_PATTERNS)
dbkit/_core/keys.py ADDED
@@ -0,0 +1,29 @@
1
+ """Engine registry keys (§9).
2
+
3
+ One engine exists per unique ``environment:database:shard:role:driver`` tuple within a
4
+ process. The key is a plain string so it is cheap to hash, log, and expose as a metric label.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass
10
+
11
+
12
+ @dataclass(frozen=True, slots=True)
13
+ class EngineKey:
14
+ """Identifies one engine: ``environment:database:shard:role:driver`` (§9)."""
15
+
16
+ environment: str
17
+ database: str
18
+ shard_id: str
19
+ role: str # "primary" | "replica:<name>"
20
+ driver: str
21
+
22
+ def __str__(self) -> str:
23
+ """``environment:database:shard_id:role:driver``."""
24
+ return f"{self.environment}:{self.database}:{self.shard_id}:{self.role}:{self.driver}"
25
+
26
+ @property
27
+ def label(self) -> str:
28
+ """Alias for ``str(self)``, for use as a metrics/log label."""
29
+ return str(self)
@@ -0,0 +1,105 @@
1
+ """Pure policy decisions: timeout resolution and retry eligibility (§12, §14).
2
+
3
+ These functions contain no I/O and no async — they are the shared brain used by both the
4
+ sync and async execution pipelines.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from .config import RetryConfig
10
+ from .errors import DatabaseError
11
+ from .query import Query
12
+
13
+
14
+ def resolve_timeout(
15
+ call_timeout: float | None,
16
+ query: Query | None,
17
+ default_timeout: float | None,
18
+ ) -> float | None:
19
+ """Pick the effective per-operation timeout (§12.1).
20
+
21
+ Precedence: explicit call argument > ``Query.timeout`` > config default. ``None`` at every
22
+ level means "no dbkit-imposed timeout" (the DB/pool timeouts still apply).
23
+ """
24
+ if call_timeout is not None:
25
+ return call_timeout
26
+ if query is not None and query.timeout is not None:
27
+ return query.timeout
28
+ return default_timeout
29
+
30
+
31
+ def remaining_deadline(deadline: float | None, now: float) -> float | None:
32
+ """Seconds left until ``deadline`` (a monotonic timestamp), or ``None`` if unset."""
33
+ if deadline is None:
34
+ return None
35
+ return deadline - now
36
+
37
+
38
+ def effective_timeout(
39
+ call_timeout: float | None,
40
+ query: Query | None,
41
+ default_timeout: float | None,
42
+ deadline: float | None,
43
+ now: float,
44
+ ) -> float | None:
45
+ """Combine the resolved timeout with any caller deadline, taking the tighter bound (§12.2)."""
46
+ base = resolve_timeout(call_timeout, query, default_timeout)
47
+ remaining = remaining_deadline(deadline, now)
48
+ candidates = [c for c in (base, remaining) if c is not None]
49
+ if not candidates:
50
+ return None
51
+ return min(candidates)
52
+
53
+
54
+ def is_idempotent(query: Query | None, idempotent_override: bool | None) -> bool:
55
+ """Whether the call may be retried: ``idempotent_override`` if given, else the query's."""
56
+ if idempotent_override is not None:
57
+ return idempotent_override
58
+ return bool(query and query.idempotent)
59
+
60
+
61
+ def should_retry(
62
+ error: DatabaseError,
63
+ *,
64
+ query: Query | None,
65
+ config: RetryConfig,
66
+ attempt: int,
67
+ idempotent_override: bool | None = None,
68
+ ) -> bool:
69
+ """Decide whether an operation may be retried after ``error`` (§14).
70
+
71
+ ``attempt`` is 1-based (the attempt that just failed). A retry is permitted only when the
72
+ error is retryable, the budget allows another attempt, and — for writes — the operation is
73
+ known-idempotent and write retries are enabled.
74
+ """
75
+ if attempt >= config.attempts:
76
+ return False
77
+ if not error.retryable:
78
+ return False
79
+ # A genuinely unknown commit outcome is never retried automatically (§15).
80
+ if error.transaction_state_unknown:
81
+ return False
82
+
83
+ is_write = bool(query and query.is_write)
84
+ if is_write:
85
+ if not config.retry_writes:
86
+ return False
87
+ if not is_idempotent(query, idempotent_override):
88
+ return False
89
+ else:
90
+ if not config.retry_reads:
91
+ return False
92
+ return True
93
+
94
+
95
+ def backoff_delay_ms(attempt: int, config: RetryConfig, rand: float) -> float:
96
+ """Exponential backoff with optional full jitter (§14.4).
97
+
98
+ ``attempt`` is 1-based; ``rand`` is a caller-supplied value in ``[0, 1)`` (injected so the
99
+ function stays pure and testable). Returns milliseconds, capped by ``maximum_delay_ms``.
100
+ """
101
+ exp = config.initial_delay_ms * (config.multiplier ** max(attempt - 1, 0))
102
+ capped = min(exp, config.maximum_delay_ms)
103
+ if config.jitter == "full":
104
+ return capped * rand
105
+ return capped
dbkit/_core/query.py ADDED
@@ -0,0 +1,142 @@
1
+ """Query objects, the ``sql()`` wrapper, and the query registry (§8, §18.3).
2
+
3
+ Every method on the database facade accepts one of:
4
+
5
+ * a :class:`Query` (named, with metadata),
6
+ * a SQLAlchemy Core ``Executable`` / ``TextClause``, or
7
+ * the result of :func:`sql` — the *only* accepted path for a raw SQL string.
8
+
9
+ Passing a bare ``str`` is rejected (§18.4): it is the single most common SQL-injection and
10
+ un-parameterized-query footgun, so we force an explicit, greppable wrapper.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from dataclasses import dataclass, field
16
+ from typing import Literal
17
+
18
+ from sqlalchemy import text
19
+ from sqlalchemy.sql.elements import TextClause
20
+ from sqlalchemy.sql.expression import Executable
21
+
22
+ from .errors import DatabaseProgrammingError
23
+
24
+ Operation = Literal["read", "write", "ddl"]
25
+ Cardinality = Literal["one", "optional", "many", "none"]
26
+
27
+ #: What the facade will actually execute — a Core construct or a text clause.
28
+ Statement = Executable | TextClause
29
+
30
+
31
+ def sql(statement: str) -> TextClause:
32
+ """Wrap a raw SQL string in a SQLAlchemy ``text()`` clause.
33
+
34
+ This is the only supported way to pass raw SQL. Parameters must be bound with
35
+ ``:name`` placeholders — never interpolated (§18.4)::
36
+
37
+ sql("SELECT * FROM users WHERE id = :user_id")
38
+ """
39
+ if not isinstance(statement, str):
40
+ raise DatabaseProgrammingError(
41
+ "sql() takes a raw SQL string; pass Core constructs directly instead"
42
+ )
43
+ return text(statement)
44
+
45
+
46
+ def coerce_statement(obj: object) -> Statement:
47
+ """Validate/normalize a caller-supplied statement, rejecting bare strings."""
48
+ if isinstance(obj, Query):
49
+ return obj.statement
50
+ if isinstance(obj, (TextClause, Executable)):
51
+ return obj
52
+ if isinstance(obj, str):
53
+ raise DatabaseProgrammingError(
54
+ "raw SQL strings must be wrapped with sql(...) — refusing bare str to prevent "
55
+ "un-parameterized queries"
56
+ )
57
+ raise DatabaseProgrammingError(
58
+ f"unsupported query type: {type(obj).__name__}; expected Query, sql(...), or a "
59
+ "SQLAlchemy Core statement"
60
+ )
61
+
62
+
63
+ @dataclass(frozen=True, slots=True)
64
+ class Query:
65
+ """A named, parameterized query with execution metadata (§8.5).
66
+
67
+ ``name`` is a stable *logical* label used for metrics, tracing, and logs — never the raw
68
+ SQL text (§18.3). ``sensitive_parameters`` are redacted everywhere (§13.4).
69
+ """
70
+
71
+ name: str
72
+ statement: Statement
73
+ operation: Operation = "read"
74
+ timeout: float | None = None
75
+ #: Declares this write *may* be retried by dbkit's retry executor (§14) — it does **not**
76
+ #: verify the SQL is actually safe to run twice. Marking a plain ``INSERT`` idempotent
77
+ #: without an ``ON CONFLICT``/uniqueness guard is the most common way a transient network
78
+ #: blip (the write commits, the client never sees the ack) turns into a duplicate row on
79
+ #: retry. Only set this when the statement itself is genuinely safe to repeat (``ON
80
+ #: CONFLICT``, ``WHERE NOT EXISTS``, or a natural-key ``UPDATE``/``DELETE``) — see
81
+ #: ``dbkit query-list``, which flags writes that look unsafe by this heuristic.
82
+ idempotent: bool = False
83
+ #: Marks this query for the separate ``expensive_queries`` concurrency tier
84
+ #: (``ConcurrencyConfig.expensive_queries``, §17), acquired *in addition to* the normal
85
+ #: reads/writes tier — for a small number of known-heavy queries (a big aggregation, an
86
+ #: ad-hoc report) that would otherwise be free to pile up alongside ordinary traffic and
87
+ #: saturate the database. Most queries should leave this ``False``.
88
+ expensive: bool = False
89
+ expected_cardinality: Cardinality | None = None
90
+ sensitive_parameters: frozenset[str] = field(default_factory=frozenset)
91
+
92
+ def __post_init__(self) -> None:
93
+ """Reject bare-string statements/empty names and normalize ``sensitive_parameters``."""
94
+ if isinstance(self.statement, str): # pragma: no cover - guarded by typing too
95
+ raise DatabaseProgrammingError(
96
+ f"Query(name={self.name!r}) statement must be sql(...) or a Core construct, "
97
+ "not a bare string"
98
+ )
99
+ if not self.name:
100
+ raise DatabaseProgrammingError("Query.name must be a non-empty logical name")
101
+ # Normalize sensitive_parameters to a frozenset even if a set/list was passed.
102
+ object.__setattr__(self, "sensitive_parameters", frozenset(self.sensitive_parameters))
103
+
104
+ @property
105
+ def is_write(self) -> bool:
106
+ """Whether this query mutates data or schema (``operation`` is ``write``/``ddl``)."""
107
+ return self.operation in ("write", "ddl")
108
+
109
+
110
+ class QueryRegistry:
111
+ """In-process registry of named queries for CLI listing and duplicate detection (§8.5)."""
112
+
113
+ def __init__(self) -> None:
114
+ """Create an empty registry."""
115
+ self._queries: dict[str, Query] = {}
116
+
117
+ def register(self, query: Query) -> Query:
118
+ """Register ``query`` and return it; raises if the name is already taken by a
119
+ *different* :class:`Query` object (registering the same object twice is a no-op)."""
120
+ existing = self._queries.get(query.name)
121
+ if existing is not None and existing is not query:
122
+ raise DatabaseProgrammingError(
123
+ f"duplicate query name {query.name!r} registered with a different statement"
124
+ )
125
+ self._queries[query.name] = query
126
+ return query
127
+
128
+ def get(self, name: str) -> Query | None:
129
+ """The registered :class:`Query` named ``name``, or ``None`` if none was registered."""
130
+ return self._queries.get(name)
131
+
132
+ def names(self) -> list[str]:
133
+ """Every registered query name, sorted."""
134
+ return sorted(self._queries)
135
+
136
+ def all(self) -> list[Query]:
137
+ """Every registered :class:`Query`, ordered by name."""
138
+ return [self._queries[n] for n in self.names()]
139
+
140
+
141
+ #: Process-global default registry. Applications may create their own.
142
+ default_registry = QueryRegistry()
dbkit/_core/result.py ADDED
@@ -0,0 +1,109 @@
1
+ """Typed results and row mappers (§8.3, §8.4).
2
+
3
+ Cardinality enforcement (exactly-one / at-most-one / scalar) is *not* reimplemented here — the
4
+ async/sync facades call SQLAlchemy's own native ``Result.one()`` / ``.one_or_none()`` /
5
+ ``.scalar_one()`` / ``.scalars().all()`` directly (see ``_async/connection.py``), which already
6
+ provide these exact semantics. This module only covers what SQLAlchemy has no opinion on:
7
+ mapping a row to an application type (dataclass, TypedDict, pydantic model, callable).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import dataclasses
13
+ import typing
14
+ from collections.abc import Callable, Sequence
15
+ from dataclasses import dataclass, field
16
+ from typing import Any, TypeVar
17
+
18
+ from sqlalchemy import RowMapping
19
+
20
+ from .errors import DatabaseMappingError
21
+
22
+ T = TypeVar("T")
23
+
24
+ #: A caller-supplied mapper receives one row mapping and returns a mapped object.
25
+ RowMapper = Callable[[RowMapping], Any]
26
+
27
+
28
+ @dataclass(frozen=True, slots=True)
29
+ class ExecutionResult:
30
+ """Standard result returned by write methods (§8.3)."""
31
+
32
+ row_count: int
33
+ query_name: str
34
+ database_name: str
35
+ duration_ms: float
36
+ inserted_primary_key: object | None = None
37
+ returned_rows: Sequence[RowMapping] = field(default_factory=tuple)
38
+ shard_id: str | None = None
39
+ role: str | None = None
40
+ retry_attempt: int = 0
41
+
42
+
43
+ def _is_typed_dict(obj: object) -> bool:
44
+ return isinstance(obj, type) and typing.is_typeddict(obj)
45
+
46
+
47
+ def build_mapper(map_to: Any) -> RowMapper:
48
+ """Return a function mapping a ``RowMapping`` to the requested type (§8.4).
49
+
50
+ Supported ``map_to`` values:
51
+
52
+ * ``None`` or ``RowMapping`` — identity (zero-copy default).
53
+ * ``dict`` — a plain dict copy.
54
+ * a dataclass type — constructed from matching column names.
55
+ * a ``TypedDict`` type — a dict with the row's contents.
56
+ * a pydantic model (has ``model_validate``) — validated from the row.
57
+ * any other callable — invoked as ``mapper(row)``.
58
+ """
59
+ if map_to is None or map_to is RowMapping:
60
+ return lambda row: row
61
+
62
+ if map_to is dict:
63
+ return lambda row: dict(row)
64
+
65
+ if dataclasses.is_dataclass(map_to) and isinstance(map_to, type):
66
+ field_names = {f.name for f in dataclasses.fields(map_to)}
67
+
68
+ def _map_dataclass(row: RowMapping) -> Any:
69
+ try:
70
+ return map_to(**{k: row[k] for k in row if k in field_names})
71
+ except Exception as exc:
72
+ raise DatabaseMappingError(
73
+ f"failed to map row to {map_to.__name__}: {exc}", original=exc
74
+ ) from exc
75
+
76
+ return _map_dataclass
77
+
78
+ if _is_typed_dict(map_to):
79
+ return lambda row: dict(row)
80
+
81
+ if isinstance(map_to, type) and hasattr(map_to, "model_validate"):
82
+
83
+ def _map_pydantic(row: RowMapping) -> Any:
84
+ try:
85
+ return map_to.model_validate(dict(row))
86
+ except Exception as exc:
87
+ raise DatabaseMappingError(
88
+ f"failed to validate row into {map_to.__name__}: {exc}", original=exc
89
+ ) from exc
90
+
91
+ return _map_pydantic
92
+
93
+ if callable(map_to):
94
+
95
+ def _map_callable(row: RowMapping) -> Any:
96
+ try:
97
+ return map_to(row)
98
+ except Exception as exc:
99
+ raise DatabaseMappingError(f"custom mapper raised: {exc}", original=exc) from exc
100
+
101
+ return _map_callable
102
+
103
+ raise DatabaseMappingError(f"unsupported map_to value: {map_to!r}")
104
+
105
+
106
+ def map_rows(rows: Sequence[RowMapping], map_to: Any) -> list[Any]:
107
+ """Map every row in ``rows`` to ``map_to`` (see :func:`build_mapper` for accepted values)."""
108
+ mapper = build_mapper(map_to)
109
+ return [mapper(r) for r in rows]