Struct TestClusterConnection 

pub struct TestClusterConnection { /* private fields */ }

Accessor for connection helpers derived from a TestCluster.

Enable the diesel-support feature to call the Diesel connection helper.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;
let url = cluster.connection().database_url("postgres");
assert!(url.contains("postgresql://"));

Implementations

impl TestClusterConnection

pub fn host(&self) -> &str

Returns host metadata without exposing internal storage.

pub const fn port(&self) -> u16

Returns the configured port.

pub fn superuser(&self) -> &str

Returns the configured superuser account name.

pub fn password(&self) -> &str

Returns the generated password for the superuser.

pub fn pgpass_file(&self) -> &Utf8Path

Returns the .pgpass file prepared during bootstrap.

pub fn metadata(&self) -> ConnectionMetadata

Provides an owned snapshot of the connection metadata.

pub fn database_url(&self, database: &str) -> String

Builds a libpq-compatible database URL for database.

impl TestClusterConnection

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

Creates a new database with the given name.

Connects to the postgres database as superuser and executes 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.connection().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.

Connects to the postgres database as superuser and executes CREATE DATABASE ... TEMPLATE. This is significantly faster than creating an empty database and running migrations, as PostgreSQL performs a filesystem-level copy.

Errors

Returns an error if:

• The target database already exists
• The template database does not exist
• The template database has active connections
• The connection fails

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;

// Create and set up a template database
cluster.connection().create_database("my_template")?;
// ... run migrations on my_template ...

// Clone the template for a test
cluster.connection().create_database_from_template("test_db", "my_template")?;

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

Drops an existing database.

Connects to the postgres database as superuser and executes 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.connection().create_database("temp_db")?;
cluster.connection().drop_database("temp_db")?;

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

Checks whether a database with the given name exists.

Errors

Returns an error if the connection fails.

Examples

use pg_embedded_setup_unpriv::TestCluster;

let cluster = TestCluster::new()?;
assert!(cluster.connection().database_exists("postgres")?);
assert!(!cluster.connection().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.

Uses per-template locking to prevent concurrent creation attempts when multiple tests race to initialise the same template. The setup_fn is called only if the template does not already exist.

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.connection().ensure_template_exists("my_template", |db_name| {
    // Run migrations on the newly created template database
    // e.g., diesel::migration::run(&mut conn)?;
    Ok(())
})?;

// Clone the template for each test
cluster.connection().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.

This is useful for test isolation where each test creates its own database and the database is automatically cleaned up when the test completes.

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.connection().temporary_database("my_temp_db")?;

// Database is dropped automatically when temp_db goes out of scope
let url = temp_db.url();

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

Creates a temporary database from a template.

Combines template cloning with RAII cleanup. The database is created by cloning the template and is automatically dropped when the guard goes out of scope.

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()?;

// Create and migrate a template once
cluster.ensure_template_exists("migrated_template", |_| Ok(()))?;

// Each test gets its own database cloned from the template
let temp_db = cluster.connection()
    .temporary_database_from_template("test_db", "migrated_template")?;

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

Trait Implementations

impl Clone for TestClusterConnection

fn clone(&self) -> TestClusterConnection

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TestClusterConnection

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

Formats the value using the given formatter.