bookclerk_plugin_database_d1::d1

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Cloudflare D1 HTTP API proxy for SeaORM.

D1 HTTP requests do not keep an interactive SQL transaction open. Autocommit statements use the documented { "sql", "params" } REST body. Interactive BEGIN is rejected: Time Travel is not a substitute for rollback, and mid-transaction SeaORM reads cannot be satisfied without committing. Atomic library operations use D1Proxy::run_typed_atomic, which sends { "batch": [...] } (a real SQL transaction) with control flow encoded in SQL and a durable operationId receipt.

Item Kind Summary
D1Proxy struct SeaORM proxy that executes statements against Cloudflare D1's HTTP API.
open function Open Cloudflare D1 with an explicit API token (host-mediated).
lookup_database function Resolves an existing D1 database UUID by name. Does not create.
ensure_database function Resolves (and provisions) a Cloudflare D1 database by name, returning its UUID.
delete_database function Deletes a Cloudflare D1 database by name. Missing databases are success.
set_shared_proxy function Stores the process-wide D1 proxy used by atomic execute after open.
shared_proxy function Process-wide D1 proxy installed by open, if any.

Structs

D1Proxy

pub struct D1Proxy {
    /* private fields */
}

SeaORM proxy that executes statements against Cloudflare D1's HTTP API.

D1Proxy::run_typed_atomic

pub async fn run_typed_atomic(
    &self,
    req: &ExecuteRequest,
    guest_receipt: GuestReceiptPersist,
    proofs: &[ResolvedStatement],
) -> Result<ExecuteReply, DbErr>

Runs a typed ExecuteRequest as one D1 HTTP batch.

DbValue::Bytes parameters are stored as true BLOBs: the placeholder is rewritten to unhex(?) with hex text (JSON has no binary scalar). BLOB result cells arrive as JSON byte arrays and decode back to DbValue::Bytes; text is never re-encoded, so a DbValue::Text cell cannot masquerade as bytes. After HTTP success, encode/size failures are ambiguous (unavailable).

Ambiguous (possibly committed) failures are retried only when the request is receipt-gated or read-only; an unwrapped mutation returns the ambiguous error without resubmitting.

Errors

Returns when the batch is rejected, HTTP fails, or the reply cannot be encoded after commit.

D1Proxy::run_typed_atomic_with

pub async fn run_typed_atomic_with(
    &self,
    req: &ExecuteRequest,
    guest_receipt: GuestReceiptPersist,
    proofs: &[ResolvedStatement],
    caps: &DbCapabilities,
) -> Result<ExecuteReply, DbErr>

Self::run_typed_atomic with the result caps the reply is held to: the D1 advertisement for execute, its streamed budget for executeStreamed.

Errors

See Self::run_typed_atomic.

D1Proxy::new

pub fn new(
    api_base: String,
    account_id: String,
    database_id: String,
    api_token: String,
) -> Self

Constructs a new instance with default or provided parameters.

Panics

Panics when the HTTP client cannot be built. Under nested Deny / bookclerk_plugin_sdk::SOCKET_PROXY_ENV this does not fall back to ambient TCP.

Implements: Clone, Debug, ProxyDatabaseTrait

Functions

open

pub async fn open(
    api_base: String,
    account_id: String,
    database_id: String,
    token: String,
) -> Result<DatabaseConnection, DbErr>

Open Cloudflare D1 with an explicit API token (host-mediated).

Connects and pings only. The host applies schema after capability negotiation.

Errors

Returns an error when the operation fails.

lookup_database

pub async fn lookup_database(
    api_base: &str,
    account_id: &str,
    api_token: &str,
    name: &str,
) -> Result<String, DbErr>

Resolves an existing D1 database UUID by name. Does not create.

Errors

Returns when lookup fails or no database with name exists.

ensure_database

pub async fn ensure_database(
    api_base: &str,
    account_id: &str,
    api_token: &str,
    name: &str,
) -> Result<String, DbErr>

Resolves (and provisions) a Cloudflare D1 database by name, returning its UUID.

Used for named plugin database bindings: each binding gets its own D1 database. Fails closed with an operator-facing error when the API token cannot list or create databases.

Errors

Returns when the HTTP lookup/create fails or the response is malformed.

delete_database

pub async fn delete_database(
    api_base: &str,
    account_id: &str,
    api_token: &str,
    name: &str,
) -> Result<(), DbErr>

Deletes a Cloudflare D1 database by name. Missing databases are success.

Used by bookclerk plugins db drop so the physical unit is gone before the plugin_databases registry row is removed. Does not create-if-missing.

Errors

Returns when lookup or delete fails, or the token lacks D1 edit permission.

set_shared_proxy

pub fn set_shared_proxy(proxy: D1Proxy)

Stores the process-wide D1 proxy used by atomic execute after open.

shared_proxy

pub fn shared_proxy() -> Option<D1Proxy>

Process-wide D1 proxy installed by open, if any.

Generated from crates/bookclerk-plugins/optional/database-d1 at main · View as Markdown