The SQL client (Effect's effect/sql/SqlClient): SqlClient is the
service, make builds one from a driver's connections.
Classes#
Functions#
make#
make(*, acquirer, compiler, driver, span_attributes=(), borrower=None, transaction_acquirer=None, transaction_service=None, prepare_transaction_controls=False, begin_transaction='BEGIN', begin=None, rollback='ROLLBACK', commit='COMMIT', on_commit_failure=None, is_transaction=None, savepoint=lambda name: f'SAVEPOINT {name}', release_savepoint=None, rollback_savepoint=lambda name: f'ROLLBACK TO SAVEPOINT {name}', transform_rows=None, reactive_queue=None) -> Effect[SqlClientService, Never, Reactivity]A client on a driver's connections (Effect's SqlClient.make).
acquirerleases connections;borrowerlends one for a single statement outside transactions;transaction_acquirer(default:acquirer) leases those of transactions andreserveprepare_transaction_controls: runBEGIN,COMMITandSAVEPOINTprepared (off by default: several databases refuse); rollbacks and savepoint releases always run unpreparedbegin(conn, statement): starts an outermost transaction, given theBeginTransactionprovided, if any, in place ofbegin_transaction, for databases that need more than one statement to start onecommit: its SQL, or an effect committing on the connection;on_commit_failurecleans up when it failsis_transaction: whether a transaction is open; when it says no, rollbacks and savepoint releases are skippedsavepoint/release_savepoint/rollback_savepoint: SQL for a savepoint name (effect_sql_<depth>)
| Parameter | Type | Description |
|---|---|---|
acquirer | Acquirer | |
compiler | Compiler | |
driver | str | |
span_attributes | SpanAttributes = () | |
borrower | Borrower | None = None | |
transaction_acquirer | Acquirer | None = None | |
transaction_service | type[TransactionConnection] | None = None | |
prepare_transaction_controls | bool = False | |
begin_transaction | str = 'BEGIN' | |
begin | Callable[[Connection, str | None], Effect[None, SqlError]] | None = None | |
rollback | str = 'ROLLBACK' | |
commit | str | Callable[[Connection], Effect[None, SqlError]] = 'COMMIT' | |
on_commit_failure | Callable[[Connection], Effect[None, SqlError]] | None = None | |
is_transaction | Callable[[Connection], bool] | None = None | |
savepoint | Callable[[str], str] = lambda name: f'SAVEPOINT {name}' | |
release_savepoint | Callable[[str], str] | None = None | |
rollback_savepoint | Callable[[str], str] = lambda name: f'ROLLBACK TO SAVEPOINT {name}' | |
transform_rows | TransformRows | None = None | |
reactive_queue | ReactiveQueue | None = None |
Returns Effect[SqlClientService, Never, Reactivity]
def make(
*,
acquirer: Acquirer,
compiler: Compiler,
driver: str,
span_attributes: SpanAttributes = (),
borrower: Borrower | None = None,
transaction_acquirer: Acquirer | None = None,
transaction_service: type[TransactionConnection] | None = None,
prepare_transaction_controls: bool = False,
begin_transaction: str = "BEGIN",
begin: Callable[[Connection, str | None], Effect[None, SqlError]] | None = None,
rollback: str = "ROLLBACK",
commit: str | Callable[[Connection], Effect[None, SqlError]] = "COMMIT",
on_commit_failure: Callable[[Connection], Effect[None, SqlError]] | None = None,
is_transaction: Callable[[Connection], bool] | None = None,
savepoint: Callable[[str], str] = lambda name: f"SAVEPOINT {name}",
release_savepoint: Callable[[str], str] | None = None,
rollback_savepoint: Callable[[str], str] = lambda name: f"ROLLBACK TO SAVEPOINT {name}",
transform_rows: TransformRows | None = None,
reactive_queue: ReactiveQueue | None = None,
) -> Effect[SqlClientService, Never, Reactivity]:
"""A client on a driver's connections (Effect's ``SqlClient.make``).
- ``acquirer`` leases connections; ``borrower`` lends one for a single
statement outside transactions; ``transaction_acquirer`` (default:
``acquirer``) leases those of transactions and ``reserve``
- ``prepare_transaction_controls``: run ``BEGIN``, ``COMMIT`` and
``SAVEPOINT`` prepared (off by default: several databases refuse);
rollbacks and savepoint releases always run unprepared
- ``begin(conn, statement)``: starts an outermost transaction, given
the ``BeginTransaction`` provided, if any, in place of
``begin_transaction``, for databases that need more than one
statement to start one
- ``commit``: its SQL, or an effect committing on the connection;
``on_commit_failure`` cleans up when it fails
- ``is_transaction``: whether a transaction is open; when it says no,
rollbacks and savepoint releases are skipped
- ``savepoint`` / ``release_savepoint`` / ``rollback_savepoint``: SQL
for a savepoint name (``effect_sql_<depth>``)
"""
service = transaction_service or transaction_connection()
def unprepared(conn: Connection, sql: str) -> Effect[None, SqlError]:
return conn.execute_unprepared(sql, (), None).as_void()
def control(conn: Connection, sql: str) -> Effect[None, SqlError]:
if prepare_transaction_controls:
return conn.execute(sql, (), None).as_void()
return unprepared(conn, sql)
def cleanup(conn: Connection, sql: str) -> Effect[None, SqlError]:
# Always unprepared, so a prepared statement the backend has dropped
# cannot stop a rollback or a savepoint release.
if is_transaction is not None and not is_transaction(conn):
return _Succeed(None)
return unprepared(conn, sql)
def default_begin(conn: Connection, statement: str | None) -> Effect[None, SqlError]:
# Unlike the client's own, a provided statement isn't fixed, so it
# isn't prepared.
if statement is None:
return control(conn, begin_transaction)
return unprepared(conn, statement)
def name(depth: int) -> str:
return f"effect_sql_{depth}"
release = release_savepoint
tx_acquirer = transaction_acquirer or acquirer
with_transaction = WithTransaction(
TransactionOptions(
transaction_service=service,
span_attributes=tuple(span_attributes),
acquire_connection=lambda restore: restore(tx_acquirer),
begin=default_begin if begin is None else begin,
savepoint=lambda conn, depth: control(conn, savepoint(name(depth))),
release_savepoint=None
if release is None
else lambda conn, depth: cleanup(conn, release(name(depth))),
commit=(lambda conn: control(conn, commit)) if isinstance(commit, str) else commit,
on_commit_failure=on_commit_failure,
rollback=lambda conn: cleanup(conn, rollback),
rollback_savepoint=lambda conn, depth: cleanup(conn, rollback_savepoint(name(depth))),
)
)
def in_transaction(fiber: Fiber[Any, Any]) -> Effect[Connection, SqlError, Scope]:
found, level = fiber._context.lookup(service)
return active_transaction_connection(level) if found else acquirer
get_connection: Acquirer = _WithFiber(in_transaction)
client_borrower: Borrower | None = None
if borrower is not None:
lend = borrower
# A statement in a transaction runs on its connection, so only
# statements outside one borrow.
def borrow[A, E, R](
f: Callable[[Connection], Effect[A, E, R]],
) -> Effect[A, E | SqlError, R]:
def body(fiber: Fiber[Any, Any]) -> Effect[A, E | SqlError, R]:
found, level = fiber._context.lookup(service)
return active_transaction_connection(level).flat_map(f) if found else lend(f)
return _WithFiber(body)
client_borrower = borrow
def build(reactivity: ReactivityService) -> SqlClientService:
return SqlClientService(
acquirer=get_connection,
compiler=compiler,
span_attributes=span_attributes,
transform_rows=transform_rows,
borrower=client_borrower,
driver=driver,
reserve=tx_acquirer,
transaction_service=service,
with_transaction=with_transaction,
after_commit=make_after_commit(service),
reactivity=reactivity,
reactive_queue=reactive_queue,
)
return Reactivity().map(build)make_sqlite_acquirers#
make_sqlite_acquirers[C: Connection](*, connection, semaphore, is_transaction=None) -> SqliteAcquirersLeases of connection that hold semaphore until their scope
closes, and a borrower that holds it for one statement.
SQLite can keep a transaction open after COMMIT fails (a deferred
foreign key violation), so on_commit_failure rolls it back. If that
fails too, the connection is rejected until a ROLLBACK retried on
each later acquisition succeeds. Without is_transaction,
ROLLBACK always runs and "no transaction is active" counts as
clean.
| Parameter | Type | Description |
|---|---|---|
connection | Effect[C, SqlError] | |
semaphore | Semaphore | |
is_transaction | Callable[[C], bool] | None = None |
Returns SqliteAcquirers
def make_sqlite_acquirers[C: Connection](
*,
connection: Effect[C, SqlError],
semaphore: Semaphore,
is_transaction: Callable[[C], bool] | None = None,
) -> SqliteAcquirers:
"""Leases of ``connection`` that hold ``semaphore`` until their scope
closes, and a borrower that holds it for one statement.
SQLite can keep a transaction open after ``COMMIT`` fails (a deferred
foreign key violation), so ``on_commit_failure`` rolls it back. If that
fails too, the connection is rejected until a ``ROLLBACK`` retried on
each later acquisition succeeds. Without ``is_transaction``,
``ROLLBACK`` always runs and "no transaction is active" counts as
clean."""
require_effect(connection, "connection")
poisoned: list[SqlError] = []
def poison(cause: Cause[SqlError]) -> SqlError:
error = SqlError(
reason=ConnectionError(
message="SQLite connection cannot be reused after failed COMMIT cleanup",
operation="rollback",
cause=cause,
)
)
poisoned[:] = [error]
return error
def rollback(conn: C) -> Effect[None, SqlError]:
if is_transaction is not None:
if is_transaction(conn):
return conn.execute_unprepared("ROLLBACK", [], None).as_void()
return _Succeed(None)
return (
conn.execute_unprepared("ROLLBACK", [], None)
.as_void()
.catch_if(_is_no_transaction_error, lambda _: _Succeed(None))
)
def check(conn: C) -> Effect[C, SqlError]:
if not poisoned:
return _Succeed(conn)
def recovered(_: object) -> Effect[C]:
poisoned.clear()
return _Succeed(conn)
return _MatchCause(rollback(conn), lambda c: _FailCause(fail_cause(poison(c))), recovered)
available = connection.flat_map(check)
# The permit's release is registered as it is taken, so an interrupt
# right after the wait cannot leak it.
lease: Effect[C, SqlError, Scope] = uninterruptible_mask(
lambda restore: restore(semaphore.take_scoped(1)).and_then(available)
)
def borrow[A, E, R](f: Callable[[Connection], Effect[A, E, R]]) -> Effect[A, E | SqlError, R]:
return semaphore.with_permits(available.flat_map(f))
def on_commit_failure(conn: Connection) -> Effect[None, SqlError]:
conn_c: Any = conn
return rollback(conn_c).tap_cause(lambda cause: _Sync(lambda: poison(cause)))
def is_open(conn: Connection) -> bool:
conn_c: Any = conn
return is_transaction is not None and is_transaction(conn_c)
return SqliteAcquirers(
acquirer=lease,
borrower=borrow,
transaction_acquirer=lease,
on_commit_failure=on_commit_failure,
is_transaction=None if is_transaction is None else is_open,
)active_transaction_connection#
active_transaction_connection(level) -> Effect[Connection, SqlError]The connection of level, or a SqlError when that level or one
of its parents has ended, checked when the effect runs. For drivers that
read their transaction service directly. Levels not started by
make_with_transaction are untracked, so their connection is always
returned.
| Parameter | Type | Description |
|---|---|---|
level | TransactionLevel |
Returns Effect[Connection, SqlError]
def active_transaction_connection(level: TransactionLevel) -> Effect[Connection, SqlError]:
"""The connection of ``level``, or a ``SqlError`` when that level or one
of its parents has ended, checked when the effect runs. For drivers that
read their transaction service directly. Levels not started by
``make_with_transaction`` are untracked, so their connection is always
returned."""
return _Suspend(
lambda: (
_transaction_ended() if _has_ended(_buffers.get(level)) else _Succeed(level.connection)
)
)make_after_commit#
make_after_commit(transaction_service) -> Callable[[Effect[None, Never, Any]], Effect[None]]after_commit for the transactions of transaction_service:
buffer the effect until the outermost commit, or run it now outside a
transaction.
| Parameter | Type | Description |
|---|---|---|
transaction_service | type[TransactionConnection] |
Returns Callable[[Effect[None, Never, Any]], Effect[None]]
def make_after_commit(
transaction_service: type[TransactionConnection],
) -> Callable[[Effect[None, Never, Any]], Effect[None]]:
"""``after_commit`` for the transactions of ``transaction_service``:
buffer the effect until the outermost commit, or run it now outside a
transaction."""
def after_commit(effect: Effect[None, Never, Any]) -> Effect[None]:
def body(fiber: Fiber[Any, Any]) -> Effect[None]:
services: Context[Any] = fiber._context
found, level = services.lookup(transaction_service)
buffer = _buffers.get(level) if found else None
if buffer is None:
return _run_after_commit(effect)
if _has_ended(buffer):
return die(RuntimeError("SqlClient.afterCommit: the transaction has already ended"))
# Runs later with the services in scope now, minus the transaction.
without = services.pipe(Context.omit(transaction_service))
buffer.callbacks.append(_Locally(effect, lambda _: without))
return _Succeed(None)
return _WithFiber(body)
return after_commitmake_with_transaction#
make_with_transaction(options) -> WithTransactionRuns effects in transactions: outermost ones BEGIN and commit on
success; nested ones use savepoints. Failures and interruptions roll
back.
| Parameter | Type | Description |
|---|---|---|
options | TransactionOptions |
Returns WithTransaction
def make_with_transaction(options: TransactionOptions) -> WithTransaction:
"""Runs effects in transactions: outermost ones ``BEGIN`` and commit on
success; nested ones use savepoints. Failures and interruptions roll
back."""
return WithTransaction(options)transaction_connection#
transaction_connection(client_id=None) -> type[TransactionConnection]A new transaction tag, for client client_id (the next free id by
default).
| Parameter | Type | Description |
|---|---|---|
client_id | int | None = None |
Returns type[TransactionConnection]
def transaction_connection(client_id: int | None = None) -> type[TransactionConnection]:
"""A new transaction tag, for client ``client_id`` (the next free id by
default)."""
client_id = next(_client_ids) if client_id is None else client_id
key = f"effect/sql/SqlClient/TransactionConnection/{client_id}"
return cast(
"type[TransactionConnection]",
types.new_class(
f"TransactionConnection{client_id}", (TransactionConnection,), {"key": key}
),
)