Crate quex

Expand description

Async SQL access for mariadb, mysql, postgres, and sqlite.

quex is a small facade over quex_driver. It gives you one API for:

opening one connection or a pool
running SQL directly
binding positional parameters
decoding rows into your own types

It stays close to SQL. This crate does not try to hide queries behind an orm or query builder.

The main entry points are:

Pool for many short-lived checked-out connections
Connection for one connection
query for one-off SQL
prepare for a reusable prepared statement
Hooks when a pool needs connection setup or validation
Executor when you want generic code that works with any supported executor type
Encode for binding your own parameter types
FromRow, FromRowRef, and Decode for mapping rows into your own types

query and prepare use ? placeholders for every driver. When the driver is postgres, quex rewrites them to $1, $2, and so on before sending the SQL to libpq.

A small sqlite example:

use quex::{FromRow, Pool, Row, SqliteConnectOptions};

struct User {
    id: i64,
    name: String,
}

impl FromRow for User {
    fn from_row(row: &Row) -> quex::Result<Self> {
        Ok(Self {
            id: row.get("id")?,
            name: row.get("name")?,
        })
    }
}

let pool = Pool::connect(SqliteConnectOptions::new().in_memory())?
    .max_size(4)
    .build()
    .await?;
let mut db = pool.acquire().await?;

quex::query("create table users(id integer primary key, name text not null)")
    .execute(&mut db)
    .await?;

quex::query("insert into users(name) values(?)")
    .bind("Ada")
    .execute(&mut db)
    .await?;

let users = quex::query("select id, name from users order by id")
    .all::<User>(&mut db)
    .await?;

When you already have a Pool, the high-level query helpers can run directly against it:

let pool = Pool::connect(SqliteConnectOptions::new().in_memory())?
    .max_size(4)
    .build()
    .await?;

let ids: Vec<i64> = quex::query("select id from users order by id")
    .all(&pool)
    .await?;

A few things matter when using the crate:

Borrowed rows only live until the stream advances. If you need to keep data longer, decode into owned types or collect owned rows.
Query::one and Query::optional ignore extra rows.
A PoolTransaction holds one checked-out connection until commit, rollback, or drop.
Pool::with_hooks can run setup on fresh connections and validate a connection before it is handed out.
Pool is the better default when many tasks need database access. Connection is the simpler single-connection option.
Postgres LISTEN/NOTIFY works on Connection and PooledConnection. Keep one checked-out connection dedicated to waiting for notifications.

Optional features add support for common value types:

mysql enables mysql and mariadb support
postgres enables postgres support
sqlite enables sqlite support
chrono for chrono date and time types
time for time crate types
uuid for uuid::Uuid
json for serde_json::Value

Setup depends on the driver you use. quex_driver talks to libpq, libmariadb, and sqlite3 through ffi, so those client libraries need to be available for your target environment. No database backend is enabled by default, so pick the ones you need in your Cargo.toml.

Structs§

BoundStatement: A prepared statement plus parameters collected through .bind(...).
Column: Metadata for one result column.
ConnectOptions: Connection settings parsed from a URL or built manually.
Connection: A simple handle for one database connection.
Date: A calendar date.
DateTime: A date and time without a timezone offset.
DateTimeTz: A date and time with a fixed offset.
Decoder: Reads one SQL column value for Decode.
Encoder: Encodes one application value into a SQL parameter sink.
ExecResult: The outcome of an insert, update, delete, or other statement that does not return rows.
Hooks: Optional pool hooks.
MysqlConnectOptions: mysql or mariadb connection settings.
Params: An owned list of positional parameters.
Pool: A cloneable pool of database connections.
PoolBuilder: Builder for Pool.
PoolStatement: A statement that belongs to a pool.
PoolTransaction: A transaction started from a Pool.
PooledConnection: A connection checked out from a Pool.
PooledStatement: A statement prepared on a checked-out connection.
PooledTransaction: A transaction borrowed from a PooledConnection.
PostgresConnectOptions: postgres connection settings.
Prepare: A request to prepare SQL against an executor.
Query: A query with optional bound parameters.
Row: A row whose column metadata and values are owned by Rust.
RowRef: A borrowed row from a result stream.
Rows: A forward-only stream of rows returned by a query.
SqliteConnectOptions: sqlite connection settings.
Time: A time of day with microsecond precision.
Transaction: A transaction on a Connection connection.

Enums§

AcquireDecision: Decides what the pool should do with a connection after before_acquire.
ColumnType: Driver-specific column type metadata.
Driver: The database driver selected for a connection or pool.
Error: Errors returned by the facade.
ParamRef: A borrowed SQL parameter value.
ParamValue: A value borrowed or owned long enough to bind to a prepared statement.
Statement: A driver-specific prepared statement behind the facade.
Value: An owned database value.

Traits§

ColumnIndex: A column lookup accepted by row accessors.
Decode: Decodes a single SQL value into an application type.
Encode: Converts application values into SQL parameters.
EncodeTarget
Executor: Something that can run SQL.
FromColumnRef: Decodes one column directly from a borrowed row.
FromRow: Decodes an owned row into an application type.
FromRowRef: Decodes a borrowed row without first collecting it into an owned row.
IntoConnectOptions: Converts a value into generic connection options.
ParamSource: A borrowed source of positional SQL parameters.
PreparedStatement: A prepared statement that can be run with borrowed parameters.
RowStream: A forward-only stream of result rows.

Functions§

prepare: Starts a prepared-statement builder.
query: Starts a query.

Type Aliases§

Result: Convenient result type used by quex.

Crate quex

Crate quex Copy item path

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate quex