GitHub

API reference for client.

The Cloudflare D1 client (Effect's @effect/sql-d1 D1Client): an SqlClient with SQLite's SQL over D1's HTTP API, sent with the HttpClient in context (pyfect.http.httpx_client.layer, or any other)::

program.pipe(
    fx.provide(d1.layer(d1.D1ClientConfig(account_id=..., database_id=..., api_token=...))),
    fx.provide(httpx_client.layer),
)

As in Effect: batch runs statements in one request that D1 commits or rolls back as a whole; transactions are a defect (D1 has none across requests), as are streams; update_values is not supported; every failure is an UnknownError. pyfect.sql.migrator runs its migrations in a transaction, so it dies on D1 too; apply D1 migrations with Cloudflare's own tooling (wrangler d1 migrations apply).

Re-exports

Classes

Functions

make

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

A client on config's database, sending with the HttpClient in context.

ParameterTypeDescription
configD1ClientConfig

Returns Effect[D1ClientService, Never, Scope | Reactivity | HttpClient]

def make(
    config: D1ClientConfig,
) -> Effect[D1ClientService, Never, Scope | Reactivity | HttpClient]:
    """A client on ``config``'s database, sending with the ``HttpClient`` in
    context."""
    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(http: HttpClientService[Any]) -> Effect[D1ClientService, Never, Reactivity]:
        api = D1Api(http, config.database_url, config.api_token)
        connection = _D1Connection(api)
        client = make_sql_client(
            driver="d1",
            acquirer=succeed(connection),
            compiler=make_compiler_sqlite(config.transform_query_names),
            transaction_acquirer=die(NotImplementedError("transactions are not supported in D1")),
            span_attributes=span_attributes,
            transform_rows=transform_rows,
        )
        return client.map(lambda c: D1ClientService(config=config, api=api, **c.fields()))

    return HttpClient().flat_map(build)

layer_from

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

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

ParameterTypeDescription
acquireEffect[D1ClientService, E, Scope | Reactivity | HttpClient]

Returns Layer[D1Client | SqlClient, E, HttpClient]

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

Provides a client (make).

ParameterTypeDescription
configD1ClientConfig

Returns Layer[D1Client | SqlClient, Never, HttpClient]

def layer(config: D1ClientConfig) -> Layer[D1Client | SqlClient, Never, HttpClient]:
    """Provides a client (``make``)."""
    return layer_from(make(config))

layer_config

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

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

d1.layer_config({
    "account_id": fx.config.string("CLOUDFLARE_ACCOUNT_ID"),
    "database_id": fx.config.string("D1_DATABASE_ID"),
    "api_token": fx.config.redacted("CLOUDFLARE_API_TOKEN"),
})
ParameterTypeDescription
configConfig[D1ClientConfig] | Mapping[str, Any]

Returns Layer[D1Client | SqlClient, ConfigError, HttpClient]

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

        d1.layer_config({
            "account_id": fx.config.string("CLOUDFLARE_ACCOUNT_ID"),
            "database_id": fx.config.string("D1_DATABASE_ID"),
            "api_token": fx.config.redacted("CLOUDFLARE_API_TOKEN"),
        })
    """
    read: Effect[D1ClientConfig, ConfigError] = (
        config
        if isinstance(config, Config)
        else unwrap(config).map(lambda fields: D1ClientConfig(**fields))
    )
    return layer_from(read.flat_map(make))