Skip to main content

Crate neotales_dbapi

Crate neotales_dbapi 

Source
Expand description

Driver-neutral async SQL execution and detached, bounded row access.

This crate deliberately provides no query builder, ORM, runtime, or driver. A provider owns connection acquisition, type conversion, transaction behavior, and cleanup. All operations use boxed Send futures so the traits are object safe. This contract cannot directly wrap browser APIs whose futures are !Send (for example, D1 Workers bindings). The local module mirrors these traits without a Send future bound for that case; it is a local-thread API, not a thread-transfer grant.

The sync module provides runtime-neutral synchronous counterparts that reuse the same rows, limits, options, and errors. The optional blocking feature adds blocking::BlockingPool, which drives an asynchronous pool on dedicated worker threads for callers that cannot await. The blocking feature is not supported on wasm32. Async or local traits may be used with providers that support them, but D1’s local DBAPI operations currently fail closed.

§Example

use neotales_dbapi::{DbType, Parameter, Pool, QueryOptions, RowLimit};

let mut session = pool.acquire_async().await?;
let params = [Parameter::new(DbType::I64, neotales_dbapi::Value::I64(7))?];
// SQLite uses `?`; PostgreSQL uses `$1`. The provider does not rewrite SQL.
let mut reader = session.fetch_async("SELECT name FROM users WHERE id = ?",
    QueryOptions::new().bind_all(&params).limit(RowLimit::new(10, 4096)?)).await?;
while let Some(row) = reader.next_row_async().await? {
    if let Some(name) = row.read::<Option<String>>("name")? {
        println!("{name}");
    }
}
reader.finish_async().await?;

A reader owns one statement’s result sets until it is finished or dropped. next_row_async yields rows from the current set. has_next_set_async advances, discarding any unread rows in the current set, and reports whether another set exists. finish_async drains and discards the full batch so a later statement error is not hidden. A provider with unread results still attached must discard the connection when a reader is dropped; a provider that materializes the bounded batch before returning may already have made the connection reusable.

The paging module adds page and row views over one existing reader. It dispatches no SQL and does not change the reader’s parameters, telemetry, or bounded RowLimit; the page view exposes result-set boundaries, including empty sets. Its paging::multi submodule adds explicit multi-request paging where a caller-implemented source owns each request, continuation, and keyset/offset logic. local::paging mirrors both for !Send local futures, and sync::paging provides native blocking iterators over the synchronous reader.

Native positional placeholder syntax is preserved (SQL is never rewritten):

use neotales_dbapi::{DbType, Parameter, Value};
let sqlite_sql = "SELECT name FROM users WHERE id = ?";
let sqlite_parameters = [Parameter::new(DbType::I64, Value::I64(7))?];
let postgres_sql = "SELECT name FROM users WHERE id = $1 AND active = $2";
let postgres_parameters = [
    Parameter::new(DbType::I64, Value::I64(7))?,
    Parameter::new(DbType::Bool, Value::Bool(true))?,
];

Modules§

local
Local-future counterparts to the asynchronous traits.
paging
Paged views over one existing Reader execution.
sync
Native synchronous counterparts to the asynchronous traits.

Structs§

BufferedReader
A reader over an already-materialized batch, preserving result-set boundaries.
Cancellation
A flag the caller sets to cancel an execution.
Capabilities
Reported provider capabilities; true means the operation is supported as described.
DbError
Sanitized database error with a stable category and no source payload.
DbEvent
Safe telemetry event: no parameters, rows, results, driver text, or connection information.
ExecuteOptions
Statement execution options.
InvalidRetryPolicy
Retry configuration was invalid.
Parameter
A positional parameter whose value must match its declared type exactly.
PolicyPool
Policy and telemetry decorator for pool, session, transaction, and script operations.
PoolDefaults
Defaults supplied by a pool for operations that inherit.
PoolPolicy
Pool-level defaults for telemetry, SQL capture, and retry support.
QueryOptions
Owned parameters and policy overrides for one pool, session, transaction, or script operation.
RetryRuntime
Caller-provided timer, backoff sleeper, cancellation flag, and random source for retries.
Row
A detached row of owned values in ordinal order with provider-supplied names.
RowLimit
Hard maximums for detached fetch results.
SqlitePolicyPool
Policy decorator that retains a pool’s SQLite immediate-transaction capability.
TxOptions
Portable transaction options; omitted values retain provider-defined defaults.

Enums§

DbType
SQL logical type used to define typed null parameters and expected row values.
Delay
How a retry policy spaces its waits.
ErrorKind
Stable, sanitized error category. No driver message or query data is retained.
InvalidArgumentReason
Static, safe explanation for invalid caller-supplied arguments.
IsolationLevel
Portable transaction isolation level.
LimitSetting
Bounded fetch limit override. There is deliberately no unbounded variant.
Operation
Fixed-cardinality operation name; SQL is never used as a metric label.
QuerySetting
Per-query inherit/off/on setting for telemetry or SQL capture.
ReplaySafety
Whether a standalone pool operation may use the configured retry policy.
RetryPolicy
Pool retry configuration backed by neotales-resilience.
RetrySetting
Per-operation retry configuration override.
TelemetryOutcome
Sanitized operation outcome used by the optional observer.
TimeoutSetting
Tri-state timeout override. Inherit uses the pool default; Disabled explicitly requests no timeout; Set replaces the pool default for this operation.
Value
A supported, owned parameter or cell value.

Traits§

FromValue
Exact typed conversion from a row value; Option<T> represents a matching typed SQL null.
ImmediateTransaction
Optional provider extension for SQLite-style immediate transaction starts without leaking driver types.
Pool
A pool able to acquire exclusive sessions and report truthful capabilities.
Reader
A statement’s bounded result sets, consumed row by row.
Session
An exclusively borrowed database session.
SqlitePool
SQLite-specific pool capabilities shared by SQLite consumers without exposing a driver.
Transaction
A transaction that exclusively borrows its session until consumed or dropped.

Type Aliases§

DbFuture
A Send boxed future returning a sanitized database result.
DbObserver
Optional per-pool observer.
RetryWait
A boxed sendable caller-owned timer or sleeper future.
SqlCaptureHook
Optional SQL-only hook. Returning None suppresses SQL text; returning a string replaces it.