# 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`](#d1proxyrun_typed_atomic), which sends
`{ "batch": [...] }` (a real SQL transaction) with control flow
encoded in SQL and a durable `operationId` receipt.

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

## Structs

### D1Proxy

```rust
pub struct D1Proxy {
    /* private fields */
}
```

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

#### D1Proxy::run_typed_atomic

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

Runs a typed [`ExecuteRequest`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#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

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

[`Self::run_typed_atomic`](#d1proxyrun_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`](#d1proxyrun_typed_atomic).

#### D1Proxy::new

```rust
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`](/docs/plugins/sdk/rust/net/index.md#socket_proxy_env) this does not fall back to
ambient TCP.

Implements: `Clone`, `Debug`, `ProxyDatabaseTrait`

## Functions

### open

```rust
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

```rust
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

```rust
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

```rust
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

```rust
pub fn set_shared_proxy(proxy: D1Proxy)
```

Stores the process-wide D1 proxy used by atomic execute after [`open`](#open).

### shared_proxy

```rust
pub fn shared_proxy() -> Option<D1Proxy>
```

Process-wide D1 proxy installed by [`open`](#open), if any.
