bookclerk_plugin_database_d1::d1
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. |
pub struct D1Proxy {
/* private fields */
}
SeaORM proxy that executes statements against Cloudflare D1's HTTP API.
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.
Returns when the batch is rejected, HTTP fails, or the reply cannot be encoded after commit.
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.
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 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
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.
Returns an error when the operation fails.
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.
Returns when lookup fails or no database with name exists.
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.
Returns when the HTTP lookup/create fails or the response is malformed.
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.
Returns when lookup or delete fails, or the token lacks D1 edit permission.
pub fn set_shared_proxy(proxy: D1Proxy)
Stores the process-wide D1 proxy used by atomic execute after open.
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