db-execute

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

Last updated View as Markdown

Classes

WriteChunksError

A DatabaseBinding.writeChunks run that failed part way. code, message and details are the failed batch's; next is the statements committed before it, to resume from.

Extends

Constructors

Constructor
new WriteChunksError(next, cause): WriteChunksError;
Parameters
Parameter Type Description
next number Statements committed before the failure.
cause PluginError The failed batch's error, whose code, message and details this error carries.
Returns

WriteChunksError

Overrides

PluginError.constructor

Properties

code
readonly code: string;

Known PluginErrorCode wire string, or unknown.

Inherited from

PluginError.code

details
readonly details: Readonly<Record<string, unknown>> | undefined;

Structured detail object from the wire (details JSON), when the error carries one.

Inherited from

PluginError.details

next
readonly next: number;

Statements committed before the failure; resume with from: next.

wireCode
readonly wireCode: string;

Raw wire code, including codes this SDK does not know.

Inherited from

PluginError.wireCode

Accessors

detailsText
Get Signature
get detailsText(): string;

details as the JSON text the wire carries.

Returns

string

JSON object text, or an empty string when the error has none.

Inherited from

PluginError.detailsText

limit
Get Signature
get limit(): LimitExceeded | undefined;

The exceeded cap when this is a limit_exceeded error.

Returns

LimitExceeded | undefined

The cap from details first, then from the canonical message; undefined for every other code.

Inherited from

PluginError.limit

Methods

fromWire()
static fromWire(
   code, 
   message, 
   details?
): PluginError;

Construct a PluginError from a Cap'n Proto / JSON wire code.

Unknown codes become unknown on PluginError.code while PluginError.wireCode keeps the raw value.

Parameters
Parameter Type Default value Description
code string undefined Wire error code (known or unknown).
message string undefined Operator-facing error text.
details? string "" details JSON text from the wire (empty when none).
Returns

PluginError

Typed plugin error.

Inherited from

PluginError.fromWire

limitExceeded()
static limitExceeded(limit): PluginError;

Builds a limit_exceeded error whose message and details both carry the exceeded cap.

Parameters
Parameter Type Description
limit LimitExceeded Exceeded cap.
Returns

PluginError

Typed plugin error.

Inherited from

PluginError.limitExceeded

Interfaces

AtomicTransport

Host GuestDatabase.execute projection.

Extended by

Methods

execute()
execute(request): Promise<ExecuteReply>;

Runs one typed atomic batch.

Parameters
Parameter Type Description
request ExecuteRequest Structured Cap'n ExecuteRequest.
Returns

Promise<ExecuteReply>

Structured ExecuteReply.

executeStreamed()?
executeStreamed?(request): Promise<
  | Uint8Array<ArrayBufferLike>
| ReadableStream<Uint8Array<ArrayBufferLike>>>;

Runs the same typed atomic batch as AtomicTransport.execute but answered as ExecuteStreamFrame bytes (GuestDatabase.executeStreamed), so the result may grow to the session's streamed budget. Transports that predate it leave it out; the binding then reads inline.

Parameters
Parameter Type Description
request ExecuteRequest Structured Cap'n ExecuteRequest.
Returns

Promise< | Uint8Array<ArrayBufferLike> | ReadableStream<Uint8Array<ArrayBufferLike>>>

The frame sequence, whole or as a byte stream.

limits()?
limits?(): Promise<DbCapabilities>;

Negotiated limits of the session (DbCapabilities). Transports that predate GuestDatabase.limits leave it out; the binding then throws unsupported.

Returns

Promise<DbCapabilities>

The adapter's capability advertisement for this session.


D1ExecResult

Cloudflare D1ExecResult.

Properties

count
count: number;

Number of statements executed (one per non-empty exec line).

duration
duration: number;

Total duration in milliseconds.


D1Meta

Cloudflare D1Result.meta shape (Bookclerk fills fields available from the typed execute reply).

Properties

changed_db
changed_db: boolean;

true when changes > 0.

changes
changes: number;

Rows changed by the statement (rowsAffected).

duration
duration: number;

Engine-reported SQL duration in milliseconds.

last_row_id
last_row_id: number;

Last inserted row id when the adapter exposes it (else 0).

rows_read
rows_read: number;

