sqlx-testcontainers

sqlx-testcontainers is a Rust library that simplifies integration testing with sqlx and testcontainers-rs. It provides a procedural macro #[sqlx_testcontainers::test] that automatically:

Starts a temporary PostgreSQL container using Testcontainers.
Connects to the container and runs your database migrations.
Provides an active sqlx::PgConnection directly to your test function.
Cleans up the container after the test finishes.

Features

Zero-Config Database Tests: No need to manually manage database instances or connection strings for tests.
Automatic Migrations: Uses sqlx::migrate!() to ensure your test database schema is up-to-date.
Isolated Environments: Every test gets its own fresh container, ensuring no cross-test interference.
Customizable Images: Easily specify PostgreSQL versions/tags.

Installation

Add this to your Cargo.toml:

[dependencies]
sqlx-testcontainers = { git = "https://github.com/anthonysuper/sqlx-testcontainers" }
sqlx = { version = "0.8", features = ["postgres", "runtime-tokio-rustls", "migrate"] }
tokio = { version = "1", features = ["full"] }

Usage

Simply replace #[tokio::test] with #[sqlx_testcontainers::test] and add a PgConnection argument to your test function.

use sqlx::Row;

#[sqlx_testcontainers::test]
async fn test_basic_query(mut conn: sqlx::postgres::PgConnection) {
    let row: (i32,) = sqlx::query_as("SELECT 1 + 1")
        .fetch_one(&mut conn)
        .await
        .expect("Failed to execute query");

    assert_eq!(row.0, 2);
}

#[sqlx_testcontainers::test(tag = "15-alpine")]
async fn test_with_specific_version(mut conn: sqlx::postgres::PgConnection) {
    let row: (String,) = sqlx::query_as("SELECT version()")
        .fetch_one(&mut conn)
        .await
        .expect("Failed to execute query");

    assert!(row.0.contains("PostgreSQL 15"));
}

#[sqlx_testcontainers::test(migrations = "custom_migrations")]
async fn test_with_custom_migrations(mut conn: sqlx::postgres::PgConnection) {
    // This will use the migrations folder at "custom_migrations"
}

Requirements

Docker: Since this uses Testcontainers, you must have Docker (or a compatible container runtime) installed and running in your environment.
SQLx Migrations: By default, it looks for a migrations/ folder in your project root to apply to the test database.

License