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,331 @@
|
|
|
1
|
+
# This file is GENERATED from ../_async/connection.py by tools/run_unasync.py.
|
|
2
|
+
# Do not edit by hand. Run `make unasync` after changing the async source.
|
|
3
|
+
|
|
4
|
+
"""Low-level execution primitives and the explicit connection scope (§11.1-11.2).
|
|
5
|
+
|
|
6
|
+
The primitives take an already-acquired SQLAlchemy connection and run one statement. Cardinality
|
|
7
|
+
(exactly-one / at-most-one / scalar) is enforced by SQLAlchemy's own native ``Result.one()`` /
|
|
8
|
+
``.one_or_none()`` / ``.scalar_one()`` / ``.scalars().all()`` — not reimplemented here — with
|
|
9
|
+
``NoResultFound`` / ``MultipleResultsFound`` translated to :class:`DatabaseResultError`. Higher
|
|
10
|
+
layers (the facade, the connection scope, the transaction scope) reuse these primitives so
|
|
11
|
+
mapping, timeouts, and error classification live in exactly one place.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import contextlib
|
|
17
|
+
from collections.abc import Mapping, Sequence
|
|
18
|
+
from typing import Any
|
|
19
|
+
|
|
20
|
+
from sqlalchemy import RowMapping, text
|
|
21
|
+
from sqlalchemy.engine import CursorResult
|
|
22
|
+
from sqlalchemy.exc import MultipleResultsFound, NoResultFound
|
|
23
|
+
from sqlalchemy import Connection
|
|
24
|
+
|
|
25
|
+
from .._core import result as result_mod
|
|
26
|
+
from .._core.errors import DatabaseResultError, classify
|
|
27
|
+
from .._core.query import Query, Statement, coerce_statement
|
|
28
|
+
from ._compat import IS_ASYNC, pipeline_scope, timeout_scope
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def apply_statement_timeout_sql(seconds: float | None) -> str | None:
|
|
32
|
+
"""Return a ``SET LOCAL statement_timeout`` statement for PostgreSQL, or ``None``.
|
|
33
|
+
|
|
34
|
+
The value is our own integer (milliseconds), never caller input, so inlining it is safe.
|
|
35
|
+
"""
|
|
36
|
+
if seconds is None or seconds <= 0:
|
|
37
|
+
return None
|
|
38
|
+
ms = max(int(seconds * 1000), 1)
|
|
39
|
+
return f"SET LOCAL statement_timeout = {ms}"
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _maybe_set_timeout(
|
|
43
|
+
conn: Connection, seconds: float | None, *, is_postgres: bool
|
|
44
|
+
) -> None:
|
|
45
|
+
# The async frontend bounds a single statement with a real client-side deadline
|
|
46
|
+
# (``asyncio.timeout``), which cancels the driver — so the extra server-side
|
|
47
|
+
# ``SET statement_timeout`` round trip is pure overhead and is skipped. The sync frontend
|
|
48
|
+
# has no client-side timeout primitive, so it relies on the server-side setting (§12.1).
|
|
49
|
+
if IS_ASYNC or not is_postgres:
|
|
50
|
+
return
|
|
51
|
+
stmt = apply_statement_timeout_sql(seconds)
|
|
52
|
+
if stmt is not None:
|
|
53
|
+
conn.execute(text(stmt))
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def run_fetch(
|
|
57
|
+
conn: Connection,
|
|
58
|
+
statement: Statement,
|
|
59
|
+
params: Mapping[str, Any] | None,
|
|
60
|
+
*,
|
|
61
|
+
timeout: float | None,
|
|
62
|
+
is_postgres: bool,
|
|
63
|
+
) -> list[RowMapping]:
|
|
64
|
+
"""Execute a read and return every row mapping, no cardinality constraint."""
|
|
65
|
+
with timeout_scope(timeout):
|
|
66
|
+
_maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
|
|
67
|
+
cursor = conn.execute(statement, params or {})
|
|
68
|
+
return list(cursor.mappings().all())
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def run_fetch_one(
|
|
72
|
+
conn: Connection,
|
|
73
|
+
statement: Statement,
|
|
74
|
+
params: Mapping[str, Any] | None,
|
|
75
|
+
*,
|
|
76
|
+
timeout: float | None,
|
|
77
|
+
is_postgres: bool,
|
|
78
|
+
) -> RowMapping:
|
|
79
|
+
"""Execute a read expecting exactly one row (``Result.one()``, §8.1)."""
|
|
80
|
+
with timeout_scope(timeout):
|
|
81
|
+
_maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
|
|
82
|
+
cursor = conn.execute(statement, params or {})
|
|
83
|
+
return cursor.mappings().one()
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def run_fetch_optional(
|
|
87
|
+
conn: Connection,
|
|
88
|
+
statement: Statement,
|
|
89
|
+
params: Mapping[str, Any] | None,
|
|
90
|
+
*,
|
|
91
|
+
timeout: float | None,
|
|
92
|
+
is_postgres: bool,
|
|
93
|
+
) -> RowMapping | None:
|
|
94
|
+
"""Execute a read expecting zero or one row (``Result.one_or_none()``, §8.1)."""
|
|
95
|
+
with timeout_scope(timeout):
|
|
96
|
+
_maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
|
|
97
|
+
cursor = conn.execute(statement, params or {})
|
|
98
|
+
return cursor.mappings().one_or_none()
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def run_fetch_value(
|
|
102
|
+
conn: Connection,
|
|
103
|
+
statement: Statement,
|
|
104
|
+
params: Mapping[str, Any] | None,
|
|
105
|
+
*,
|
|
106
|
+
timeout: float | None,
|
|
107
|
+
is_postgres: bool,
|
|
108
|
+
) -> Any:
|
|
109
|
+
"""Execute a read expecting exactly one row and take its first column
|
|
110
|
+
(``Result.scalar_one()``, §8.1)."""
|
|
111
|
+
with timeout_scope(timeout):
|
|
112
|
+
_maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
|
|
113
|
+
cursor = conn.execute(statement, params or {})
|
|
114
|
+
return cursor.scalar_one()
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def run_fetch_values(
|
|
118
|
+
conn: Connection,
|
|
119
|
+
statement: Statement,
|
|
120
|
+
params: Mapping[str, Any] | None,
|
|
121
|
+
*,
|
|
122
|
+
timeout: float | None,
|
|
123
|
+
is_postgres: bool,
|
|
124
|
+
) -> list[Any]:
|
|
125
|
+
"""Execute a read and take the first column of every row (``Result.scalars().all()``)."""
|
|
126
|
+
with timeout_scope(timeout):
|
|
127
|
+
_maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
|
|
128
|
+
cursor = conn.execute(statement, params or {})
|
|
129
|
+
return list(cursor.scalars().all())
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def run_execute(
|
|
133
|
+
conn: Connection,
|
|
134
|
+
statement: Statement,
|
|
135
|
+
params: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None,
|
|
136
|
+
*,
|
|
137
|
+
timeout: float | None,
|
|
138
|
+
is_postgres: bool,
|
|
139
|
+
) -> CursorResult[Any]:
|
|
140
|
+
"""Execute a write/DDL statement and return the cursor result (for rowcount/returning)."""
|
|
141
|
+
with timeout_scope(timeout):
|
|
142
|
+
_maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
|
|
143
|
+
return conn.execute(statement, params or {})
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
class ConnectionScope:
|
|
147
|
+
"""A held connection exposing the fetch/execute family (§11.2).
|
|
148
|
+
|
|
149
|
+
Obtained via ``with db.connection(target) as conn:``. All operations run on the same
|
|
150
|
+
physical connection; use this when several statements must share connection state.
|
|
151
|
+
"""
|
|
152
|
+
|
|
153
|
+
def __init__(
|
|
154
|
+
self,
|
|
155
|
+
conn: Connection,
|
|
156
|
+
*,
|
|
157
|
+
is_postgres: bool,
|
|
158
|
+
default_timeout: float | None,
|
|
159
|
+
database: str,
|
|
160
|
+
shard_id: str,
|
|
161
|
+
role: str,
|
|
162
|
+
) -> None:
|
|
163
|
+
"""Wrap an already-acquired connection; not constructed directly by applications."""
|
|
164
|
+
self._conn = conn
|
|
165
|
+
self._is_postgres = is_postgres
|
|
166
|
+
self._default_timeout = default_timeout
|
|
167
|
+
self._database = database
|
|
168
|
+
self._shard_id = shard_id
|
|
169
|
+
self._role = role
|
|
170
|
+
|
|
171
|
+
@property
|
|
172
|
+
def raw(self) -> Connection:
|
|
173
|
+
"""The underlying SQLAlchemy connection — an explicit "you now own error handling"
|
|
174
|
+
escape hatch (§7.3).
|
|
175
|
+
|
|
176
|
+
Anything executed via ``.raw`` bypasses dbkit entirely: no error classification (you'll
|
|
177
|
+
see raw driver/SQLAlchemy exceptions, not :class:`~dbkit.errors.DatabaseError`
|
|
178
|
+
subclasses — an ``except DatabaseError`` handler will not catch them), no metrics, no
|
|
179
|
+
tracing, and no retry/circuit-breaker/commit-unknown handling. Use it only for the two
|
|
180
|
+
things dbkit doesn't itself implement (:meth:`pipeline`, :meth:`~dbkit.Database.
|
|
181
|
+
copy_records`'s underlying driver connection) or a genuine one-off that needs raw driver
|
|
182
|
+
access — not as a routine way to run queries.
|
|
183
|
+
"""
|
|
184
|
+
return self._conn
|
|
185
|
+
|
|
186
|
+
def pipeline(self) -> contextlib.AbstractContextManager[None]:
|
|
187
|
+
"""Enter psycopg pipeline mode (§7.3): statements issued in this block are sent to the
|
|
188
|
+
server without waiting for each response before the next — one round trip for several
|
|
189
|
+
dependent-but-batchable statements (e.g. a business write plus its inbox record, §28).
|
|
190
|
+
|
|
191
|
+
Usage::
|
|
192
|
+
|
|
193
|
+
with db.transaction(target=t) as tx, tx.pipeline():
|
|
194
|
+
tx.execute(INSERT_ORDER, params)
|
|
195
|
+
tx.execute(INSERT_INBOX, params)
|
|
196
|
+
|
|
197
|
+
PostgreSQL + psycopg only; raises :class:`DatabaseUnsupportedOperationError` otherwise.
|
|
198
|
+
Ordinary ``tx.execute(...)`` calls work unchanged inside the block — SQLAlchemy's
|
|
199
|
+
cursor execution transparently syncs the pipeline whenever a result is fetched.
|
|
200
|
+
"""
|
|
201
|
+
return pipeline_scope(self._conn)
|
|
202
|
+
|
|
203
|
+
def _resolve(
|
|
204
|
+
self, query: object, params: Mapping[str, Any] | None
|
|
205
|
+
) -> tuple[Statement, Query | None, float | None, str]:
|
|
206
|
+
statement = coerce_statement(query)
|
|
207
|
+
q = query if isinstance(query, Query) else None
|
|
208
|
+
timeout = q.timeout if (q and q.timeout is not None) else self._default_timeout
|
|
209
|
+
name = q.name if q else "adhoc"
|
|
210
|
+
return statement, q, timeout, name
|
|
211
|
+
|
|
212
|
+
def fetch_all(
|
|
213
|
+
self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
|
|
214
|
+
) -> list[Any]:
|
|
215
|
+
"""Run a read and return every row, mapped to ``map_to`` (no cardinality check)."""
|
|
216
|
+
statement, _q, timeout, name = self._resolve(query, params)
|
|
217
|
+
try:
|
|
218
|
+
rows = run_fetch(
|
|
219
|
+
self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
|
|
220
|
+
)
|
|
221
|
+
except Exception as exc:
|
|
222
|
+
raise classify(
|
|
223
|
+
exc, query_name=name, database_name=self._database, role=self._role
|
|
224
|
+
) from exc
|
|
225
|
+
return result_mod.map_rows(rows, map_to)
|
|
226
|
+
|
|
227
|
+
def fetch_one(
|
|
228
|
+
self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
|
|
229
|
+
) -> Any:
|
|
230
|
+
"""Run a read expecting exactly one row; raises :class:`DatabaseResultError` otherwise."""
|
|
231
|
+
statement, _q, timeout, name = self._resolve(query, params)
|
|
232
|
+
try:
|
|
233
|
+
row = run_fetch_one(
|
|
234
|
+
self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
|
|
235
|
+
)
|
|
236
|
+
except NoResultFound as exc:
|
|
237
|
+
raise DatabaseResultError(
|
|
238
|
+
f"query {name!r} returned no rows, expected exactly one",
|
|
239
|
+
query_name=name,
|
|
240
|
+
database_name=self._database,
|
|
241
|
+
role=self._role,
|
|
242
|
+
) from exc
|
|
243
|
+
except MultipleResultsFound as exc:
|
|
244
|
+
raise DatabaseResultError(
|
|
245
|
+
f"query {name!r} returned more than one row, expected exactly one",
|
|
246
|
+
query_name=name,
|
|
247
|
+
database_name=self._database,
|
|
248
|
+
role=self._role,
|
|
249
|
+
) from exc
|
|
250
|
+
except Exception as exc:
|
|
251
|
+
raise classify(
|
|
252
|
+
exc, query_name=name, database_name=self._database, role=self._role
|
|
253
|
+
) from exc
|
|
254
|
+
return result_mod.build_mapper(map_to)(row)
|
|
255
|
+
|
|
256
|
+
def fetch_optional(
|
|
257
|
+
self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
|
|
258
|
+
) -> Any | None:
|
|
259
|
+
"""Run a read expecting zero or one row; ``None`` if empty, else the mapped row."""
|
|
260
|
+
statement, _q, timeout, name = self._resolve(query, params)
|
|
261
|
+
try:
|
|
262
|
+
row = run_fetch_optional(
|
|
263
|
+
self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
|
|
264
|
+
)
|
|
265
|
+
except MultipleResultsFound as exc:
|
|
266
|
+
raise DatabaseResultError(
|
|
267
|
+
f"query {name!r} returned more than one row, expected at most one",
|
|
268
|
+
query_name=name,
|
|
269
|
+
database_name=self._database,
|
|
270
|
+
role=self._role,
|
|
271
|
+
) from exc
|
|
272
|
+
except Exception as exc:
|
|
273
|
+
raise classify(
|
|
274
|
+
exc, query_name=name, database_name=self._database, role=self._role
|
|
275
|
+
) from exc
|
|
276
|
+
if row is None:
|
|
277
|
+
return None
|
|
278
|
+
return result_mod.build_mapper(map_to)(row)
|
|
279
|
+
|
|
280
|
+
def fetch_value(self, query: object, params: Mapping[str, Any] | None = None) -> Any:
|
|
281
|
+
"""Run a read expecting exactly one row and return its first column."""
|
|
282
|
+
statement, _q, timeout, name = self._resolve(query, params)
|
|
283
|
+
try:
|
|
284
|
+
return run_fetch_value(
|
|
285
|
+
self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
|
|
286
|
+
)
|
|
287
|
+
except NoResultFound as exc:
|
|
288
|
+
raise DatabaseResultError(
|
|
289
|
+
f"query {name!r} returned no rows, expected a single scalar value",
|
|
290
|
+
query_name=name,
|
|
291
|
+
database_name=self._database,
|
|
292
|
+
role=self._role,
|
|
293
|
+
) from exc
|
|
294
|
+
except MultipleResultsFound as exc:
|
|
295
|
+
raise DatabaseResultError(
|
|
296
|
+
f"query {name!r} returned more than one row, expected a single scalar value",
|
|
297
|
+
query_name=name,
|
|
298
|
+
database_name=self._database,
|
|
299
|
+
role=self._role,
|
|
300
|
+
) from exc
|
|
301
|
+
except Exception as exc:
|
|
302
|
+
raise classify(
|
|
303
|
+
exc, query_name=name, database_name=self._database, role=self._role
|
|
304
|
+
) from exc
|
|
305
|
+
|
|
306
|
+
def fetch_values(
|
|
307
|
+
self, query: object, params: Mapping[str, Any] | None = None
|
|
308
|
+
) -> list[Any]:
|
|
309
|
+
"""Run a read and return the first column of every row."""
|
|
310
|
+
statement, _q, timeout, name = self._resolve(query, params)
|
|
311
|
+
try:
|
|
312
|
+
return run_fetch_values(
|
|
313
|
+
self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
|
|
314
|
+
)
|
|
315
|
+
except Exception as exc:
|
|
316
|
+
raise classify(
|
|
317
|
+
exc, query_name=name, database_name=self._database, role=self._role
|
|
318
|
+
) from exc
|
|
319
|
+
|
|
320
|
+
def execute(self, query: object, params: Mapping[str, Any] | None = None) -> int:
|
|
321
|
+
"""Run a write/DDL statement and return the affected row count."""
|
|
322
|
+
statement, _q, timeout, name = self._resolve(query, params)
|
|
323
|
+
try:
|
|
324
|
+
cursor = run_execute(
|
|
325
|
+
self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
|
|
326
|
+
)
|
|
327
|
+
return cursor.rowcount
|
|
328
|
+
except Exception as exc:
|
|
329
|
+
raise classify(
|
|
330
|
+
exc, query_name=name, database_name=self._database, role=self._role
|
|
331
|
+
) from exc
|