GitHub

SqliteClientService

API reference for SqliteClientService.

A SQLite client: a SqlClientService that can also back up the database and load extensions. update_values is not supported.

Attributes

AttributeTypeDescription
configSqliteClientConfig = config
connectionSqliteConnection = connection

Functions

__init__

__init__(*, config, connection, **fields) -> None
ParameterTypeDescription
configSqliteClientConfig
connectionSqliteConnection
fieldsUnpack[ClientFields] = {}
def __init__(
    self,
    *,
    config: SqliteClientConfig,
    connection: SqliteConnection,
    **fields: Unpack[ClientFields],
) -> None:
    super().__init__(**fields)
    self.config = config
    self.connection = connection

backup

backup(destination) -> Effect[BackupMetadata, SqlError]

Copy the database to the file destination.

ParameterTypeDescription
destinationstr

Returns Effect[BackupMetadata, SqlError]

def backup(self, destination: str) -> Effect[BackupMetadata, SqlError]:
    """Copy the database to the file ``destination``."""
    conn = self.connection
    return scoped(self.reserve.flat_map(lambda _: conn.backup(destination)))

load_extension

load_extension(path) -> Effect[None, SqlError]

Loads the SQLite extension at path into the connection, with extension loading enabled only while it loads. Fails with an SqlError when the extension cannot be loaded, or Python's sqlite3 was built without extension loading.

ParameterTypeDescription
pathstr

Returns Effect[None, SqlError]

def load_extension(self, path: str) -> Effect[None, SqlError]:
    """Loads the SQLite extension at ``path`` into the connection,
    with extension loading enabled only while it loads. Fails with an
    ``SqlError`` when the extension cannot be loaded, or Python's
    ``sqlite3`` was built without extension loading."""
    conn = self.connection
    return scoped(self.reserve.flat_map(lambda _: conn.load_extension(path)))

update_values

update_values(value, alias) -> RecordUpdateHelper

Not supported by SQLite: a type error (Effect's never), and a TypeError when called anyway.

ParameterTypeDescription
valueSequence[Mapping[str, object]]
aliasstr

Returns RecordUpdateHelper

@staticmethod
@deprecated("update_values is not supported by SQLite")
def update_values(value: Sequence[Mapping[str, object]], alias: str) -> RecordUpdateHelper:
    """Not supported by SQLite: a type error (Effect's ``never``), and a
    ``TypeError`` when called anyway."""
    raise TypeError("update_values is not supported by SQLite")

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

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

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)