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
dbkit/__init__.py ADDED
@@ -0,0 +1,77 @@
1
+ """dbkit — a thin, high-throughput SQL toolkit over SQLAlchemy Core (sync + async).
2
+
3
+ Public API::
4
+
5
+ from dbkit import AsyncDatabase, Database, Query, sql, DatabaseTarget
6
+ from dbkit import errors
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from . import errors
12
+ from ._async.database import AsyncDatabase
13
+ from ._core.config import (
14
+ BulkConfig,
15
+ CircuitBreakerConfig,
16
+ ConcurrencyConfig,
17
+ ConnectionBudgetConfig,
18
+ DatabaseConfig,
19
+ DbkitConfig,
20
+ Defaults,
21
+ ObservabilityConfig,
22
+ PoolConfig,
23
+ RetryConfig,
24
+ TargetConfig,
25
+ )
26
+ from ._core.query import Query, QueryRegistry, default_registry, sql
27
+ from ._core.result import ExecutionResult
28
+ from ._core.routing import (
29
+ CallableShardResolver,
30
+ DatabaseTarget,
31
+ DirectoryShardResolver,
32
+ HashShardResolver,
33
+ RangeShardResolver,
34
+ ReplicaSelector,
35
+ RoundRobinReplicaSelector,
36
+ ShardRange,
37
+ ShardResolver,
38
+ SingleShardResolver,
39
+ WeightedReplicaSelector,
40
+ )
41
+ from ._sync.database import Database
42
+
43
+ __version__ = "0.1.0"
44
+
45
+ __all__ = [
46
+ "AsyncDatabase",
47
+ "BulkConfig",
48
+ "CallableShardResolver",
49
+ "CircuitBreakerConfig",
50
+ "ConcurrencyConfig",
51
+ "ConnectionBudgetConfig",
52
+ "Database",
53
+ "DatabaseConfig",
54
+ "DatabaseTarget",
55
+ "DbkitConfig",
56
+ "Defaults",
57
+ "DirectoryShardResolver",
58
+ "ExecutionResult",
59
+ "HashShardResolver",
60
+ "ObservabilityConfig",
61
+ "PoolConfig",
62
+ "Query",
63
+ "QueryRegistry",
64
+ "RangeShardResolver",
65
+ "ReplicaSelector",
66
+ "RetryConfig",
67
+ "RoundRobinReplicaSelector",
68
+ "ShardRange",
69
+ "ShardResolver",
70
+ "SingleShardResolver",
71
+ "TargetConfig",
72
+ "WeightedReplicaSelector",
73
+ "__version__",
74
+ "default_registry",
75
+ "errors",
76
+ "sql",
77
+ ]
@@ -0,0 +1,17 @@
1
+ """Async frontend (hand-written source of truth; the sync frontend is generated from it)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .connection import AsyncConnectionScope
6
+ from .database import AsyncDatabase
7
+ from .engine import AsyncEngineRegistry
8
+ from .health import HealthReport
9
+ from .transaction import AsyncTransactionScope
10
+
11
+ __all__ = [
12
+ "AsyncConnectionScope",
13
+ "AsyncDatabase",
14
+ "AsyncEngineRegistry",
15
+ "AsyncTransactionScope",
16
+ "HealthReport",
17
+ ]
@@ -0,0 +1,111 @@
1
+ """Async-specific primitives that do not translate by token substitution.
2
+
3
+ This module is hand-written on both sides (see ``_sync/_compat.py``); the unasync generator
4
+ skips it. It isolates the two genuine sync/async differences: client-side timeouts and
5
+ cancellation handling (§12).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import asyncio
11
+ import contextlib
12
+ from collections.abc import Coroutine
13
+ from typing import Any, TypeVar
14
+
15
+ IS_ASYNC = True
16
+
17
+ #: Metric/label value distinguishing this frontend (§25.1).
18
+ API_LABEL = "async"
19
+
20
+ T = TypeVar("T")
21
+
22
+
23
+ def sync_engine_of(engine: Any) -> Any:
24
+ """The synchronous ``Engine`` that owns the pool and fires pool events.
25
+
26
+ For an ``AsyncEngine`` this is ``engine.sync_engine``; pool events are always synchronous
27
+ and fire on it. (The sync build returns the engine itself.)
28
+ """
29
+ return engine.sync_engine
30
+
31
+
32
+ async def sleep(seconds: float) -> None:
33
+ """Frontend-appropriate sleep (async ``asyncio.sleep``; sync ``time.sleep``)."""
34
+ await asyncio.sleep(seconds)
35
+
36
+
37
+ async def stream_mappings(conn: Any, statement: Any, params: Any, batch_size: int) -> Any:
38
+ """Yield row mappings from a server-side cursor without buffering the full result.
39
+
40
+ Async uses ``AsyncConnection.stream`` (a real server-side cursor); the sync build uses
41
+ ``yield_per`` execution options. Both fetch in ``batch_size`` chunks (§20).
42
+ """
43
+ result = await conn.stream(statement, params or {}, execution_options={"yield_per": batch_size})
44
+ async for row in result.mappings():
45
+ yield row
46
+
47
+
48
+ async def copy_from_records(sa_conn: Any, table: str, columns: Any, records: Any) -> int:
49
+ """Dispatch to the async PostgreSQL COPY implementation (§19.2)."""
50
+ from ..postgres.copy import copy_records_async
51
+
52
+ return await copy_records_async(sa_conn, table, columns, records)
53
+
54
+
55
+ def pipeline_scope(sa_conn: Any) -> contextlib.AbstractAsyncContextManager[None]:
56
+ """Dispatch to the async psycopg pipeline-mode implementation (§7.3)."""
57
+ from ..postgres.pipeline import pipeline_scope_async
58
+
59
+ return pipeline_scope_async(sa_conn)
60
+
61
+
62
+ def timeout_scope(seconds: float | None) -> contextlib.AbstractAsyncContextManager[Any]:
63
+ """A client-side deadline. Async uses :func:`asyncio.timeout`; the sync build has no
64
+ client-side timeout and relies on the server ``statement_timeout`` instead (§12.1)."""
65
+ if seconds is None or seconds <= 0:
66
+ return contextlib.nullcontext()
67
+ return asyncio.timeout(seconds)
68
+
69
+
70
+ async def semaphore_acquire(sem: asyncio.Semaphore, timeout: float | None) -> bool:
71
+ """Acquire ``sem``, returning False (never raising) if ``timeout`` elapses first.
72
+
73
+ ``asyncio.Semaphore.acquire()`` has no built-in timeout, unlike ``threading.Semaphore``
74
+ (§17); this wraps it in :func:`asyncio.wait_for` so both frontends expose the same
75
+ bounded-wait contract to :class:`ConcurrencyLimiter`.
76
+ """
77
+ if timeout is None:
78
+ await sem.acquire()
79
+ return True
80
+ try:
81
+ await asyncio.wait_for(sem.acquire(), timeout=timeout)
82
+ except TimeoutError:
83
+ return False
84
+ return True
85
+
86
+
87
+ def is_cancellation(exc: BaseException) -> bool:
88
+ """True if ``exc`` is a cooperative cancellation that must be re-raised, not swallowed."""
89
+ return isinstance(exc, asyncio.CancelledError)
90
+
91
+
92
+ async def shield_from_cancellation(coro: Coroutine[Any, Any, T]) -> T:
93
+ """Run ``coro`` (a short cleanup: rollback/return-to-pool) to completion even if the
94
+ current task is cancelled again while it's in progress (§12.3).
95
+
96
+ A plain ``try/except CancelledError`` around an ``await`` in the *same* task cannot prevent
97
+ that await from being interrupted — it can only react after the fact. Genuine shielding
98
+ requires the protected work to run as a separate task: ``asyncio.shield()`` protects that
99
+ inner task from a cancellation delivered to the *outer* one. If the caller's task is
100
+ cancelled while waiting here, the cancellation is deferred until the shielded cleanup has
101
+ actually finished running (not swallowed — the cancellation is still re-raised once cleanup
102
+ completes), so a caller can rely on rollback/release never being left half-done.
103
+ """
104
+ task = asyncio.ensure_future(coro)
105
+ try:
106
+ return await asyncio.shield(task)
107
+ except asyncio.CancelledError:
108
+ if not task.done():
109
+ with contextlib.suppress(asyncio.CancelledError, Exception):
110
+ await asyncio.shield(task)
111
+ raise
@@ -0,0 +1,328 @@
1
+ """Low-level execution primitives and the explicit connection scope (§11.1-11.2).
2
+
3
+ The primitives take an already-acquired SQLAlchemy connection and run one statement. Cardinality
4
+ (exactly-one / at-most-one / scalar) is enforced by SQLAlchemy's own native ``Result.one()`` /
5
+ ``.one_or_none()`` / ``.scalar_one()`` / ``.scalars().all()`` — not reimplemented here — with
6
+ ``NoResultFound`` / ``MultipleResultsFound`` translated to :class:`DatabaseResultError`. Higher
7
+ layers (the facade, the connection scope, the transaction scope) reuse these primitives so
8
+ mapping, timeouts, and error classification live in exactly one place.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import contextlib
14
+ from collections.abc import Mapping, Sequence
15
+ from typing import Any
16
+
17
+ from sqlalchemy import RowMapping, text
18
+ from sqlalchemy.engine import CursorResult
19
+ from sqlalchemy.exc import MultipleResultsFound, NoResultFound
20
+ from sqlalchemy.ext.asyncio import AsyncConnection
21
+
22
+ from .._core import result as result_mod
23
+ from .._core.errors import DatabaseResultError, classify
24
+ from .._core.query import Query, Statement, coerce_statement
25
+ from ._compat import IS_ASYNC, pipeline_scope, timeout_scope
26
+
27
+
28
+ def apply_statement_timeout_sql(seconds: float | None) -> str | None:
29
+ """Return a ``SET LOCAL statement_timeout`` statement for PostgreSQL, or ``None``.
30
+
31
+ The value is our own integer (milliseconds), never caller input, so inlining it is safe.
32
+ """
33
+ if seconds is None or seconds <= 0:
34
+ return None
35
+ ms = max(int(seconds * 1000), 1)
36
+ return f"SET LOCAL statement_timeout = {ms}"
37
+
38
+
39
+ async def _maybe_set_timeout(
40
+ conn: AsyncConnection, seconds: float | None, *, is_postgres: bool
41
+ ) -> None:
42
+ # The async frontend bounds a single statement with a real client-side deadline
43
+ # (``asyncio.timeout``), which cancels the driver — so the extra server-side
44
+ # ``SET statement_timeout`` round trip is pure overhead and is skipped. The sync frontend
45
+ # has no client-side timeout primitive, so it relies on the server-side setting (§12.1).
46
+ if IS_ASYNC or not is_postgres:
47
+ return
48
+ stmt = apply_statement_timeout_sql(seconds)
49
+ if stmt is not None:
50
+ await conn.execute(text(stmt))
51
+
52
+
53
+ async def run_fetch(
54
+ conn: AsyncConnection,
55
+ statement: Statement,
56
+ params: Mapping[str, Any] | None,
57
+ *,
58
+ timeout: float | None,
59
+ is_postgres: bool,
60
+ ) -> list[RowMapping]:
61
+ """Execute a read and return every row mapping, no cardinality constraint."""
62
+ async with timeout_scope(timeout):
63
+ await _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
64
+ cursor = await conn.execute(statement, params or {})
65
+ return list(cursor.mappings().all())
66
+
67
+
68
+ async def run_fetch_one(
69
+ conn: AsyncConnection,
70
+ statement: Statement,
71
+ params: Mapping[str, Any] | None,
72
+ *,
73
+ timeout: float | None,
74
+ is_postgres: bool,
75
+ ) -> RowMapping:
76
+ """Execute a read expecting exactly one row (``Result.one()``, §8.1)."""
77
+ async with timeout_scope(timeout):
78
+ await _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
79
+ cursor = await conn.execute(statement, params or {})
80
+ return cursor.mappings().one()
81
+
82
+
83
+ async def run_fetch_optional(
84
+ conn: AsyncConnection,
85
+ statement: Statement,
86
+ params: Mapping[str, Any] | None,
87
+ *,
88
+ timeout: float | None,
89
+ is_postgres: bool,
90
+ ) -> RowMapping | None:
91
+ """Execute a read expecting zero or one row (``Result.one_or_none()``, §8.1)."""
92
+ async with timeout_scope(timeout):
93
+ await _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
94
+ cursor = await conn.execute(statement, params or {})
95
+ return cursor.mappings().one_or_none()
96
+
97
+
98
+ async def run_fetch_value(
99
+ conn: AsyncConnection,
100
+ statement: Statement,
101
+ params: Mapping[str, Any] | None,
102
+ *,
103
+ timeout: float | None,
104
+ is_postgres: bool,
105
+ ) -> Any:
106
+ """Execute a read expecting exactly one row and take its first column
107
+ (``Result.scalar_one()``, §8.1)."""
108
+ async with timeout_scope(timeout):
109
+ await _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
110
+ cursor = await conn.execute(statement, params or {})
111
+ return cursor.scalar_one()
112
+
113
+
114
+ async def run_fetch_values(
115
+ conn: AsyncConnection,
116
+ statement: Statement,
117
+ params: Mapping[str, Any] | None,
118
+ *,
119
+ timeout: float | None,
120
+ is_postgres: bool,
121
+ ) -> list[Any]:
122
+ """Execute a read and take the first column of every row (``Result.scalars().all()``)."""
123
+ async with timeout_scope(timeout):
124
+ await _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
125
+ cursor = await conn.execute(statement, params or {})
126
+ return list(cursor.scalars().all())
127
+
128
+
129
+ async def run_execute(
130
+ conn: AsyncConnection,
131
+ statement: Statement,
132
+ params: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None,
133
+ *,
134
+ timeout: float | None,
135
+ is_postgres: bool,
136
+ ) -> CursorResult[Any]:
137
+ """Execute a write/DDL statement and return the cursor result (for rowcount/returning)."""
138
+ async with timeout_scope(timeout):
139
+ await _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
140
+ return await conn.execute(statement, params or {})
141
+
142
+
143
+ class AsyncConnectionScope:
144
+ """A held connection exposing the fetch/execute family (§11.2).
145
+
146
+ Obtained via ``async with db.connection(target) as conn:``. All operations run on the same
147
+ physical connection; use this when several statements must share connection state.
148
+ """
149
+
150
+ def __init__(
151
+ self,
152
+ conn: AsyncConnection,
153
+ *,
154
+ is_postgres: bool,
155
+ default_timeout: float | None,
156
+ database: str,
157
+ shard_id: str,
158
+ role: str,
159
+ ) -> None:
160
+ """Wrap an already-acquired connection; not constructed directly by applications."""
161
+ self._conn = conn
162
+ self._is_postgres = is_postgres
163
+ self._default_timeout = default_timeout
164
+ self._database = database
165
+ self._shard_id = shard_id
166
+ self._role = role
167
+
168
+ @property
169
+ def raw(self) -> AsyncConnection:
170
+ """The underlying SQLAlchemy connection — an explicit "you now own error handling"
171
+ escape hatch (§7.3).
172
+
173
+ Anything executed via ``.raw`` bypasses dbkit entirely: no error classification (you'll
174
+ see raw driver/SQLAlchemy exceptions, not :class:`~dbkit.errors.DatabaseError`
175
+ subclasses — an ``except DatabaseError`` handler will not catch them), no metrics, no
176
+ tracing, and no retry/circuit-breaker/commit-unknown handling. Use it only for the two
177
+ things dbkit doesn't itself implement (:meth:`pipeline`, :meth:`~dbkit.AsyncDatabase.
178
+ copy_records`'s underlying driver connection) or a genuine one-off that needs raw driver
179
+ access — not as a routine way to run queries.
180
+ """
181
+ return self._conn
182
+
183
+ def pipeline(self) -> contextlib.AbstractAsyncContextManager[None]:
184
+ """Enter psycopg pipeline mode (§7.3): statements issued in this block are sent to the
185
+ server without waiting for each response before the next — one round trip for several
186
+ dependent-but-batchable statements (e.g. a business write plus its inbox record, §28).
187
+
188
+ Usage::
189
+
190
+ async with db.transaction(target=t) as tx, tx.pipeline():
191
+ await tx.execute(INSERT_ORDER, params)
192
+ await tx.execute(INSERT_INBOX, params)
193
+
194
+ PostgreSQL + psycopg only; raises :class:`DatabaseUnsupportedOperationError` otherwise.
195
+ Ordinary ``tx.execute(...)`` calls work unchanged inside the block — SQLAlchemy's
196
+ cursor execution transparently syncs the pipeline whenever a result is fetched.
197
+ """
198
+ return pipeline_scope(self._conn)
199
+
200
+ def _resolve(
201
+ self, query: object, params: Mapping[str, Any] | None
202
+ ) -> tuple[Statement, Query | None, float | None, str]:
203
+ statement = coerce_statement(query)
204
+ q = query if isinstance(query, Query) else None
205
+ timeout = q.timeout if (q and q.timeout is not None) else self._default_timeout
206
+ name = q.name if q else "adhoc"
207
+ return statement, q, timeout, name
208
+
209
+ async def fetch_all(
210
+ self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
211
+ ) -> list[Any]:
212
+ """Run a read and return every row, mapped to ``map_to`` (no cardinality check)."""
213
+ statement, _q, timeout, name = self._resolve(query, params)
214
+ try:
215
+ rows = await run_fetch(
216
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
217
+ )
218
+ except Exception as exc:
219
+ raise classify(
220
+ exc, query_name=name, database_name=self._database, role=self._role
221
+ ) from exc
222
+ return result_mod.map_rows(rows, map_to)
223
+
224
+ async def fetch_one(
225
+ self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
226
+ ) -> Any:
227
+ """Run a read expecting exactly one row; raises :class:`DatabaseResultError` otherwise."""
228
+ statement, _q, timeout, name = self._resolve(query, params)
229
+ try:
230
+ row = await run_fetch_one(
231
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
232
+ )
233
+ except NoResultFound as exc:
234
+ raise DatabaseResultError(
235
+ f"query {name!r} returned no rows, expected exactly one",
236
+ query_name=name,
237
+ database_name=self._database,
238
+ role=self._role,
239
+ ) from exc
240
+ except MultipleResultsFound as exc:
241
+ raise DatabaseResultError(
242
+ f"query {name!r} returned more than one row, expected exactly one",
243
+ query_name=name,
244
+ database_name=self._database,
245
+ role=self._role,
246
+ ) from exc
247
+ except Exception as exc:
248
+ raise classify(
249
+ exc, query_name=name, database_name=self._database, role=self._role
250
+ ) from exc
251
+ return result_mod.build_mapper(map_to)(row)
252
+
253
+ async def fetch_optional(
254
+ self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
255
+ ) -> Any | None:
256
+ """Run a read expecting zero or one row; ``None`` if empty, else the mapped row."""
257
+ statement, _q, timeout, name = self._resolve(query, params)
258
+ try:
259
+ row = await run_fetch_optional(
260
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
261
+ )
262
+ except MultipleResultsFound as exc:
263
+ raise DatabaseResultError(
264
+ f"query {name!r} returned more than one row, expected at most one",
265
+ query_name=name,
266
+ database_name=self._database,
267
+ role=self._role,
268
+ ) from exc
269
+ except Exception as exc:
270
+ raise classify(
271
+ exc, query_name=name, database_name=self._database, role=self._role
272
+ ) from exc
273
+ if row is None:
274
+ return None
275
+ return result_mod.build_mapper(map_to)(row)
276
+
277
+ async def fetch_value(self, query: object, params: Mapping[str, Any] | None = None) -> Any:
278
+ """Run a read expecting exactly one row and return its first column."""
279
+ statement, _q, timeout, name = self._resolve(query, params)
280
+ try:
281
+ return await run_fetch_value(
282
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
283
+ )
284
+ except NoResultFound as exc:
285
+ raise DatabaseResultError(
286
+ f"query {name!r} returned no rows, expected a single scalar value",
287
+ query_name=name,
288
+ database_name=self._database,
289
+ role=self._role,
290
+ ) from exc
291
+ except MultipleResultsFound as exc:
292
+ raise DatabaseResultError(
293
+ f"query {name!r} returned more than one row, expected a single scalar value",
294
+ query_name=name,
295
+ database_name=self._database,
296
+ role=self._role,
297
+ ) from exc
298
+ except Exception as exc:
299
+ raise classify(
300
+ exc, query_name=name, database_name=self._database, role=self._role
301
+ ) from exc
302
+
303
+ async def fetch_values(
304
+ self, query: object, params: Mapping[str, Any] | None = None
305
+ ) -> list[Any]:
306
+ """Run a read and return the first column of every row."""
307
+ statement, _q, timeout, name = self._resolve(query, params)
308
+ try:
309
+ return await run_fetch_values(
310
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
311
+ )
312
+ except Exception as exc:
313
+ raise classify(
314
+ exc, query_name=name, database_name=self._database, role=self._role
315
+ ) from exc
316
+
317
+ async def execute(self, query: object, params: Mapping[str, Any] | None = None) -> int:
318
+ """Run a write/DDL statement and return the affected row count."""
319
+ statement, _q, timeout, name = self._resolve(query, params)
320
+ try:
321
+ cursor = await run_execute(
322
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
323
+ )
324
+ return cursor.rowcount
325
+ except Exception as exc:
326
+ raise classify(
327
+ exc, query_name=name, database_name=self._database, role=self._role
328
+ ) from exc