Rows returned to the guest for this statement.

rows_written
rows_written: number;

Rows written (changes for DML).


D1Result

Cloudflare D1Result projection for plugin guests. Errors throw; successful calls always set success: true.

Type Parameters

Type Parameter Default type
<a id="type-parameter-t"></a> T Record<string, DbValue>

Properties

meta
meta: D1Meta;
results
results: T[] | null;

Row objects for selects; [] when empty; null when not applicable (DML).

success
success: true;

DatabaseBinding

Host-mediated typed SQL surface for plugin guests.

Public API is Cloudflare-style prepare().bind().run()/first()/all() plus atomic batch(). Raw execute stays internal.

Methods

batch()
batch(statements, options?): Promise<D1Result<Record<string, DbValue>>[]>;

Run prepared statements as one typed atomic batch.

Ordinary bound prepared statements use Cloudflare run() semantics (resultSelection: rows) by default. Optional asRun / asFirst / asAll override per-statement intent. Returns one Cloudflare-shaped D1Result per statement.

Parameters
Parameter Type Description
statements PreparedStatement[] Prepared statements (binds and intent already applied).
options? { retry?: RetryToken; } Retry token.
options.retry? RetryToken -
Returns

Promise<D1Result<Record<string, DbValue>>[]>

chunk()
chunk(statements, options?): AsyncIterable<PreparedStatement[]>;

Splits statements into batches that each fit one request (maxStatements of the session and the tighter of the session's and the binding's maxRequestBytes, or the caps in options): for await (const b of db.chunk(stmts)) await db.batch(b). Each batch is atomic; the loop is not. A single statement larger than the request cap is yielded alone, so batch() reports the typed error. Batches are sized with the UUID-shaped retry id the binding mints; a caller-chosen retry id that is longer leaves that much less room.

Parameters
Parameter Type Description
statements PreparedStatement[] Prepared statements (binds and intent already applied).
options? { maxRequestBytes?: number; maxStatements?: number; } Caps to split by instead of the session's limits; 0 given explicitly means no cap (one batch when both are 0).
options.maxRequestBytes? number -
options.maxStatements? number -
Returns

AsyncIterable<PreparedStatement[]>

exec()
exec(query, options?): Promise<D1ExecResult>;

Execute raw SQL without bind parameters (Cloudflare D1Database.exec).

Parameters
Parameter Type Description
query string Canonical SQL string.
options? { retry?: RetryToken; } Optional retry token.
options.retry? RetryToken -
Returns

Promise<D1ExecResult>

execute()
execute(batch, options?): Promise<ExecuteReply>;

Internal typed-batch transport. Prefer DatabaseBinding.prepare.

Parameters
Parameter Type Description
batch TypedDbStatement[] Ordered statements with typed DbValue parameters.
options? { retry?: RetryToken; } Optional retry token.
options.retry? RetryToken -
Returns

Promise<ExecuteReply>

limits()
limits(): Promise<DbCapabilities>;

The negotiated limits of this binding's session (DbCapabilities): maxRequestBytes, maxStatements, maxResultBytes, maxResultRows and the rest. Use them to size a batch or a read before sending.

Returns

Promise<DbCapabilities>

Throws

PluginError with code unsupported on a host that predates GuestDatabase.limits.

prepare()
prepare(sql): PreparedStatement;

Prepare one canonical-SQL statement (? placeholders).

Parameters
Parameter Type Description
sql string Host-mediated SQL. Kind and bounds are derived by the host.
Returns

PreparedStatement

writeChunks()
writeChunks(statements, options): Promise<WriteProgress>;

Writes statements in batches that fit one request, resumably.

The batches are the ones DatabaseBinding.chunk yields for statements.slice(from), each committed with batch() under an operation id derived from key and the batch's offset (writeChunksOperationId). Store the returned next (for example in a job checkpoint) and call again with the same list, the same key and from: next to carry on: a batch whose reply was lost is resent under the same id and the host replays its receipt. Receipts are kept for 24 hours; a batch resent later runs again, so a write that may pause that long uses statements safe to repeat.

stop(next) is asked before each batch; returning true pauses the run there. The list and the caps must not change between calls with one key, or a resent batch no longer matches its receipt and the host answers conflict.

