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 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.

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

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.

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.