GitHub

API reference for client.

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).

  • 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>)
ParameterTypeDescription
acquirerAcquirer
compilerCompiler
driverstr
span_attributesSpanAttributes = ()
borrowerBorrower | None = None
transaction_acquirerAcquirer | None = None
transaction_servicetype[TransactionConnection] | None = None
prepare_transaction_controlsbool = False
begin_transactionstr = 'BEGIN'
beginCallable[[Connection, str | None], Effect[None, SqlError]] | None = None
rollbackstr = 'ROLLBACK'
commitstr | Callable[[Connection], Effect[None, SqlError]] = 'COMMIT'
on_commit_failureCallable[[Connection], Effect[None, SqlError]] | None = None
is_transactionCallable[[Connection], bool] | None = None
savepointCallable[[str], str] = lambda name: f'SAVEPOINT {name}'
release_savepointCallable[[str], str] | None = None
rollback_savepointCallable[[str], str] = lambda name: f'ROLLBACK TO SAVEPOINT {name}'
transform_rowsTransformRows | None = None
reactive_queueReactiveQueue | 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) -> 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.

ParameterTypeDescription
connectionEffect[C, SqlError]
semaphoreSemaphore
is_transactionCallable[[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.

ParameterTypeDescription
levelTransactionLevel

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.

ParameterTypeDescription
transaction_servicetype[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_commit

make_with_transaction

make_with_transaction(options) -> WithTransaction

Runs effects in transactions: outermost ones BEGIN and commit on success; nested ones use savepoints. Failures and interruptions roll back.

ParameterTypeDescription
optionsTransactionOptions

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).

ParameterTypeDescription
client_idint | 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}
        ),
    )