Struct TestCluster 

pub struct TestCluster { /* private fields */ }

Embedded PostgreSQL instance whose lifecycle follows Rust’s drop semantics.

TestCluster combines a ClusterHandle (for cluster access) with a ClusterGuard (for lifecycle management). For most use cases, this combined type is the simplest option.

Send-Safe Patterns

TestCluster is !Send because it contains environment guards that must be dropped on the creating thread. For patterns requiring Send (such as OnceLock or rstest timeouts), use new_split() to obtain a Send-safe ClusterHandle:

use std::sync::OnceLock;
use pg_embedded_setup_unpriv::{ClusterHandle, TestCluster};

static SHARED: OnceLock<ClusterHandle> = OnceLock::new();

fn shared_cluster() -> &'static ClusterHandle {
    SHARED.get_or_init(|| {
        let (handle, guard) = TestCluster::new_split()
            .expect("cluster bootstrap failed");
        // Forget the guard to prevent shutdown on drop
        std::mem::forget(guard);
        handle
    })
}

Implementations

impl TestCluster

pub fn with_cleanup_mode(self, cleanup_mode: CleanupMode) -> Self

Overrides the cleanup mode used when the cluster is dropped.

Examples

use pg_embedded_setup_unpriv::{CleanupMode, TestCluster};

let cluster = TestCluster::new()?.with_cleanup_mode(CleanupMode::Full);

impl TestCluster

pub fn create_database( &self, name: impl Into<DatabaseName>, ) -> BootstrapResult<()>

Creates a new database with the given name.

Delegates to crate::TestClusterConnection::create_database.

Errors

Returns an error if the database already exists or if the connection fails.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;
cluster.create_database("my_test_db")?;

pub fn create_database_from_template( &self, name: impl Into<DatabaseName>, template: impl Into<DatabaseName>, ) -> BootstrapResult<()>

Creates a new database by cloning an existing template.

Delegates to crate::TestClusterConnection::create_database_from_template.

Errors

Returns an error if the target database already exists, the template does not exist, the template has active connections, or if the connection fails.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;
cluster.create_database("my_template")?;
// ... run migrations on my_template ...
cluster.create_database_from_template("test_db", "my_template")?;

pub fn drop_database( &self, name: impl Into<DatabaseName>, ) -> BootstrapResult<()>

Drops an existing database.

Delegates to crate::TestClusterConnection::drop_database.

Errors

Returns an error if the database does not exist, has active connections, or if the connection fails.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;
cluster.create_database("temp_db")?;
cluster.drop_database("temp_db")?;

pub fn database_exists( &self, name: impl Into<DatabaseName>, ) -> BootstrapResult<bool>

Checks whether a database with the given name exists.

Delegates to crate::TestClusterConnection::database_exists.

Errors

Returns an error if the connection fails.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;
assert!(cluster.database_exists("postgres")?);
assert!(!cluster.database_exists("nonexistent")?);

pub fn ensure_template_exists<F>( &self, name: impl Into<DatabaseName>, setup_fn: F, ) -> BootstrapResult<()>

where F: FnOnce(&str) -> BootstrapResult<()>,

Ensures a template database exists, creating it if necessary.

Delegates to crate::TestClusterConnection::ensure_template_exists.

Errors

Returns an error if database creation fails or if setup_fn returns an error.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;

// Ensure template exists, running migrations if needed
cluster.ensure_template_exists("my_template", |db_name| {
    // Run migrations on the newly created template database
    Ok(())
})?;

// Clone the template for each test
cluster.create_database_from_template("test_db_1", "my_template")?;

pub fn temporary_database( &self, name: impl Into<DatabaseName>, ) -> BootstrapResult<TemporaryDatabase>

Creates a temporary database that is dropped when the guard is dropped.

Delegates to crate::TestClusterConnection::temporary_database.

Errors

Returns an error if the database already exists or if the connection fails.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;
let temp_db = cluster.temporary_database("my_temp_db")?;

// Database is dropped automatically when temp_db goes out of scope

pub fn temporary_database_from_template( &self, name: impl Into<DatabaseName>, template: impl Into<DatabaseName>, ) -> BootstrapResult<TemporaryDatabase>

Creates a temporary database from a template.

Delegates to crate::TestClusterConnection::temporary_database_from_template.

Errors

Returns an error if the target database already exists, the template does not exist, the template has active connections, or if the connection fails.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;
cluster.ensure_template_exists("migrated_template", |_| Ok(()))?;

let temp_db = cluster.temporary_database_from_template("test_db", "migrated_template")?;

// Database is dropped automatically when temp_db goes out of scope

impl TestCluster

pub fn new() -> BootstrapResult<Self>

Boots a PostgreSQL instance configured by bootstrap_for_tests.

