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,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)
|
dbkit/_core/policies.py
ADDED
|
@@ -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]
|