GitHub

API reference for client.

The SQL Server client (Effect's @effect/sql-mssql MssqlClient): an SqlClient on a pool of pytds connections, with typed parameters (param) and stored procedure calls (call).

make opens the pool and checks it with SELECT 1 (within connect_timeout, five seconds by default); statements outside a transaction each take a connection for themselves, a transaction keeps one until it ends, and its savepoints are never released (SQL Server has no RELEASE SAVEPOINT). Streams are not implemented, as in Effect::

program.pipe(fx.provide(mssql.layer(mssql.MssqlClientConfig(server="localhost", ...))))

Re-exports

Classes

Functions

make_compiler

make_compiler(transform=None) -> Compiler

SQL Server's compiler: @1, @2, ... placeholders, [quoted] names (renamed with transform unless a statement runs without transforms) and OUTPUT INSERTED for returning.

ParameterTypeDescription
transformCallable[[str], str] | None = None

Returns Compiler

def make_compiler(transform: Callable[[str], str] | None = None) -> Compiler:
    """SQL Server's compiler: ``@1``, ``@2``, ... placeholders, ``[quoted]``
    names (renamed with ``transform`` unless a statement runs without
    transforms) and ``OUTPUT INSERTED`` for ``returning``."""

    def on_identifier(value: str, without_transform: bool) -> str:
        if transform is None or without_transform:
            return escape(value)
        return escape(transform(value))

    return make_statement_compiler(
        dialect="mssql",
        placeholder=lambda index, _value: f"@{index}",
        on_identifier=on_identifier,
        on_record_update=_on_record_update,
        on_custom=_on_custom,
        on_insert=_on_insert,
    )

connect_options

connect_options(config) -> ConnectOptions

What the driver connects with, for config.

ParameterTypeDescription
configMssqlClientConfig

Returns ConnectOptions

def connect_options(config: MssqlClientConfig) -> ConnectOptions:
    """What the driver connects with, for ``config``."""
    retries = config.max_retries_on_transient_errors
    return ConnectOptions(
        server=config.server,
        port=config.port if config.port is not None or config.instance_name else DEFAULT_PORT,
        instance_name=config.instance_name,
        database=config.database,
        username=config.username,
        password=None if config.password is None else redacted_value(config.password),
        encrypt=config.encrypt,
        trust_server=config.trust_server,
        connect_timeout=driver_seconds_or(config.connect_timeout, DEFAULT_CONNECT_TIMEOUT),
        cancel_timeout=driver_seconds_or(config.cancel_timeout, DEFAULT_CANCEL_TIMEOUT),
        connection_retry_interval=driver_seconds_or(
            config.connection_retry_interval, DEFAULT_CONNECTION_RETRY_INTERVAL
        ),
        max_retries_on_transient_errors=DEFAULT_MAX_RETRIES_ON_TRANSIENT_ERRORS
        if retries is None
        else retries,
    )

make

make(config) -> Effect[MssqlClientService, SqlError, Scope | Reactivity]

A client on a pool of connections; it closes with the scope.

ParameterTypeDescription
configMssqlClientConfig

Returns Effect[MssqlClientService, SqlError, Scope | Reactivity]

def make(config: MssqlClientConfig) -> Effect[MssqlClientService, SqlError, Scope | Reactivity]:
    """A client on a pool of connections; it closes with the scope."""
    pool = _pool.make(
        connect_options(config),
        config.parameter_types,
        min_connections=DEFAULT_MIN_CONNECTIONS
        if config.min_connections is None
        else config.min_connections,
        max_connections=config.max_connections or DEFAULT_MAX_CONNECTIONS,
        ttl=seconds_or(config.connection_ttl, DEFAULT_CONNECTION_TTL),
    )
    span_attributes = _span_attributes(config)

    def build(
        check_out: Effect[MssqlConnection, SqlError, Scope],
    ) -> Effect[MssqlClientService, SqlError, Reactivity]:
        acquirer = cast("Effect[Connection, SqlError, Scope]", check_out)
        connected = (
            scoped(
                acquirer.flat_map(
                    lambda conn: conn.execute_unprepared("SELECT 1", (), None)
                ).map_error(_connect_failed)
            )
            .timeout_or_else(
                seconds_or(config.connect_timeout, DEFAULT_CHECK_TIMEOUT), _connect_timed_out
            )
            .as_void()
        )
        transform_rows = (
            None
            if config.transform_result_names is None
            else default_transforms(config.transform_result_names).array
        )
        service = transaction_connection()

        def mssql(conn: Connection) -> MssqlConnection:
            return cast("MssqlConnection", conn)

        with_transaction = make_with_transaction(
            TransactionOptions(
                transaction_service=service,
                span_attributes=tuple(span_attributes),
                acquire_connection=lambda restore: restore(acquirer),
                begin=lambda conn, _statement: mssql(conn).begin,
                savepoint=lambda conn, depth: mssql(conn).savepoint(f"effect_sql_{depth}"),
                commit=lambda conn: mssql(conn).commit,
                rollback=lambda conn: mssql(conn).rollback(),
                rollback_savepoint=lambda conn, depth: mssql(conn).rollback(f"effect_sql_{depth}"),
            )
        )
        client = make_sql_client(
            driver="mssql",
            acquirer=acquirer,
            compiler=make_compiler(config.transform_query_names),
            transaction_service=service,
            span_attributes=span_attributes,
            transform_rows=transform_rows,
        )

        def finish(c: SqlClientService) -> MssqlClientService:
            fields = c.fields()
            fields["with_transaction"] = with_transaction
            return MssqlClientService(config=config, **fields)

        return connected.and_then(client.map(finish))

    return pool.flat_map(build)

layer_from

layer_from[E](acquire) -> Layer[MssqlClient | SqlClient, E]

Provides the client acquire makes as MssqlClient and SqlClient, with its own Reactivity.

ParameterTypeDescription
acquireEffect[MssqlClientService, E, Scope | Reactivity]

Returns Layer[MssqlClient | SqlClient, E]

def layer_from[E](
    acquire: Effect[MssqlClientService, E, Scope | Reactivity],
) -> Layer[MssqlClient | SqlClient, E]:
    """Provides the client ``acquire`` makes as ``MssqlClient`` and
    ``SqlClient``, with its own ``Reactivity``."""
    require_effect(acquire, "acquire")
    return layer_effect_context(acquire.map(_contexts)).pipe(provide(reactivity_layer))

layer

layer(config) -> Layer[MssqlClient | SqlClient, SqlError]

Provides a client (make).

ParameterTypeDescription
configMssqlClientConfig

Returns Layer[MssqlClient | SqlClient, SqlError]

def layer(config: MssqlClientConfig) -> Layer[MssqlClient | SqlClient, SqlError]:
    """Provides a client (``make``)."""
    return layer_from(make(config))

layer_config

layer_config(config) -> Layer[MssqlClient | SqlClient, ConfigError | SqlError]

layer with the config read from the ConfigProvider: a Config of the whole config, or a mapping from field names to their Config (Effect's Config.Wrap)::

mssql.layer_config({
    "server": fx.config.string("MSSQL_SERVER"),
    "password": fx.config.redacted("MSSQL_PASSWORD"),
})
ParameterTypeDescription
configConfig[MssqlClientConfig] | Mapping[str, Any]

Returns Layer[MssqlClient | SqlClient, ConfigError | SqlError]

def layer_config(
    config: Config[MssqlClientConfig] | Mapping[str, Any],
) -> Layer[MssqlClient | SqlClient, ConfigError | SqlError]:
    """``layer`` with the config read from the ``ConfigProvider``: a
    ``Config`` of the whole config, or a mapping from field names to their
    ``Config`` (Effect's ``Config.Wrap``)::

        mssql.layer_config({
            "server": fx.config.string("MSSQL_SERVER"),
            "password": fx.config.redacted("MSSQL_PASSWORD"),
        })
    """
    read: Effect[MssqlClientConfig, ConfigError] = (
        config
        if isinstance(config, Config)
        else unwrap(config).map(lambda fields: MssqlClientConfig(**fields))
    )
    return layer_from(read.flat_map(make))