Crate turso_orm_driver

Expand description

Execution layer: connection pool, transactions and typed rows for Turso.

This crate is the execution layer of turso-orm. It wraps the turso client in a small connection pool and gives the layers above a uniform way to run a Statement — on the pooled handle or inside a transaction — and to read the rows back by the Rust type they want. It owns everything that touches a live connection: opening, pooling, per-connection pragmas, transactions and savepoints, statement execution, streaming, value decoding and error classification. It deliberately does not own SQL generation, which is turso-sql’s job, nor entity mapping, which is turso-orm’s.

§Design

The pool hands out connections created with db.connect(), one per slot, and never multiplies a slot by cloning a turso::Connection: clones share one engine connection and would serialise on it. A connection goes back to the idle list only when it is in autocommit mode, so a transaction that was dropped mid-way can never leak into the next borrower.
A Transaction pins one pooled connection for its whole life. Nested transactions are SAVEPOINTs on that same connection. Because Drop cannot await, rolling back a dropped transaction is deferred: a top-level one discards its connection, a nested one records its depth and the rollback runs before the parent’s next statement.
Rows keep their storage class and are decoded on access through FromValue, with SQLite-style leniency — integers become booleans, text parses into dates and UUIDs — so the same column can be read as whatever the caller asks for.
turso::Error carries only strings for most variants, so ErrorKind is derived by variant and, for MVCC conflicts, by message.

§Example

use turso_orm_driver::{ConnectOptions, ConnectionTrait, Database};
use turso_sql::Statement;

let db = Database::connect(ConnectOptions::new("app.db")).await?;
db.execute_unprepared("CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY, n TEXT)").await?;
let row = db.query_one(Statement::from_string("SELECT COUNT(*) AS n FROM t")).await?;
let count: i64 = row.expect("one row").get("n")?;

Re-exports§

pub use turso;
pub use turso_sql;

Structs§

ConnectOptions: The options for opening a Turso database.
Database: A Turso database with a pool of connections.
Encryption: The encryption-at-rest settings — experimental in Turso.
ExecResult: The result of a statement that does not return rows.
Experimental: Turso engine features that are opt-in because they are still experimental.
RemoteOptionsserverless: The settings of a remote Turso Cloud database.
Row: A result row.
Statement: A rendered statement: SQL with ? placeholders and the values to bind.
SyncOptionssync: The settings of an embedded replica synchronised with Turso Cloud.
Transaction: A transaction on one Turso connection.

Enums§

ConstraintKind: Which constraint a statement violated.
Error: The crate’s error type.
ErrorKind: The classification of an Error.
Source: Where the database lives.
TransactionMode: How a top-level transaction is started.
Value: A bound parameter or literal.

Traits§

ConnectionTrait: Executes statements and fetches rows.
FromValue: Types that can be read out of a result column.
StreamTrait: Streams rows lazily.
TransactionTrait: Starts transactions.

Type Aliases§

Result: The crate’s result alias.
RowStream: A boxed, sendable stream of rows.