Parameters
Parameter Type Description
statements PreparedStatement[] The whole list, the same on every call.
options WriteChunksOptions key names the write (stable across resumes, at most MAX_WRITE_KEY_BYTES UTF-8 bytes); from is the statements already committed (default 0); stop is asked before each batch; maxStatements / maxRequestBytes are as for chunk().
Returns

Promise<WriteProgress>

{ next, done }: statements committed, and whether all are.

Throws

WriteChunksError carrying next when a batch fails or the input is invalid.


DatabaseBindingOptions

Options for createDatabaseBinding.

Properties

deadlineUnixMs?
deadlineUnixMs?: number;

Guest-visible deadline (unix ms).

maxRequestBytes?
maxRequestBytes?: number;

Negotiated maxRequestBytes (0 = unlimited).

maxResultRows?
maxResultRows?: number;

Default maxRows for all() (0 = host adapter cap).

operationId?
operationId?: string;

Idempotency key; generated when omitted.

requestHash?
requestHash?: string;

SHA-256 hex of the request; empty when omitted.

retry?
retry?: RetryToken;

Default retry token; omitted calls mint a UUID and leave the hash empty.


DbColumn

One column in a typed result set.

Properties

dbType
dbType: "unspecified" | "bool" | "text" | "int64" | "float64" | "bytes";

Declared / inferred type.

name
name: string;

Column name.


DbRow

One positional result row.

Properties

values
values: DbValue[];

Cells in column order.


DbTiming

Handler/engine timing on ExecuteReply.

Properties

attemptElapsedUs
attemptElapsedUs: number;

Whole-attempt elapsed microseconds.

dbExecutionUs
dbExecutionUs: number;

Engine-reported SQL microseconds when available.

dbTimingSource
dbTimingSource: string;

Observability source (sqlite_txn, d1_sql_duration, …).


ExecuteReply

Typed execute reply.

Properties

operationId
operationId: string;

Echo of the request operationId.

statements
statements: StatementResult[];

Per-statement results, in plan order.

timing
timing: DbTiming;

Handler/engine timing.


ExecuteRequest

Typed execute request.

Properties

deadlineUnixMs
deadlineUnixMs: number;

Guest-visible deadline (unix ms). Zero means omitted.

operationId
operationId: string;

Caller-chosen idempotency key.

requestHash
requestHash: string;

SHA-256 hex of the idempotency-relevant request; empty when omitted.

statements
statements: TypedDbStatement[];

Ordered statements (must be non-empty).


PreparedStatement

Cloudflare-style prepared statement. Kind, bounds, and request hash are derived by the trusted host. Only universal DbValues are public.

Methods

all()
all(options?): Promise<D1Result<Record<string, DbValue>>>;

Execute as a row-returning query. Returns a Cloudflare-shaped D1Result.

Parameters
Parameter Type Description
options? { retry?: RetryToken; } Optional retry token.
options.retry? RetryToken -
Returns

Promise<D1Result<Record<string, DbValue>>>

asAll()
asAll(): PreparedStatement;

Mark row-returning intent for DatabaseBinding.batch.

Returns

PreparedStatement

asFirst()
asFirst(): PreparedStatement;

Mark maxRows = 1 row intent for DatabaseBinding.batch.

Returns

PreparedStatement

asRun()
asRun(): PreparedStatement;

Mark DML intent for DatabaseBinding.batch.

Returns

PreparedStatement

bind()
bind(...values): PreparedStatement;

Replace bound parameters.

Parameters
Parameter Type Description
...values DbValue[] Universal DbValues only.
Returns

PreparedStatement

first()
first(colName?, options?): Promise<
  | DbValue
  | Record<string, DbValue>
| null>;

First row as a name→value map, or one column when colName is set.

Parameters
Parameter Type Description
colName? string Optional column name (Cloudflare first(colName)).
options? { retry?: RetryToken; } Optional retry token.
options.retry? RetryToken -
Returns

Promise< | DbValue | Record<string, DbValue> | null>

iterate()
iterate(options?): AsyncIterable<Record<string, DbValue>>;

Rows one at a time from the same single-snapshot streamed read as PreparedStatement.all, without holding the whole result: for await (const row of stmt.iterate()) …. The read still fails closed (limit_exceeded) past the session's streamed budget. On a session that does not stream the rows come from one inline all().

