Struct PgAccess 

pub struct PgAccess {
    pub cache_dir: PathBuf,
    pub database_dir: PathBuf,
    pub pg_ctl_exe: PathBuf,
    pub init_db_exe: PathBuf,
    pub pw_file_path: PathBuf,
    pub zip_file_path: PathBuf,
    /* private fields */
}

Manages all file-system paths and I/O operations for a single pg-embed instance.

Created by PgAccess::new, which also creates the required directory structure. All path fields are derived from the fetch settings and the caller-supplied database directory.

Cache layout

{cache_dir}/pg-embed/{os}/{arch}/{version}/
  bin/pg_ctl
  bin/initdb
  {platform}-{version}.zip

Fields

cache_dir: PathBuf

Root of the per-version binary cache.

database_dir: PathBuf

Directory that holds the PostgreSQL cluster data files.

pg_ctl_exe: PathBuf

Path to the pg_ctl executable inside the cache.

init_db_exe: PathBuf

Path to the initdb executable inside the cache.

pw_file_path: PathBuf

Path to the password file used by initdb.

zip_file_path: PathBuf

Path where the downloaded JAR is written before unpacking.

Implementations

impl PgAccess

pub async fn new( fetch_settings: &PgFetchSettings, database_dir: &Path, ) -> Result<Self>

Creates a new PgAccess and ensures the required directories exist.

Both the per-version binary cache directory and database_dir are created with tokio::fs::create_dir_all if they do not already exist.

Arguments

• fetch_settings — Determines the OS, architecture, and version used to construct the cache path.
• database_dir — Where the PostgreSQL cluster data files will live.

Errors

Returns Error::InvalidPgUrl if the OS cache directory cannot be resolved. Returns Error::DirCreationError if either directory cannot be created.

pub async fn maybe_acquire_postgres(&self) -> Result<()>

Downloads and unpacks the PostgreSQL binaries if they are not already cached.

Acquires the ACQUIRED_PG_BINS lock for the duration. If another instance already cached the binaries (i.e. Self::pg_executables_cached returns true), this method returns immediately without downloading.

Errors

Returns Error::DirCreationError if directories cannot be created. Returns Error::DownloadFailure or Error::ConversionFailure if the HTTP download fails. Returns Error::WriteFileError if the JAR cannot be written to disk. Returns Error::UnpackFailure or Error::InvalidPgPackage if extraction fails.

pub async fn pg_executables_cached(&self) -> Result<bool>

Returns true if the initdb executable is present in the cache.

Errors

Returns Error::ReadFileError if the filesystem existence check fails.

pub async fn db_files_exist(&self) -> Result<bool>

Returns true if both the executables and the cluster version file exist.

A true result indicates the cluster was previously initialised with initdb and does not need to be re-initialised.

Errors

Returns Error::ReadFileError if either filesystem check fails.

pub async fn pg_version_file_exists(db_dir: &Path) -> Result<bool>

Returns true if the PG_VERSION file exists inside db_dir.

Useful for confirming that a cluster directory is non-empty without holding a PgAccess instance.

Arguments

• db_dir — The cluster data directory to inspect.

Errors

Returns Error::ReadFileError if the filesystem check fails.

pub async fn acquisition_status(&self) -> PgAcquisitionStatus

Returns the current acquisition status for this instance’s cache directory.

pub fn clean(&self) -> Result<()>

Removes the database cluster directory and the password file.

Both removals are attempted even if the first one fails; the first error encountered is returned. Called synchronously from crate::postgres::PgEmbed’s Drop implementation.

Errors

Returns Error::PgCleanUpFailure if either removal fails.

pub async fn purge() -> Result<()>

Removes the entire pg-embed binary cache directory.

Useful for freeing disk space or forcing a fresh download. Errors during removal are silently ignored (the function always returns Ok).

Errors

Returns Error::ReadFileError if the OS cache directory cannot be resolved.

pub async fn clean_up(database_dir: PathBuf, pw_file: PathBuf) -> Result<()>

Removes database_dir and pw_file asynchronously.

Unlike Self::clean, this is an async free-standing helper and stops on the first error.

Arguments

• database_dir — The cluster data directory to remove.
• pw_file — The password file to remove.

Errors

Returns Error::PgCleanUpFailure if either removal fails.

pub async fn create_password_file(&self, password: &[u8]) -> Result<()>

Writes password bytes to Self::pw_file_path.

initdb reads this file via --pwfile to set the superuser password without exposing it on the command line.

Arguments

• password — The password bytes to write (UTF-8 text is expected but not enforced).

Errors

Returns Error::WriteFileError if the file cannot be created or the write fails.

pub async fn install_extension(&self, extension_dir: &Path) -> Result<()>

pub fn stop_db_command_sync(&self, database_dir: &Path) -> PgCommandSync

Builds a synchronous pg_ctl stop std::process::Command.

Uses OsStr arguments throughout to avoid UTF-8 conversion failures on platforms with non-Unicode paths. The returned PgCommandSync is ready to be spawned but has not yet been started.

Arguments

• database_dir — Passed as the -D argument to pg_ctl stop.