GitHub

MssqlClientService

API reference for MssqlClientService.

A SQL Server client: an SqlClientService, its config, typed parameters and stored procedure calls.

Attributes

AttributeTypeDescription
configMssqlClientConfig = config

Functions

__init__

__init__(*, config, **fields) -> None
ParameterTypeDescription
configMssqlClientConfig
fieldsUnpack[ClientFields] = {}
def __init__(self, *, config: MssqlClientConfig, **fields: Unpack[ClientFields]) -> None:
    super().__init__(**fields)
    self.config = config

param

param(type, value, options=None) -> Fragment

A parameter sent as type (client.param(TYPES.BigInt, 1)).

ParameterTypeDescription
typeDataType
valueobject
optionsParameterOptions | None = None

Returns Fragment

def param(
    self,
    type: DataType,
    value: object,
    options: ParameterOptions | None = None,
) -> Fragment:
    """A parameter sent as ``type`` (``client.param(TYPES.BigInt, 1)``)."""
    return Fragment((mssql_param(type, value, options or ParameterOptions()),))

call

call[A](procedure) -> Effect[Result[A], SqlError]

Run a stored procedure (on the transaction's connection inside one): its output parameters and rows, renamed as the client renames results.

ParameterTypeDescription
procedureProcedureWithValues[A]

Returns Effect[Result[A], SqlError]

def call[A](self, procedure: ProcedureWithValues[A]) -> Effect[Result[A], SqlError]:
    """Run a stored procedure (on the transaction's connection inside
    one): its output parameters and rows, renamed as the client renames
    results."""
    transform_rows = self.transform_rows
    return scoped(
        self.acquirer.flat_map(
            lambda conn: cast("MssqlConnection", conn).call(procedure, transform_rows)
        )
    )

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

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)