Struct TestDb 

pub struct TestDb { /* private fields */ }

Available on crate features model-mysql or model-postgres or model-sqlite only.

A database for one test; see the module docs.

Implementations

impl TestDb

pub fn sqlite() -> TestDbBuilder

Available on crate feature model-sqlite only.

A fresh SQLite in-memory database.

pub fn postgres(url: &str) -> TestDbBuilder

Available on crate feature model-postgres only.

The PostgreSQL database at url (postgres://user:password@host/db, sqlx’s URL syntax), each test inside a transaction that’s rolled back.

pub fn mysql(url: &str) -> TestDbBuilder

Available on crate feature model-mysql only.

The MySQL database at url (mysql://user:password@host/db), each test inside a transaction that’s rolled back.

pub fn postgres_from_env() -> Option<TestDbBuilder>

Available on crate feature model-postgres only.

TestDb::postgres with the URL in RWS_TEST_POSTGRES_URL; None (after printing that the test is skipped) when it isn’t set, so a test can return early on a machine without the server:

use rust_web_server::test_client::TestDb;

let Some(db) = TestDb::postgres_from_env() else { return Ok(()) };
let db = db.migrations("migrations").await?;

pub fn mysql_from_env() -> Option<TestDbBuilder>

Available on crate feature model-mysql only.

TestDb::mysql with the URL in RWS_TEST_MYSQL_URL; None (after printing that the test is skipped) when it isn’t set.

pub fn pool(&self) -> DbPool

A clone of the pool (cheap: same connections, same database), for the app’s state.

pub fn backend(&self) -> Backend

Which backend this database is.

pub fn is_transactional(&self) -> bool

true for PostgreSQL / MySQL, whose writes are rolled back; false for SQLite, whose database is dropped instead.

pub async fn rollback(self) -> Result<(), DbError>

End the test now: roll the transaction back (PostgreSQL, MySQL) and close the pool. Dropping the TestDb does the same without waiting for it; this reports errors.

Methods from Deref<Target = DbPool>

pub async fn schema(&self) -> Result<DbSchema, DbError>

The connected schema’s tables (18.30.0), read from the primary: see db_schema.

pub fn primary(&self) -> &DbPool

The pool writes go to: the primary of a replicated pool, else this pool (18.30.0).

pub fn replica(&self) -> &DbPool

The pool the next read goes to: a replicated pool’s replicas in turn (its primary when it has none), else this pool (18.30.0).

pub fn replicas(&self) -> &[DbPool]

A replicated pool’s replicas; empty for any other (18.30.0).

pub async fn close(&self)

Close the pool — every pool of a replicated one — waiting for the connections in use to be returned (18.30.0).

pub fn backend(&self) -> Backend

Which backend this pool talks to.

pub async fn execute(&self, sql: &str, params: &[Value]) -> Result<u64, DbError>

Execute a SQL statement (INSERT / UPDATE / DELETE / DDL).

Returns the number of rows affected.

pub async fn query_rows( &self, sql: &str, params: &[Value], ) -> Result<Vec<ModelRow>, DbError>

Execute a SQL query and return untyped rows — on a replica when the pool has them.

pub async fn query<T>( &self, sql: &str, params: &[Value], ) -> Result<Vec<T>, DbError>

where T: Model,

Execute a SQL query and deserialise results into T: Model.

pub async fn query_raw( &self, sql: &str, params: &[Value], ) -> Result<Vec<ModelRow>, DbError>

Execute a SQL query returning untyped rows (alias for query_rows).

pub async fn begin(&self) -> Result<DbTransaction, DbError>

Begin a transaction. Call DbTransaction::commit to commit or let it drop to automatically roll back.

pub async fn transaction<F, T, Fut>(&self, f: F) -> Result<T, DbError>

where F: FnOnce(DbTransaction) -> Fut + Send, Fut: Future<Output = Result<T, DbError>> + Send, T: Send,

Run a closure in a transaction.

The closure owns the transaction: call tx.commit() before returning Ok. A transaction that isn’t committed — the closure returns Err, or Ok without committing — is dropped, which rolls it back.

use rust_web_server::model::{DbPool, Value};

let pool = DbPool::memory().await?;
let result = pool.transaction(|mut tx| async move {
    tx.execute("INSERT INTO t (v) VALUES (?)", &[Value::Text("hi".into())]).await?;
    tx.commit().await?;
    Ok(42i32)
}).await?;
assert_eq!(42, result);

pub async fn migrate(&self, dir: &str) -> Result<(), DbError>

Run pending migrations from SQL files in dir.

Files are applied in lexicographic order. Already-applied versions are tracked in a _schema_migrations table (created if absent). Idempotent.

pub async fn migration_status( &self, dir: &str, ) -> Result<Vec<MigrationStatus>, DbError>

Return the status (applied / pending) for each SQL file in dir.

pub async fn rollback_last(&self, dir: &str) -> Result<Option<String>, DbError>

Roll back the most recently applied migration in dir.

Requires a companion <version-stem>.down.sql file next to the up migration it undoes (e.g. 0001_x.sql → 0001_x.down.sql); returns Err if that file is missing. Returns Ok(None) if nothing is currently applied.

pub async fn rollback( &self, dir: &str, n: usize, ) -> Result<Vec<String>, DbError>

Roll back the last n applied migrations, most recently applied first. Returns the versions actually rolled back — fewer than n if fewer than n migrations were applied. Stops at the first missing down file or SQL error; migrations already rolled back in earlier iterations stay rolled back.

pub async fn seed(&self, dir: &str) -> Result<Vec<String>, DbError>

Run the seed files in dir (18.30.0): every *.sql file, in lexicographic order, each in its own transaction (statements split at ;, as migrations). Unlike migrations nothing records that a seed ran — it runs again every time, so write seeds that can (INSERT … ON CONFLICT DO NOTHING on PostgreSQL and SQLite, INSERT IGNORE on MySQL). Answers the files run; stops at the first that fails, whose statements are rolled back.

pub async fn seed_with( &self, dir: &str, seeders: &Seeders, ) -> Result<Vec<String>, DbError>

seed the *.sql files in dir, then run seeders (18.30.0); answers the files and the seeders’ names, in the order they ran. With seeders, a missing dir means no SQL seeds rather than an error.

Trait Implementations

impl Deref for TestDb

type Target = DbPool

The resulting type after dereferencing.

fn deref(&self) -> &DbPool

Dereferences the value.

impl Drop for TestDb

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.