bookclerk_db_guest
First-party database guest internals (SeaORM session workers).
Third-party database plugin authors should depend on
bookclerk_plugin_sdk::database_adapter only. Platform SQLite / Postgres /
D1 guests use this crate for host-mediated session and transaction workers.
| Item | Kind | Summary |
|---|---|---|
BoundGuestHostAdapterSession |
struct | Host-private envelope session bound to one dedicated connection (named bindings). |
GuestHostAdapterSession |
struct | In-process SeaORM transaction bridge for host begin RPC (shared library connection). |
GuestStatement |
struct | SQL text, JSON-encoded binds, and optional txn id for the session worker. |
host_session |
function | Returns the default host adapter session on the shared guest connection. |
host_session_on |
function | Host envelope session that persists guest receipts on conn. |
bootstrap_for |
function | Bootstrap metadata for an explicit connection's engine family. |
capabilities_for |
function | Advertised capabilities for an explicit connection's engine family. |
guest_assert_restore_constraints |
function | Assert restore constraints on the process-wide connection. |
guest_assert_restore_constraints_on |
function | Assert restore constraints on conn. |
guest_assert_restore_constraints_on_txn |
function | Assert restore constraints on an open guest transaction. |
guest_begin |
function | Begins a top-level transaction or a nested savepoint. |
guest_begin_isolated |
function | Begins a top-level transaction realizing isolation (or a nested savepoint). |
guest_begin_on |
function | Begins a top-level transaction on an explicit connection (plugin bindings). |
guest_begin_on_isolated |
function | guest_begin_on with an explicit isolation requirement. |
guest_bootstrap |
function | Bootstrap-only SeaORM proxy metadata for the connected engine. |
guest_capabilities |
function | Typed AdapterDatabaseSession.capabilities for the connected engine. |
guest_commit |
function | Commits a transaction previously returned by guest_begin. |
guest_drop_user_relations |
function | Drop relations on the process-wide connection. |
guest_drop_user_relations_on |
function | Drop relations on conn. |
guest_drop_user_relations_on_txn |
function | Drop relations on an open guest transaction. |
guest_execute |
function | Runs a mutating SQL statement through the guest database bridge. |
guest_execute_atomic |
function | Typed AdapterDatabaseSession.execute on the shared library connection. |
guest_execute_atomic_on |
function | Typed execute on an explicit connection (per-binding sessions). |
guest_execute_atomic_on_txn |
function | Typed Transaction.executeAtomic on an already-open guest transaction. |
guest_execute_request |
function | First-party adapter execute: proofs required (require_stamped=true). |
guest_execute_request_on |
function | First-party adapter execute on an explicit connection. |
guest_execute_streamed_request |
function | guest_execute_atomic answered as a streamed reply: the batch runs under the advertised streamed budget and its reply is framed. |
guest_execute_streamed_request_on |
function | guest_execute_atomic_on answered as a streamed reply (per-binding sessions). |
guest_export_identity |
function | Identity high-water on the process-wide connection. |
guest_export_identity_on |
function | Identity high-water on conn. |
guest_export_identity_on_txn |
function | Identity high-water on an open guest transaction. |
guest_import_identity |
function | Restore identity on the process-wide connection. |
guest_import_identity_on |
function | Restore identity on conn. |
guest_import_identity_on_txn |
function | Restore identity on an open guest transaction. |
guest_list_user_relations |
function | User-visible relations on the process-wide connection. |
guest_list_user_relations_on |
function | User-visible relations on conn. |
guest_list_user_relations_on_txn |
function | User-visible relations on an open guest transaction. |
guest_ping |
function | Issues a guest db.ping RPC against the process-local SeaORM connection. |
guest_prepare_unit_restore |
function | Prepare restore on the process-wide connection. |
guest_prepare_unit_restore_on |
function | Prepare restore on conn. |
guest_prepare_unit_restore_on_txn |
function | Prepare restore on an open guest transaction. |
guest_query |
function | Runs a read-only SQL query through the guest database bridge. |
guest_query_page |
function | Runs a read-only statement and returns one bounded page (limit + 1 fetch). |
guest_rollback |
function | Rolls back a transaction previously returned by guest_begin. |
row_to_dto |
function | Projects one SeaORM query row into a GuestRow (integration tests). |
set_connection |
function | Store the opened engine connection for subsequent ping/query/execute calls. |
guest_sql |
function | Builds a GuestStatement for plain SQL without binds. |
pub struct BoundGuestHostAdapterSession {
/* private fields */
}
Host-private envelope session bound to one dedicated connection (named bindings).
Implements: HostAdapterDatabaseSession
pub struct GuestHostAdapterSession;
In-process SeaORM transaction bridge for host begin RPC (shared library connection).
Implements: HostAdapterDatabaseSession
pub struct GuestStatement {
pub sql: String,
pub values: Vec<Value>,
pub txn_id: Option<String>,
}
SQL text, JSON-encoded binds, and optional txn id for the session worker.
Fields
sql: SQL text with positional placeholders.values: Ordered bind values (JSON encoding for typed nulls and bytes).txn_id: Active guest transaction id, if any.
Implements: Clone, Debug
pub fn host_session() -> GuestHostAdapterSession
Returns the default host adapter session on the shared guest connection.
pub fn host_session_on(conn: DatabaseConnection) -> BoundGuestHostAdapterSession
Host envelope session that persists guest receipts on conn.
pub fn bootstrap_for(conn: &DatabaseConnection) -> DbBootstrap
Bootstrap metadata for an explicit connection's engine family.
pub fn capabilities_for(conn: &DatabaseConnection) -> DbCapabilities
Advertised capabilities for an explicit connection's engine family.
pub async fn guest_assert_restore_constraints() -> Result<(), String>
Assert restore constraints on the process-wide connection.
Returns when not connected or FK violations remain.
pub async fn guest_assert_restore_constraints_on(
conn: &DatabaseConnection,
) -> Result<(), String>
Assert restore constraints on conn.
Returns when FK violations remain.
pub async fn guest_assert_restore_constraints_on_txn(txn_id: String) -> Result<(), String>
Assert restore constraints on an open guest transaction.
Returns when the txn id is unknown or FK violations remain.
pub async fn guest_begin(parent_txn_id: Option<String>) -> Result<String, String>
Begins a top-level transaction or a nested savepoint.
Top-level begins wait until no other transaction is open so SQLite never interleaves writers. Nested begins run on the parent worker task.
parent_txn_id- Existing txn id to nest under;Nonefor top-level.
Opaque txn id the host must attach to subsequent statements.
Returns an error string when not connected, the parent is unknown, or the
engine rejects BEGIN.
pub async fn guest_begin_isolated(
parent_txn_id: Option<String>,
isolation: IsolationReq,
) -> Result<String, String>
Begins a top-level transaction realizing isolation (or a nested savepoint).
Returns an error string when not connected, the parent is unknown, or the
engine rejects BEGIN.
pub async fn guest_begin_on(conn: DatabaseConnection) -> Result<String, String>
Begins a top-level transaction on an explicit connection (plugin bindings).
Does not take the process-wide library writer gate; each binding connection is independent.
Returns an error string when begin fails.
pub async fn guest_begin_on_isolated(
conn: DatabaseConnection,
isolation: IsolationReq,
) -> Result<String, String>
guest_begin_on with an explicit isolation requirement.
Returns an error string when begin fails.
pub async fn guest_bootstrap() -> Result<DbBootstrap, PluginError>
Bootstrap-only SeaORM proxy metadata for the connected engine.
Returns when no connection has been opened.
pub async fn guest_capabilities() -> Result<DbCapabilities, PluginError>
Typed AdapterDatabaseSession.capabilities for the connected engine.
Returns when no connection has been opened.
pub async fn guest_commit(txn_id: String) -> Result<(), String>
Commits a transaction previously returned by guest_begin.
txn_id- Id fromguest_begin.
Returns an error string when the id is unknown or the engine rejects commit.
pub async fn guest_drop_user_relations(names: &[String]) -> Result<(), String>
Drop relations on the process-wide connection.
Returns when not connected or a drop fails.
pub async fn guest_drop_user_relations_on(
conn: &DatabaseConnection,
names: &[String],
) -> Result<(), String>
Drop relations on conn.
Returns when a drop fails.
pub async fn guest_drop_user_relations_on_txn(
txn_id: String,
names: Vec<String>,
) -> Result<(), String>
Drop relations on an open guest transaction.
Returns when the txn id is unknown or a drop fails.
pub async fn guest_execute(dto: GuestStatement) -> Result<GuestExecResult, String>
Runs a mutating SQL statement through the guest database bridge.
dto- RPC statement DTO from the host bridge.
Last-insert id and rows-affected in a GuestExecResult.
Returns an error string when not connected or the engine rejects the statement.
pub async fn guest_execute_atomic(
envelope: AdapterExecuteRequest,
) -> Result<ExecuteReply, PluginError>
Typed AdapterDatabaseSession.execute on the shared library connection.
Proofs are required. The guest encodes ExecuteReply before COMMIT;
post-commit failures are classified as unavailable.
Returns when no connection is open, proofs are missing, isolation is unsupported, or the engine rejects the work.
pub async fn guest_execute_atomic_on(
conn: &DatabaseConnection,
envelope: AdapterExecuteRequest,
) -> Result<ExecuteReply, PluginError>
Typed execute on an explicit connection (per-binding sessions).
Unlike guest_execute_atomic, no process-wide writer gate applies:
plugin database bindings are independent databases, so their transactions
never interleave with the shared library connection.
Returns when the engine rejects the work.
pub async fn guest_execute_atomic_on_txn(
txn_id: String,
request: AdapterExecuteRequest,
) -> Result<ExecuteReply, PluginError>
Typed Transaction.executeAtomic on an already-open guest transaction.
Does not BEGIN or COMMIT. The host still owns commit/rollback.
Returns when the txn id is unknown or the engine rejects the work.
pub async fn guest_execute_request(
request: AdapterExecuteRequest,
) -> Result<ExecuteReply, PluginError>
First-party adapter execute: proofs required (require_stamped=true).
Returns when no connection is open, proofs are missing, or the engine rejects the work.
pub async fn guest_execute_request_on(
conn: &DatabaseConnection,
request: AdapterExecuteRequest,
) -> Result<ExecuteReply, PluginError>
First-party adapter execute on an explicit connection.
Returns when proofs are missing or the engine rejects the work.
pub async fn guest_execute_streamed_request(
envelope: AdapterExecuteRequest,
) -> Result<ExecuteStream, PluginError>
guest_execute_atomic answered as a streamed reply: the batch runs
under the advertised streamed budget and its reply is framed.
Returns unsupported when this engine advertises no streamed budget, and
otherwise what guest_execute_atomic returns.
pub async fn guest_execute_streamed_request_on(
conn: &DatabaseConnection,
envelope: AdapterExecuteRequest,
) -> Result<ExecuteStream, PluginError>
guest_execute_atomic_on answered as a streamed reply (per-binding
sessions).
Returns unsupported when this engine advertises no streamed budget, and
otherwise what guest_execute_atomic_on returns.
pub async fn guest_export_identity() -> Result<Vec<DbIdentityHighWater>, String>
Identity high-water on the process-wide connection.
Returns when not connected or a catalog query fails.
pub async fn guest_export_identity_on(
conn: &DatabaseConnection,
) -> Result<Vec<DbIdentityHighWater>, String>
Identity high-water on conn.
Returns when a catalog query fails.
pub async fn guest_export_identity_on_txn(
txn_id: String,
) -> Result<Vec<DbIdentityHighWater>, String>
Identity high-water on an open guest transaction.
Returns when the txn id is unknown or a catalog query fails.
pub async fn guest_import_identity(rows: &[DbIdentityHighWater]) -> Result<(), String>
Restore identity on the process-wide connection.
Returns when not connected or a catalog write fails.
pub async fn guest_import_identity_on(
conn: &DatabaseConnection,
rows: &[DbIdentityHighWater],
) -> Result<(), String>
Restore identity on conn.
Returns when a catalog write fails.
pub async fn guest_import_identity_on_txn(
txn_id: String,
rows: Vec<DbIdentityHighWater>,
) -> Result<(), String>
Restore identity on an open guest transaction.
Returns when the txn id is unknown or a catalog write fails.
pub async fn guest_list_user_relations() -> Result<Vec<String>, String>
User-visible relations on the process-wide connection.
Returns when not connected or the catalog probe fails.
pub async fn guest_list_user_relations_on(
conn: &DatabaseConnection,
) -> Result<Vec<String>, String>
User-visible relations on conn.
Returns when the catalog probe fails.
pub async fn guest_list_user_relations_on_txn(
txn_id: String,
) -> Result<Vec<String>, String>
User-visible relations on an open guest transaction.
Returns when the txn id is unknown or the catalog probe fails.
pub async fn guest_ping() -> Result<(), String>
Issues a guest db.ping RPC against the process-local SeaORM connection.
Ok(()) when the engine responds to ping.
Returns an error string when set_connection was never called or ping fails.
pub async fn guest_prepare_unit_restore() -> Result<(), String>
Prepare restore on the process-wide connection.
Returns when not connected or the pragma fails.
pub async fn guest_prepare_unit_restore_on(
conn: &DatabaseConnection,
) -> Result<(), String>
Prepare restore on conn.
Returns when the pragma fails.
pub async fn guest_prepare_unit_restore_on_txn(txn_id: String) -> Result<(), String>
Prepare restore on an open guest transaction.
Returns when the txn id is unknown or the pragma fails.
pub async fn guest_query(dto: GuestStatement) -> Result<GuestQueryResult, String>
Runs a read-only SQL query through the guest database bridge.
dto- RPC statement DTO from the host bridge.
Query rows projected into GuestQueryResult.
Returns an error string when not connected or the engine rejects the statement.
pub async fn guest_query_page(
dto: GuestStatement,
cursor: &str,
limit: u32,
) -> Result<QueryPage, String>
Runs a read-only statement and returns one bounded page (limit + 1 fetch).
The adapter wraps SELECT/WITH SQL once with LIMIT/OFFSET so later
pages do not rematerialize the full result set. Data-modifying CTEs and
FOR UPDATE/FOR SHARE are rejected with a literal/comment-aware scan.
Postgres pins one transaction for create → probe → stream → drop:
autocommit pages BEGIN + CREATE TEMP TABLE … ON COMMIT DROP AS (caller
SQL once), then pg_column_size and an ordered select from that table.
The adapter-private ROW_NUMBER column reuses the temp-table UUID as a
suffix so it cannot collide with a caller alias such as _bookclerk_page_ord.
Guest-txn pages reuse the already-pinned DatabaseTransaction.
SET TRANSACTION READ ONLY cannot wrap this path: PostgreSQL rejects
CREATE TABLE in a read-only transaction. SQLite/D1 issue one
query_all_raw. Encoding stops at MAX_SCALAR_BYTES. Cursors are parsed
as a bounded u64 so offset + page cannot overflow.
Huge server-side expressions can still stress the engine during materialize; the protocol bound is the decode/scalar cap.
Returns an error string when not connected, the cursor is invalid, the
engine rejects the statement, a row exceeds the scalar budget, or the
driver returns more than limit + 1 rows.
pub async fn guest_rollback(txn_id: String) -> Result<(), String>
Rolls back a transaction previously returned by guest_begin.
txn_id- Id fromguest_begin.
Returns an error string when the id is unknown or the engine rejects rollback.
pub fn row_to_dto(row: &QueryResult) -> GuestRow
Projects one SeaORM query row into a GuestRow (integration tests).
pub async fn set_connection(conn: DatabaseConnection)
Store the opened engine connection for subsequent ping/query/execute calls.
conn- Opened SeaORM database connection for this guest process.
pub fn guest_sql(sql: impl Into<String>) -> GuestStatement
Builds a GuestStatement for plain SQL without binds.
Generated from crates/bookclerk-db-guest at main · View as Markdown