Struct ClusterHandle 

pub struct ClusterHandle { /* private fields */ }

Send-safe handle providing read-only access to a running PostgreSQL cluster.

Handles are lightweight and cloneable. They contain only the bootstrap metadata needed to construct connections and query cluster state.

Thread Safety

ClusterHandle implements Send and Sync, making it safe to share across threads. The underlying PostgreSQL process is an external OS process that handles concurrent connections safely.

Obtaining a Handle

Use TestCluster::new_split() to obtain a handle and guard pair:

use pg_embedded_setup_unpriv::TestCluster;

let (handle, guard) = TestCluster::new_split()?;
// handle: ClusterHandle (Send + Sync)
// guard: ClusterGuard (!Send, manages lifecycle)

Implementations

impl ClusterHandle

pub const 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 const 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 const 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(),
);

impl ClusterHandle

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 Clone for ClusterHandle

fn clone(&self) -> ClusterHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClusterHandle

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

Formats the value using the given formatter.

impl From<TestBootstrapSettings> for ClusterHandle

fn from(bootstrap: TestBootstrapSettings) -> Self

Converts to this type from the input type.