Parameters
Parameter Type Description
options? { retry?: RetryToken; } Optional retry token.
options.retry? RetryToken -
Returns

AsyncIterable<Record<string, DbValue>>

raw()
raw(options?): Promise<DbValue[][]>;

Positional cell values per row (Cloudflare raw()).

Parameters
Parameter Type Description
options? { retry?: RetryToken; } Optional retry token.
options.retry? RetryToken -
Returns

Promise<DbValue[][]>

run()
run(options?): Promise<D1Result<Record<string, DbValue>>>;

Execute as DML. Returns a Cloudflare-shaped D1Result.

Parameters
Parameter Type Description
options? { retry?: RetryToken; } Optional retry token.
options.retry? RetryToken -
Returns

Promise<D1Result<Record<string, DbValue>>>


RetryToken

Explicit retry identity. Reuses both operationId and requestHash.

Properties

operationId
operationId: string;

Caller-chosen idempotency key.

requestHash
requestHash: string;

Canonical Cap'n request hash stamped by the host.


StatementResult

Result of one statement in an atomic batch.

Properties

columns
columns: DbColumn[];

Column metadata aligned with each row.

rows
rows: DbRow[];

Positional rows.

rowsAffected
rowsAffected: number;

Engine rowsAffected (0 for Select).


TypedDbStatement

One statement in a typed atomic batch.

Properties

kind
kind: "execute" | "select" | "returning";

Host-authored kind (adapters must not reparse SQL).

maxRows
maxRows: number;

Proven row upper bound (0 = unproven).

parameters
parameters: DbValue[];

Ordered typed binds.

resultSelection
resultSelection: "discard" | "affectedRows" | "rows";

Which result fields the caller needs.

sql
sql: string;

Canonical Bookclerk SQL (? placeholders).


WriteChunksOptions

Options for DatabaseBinding.writeChunks.

Properties

from?
from?: number;

Statements already committed; 0 on the first call.

key
key: string;

Names this write, stable across resumes (a job id plus a step name).

maxRequestBytes?
maxRequestBytes?: number;

Request bytes per batch instead of the session's cap (0 = no cap).

maxStatements?
maxStatements?: number;

Statements per batch instead of the session's cap (0 = no cap).

stop?
stop?: (next) => boolean;

Asked before each batch with the statements committed so far; true pauses.

Parameters
Parameter Type
next number
Returns

boolean


WriteProgress

Where a DatabaseBinding.writeChunks run stands.

Properties

done
done: boolean;

True when every statement is committed; false when stop paused the run.

next
next: number;

Statements committed from the start of the list; always a batch boundary.

Variables

MAX_WRITE_KEY_BYTES

const MAX_WRITE_KEY_BYTES: 256 = 256;

Longest key DatabaseBinding.writeChunks accepts, in UTF-8 bytes.

Functions

canonicalExecuteRequestHash()

function canonicalExecuteRequestHash(request): Promise<string>;

SHA-256 hex of the Cap'n request with id and hash cleared.

Parameters

Parameter Type Description
request ExecuteRequest Structured request.

Returns

Promise<string>

Hex digest matching the host canonical hash.


chunkIndexes()

function chunkIndexes(
   typed, 
   maxStatements, 
   maxRequestBytes
): number[][];

Greedy split of typed into index runs whose encoded request stays within maxRequestBytes and whose length stays within maxStatements (0 lifts a cap). Sizes are estimated per statement and each run is verified by one exact encode; a run the estimate let through is halved until it fits, and a lone statement over the cap is yielded on its own.

Parameters

Parameter Type Description
typed TypedDbStatement[] Statements to split.
maxStatements number Statements per request (0 = no cap).
maxRequestBytes number Encoded request bytes (0 = no cap).

Returns

number[][]

Index runs in order, covering every statement once.


createDatabaseBinding()

function createDatabaseBinding(transport, options?): DatabaseBinding;

Builds a host-mediated DatabaseBinding over an execute transport.

Parameters

Parameter Type Description
transport AtomicTransport Host session projection.
options? DatabaseBindingOptions Request-budget and idempotency knobs.

Returns

DatabaseBinding

