GitHub

API reference for client.

The libSQL client (Effect's @effect/sql-libsql LibsqlClient): an SqlClient with SQLite's SQL on one SDK client.

On a local database statements and transactions take turns: a statement outside a transaction holds the client until it is done, and a transaction from its BEGIN until it commits or rolls back. Remote statements and transactions overlap, each on a stream of its own. BeginTransaction is ignored: transactions begin in write mode (BEGIN IMMEDIATE). Streams are not supported.

Classes

Functions

make

make(config) -> Effect[LibsqlClientService, Never, Scope | Reactivity]

A client on config's database; one it opened closes with the scope.

ParameterTypeDescription
configLibsqlClientConfig | LibsqlLiveConfig

Returns Effect[LibsqlClientService, Never, Scope | Reactivity]

def make(
    config: LibsqlClientConfig | LibsqlLiveConfig,
) -> Effect[LibsqlClientService, Never, Scope | Reactivity]:
    """A client on ``config``'s database; one it opened closes with the
    scope."""
    service = transaction_connection()
    transform_rows = (
        None
        if config.transform_result_names is None
        else default_transforms(config.transform_result_names).array
    )
    span_attributes: list[tuple[str, object]] = [
        *config.span_attributes.items(),
        ("db.system.name", "sqlite"),
    ]

    def build(sdk: LibsqlSdk) -> Effect[LibsqlClientService, Never, Reactivity]:
        connection = ClientConnection(sdk)
        # Remote transports run each statement and transaction on a stream of
        # its own. A local client may own a single connection that it refuses
        # to lend while a transaction holds it, so take turns on it instead.
        permit: Effect[None, Never, Scope] = (
            succeed(None) if sdk.protocol in {"http", "ws"} else Semaphore(1).take_scoped(1)
        )

        def acquire_transaction(restore: Restore) -> Effect[Connection, SqlError, Scope]:
            # Runs masked: only the wait for the permit is interruptible, so
            # a BEGIN the SDK started always ends in a commit or rollback.
            began: Effect[Connection, SqlError] = connection.begin_transaction()
            return restore(permit).and_then(began)

        # Outside a transaction, hold the permit until the statement's scope
        # closes, so no other fiber can begin a transaction while it runs.
        lease: Effect[Connection, SqlError, Scope] = permit.as_(connection)
        with_transaction = make_with_transaction(
            TransactionOptions(
                transaction_service=service,
                span_attributes=tuple(span_attributes),
                acquire_connection=acquire_transaction,
                begin=_no_begin,
                savepoint=_savepoint("SAVEPOINT"),
                release_savepoint=_savepoint("RELEASE SAVEPOINT"),
                rollback_savepoint=_savepoint("ROLLBACK TO SAVEPOINT"),
                commit=_commit,
                rollback=_rollback,
            )
        )
        client = make_sql_client(
            driver="libsql",
            acquirer=lease,
            compiler=make_compiler_sqlite(config.transform_query_names),
            transaction_service=service,
            span_attributes=span_attributes,
            transform_rows=transform_rows,
        )

        def reserve(level: Option[TransactionLevel]) -> Effect[Connection, SqlError, Scope]:
            # Inside a transaction, its connection: the permit is the transaction's.
            return active_transaction_connection(level.value) if is_some(level) else lease

        def service_of(c: SqlClientService) -> LibsqlClientService:
            fields = c.fields()
            fields["with_transaction"] = with_transaction
            fields["reserve"] = service_option(service).flat_map(reserve)
            return LibsqlClientService(config=config, sdk=sdk, **fields)

        return client.map(service_of)

    return _sdk(config).flat_map(build)

layer_from

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

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

ParameterTypeDescription
acquireEffect[LibsqlClientService, E, Scope | Reactivity]

Returns Layer[LibsqlClient | SqlClient, E]

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

Provides a client (make).

ParameterTypeDescription
configLibsqlClientConfig | LibsqlLiveConfig

Returns Layer[LibsqlClient | SqlClient]

def layer(config: LibsqlClientConfig | LibsqlLiveConfig) -> Layer[LibsqlClient | SqlClient]:
    """Provides a client (``make``)."""
    return layer_from(make(config))

layer_config

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

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

libsql.layer_config({"url": fx.config.string("LIBSQL_URL")})
ParameterTypeDescription
configConfig[LibsqlClientConfig] | Config[LibsqlLiveConfig] | Mapping[str, Any]

Returns Layer[LibsqlClient | SqlClient, ConfigError]

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

        libsql.layer_config({"url": fx.config.string("LIBSQL_URL")})
    """
    read: Effect[LibsqlClientConfig | LibsqlLiveConfig, ConfigError] = (
        config
        if isinstance(config, Config)
        else unwrap(config).map(lambda fields: LibsqlClientConfig(**fields))
    )
    return layer_from(read.flat_map(make))