bookclerk_db_testkit::binding

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

Last updated View as Markdown

A plugin-owned database that behaves like a granted [[databases]] binding on a deployed host.

A plugin's env.DB reaches an isolated unit through the host, which authorizes the SQL against the binding-owned scope, wraps every batch in a receipt and holds it to the adapter's advertisement. The in-process fakes an author would otherwise test against do none of that. BindingDatabase runs the same host path on an in-memory SQLite unit under one Profile, so a plugin's queries meet the caps, the typed limit_exceeded error and the refused interactive transaction before they meet a real adapter.

The TypeScript and Python SDKs reach it through the bookclerk-db-testkit binary, which serves one binding over the granted channel the isolates already speak (POST /db/execute, POST /db/execute-streamed, GET /db/limits).

Structs

BindingDatabase

pub struct BindingDatabase {
    /* private fields */
}

An in-memory plugin database binding under one capability profile.

Open one with BindingDatabase::open, giving it the plugin's databaseMigrations registration, and run the plugin's SQL through the GuestDatabase methods the host serves.

BindingDatabase::open

pub async fn open(
    profile: Profile,
    migrations: Vec<PluginMigration>,
) -> Result<Self, PluginError>

Opens an empty in-memory unit under profile and applies migrations the way the host applies a plugin's databaseMigrations registration at enrollment: one typed batch per migration, stamped with the binding's schema and held to the profile's advertisement, as the adapter holds it.

Errors

Returns invalid_params when the registration fails the BookclerkSQL proof (an unsupported statement, a reserved table, a repeated id), limit_exceeded when a migration's apply batch breaks one of the profile's caps, and the engine's error when the unit cannot be opened or a migration cannot be applied.

BindingDatabase::profile

pub fn profile(&self) -> Profile

The profile this binding enforces.

BindingDatabase::capabilities

pub fn capabilities(&self) -> &DbCapabilities

The advertisement every batch is held to.

BindingDatabase::connection

pub fn connection(&self) -> &DatabaseConnection

The unit itself, for a test that inspects what the plugin wrote.

BindingDatabase::batch_sizes

pub fn batch_sizes(&self) -> Vec<usize>

Statement counts of every batch sent so far, in arrival order, including batches the profile turned away.

Implements: Debug, GuestDatabase

Generated from crates/bookclerk-db-testkit at main · View as Markdown