Binding whose execute(batch) encodes Cap'n then calls the host.


decodeDbCapabilitiesReply()

function decodeDbCapabilitiesReply(bytes): DbCapabilities;

Decodes a standalone DbCapabilitiesReply. err is thrown as PluginError.

Parameters

Parameter Type Description
bytes Uint8Array Unpacked Cap'n stream.

Returns

DbCapabilities

The session's DbCapabilities.

Throws

When the union is err or the buffer is invalid.


decodeExecuteRequest()

function decodeExecuteRequest(bytes): ExecuteRequest;

Decodes a standalone unpacked Cap'n ExecuteRequest message.

Parameters

Parameter Type Description
bytes Uint8Array Unpacked Cap'n stream.

Returns

ExecuteRequest

Structured request.

Throws

When the buffer is not a valid non-empty ExecuteRequest.


decodeExecuteResultReply()

function decodeExecuteResultReply(bytes): ExecuteReply;

Decodes a standalone ExecuteResultReply. err is thrown as PluginError.

Parameters

Parameter Type Description
bytes Uint8Array Unpacked Cap'n stream.

Returns

ExecuteReply

Structured ExecuteReply.

Throws

When the union is err or the buffer is invalid.


encodeDbCapabilitiesReply()

function encodeDbCapabilitiesReply(outcome): Uint8Array;

Encodes a standalone DbCapabilitiesReply (ok or err), the answer of GuestDatabase.limits on the granted channel (GET /db/limits).

Parameters

Parameter Type Description
outcome | { ok: DbCapabilities; } | { err: { code: string; details?: string; message: string; }; } Capability advertisement or a wire PluginError.

Returns

Uint8Array

Unpacked Cap'n stream bytes.


encodeExecuteReply()

function encodeExecuteReply(reply): Uint8Array;

Encodes a standalone unpacked Cap'n ExecuteReply message.

Parameters

Parameter Type Description
reply ExecuteReply Structured reply.

Returns

Uint8Array

Unpacked Cap'n stream bytes.


encodeExecuteRequest()

function encodeExecuteRequest(request): Uint8Array;

Encodes a standalone unpacked Cap'n ExecuteRequest message.

Parameters

Parameter Type Description
request ExecuteRequest Structured request (non-empty statements).

Returns

Uint8Array

Unpacked Cap'n stream bytes (same encoding as the Rust SDK).

Throws

When statements is empty.


encodeExecuteResultReply()

function encodeExecuteResultReply(outcome): Uint8Array;

Encodes ExecuteResultReply (ok or err).

Parameters

Parameter Type Description
outcome | { ok: ExecuteReply; } | { err: { code: string; details?: string; message: string; }; } Successful reply or a wire PluginError.

Returns

Uint8Array

Unpacked Cap'n stream bytes.


executeReplyToD1Results()

function executeReplyToD1Results(reply): D1Result<Record<string, DbValue>>[];

Maps a typed execute reply to Cloudflare D1Result per statement.

Parameters

Parameter Type Description
reply ExecuteReply Decoded ExecuteReply from the host transport.

Returns

D1Result<Record<string, DbValue>>[]

One D1Result per statement, in plan order.


statementResultToD1Result()

function statementResultToD1Result(stmt, timing): D1Result;

Maps one typed statement result to Cloudflare D1Result.

Parameters

Parameter Type Description
stmt StatementResult Per-statement rows, columns, and rowsAffected.
timing DbTiming Handler/engine timing from the execute reply.

Returns

D1Result

Cloudflare-shaped { success, results, meta }.


writeChunksOperationId()

function writeChunksOperationId(key, offset): Promise<string>;

The operation id DatabaseBinding.writeChunks sends for the batch that starts at offset of the write named key: the first 16 bytes of SHA-256 over "bookclerk-write-chunks\0" + key + "\0" + offset (decimal), as lowercase hex grouped 8-4-4-4-12. The Rust and Python SDKs derive the same id.

Parameters

Parameter Type Description
key string Name of the write.
offset number Index of the batch's first statement.

Returns

Promise<string>

A UUID-shaped operation id.

References

DbResultSelection

Re-exports DbResultSelection


DbStatementKind

Re-exports DbStatementKind

Generated from packages/plugin-sdk at main · View as Markdown