The constructor blocks until the underlying server process is running and returns an error when startup fails.

Errors

Returns an error if the bootstrap configuration cannot be prepared or if starting the embedded cluster fails.

pub fn new_split() -> BootstrapResult<(ClusterHandle, ClusterGuard)>

Boots a PostgreSQL instance and returns a separate handle and guard.

This constructor is useful for patterns requiring Send, such as shared cluster fixtures with OnceLock or rstest fixtures with timeouts.

Returns

A tuple of:

• ClusterHandle: Send + Sync handle for accessing the cluster
• ClusterGuard: !Send guard managing shutdown and environment

Errors

Returns an error if the bootstrap configuration cannot be prepared or if starting the embedded cluster fails.

Examples

Shared Cluster with OnceLock

For shared clusters that run for the entire process lifetime, forget the guard to prevent shutdown:

use std::sync::OnceLock;
use pg_embedded_setup_unpriv::{ClusterHandle, TestCluster};

static SHARED: OnceLock<ClusterHandle> = OnceLock::new();

fn shared_cluster() -> &'static ClusterHandle {
    SHARED.get_or_init(|| {
        let (handle, guard) = TestCluster::new_split()
            .expect("cluster bootstrap failed");
        // Forget the guard to prevent shutdown on drop
        std::mem::forget(guard);
        handle
    })
}

Warning: Dropping the guard shuts down the cluster. Do not use the handle after the guard has been dropped unless the guard was forgotten.

Methods from Deref<Target = ClusterHandle>

pub fn settings(&self) -> &Settings

Returns the prepared PostgreSQL settings for the running cluster.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let (handle, _guard) = TestCluster::new_split()?;
let url = handle.settings().url("my_database");

pub fn environment(&self) -> &TestBootstrapEnvironment

Returns the environment required for clients to interact with the cluster.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let (handle, _guard) = TestCluster::new_split()?;
let env = handle.environment();

pub fn bootstrap(&self) -> &TestBootstrapSettings

Returns the bootstrap metadata captured when the cluster was started.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let (handle, _guard) = TestCluster::new_split()?;
let bootstrap = handle.bootstrap();

pub fn connection(&self) -> TestClusterConnection

Returns helper methods for constructing connection artefacts.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let (handle, _guard) = TestCluster::new_split()?;
let metadata = handle.connection().metadata();
println!(
    "postgresql://{}:***@{}:{}/postgres",
    metadata.superuser(),
    metadata.host(),
    metadata.port(),
);

pub fn create_database( &self, name: impl Into<DatabaseName>, ) -> BootstrapResult<()>

Creates a new database with the given name.

See TestClusterConnection::create_database for details.

Errors

Returns an error if the database already exists or if the connection fails.

pub fn create_database_from_template( &self, name: impl Into<DatabaseName>, template: impl Into<DatabaseName>, ) -> BootstrapResult<()>

Creates a new database by cloning an existing template.

See TestClusterConnection::create_database_from_template for details.

Errors

Returns an error if the target database already exists, the template does not exist, or the connection fails.

pub fn drop_database( &self, name: impl Into<DatabaseName>, ) -> BootstrapResult<()>

Drops an existing database.

See TestClusterConnection::drop_database for details.

Errors

Returns an error if the database does not exist or the connection fails.

pub fn database_exists( &self, name: impl Into<DatabaseName>, ) -> BootstrapResult<bool>

Checks whether a database with the given name exists.

See TestClusterConnection::database_exists for details.

Errors

Returns an error if the connection fails.

pub fn ensure_template_exists<F>( &self, name: impl Into<DatabaseName>, setup_fn: F, ) -> BootstrapResult<()>

where F: FnOnce(&str) -> BootstrapResult<()>,

Ensures a template database exists, creating it if necessary.

See TestClusterConnection::ensure_template_exists for details.

Errors

Returns an error if database creation fails or if setup_fn returns an error.

pub fn temporary_database( &self, name: impl Into<DatabaseName>, ) -> BootstrapResult<TemporaryDatabase>

Creates a temporary database that is dropped when the guard is dropped.

See TestClusterConnection::temporary_database for details.

Errors

Returns an error if the database already exists or the connection fails.

pub fn temporary_database_from_template( &self, name: impl Into<DatabaseName>, template: impl Into<DatabaseName>, ) -> BootstrapResult<TemporaryDatabase>

Creates a temporary database from a template.

See TestClusterConnection::temporary_database_from_template for details.

Errors

Returns an error if the target database already exists, the template does not exist, or the connection fails.

Trait Implementations

impl Debug for TestCluster

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for TestCluster

Provides transparent access to ClusterHandle methods.

This allows TestCluster to be used interchangeably with ClusterHandle for all read-only operations like settings(), connection(), etc.

type Target = ClusterHandle

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.