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
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
|
+
]
|
dbkit/_async/__init__.py
ADDED
|
@@ -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
|
+
]
|
dbkit/_async/_compat.py
ADDED
|
@@ -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
|