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.
| Parameter | Type | Description |
|---|---|---|
config | LibsqlClientConfig | 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.
| Parameter | Type | Description |
|---|---|---|
acquire | Effect[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).
| Parameter | Type | Description |
|---|---|---|
config | LibsqlClientConfig | 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")})| Parameter | Type | Description |
|---|---|---|
config | Config[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))