GitHub

SqlClientService

API reference for SqlClientService.

A database client: a statement constructor (call it with SQL; see Constructor) with transactions and reactive queries.

Attributes

AttributeTypeDescription
driverstr = driver

The driver that made the client, such as "sqlite". Unlike the dialect, it tells apart drivers of the same SQL.

transaction_servicetype[TransactionConnection] = transaction_service

The tag of this client's open transaction.

reserveAcquirer

Leases a connection of its own (the driver's transaction acquirer, never the open transaction's connection) until the current scope closes. Fails with an SqlError when no connection can be acquired.

safeSqlClientService

The client itself (Effect's copy for SafeQL).

Functions

__init__

__init__(*, acquirer, compiler, span_attributes, transform_rows, borrower, driver, reserve, transaction_service, with_transaction, after_commit, reactivity, reactive_queue) -> None
ParameterTypeDescription
acquirerAcquirer
compilerCompiler
span_attributesSpanAttributes
transform_rowsTransformRows | None
borrowerBorrower | None
driverstr
reserveAcquirer
transaction_servicetype[TransactionConnection]
with_transactionWithTransaction
after_commitCallable[[Effect[None, Never, Any]], Effect[None]]
reactivityReactivityService
reactive_queueReactiveQueue | None
def __init__(
    self,
    *,
    acquirer: Acquirer,
    compiler: Compiler,
    span_attributes: SpanAttributes,
    transform_rows: TransformRows | None,
    borrower: Borrower | None,
    driver: str,
    reserve: Acquirer,
    transaction_service: type[TransactionConnection],
    with_transaction: WithTransaction,
    after_commit: Callable[[Effect[None, Never, Any]], Effect[None]],
    reactivity: ReactivityService,
    reactive_queue: ReactiveQueue | None,
) -> None:
    super().__init__(acquirer, compiler, span_attributes, transform_rows, borrower)
    self.driver = driver
    self._reserve = reserve
    self.transaction_service = transaction_service
    self._with_transaction = with_transaction
    self._after_commit = after_commit
    self._reactivity = reactivity
    self._reactive_queue = reactive_queue

fields

fields() -> ClientFields

What the client was built from, to build a driver's own client class on it: Driver(extra=..., **client.fields()).

Returns ClientFields

def fields(self) -> ClientFields:
    """What the client was built from, to build a driver's own client
    class on it: ``Driver(extra=..., **client.fields())``."""
    return {
        "acquirer": self.acquirer,
        "compiler": self.compiler,
        "span_attributes": self.span_attributes,
        "transform_rows": self.transform_rows,
        "borrower": self.borrower,
        "driver": self.driver,
        "reserve": self._reserve,
        "transaction_service": self.transaction_service,
        "with_transaction": self._with_transaction,
        "after_commit": self._after_commit,
        "reactivity": self._reactivity,
        "reactive_queue": self._reactive_queue,
    }

without_transforms

without_transforms() -> Self

A copy of this client that renames neither identifiers nor result columns.

Returns Self

def without_transforms(self) -> Self:
    """A copy of this client that renames neither identifiers nor result
    columns."""
    copy = copy_module.copy(self)
    copy.compiler = self.compiler.without_transform
    copy.transform_rows = None
    return copy

with_transaction

with_transaction[A, E, R](effect) -> Effect[A, E | SqlError, R]

Run effect in a transaction: it commits if effect succeeds and rolls back otherwise (also when interrupted). Nested, it is a savepoint.

Inside, Reactivity invalidations wait for the outermost commit (and are dropped on rollback). BeginTransaction replaces the client's BEGIN. Statements from a fiber that outlives the transaction it was forked in fail with an SqlError: use after_commit for work after the commit.

ParameterTypeDescription
effectEffect[A, E, R]

Returns Effect[A, E | SqlError, R]

def with_transaction[A, E, R](self, effect: Effect[A, E, R]) -> Effect[A, E | SqlError, R]:
    """Run ``effect`` in a transaction: it commits if ``effect``
    succeeds and rolls back otherwise (also when interrupted). Nested,
    it is a savepoint.

    Inside, ``Reactivity`` invalidations wait for the outermost commit
    (and are dropped on rollback). ``BeginTransaction`` replaces the
    client's ``BEGIN``. Statements from a fiber that outlives the
    transaction it was forked in fail with an ``SqlError``: use
    ``after_commit`` for work after the commit."""
    require_effect(effect, "effect")
    return self._with_transaction(effect)

after_commit

after_commit[R](effect) -> Effect[None, Never, R]

Run effect once the outermost transaction commits, or now outside a transaction.

Callbacks are dropped if the transaction (or their savepoint) rolls back or its COMMIT fails. They run in registration order, after the connection is released and before with_transaction returns, uninterruptibly, with the services in scope when registered minus the transaction. A callback that dies is logged at UnhandledLogLevel. Registering after the transaction ended is a defect.

ParameterTypeDescription
effectEffect[None, Never, R]

Returns Effect[None, Never, R]

def after_commit[R](self, effect: Effect[None, Never, R]) -> Effect[None, Never, R]:
    """Run ``effect`` once the outermost transaction commits, or now
    outside a transaction.

    Callbacks are dropped if the transaction (or their savepoint) rolls
    back or its ``COMMIT`` fails. They run in registration order, after
    the connection is released and before ``with_transaction`` returns,
    uninterruptibly, with the services in scope when registered minus
    the transaction. A callback that dies is logged at
    ``UnhandledLogLevel``. Registering after the transaction ended is a
    defect."""
    require_effect(effect, "effect")
    return self._after_commit(effect)

reactive

reactive[A, E, R](keys, effect) -> Stream[A, E, R]

effect's results, again each time keys are invalidated.

ParameterTypeDescription
keysKeys
effectEffect[A, E, R]

Returns Stream[A, E, R]

def reactive[A, E, R](self, keys: Keys, effect: Effect[A, E, R]) -> Stream[A, E, R]:
    """``effect``'s results, again each time ``keys`` are
    invalidated."""
    from pyfect import stream

    require_effect(effect, "effect")
    if self._reactive_queue is None:
        return self._reactivity.stream(keys, effect)
    queues = self._reactive_queue(keys, effect).map(stream.from_queue)
    return stream.unwrap(cast("Effect[Stream[A, E, R], E, Scope | R]", queues))

reactive_mailbox

reactive_mailbox[A, E, R](keys, effect) -> Effect[Dequeue[A, E | Done], Never, R | Scope]

A queue of effect's results, refreshed when keys are invalidated.

ParameterTypeDescription
keysKeys
effectEffect[A, E, R]

Returns Effect[Dequeue[A, E | Done], Never, R | Scope]

def reactive_mailbox[A, E, R](
    self, keys: Keys, effect: Effect[A, E, R]
) -> Effect[Dequeue[A, E | Done], Never, R | Scope]:
    """A queue of ``effect``'s results, refreshed when ``keys`` are
    invalidated."""
    require_effect(effect, "effect")
    if self._reactive_queue is None:
        return self._reactivity.query(keys, effect)
    return self._reactive_queue(keys, effect)

__call__

__call__(template, *args, **kwargs) -> Statement[Row]
ParameterTypeDescription
templateSqlText
argsobject = ()
kwargsobject = {}

Returns Statement[Row]

def __call__(self, template: SqlText, /, *args: object, **kwargs: object) -> Statement[Row]:
    return self._statement(segments_of(template, args, kwargs))

unsafe

unsafe(sql, params=None) -> Statement[Row]

A statement of SQL text built at runtime, with params bound to its placeholders. Never build the text from untrusted input.

ParameterTypeDescription
sqlstr
paramsSequence[object] | None = None

Returns Statement[Row]

def unsafe(self, sql: str, params: Sequence[object] | None = None) -> Statement[Row]:
    """A statement of SQL text built at runtime, with ``params`` bound to
    its placeholders. Never build the text from untrusted input."""
    return self._statement((literal_unsafe(sql, params),))

literal

literal(sql) -> Fragment

SQL text as a fragment.

ParameterTypeDescription
sqlLiteralString

Returns Fragment

@staticmethod
def literal(sql: LiteralString) -> Fragment:
    """SQL text as a fragment."""
    return Fragment((literal(sql),))

identifier

identifier(name) -> Identifier

A name, escaped (Effect's sql("name")).

ParameterTypeDescription
namestr

Returns Identifier

@staticmethod
def identifier(name: str) -> Identifier:
    """A name, escaped (Effect's ``sql("name")``)."""
    return identifier(name)

in_

in_(values: Sequence[object], /) -> ArrayHelper
in_(column: str, values: Sequence[object], /) -> Fragment

in_(values): (a, b, ...); in_(column, values): "column" IN (...), or 1=0 for no values.

ParameterTypeDescription
args= ()
@overload
@staticmethod
def in_(values: Sequence[object], /) -> ArrayHelper: ...
@overload
@staticmethod
def in_(column: str, values: Sequence[object], /) -> Fragment: ...
@staticmethod
def in_(*args: Any) -> ArrayHelper | Fragment:
    """``in_(values)``: ``(a, b, ...)``; ``in_(column, values)``:
    ``"column" IN (...)``, or ``1=0`` for no values."""
    if len(args) == 1:
        return in_(args[0])
    column, values = args
    return in_(column, values)

insert

insert(value) -> RecordInsertHelper

(columns) VALUES (...) for one row or several.

ParameterTypeDescription
valueMapping[str, object] | Sequence[Mapping[str, object]]

Returns RecordInsertHelper

@staticmethod
def insert(value: Mapping[str, object] | Sequence[Mapping[str, object]]) -> RecordInsertHelper:
    """``(columns) VALUES (...)`` for one row or several."""
    return insert(value)

update

update(value, omit=()) -> RecordUpdateHelperSingle

column = value, ... for one row, without the omit columns.

ParameterTypeDescription
valueMapping[str, object]
omitSequence[str] = ()

Returns RecordUpdateHelperSingle

@staticmethod
def update(value: Mapping[str, object], omit: Sequence[str] = ()) -> RecordUpdateHelperSingle:
    """``column = value, ...`` for one row, without the ``omit``
    columns."""
    return update(value, omit)

update_values

update_values(value, alias) -> RecordUpdateHelper

Several rows to update, as a VALUES list named alias. Not supported by SQLite.

ParameterTypeDescription
valueSequence[Mapping[str, object]]
aliasstr

Returns RecordUpdateHelper

@staticmethod
def update_values(value: Sequence[Mapping[str, object]], alias: str) -> RecordUpdateHelper:
    """Several rows to update, as a ``VALUES`` list named ``alias``. Not
    supported by SQLite."""
    return update_values(value, alias)

and_

and_(clauses) -> Fragment

(a AND b ...); 1=1 for no clauses.

ParameterTypeDescription
clausesSequence[LiteralString | Fragment]

Returns Fragment

@staticmethod
def and_(clauses: Sequence[LiteralString | Fragment]) -> Fragment:
    """``(a AND b ...)``; ``1=1`` for no clauses."""
    return and_(clauses)

or_

or_(clauses) -> Fragment

(a OR b ...); 1=1 for no clauses.

ParameterTypeDescription
clausesSequence[LiteralString | Fragment]

Returns Fragment

@staticmethod
def or_(clauses: Sequence[LiteralString | Fragment]) -> Fragment:
    """``(a OR b ...)``; ``1=1`` for no clauses."""
    return or_(clauses)

csv

csv(values, prefix=None) -> Fragment

a,b,... after prefix (ORDER BY); nothing for none.

ParameterTypeDescription
valuesSequence[LiteralString | Fragment]
prefixLiteralString | None = None

Returns Fragment

@staticmethod
def csv(
    values: Sequence[LiteralString | Fragment], prefix: LiteralString | None = None
) -> Fragment:
    """``a,b,...`` after ``prefix`` (``ORDER BY``); nothing for none."""
    return csv(values, prefix)

join

join(separator, add_parens=True, fallback='') -> Callable[[Sequence[LiteralString | Fragment]], Fragment]

A function joining clauses with separator: several in parentheses (unless add_parens=False), one as it is, none as fallback.

ParameterTypeDescription
separatorLiteralString
add_parensbool = True
fallbackLiteralString = ''

Returns Callable[[Sequence[LiteralString | Fragment]], Fragment]

@staticmethod
def join(
    separator: LiteralString, add_parens: bool = True, fallback: LiteralString = ""
) -> Callable[[Sequence[LiteralString | Fragment]], Fragment]:
    """A function joining clauses with ``separator``: several in
    parentheses (unless ``add_parens=False``), one as it is, none as
    ``fallback``."""
    return join(separator, add_parens, fallback)

on_dialect

on_dialect[T](*, sqlite, pg, mysql, mssql, clickhouse) -> T

The result of the function for the client's dialect.

ParameterTypeDescription
sqliteCallable[[], T]
pgCallable[[], T]
mysqlCallable[[], T]
mssqlCallable[[], T]
clickhouseCallable[[], T]

Returns T

def on_dialect[T](
    self,
    *,
    sqlite: Callable[[], T],
    pg: Callable[[], T],
    mysql: Callable[[], T],
    mssql: Callable[[], T],
    clickhouse: Callable[[], T],
) -> T:
    """The result of the function for the client's dialect."""
    branches: dict[str, Callable[[], T]] = {
        "sqlite": sqlite,
        "pg": pg,
        "mysql": mysql,
        "mssql": mssql,
        "clickhouse": clickhouse,
    }
    return branches[self.dialect]()

on_dialect_or_else

on_dialect_or_else[T](*, or_else, sqlite=None, pg=None, mysql=None, mssql=None, clickhouse=None) -> T

The result of the function for the client's dialect, or of or_else when it has none.

ParameterTypeDescription
or_elseCallable[[], T]
sqliteCallable[[], T] | None = None
pgCallable[[], T] | None = None
mysqlCallable[[], T] | None = None
mssqlCallable[[], T] | None = None
clickhouseCallable[[], T] | None = None

Returns T

def on_dialect_or_else[T](
    self,
    *,
    or_else: Callable[[], T],
    sqlite: Callable[[], T] | None = None,
    pg: Callable[[], T] | None = None,
    mysql: Callable[[], T] | None = None,
    mssql: Callable[[], T] | None = None,
    clickhouse: Callable[[], T] | None = None,
) -> T:
    """The result of the function for the client's dialect, or of
    ``or_else`` when it has none."""
    branches: dict[str, Callable[[], T] | None] = {
        "sqlite": sqlite,
        "pg": pg,
        "mysql": mysql,
        "mssql": mssql,
        "clickhouse": clickhouse,
    }
    branch = branches[self.dialect]
    return (or_else if branch is None else branch)()