Struct ClusterGuard 

pub struct ClusterGuard { /* private fields */ }

Lifecycle guard for a running PostgreSQL cluster.

This guard manages cluster shutdown and environment restoration. It is intentionally !Send to ensure thread-local environment state is handled correctly.

Obtaining a Guard

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)

// When guard drops, cluster shuts down and environment is restored

Shared Cluster Pattern

For shared clusters that should run for the entire process lifetime, the guard must be explicitly forgotten to prevent shutdown on drop. Use std::mem::forget to keep the cluster running:

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

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

fn shared_handle() -> &'static ClusterHandle {
    SHARED.get_or_init(|| {
        let (handle, guard) = TestCluster::new_split()
            .expect("cluster bootstrap failed");
        // Forget the guard to prevent shutdown - cluster runs for process lifetime
        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.

Implementations

impl ClusterGuard

pub fn with_worker_guard(self, worker_guard: Option<ScopedEnv>) -> Self

Extends the guard to cover an additional scoped environment.

Primarily used by fixtures that need to ensure PG_EMBEDDED_WORKER remains set for the duration of the cluster lifetime.

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

Overrides the cleanup mode used when the guard is dropped.

Examples

use pg_embedded_setup_unpriv::{CleanupMode, TestCluster};

let (handle, guard) = TestCluster::new_split()?;
let guard = guard.with_cleanup_mode(CleanupMode::None);

Trait Implementations

impl Debug for ClusterGuard

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

Formats the value using the given formatter.

impl Drop for ClusterGuard

fn drop(&mut self)

Executes the destructor for this type.