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(¶ms).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
Readerexecution. - sync
- Native synchronous counterparts to the asynchronous traits.
Structs§
- Buffered
Reader - 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.
- Execute
Options - Statement execution options.
- Invalid
Retry Policy - Retry configuration was invalid.
- Parameter
- A positional parameter whose value must match its declared type exactly.
- Policy
Pool - Policy and telemetry decorator for pool, session, transaction, and script operations.
- Pool
Defaults - Defaults supplied by a pool for operations that inherit.
- Pool
Policy - Pool-level defaults for telemetry, SQL capture, and retry support.
- Query
Options - Owned parameters and policy overrides for one pool, session, transaction, or script operation.
- Retry
Runtime - 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.
- Sqlite
Policy Pool - 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.
- Error
Kind - Stable, sanitized error category. No driver message or query data is retained.
- Invalid
Argument Reason - Static, safe explanation for invalid caller-supplied arguments.
- Isolation
Level - Portable transaction isolation level.
- Limit
Setting - Bounded fetch limit override. There is deliberately no unbounded variant.
- Operation
- Fixed-cardinality operation name; SQL is never used as a metric label.
- Query
Setting - Per-query inherit/off/on setting for telemetry or SQL capture.
- Replay
Safety - Whether a standalone pool operation may use the configured retry policy.
- Retry
Policy - Pool retry configuration backed by
neotales-resilience. - Retry
Setting - Per-operation retry configuration override.
- Telemetry
Outcome - Sanitized operation outcome used by the optional observer.
- Timeout
Setting - Tri-state timeout override.
Inherituses the pool default;Disabledexplicitly requests no timeout;Setreplaces the pool default for this operation. - Value
- A supported, owned parameter or cell value.
Traits§
- From
Value - Exact typed conversion from a row value;
Option<T>represents a matching typed SQL null. - Immediate
Transaction - 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.
- Sqlite
Pool - 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
Sendboxed future returning a sanitized database result. - DbObserver
- Optional per-pool observer.
- Retry
Wait - A boxed sendable caller-owned timer or sleeper future.
- SqlCapture
Hook - Optional SQL-only hook. Returning
Nonesuppresses SQL text; returning a string replaces it.