GitHub

API reference for client.

The MySQL client (Effect's @effect/sql-mysql2 MysqlClient): an SqlClient on a pool of asyncmy connections.

make opens the pool and checks it with SELECT 1 (within five seconds); statements outside a transaction each take a connection for themselves, a transaction or a stream keeps one until it ends::

program.pipe(fx.provide(mysql.layer(mysql.MysqlClientConfig(url=redacted.make(url)))))

Re-exports

Classes

Functions

make_compiler

make_compiler(transform=None) -> Compiler

MySQL's compiler: ? placeholders and `quoted` names (renamed with transform unless a statement runs without transforms).

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

Returns Compiler

def make_compiler(transform: Callable[[str], str] | None = None) -> Compiler:
    """MySQL's compiler: ``?`` placeholders and `` `quoted` `` names (renamed
    with ``transform`` unless a statement runs without transforms)."""

    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="mysql",
        placeholder=lambda _index, _value: "?",
        on_identifier=on_identifier,
        on_record_update=_nothing,
        on_custom=_nothing,
    )

connect_options

connect_options(config) -> dict[str, Any]

asyncmy.connect's keywords for config.

ParameterTypeDescription
configMysqlClientConfig

Returns dict[str, Any]

def connect_options(config: MysqlClientConfig) -> dict[str, Any]:
    """``asyncmy.connect``'s keywords for ``config``."""
    if config.url is not None:
        url = parse_url(redacted_value(config.url))
        fields: dict[str, Any] = {
            "host": url.host,
            "port": url.port or 3306,
            "user": url.username,
            "password": url.password or "",
            "database": url.database,
        }
        if url.options.tls is not None:
            fields["ssl"] = url.options.tls.context()
        if url.options.connect_timeout is not None:
            fields["connect_timeout"] = url.options.connect_timeout.to_seconds()
        return connect_keywords(fields)
    fields = {
        **config.connect_options,
        "host": config.host or config.connect_options.get("host", "localhost"),
        "port": config.port or config.connect_options.get("port", 3306),
    }
    if config.database is not None:
        fields["database"] = config.database
    if config.username is not None:
        fields["user"] = config.username
    if config.password is not None:
        fields["password"] = redacted_value(config.password)
    return connect_keywords(fields)

make

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

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

A BeginTransaction starting with SET TRANSACTION, such as SET TRANSACTION ISOLATION LEVEL READ COMMITTED, runs just before BEGIN, since START TRANSACTION can't set an isolation level. Any other statement replaces BEGIN.

ParameterTypeDescription
configMysqlClientConfig

Returns Effect[MysqlClientService, SqlError, Scope | Reactivity]

def make(config: MysqlClientConfig) -> Effect[MysqlClientService, SqlError, Scope | Reactivity]:
    """A client on a pool of connections; it closes with the scope.

    A ``BeginTransaction`` starting with ``SET TRANSACTION``, such as
    ``SET TRANSACTION ISOLATION LEVEL READ COMMITTED``, runs just before
    ``BEGIN``, since ``START TRANSACTION`` can't set an isolation level. Any
    other statement replaces ``BEGIN``."""
    prepare = not config.disable_prepared_statements
    idle = (
        DEFAULT_IDLE_TIMEOUT
        if config.connection_ttl is None
        else from_input_unsafe(config.connection_ttl)
    )
    pool = _pool.make(
        connect_options(config),
        max_connections=config.max_connections or DEFAULT_MAX_CONNECTIONS,
        idle_timeout=idle,
    )

    def build(
        check_out: Effect[Any, SqlError, Scope],
    ) -> Effect[MysqlClientService, SqlError, Reactivity]:
        acquirer: Effect[Connection, SqlError, Scope] = check_out.map(
            lambda session: MysqlConnection(session, prepare=prepare)
        )

        def borrow[A, E, R](
            f: Callable[[Connection], Effect[A, E, R]],
        ) -> Effect[A, E | SqlError, R]:
            return scoped(acquirer.flat_map(f))

        connected = (
            scoped(
                acquirer.flat_map(
                    lambda conn: conn.execute_unprepared("SELECT 1", (), None)
                ).map_error(_connect_failed)
            )
            .timeout_or_else(_CONNECT_TIMEOUT, _connect_timed_out)
            .as_void()
        )
        transform_rows = (
            None
            if config.transform_result_names is None
            else default_transforms(config.transform_result_names).array
        )
        client = make_sql_client(
            driver="mysql2",
            acquirer=acquirer,
            borrower=borrow,
            transaction_acquirer=acquirer,
            begin=_begin,
            release_savepoint=lambda name: f"RELEASE SAVEPOINT {name}",
            compiler=make_compiler(config.transform_query_names),
            span_attributes=_span_attributes(config),
            transform_rows=transform_rows,
        )
        return connected.and_then(
            client.map(lambda c: MysqlClientService(config=config, **c.fields()))
        )

    return pool.flat_map(build)

layer_from

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

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

ParameterTypeDescription
acquireEffect[MysqlClientService, E, Scope | Reactivity]

Returns Layer[MysqlClient | SqlClient, E]

def layer_from[E](
    acquire: Effect[MysqlClientService, E, Scope | Reactivity],
) -> Layer[MysqlClient | SqlClient, E]:
    """Provides the client ``acquire`` makes as ``MysqlClient`` 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[MysqlClient | SqlClient, SqlError]

Provides a client (make).

ParameterTypeDescription
configMysqlClientConfig

Returns Layer[MysqlClient | SqlClient, SqlError]

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

layer_config

layer_config(config) -> Layer[MysqlClient | 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)::

mysql.layer_config({"url": fx.config.redacted("DATABASE_URL")})
ParameterTypeDescription
configConfig[MysqlClientConfig] | Mapping[str, Any]

Returns Layer[MysqlClient | SqlClient, ConfigError | SqlError]

def layer_config(
    config: Config[MysqlClientConfig] | Mapping[str, Any],
) -> Layer[MysqlClient | 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``)::

        mysql.layer_config({"url": fx.config.redacted("DATABASE_URL")})
    """
    read: Effect[MysqlClientConfig, ConfigError] = (
        config
        if isinstance(config, Config)
        else unwrap(config).map(lambda fields: MysqlClientConfig(**fields))
    )
    return layer_from(read.flat_map(make))