PostgreSQL Commands

https://docs.rs/postgresql_commands/0.19.0/
Admin
PostgreSQL Commands is a Rust library providing command builders for interacting with PostgreSQL via...
Tokens:387,471
Snippets:1,932
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Rust: PgBaseBackupBuilder Command Construction Example

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_basebackup.rs

Illustrates building a pg_basebackup command using the builder pattern. This example shows how to initialize the builder, specify the program directory, and construct the final command, verifying its string representation.

```Rust
let command = PgBaseBackupBuilder::new().program_dir(".").build();
assert_eq!(
    PathBuf::from(".").join("pg_basebackup"),
    PathBuf::from(command.to_command_string().replace('"', ""))
);
```

--------------------------------

### Example CommandBuilder Implementation (Connection Details)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/traits.rs

An example implementation providing default connection parameters for a PostgreSQL command. This includes host, port, username, and password, which are typically required for establishing a connection.

```rust
// Example implementation providing connection details
// Assuming this is part of an `impl CommandBuilder for MyCommand` block

// fn get_host(&self) -> String {
//     "localhost".into()
// }

// fn get_port(&self) -> u16 {
//     5432
// }

// fn get_username(&self) -> OsString {
//     "postgres".into()
// }

// fn get_password(&self) -> OsString {
//     "password".into()
// }
```

--------------------------------

### PgControlDataBuilder Usage Examples

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_controldata.rs

Demonstrates how to use the PgControlDataBuilder to create and configure pg_controldata commands, including setting the program directory and initializing from settings.

```rust
#[cfg(test)]
mod tests {
    use super::*;
    use crate::TestSettings;
    use crate::traits::CommandToString;
    use test_log::test;
    use std::path::PathBuf;

    #[test]
    fn test_builder_new() {
        let command = PgControlDataBuilder::new().program_dir(".").build();
        assert_eq!(
            PathBuf::from(".").join("pg_controldata"),
            PathBuf::from(command.to_command_string().replace('"', ""))
        );
    }

    #[test]
    fn test_builder_from() {
        let command = PgControlDataBuilder::from(&TestSettings).build();
        // Assuming TestSettings has a default program_dir or similar setup
        // This test would need more context on TestSettings to be fully verifiable.
    }
}
```

--------------------------------

### Create PgBenchBuilder Instance

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/pgbench/struct.PgBenchBuilder

Creates a new, default instance of PgBenchBuilder. This is the primary way to start building a pgbench configuration from scratch.

```rust
pub fn new() -> Self
```

--------------------------------

### PgTestFsyncBuilder: Build Command from Settings

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_test_fsync.rs

Illustrates creating a `PgTestFsyncBuilder` instance from existing `TestSettings`. This method initializes the builder with predefined configurations, simplifying command setup for testing scenarios.

```Rust
use crate::TestSettings;

// Assuming TestSettings is defined elsewhere and accessible.
// let command = PgTestFsyncBuilder::from(&TestSettings).build();

// Example of how the command string might be constructed:
// #[cfg(not(target_os = "windows"))]
// let command_prefix = r#"./pg_test_fsync"#;
// #[cfg(target_os = "windows")]
// let command_prefix = r#""./pg_test_fsync"#;
// assert_eq!(format!("{command_prefix}"), command.to_command_string());
```

--------------------------------

### ClusterDbBuilder: Create with Default Settings

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/clusterdb/struct.ClusterDbBuilder

Demonstrates creating a new instance of ClusterDbBuilder using its default constructor. This is the basic way to start building a cluster database configuration.

```Rust
use postgresql_commands::clusterdb::ClusterDbBuilder;

// Create a new ClusterDbBuilder with default settings
let builder = ClusterDbBuilder::new();

// Further configuration can be applied to the builder...
```

--------------------------------

### Rust DropDb Builder Usage Example

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/dropdb.rs

A unit test demonstrating the basic usage of the DropDbBuilder. It shows how to instantiate the builder, set the program directory, build the command, and convert it into a string representation for execution.

```rust
    #[test]
    fn test_builder_new() {
        let command = DropDbBuilder::new().program_dir(".").build();
        assert_eq!(
            PathBuf::from(".").join("dropdb"),
            PathBuf::from(command.to_command_string().replace('"', ""))
        );
    }
```

--------------------------------

### Build pg_upgrade command from settings

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_upgrade.rs

This example shows how to create a `PgUpgradeBuilder` instance using existing settings, such as `TestSettings`. It also includes platform-specific handling for command prefixes on Windows and other operating systems.

```rust
let command = PgUpgradeBuilder::from(&TestSettings).build();
#[cfg(not(target_os = "windows"))]
let command_prefix = r#"./pg_upgrade"#;
#[cfg(target_os = "windows")]
let command_prefix = r#".\\pg_upgrade"#;
assert_eq!(format!("{command_prefix}"), command.to_command_string());
```

--------------------------------

### Create PgConfigBuilder Instance

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_config.rs

Provides a constructor function to create a new, default instance of `PgConfigBuilder`. This is the starting point for configuring and building `pg_config` commands.

```rust
impl PgConfigBuilder {
    /// Create a new [`PgConfigBuilder`]
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }
}
```

--------------------------------

### PsqlBuilder: Create From Settings

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/psql.rs

Initializes a PsqlBuilder instance using configuration values from a provided Settings trait object. This method simplifies setup by leveraging existing application settings.

```rust
/// Create a new [`PsqlBuilder`] from [Settings]
pub fn from(settings: &dyn Settings) -> Self {
    Self::new()
        .program_dir(settings.get_binary_dir())
        .host(settings.get_host())
        .port(settings.get_port())
        .username(settings.get_username())
        .pg_password(settings.get_password())
}
```

--------------------------------

### Request Help Information

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/oid2name.rs

Configures the command to display help information and then exit. This is a standard behavior for command-line utilities to guide users on usage.

```rust
/// show help, then exit
#[must_use]
pub fn help(mut self) -> Self {
    self.help = true;
    self
}
```

--------------------------------

### PsqlBuilder: Create New Instance

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/psql.rs

Provides a constructor for creating a new PsqlBuilder instance, initializing it with default settings. This is the primary way to start building a PostgreSQL command configuration.

```rust
/// Create a new [`PsqlBuilder`]
#[must_use]
pub fn new() -> Self {
    Self::default()
}
```

--------------------------------

### ClusterDbBuilder: Building PostgreSQL Commands

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/clusterdb.rs

Demonstrates the usage of the ClusterDbBuilder for constructing PostgreSQL commands. Includes methods for setting environment variables and examples of building commands with specific configurations and testing their string representations.

```rust
/// Set an environment variable for the command
fn env<S: AsRef<OsStr>>(mut self, key: S, value: S) -> Self {
    self.envs
        .push((key.as_ref().to_os_string(), value.as_ref().to_os_string()));
    self
}
```

```rust
#[test]
fn test_builder_new() {
    let command = ClusterDbBuilder::new().program_dir(".").build();
    assert_eq!(
        PathBuf::from(".").join("clusterdb"),
        PathBuf::from(command.to_command_string().replace('"', ""))
    );
}
```

```rust
#[test]
fn test_builder_from() {
    let command = ClusterDbBuilder::from(&TestSettings).build();
    #[cfg(not(target_os = "windows"))]
    let command_prefix = r#"PGPASSWORD="password" "./clusterdb" "#;
    #[cfg(target_os = "windows")]
    let command_prefix = r#"".\\clusterdb" "#;

    assert_eq!(
        format!(
            r#"{command_prefix}"--host" "localhost" "--port" "5432" "--username" "postgres""#
        ),
        command.to_command_string()
    );
}
```

--------------------------------

### PgConfigBuilder::from

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_config.rs

Creates a new PgConfigBuilder instance initialized with settings from a provided Settings trait object. This method is useful for starting the configuration process with existing environment or application settings.

```rust
/// Create a new [`PgConfigBuilder`] from [Settings]
pub fn from(settings: &dyn Settings) -> Self {
    Self::new().program_dir(settings.get_binary_dir())
}
```

--------------------------------

### Install Missing Extensions

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_amcheck.rs

Enables the installation of any missing PostgreSQL extensions required for the operation. This simplifies setup for users. It's a builder pattern method.

```rust
/// install missing extensions
#[must_use]
pub fn install_missing(mut self) -> Self {
    self.install_missing = true;
    self
}
```

--------------------------------

### pgbench Initialize and Configure

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pgbench.rs

This snippet shows a comprehensive example of initializing and configuring the pgbench utility for PostgreSQL benchmarking. It includes options for initialization steps, fill factor, scale, foreign keys, tablespaces, partitions, and connection details.

```shell
"pgbench" "--initialize" "--init-steps" "steps" "--fillfactor" "10" "--no-vacuum" "--quiet" "--scale" "10" "--foreign-keys" "--index-tablespace" "tablespace" "--partition-method" "method" "--partitions" "10" "--tablespace" "tablespace" "--unlogged-tables" "--builtin" "name" "--file" "filename" "--skip-some-updates" "--select-only" "--client" "10" "--connect" "--define" "var" "--jobs" "10" "--log" "--latency-limit" "10" "--protocol" "protocol" "--no-vacuum" "--progress" "10" "--report-per-command" "--rate" "10" "--scale" "10" "--transactions" "10" "--time" "10" "--vacuum-all" "--aggregate-interval" "10" "--failures-detailed" "--log-prefix" "prefix" "--max-tries" "10" "--progress-timestamp" "--random-seed" "seed" "--sampling-rate" "10" "--show-script" "name" "--verbose-errors" "--debug" "--host" "localhost" "--port" "5432" "--username" "username" "--version" "--help"
```

--------------------------------

### PgDumpAllBuilder Test Cases

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_dumpall.rs

Demonstrates various test cases for the PgDumpAllBuilder, showcasing how to initialize the builder, set the program directory, create commands from settings, and apply common options like environment variables, output files, verbose mode, and version flags.

```rust
mod tests {
    use super::*;
    use crate::TestSettings;
    use crate::traits::CommandToString;
    use test_log::test;

    #[test]
    fn test_builder_new() {
        let command = PgDumpAllBuilder::new().program_dir(".").build();
        assert_eq!(
            PathBuf::from(".").join("pg_dumpall"),
            PathBuf::from(command.to_command_string().replace('"', ""))
        );
    }

    #[test]
    fn test_builder_from() {
        let command = PgDumpAllBuilder::from(&TestSettings).build();
        #[cfg(not(target_os = "windows"))]
        let command_prefix = r#"PGPASSWORD=\"password\" \"./pg_dumpall\" "#;
        #[cfg(target_os = "windows")]
        let command_prefix = r#"\".\\pg_dumpall\" "#;

        assert_eq!(
            format!(
                r#"{command_prefix}"--host" \"localhost\" "--port" \"5432\" "--username" \"postgres\""#
            ),
            command.to_command_string()
        );
    }

    #[test]
    fn test_builder() {
        let command = PgDumpAllBuilder::new()
            .env("PGDATABASE", "database")
            .file("dump.sql")
            .verbose()
            .version()
            .build();
        
        // Example assertion for the constructed command string
        // The exact output might vary based on OS and other factors not fully shown.
        // This is a conceptual representation of what the test might assert.
        let expected_command_part = r#"-f" \"dump.sql\" --verbose --version"#;
        assert!(command.to_command_string().contains(expected_command_part));
        assert!(command.to_command_string().contains(r#"PGDATABASE=\"database\""#));
    }
}
```

--------------------------------

### Get Default PgResetWalBuilder

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/pg_resetwal/struct.PgResetWalBuilder

Provides the default value for the `PgResetWalBuilder` struct by implementing the `Default` trait. This method returns a new instance of `PgResetWalBuilder` with its default configuration, useful for starting a builder pattern without explicit initialization.

```rust
fn default() -> PgResetWalBuilder
```

--------------------------------

### Test PgBaseBackupBuilder::from (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_basebackup.rs

Demonstrates creating a PgBaseBackupBuilder from existing settings and verifying the generated command string. It shows how to set basic connection parameters like host and port.

```Rust
    #[test]
    fn test_builder_from() {
        let command = PgBaseBackupBuilder::from(&TestSettings).build();
        #[cfg(not(target_os = "windows"))]
        let command_prefix = r#"PGPASSWORD=\"password\" \"./pg_basebackup\" "#;
        #[cfg(target_os = "windows")]
        let command_prefix = r#"\".\\pg_basebackup\" "#;

        assert_eq!(
            format!(
                r#"{command_prefix}"--host" \"localhost\" "--port" \"5432\" "--username" \"postgres\""#
            ),
            command.to_command_string()
        );
    }
```

--------------------------------

### Build pg_verifybackup command from settings

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_verifybackup.rs

Shows how to initialize `PgVerifyBackupBuilder` from existing settings and build the command. Includes OS-specific handling for command prefixes to ensure cross-platform compatibility.

```Rust
let command = PgVerifyBackupBuilder::from(&TestSettings).build();
#[cfg(not(target_os = "windows"))]
let command_prefix = r#"./pg_verifybackup"#;
#[cfg(target_os = "windows")]
let command_prefix = r#".\\pg_verifybackup"#;
assert_eq!(format!("{command_prefix}"), command.to_command_string());
```

--------------------------------

### Configure amcheck: Start block number

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_amcheck.rs

Sets the starting block number for checking tables. The amcheck utility will begin its verification process from this specified block, useful for resuming interrupted checks or focusing on specific data segments.

```rust
/// begin checking table(s) at the given block number
#[must_use]
pub fn start_block<S: AsRef<OsStr>>(mut self, start_block: S) -> Self {
    self.start_block = Some(start_block.as_ref().to_os_string());
    self
}
```

--------------------------------

### Test EcpgBuilder Initialization from Settings and OS Paths

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/ecpg.rs

Demonstrates creating an EcpgBuilder from existing settings and handles OS-specific path formatting for the ecpg executable. It asserts the correct command prefix for both Windows and non-Windows targets.

```rust
use super::*;
use crate::TestSettings;
use crate::traits::CommandToString;
use test_log::test;

#[test]
fn test_builder_from() {
    let command = EcpgBuilder::from(&TestSettings).build();
    #[cfg(not(target_os = "windows"))]
    let command_prefix = r#"./ecpg"#;
    #[cfg(target_os = "windows")]
    let command_prefix = r#".\\ecpg"#;

    assert_eq!(format!("{command_prefix}"), command.to_command_string());
}
```

--------------------------------

### Configure Start Position for PostgreSQL Logical Replication (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_recvlogical.rs

Sets the starting Log Sequence Number (LSN) or position from which replication should begin. This method is part of a builder pattern for configuring logical replication. It takes a string slice representing the LSN.

```Rust
/// where in an existing slot should the streaming start
#[must_use]
pub fn startpos<S: AsRef<OsStr>>(mut self, startpos: S) -> Self {
    self.startpos = Some(startpos.as_ref().to_os_string());
    self
}
```

--------------------------------

### Rust PgCtl Mode Enum for Operations

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_ctl.rs

The `Mode` enum defines the different operational modes available for the `pg_ctl` utility. These modes include initializing a database (`InitDb`), stopping the server (`Kill`, `Stop`), starting it (`Start`), managing logs (`LogRotate`), and checking status (`Status`).

```rust
#[derive(Clone, Debug)]
pub enum Mode {
    InitDb,
    Kill,
    LogRotate,
    Promote,
    Restart,
    Reload,
    Start,
    Stop,
    Status,
}
```

--------------------------------

### PgBaseBackupBuilder Configuration Methods

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_basebackup.rs

Provides methods to configure the `PgBaseBackupBuilder` for creating PostgreSQL base backups. This includes initializing the builder, creating it from settings, and setting essential parameters like program directory and data directory.

```rust
/// Represents a builder for the pg_basebackup command.
/// Fields like host, port, username, etc., are configured via builder methods.
struct PgBaseBackupBuilder {
    program_dir: Option<std::path::PathBuf>,
    pgdata: Option<std::path::PathBuf>,
    host: Option<std::ffi::OsString>,
    port: Option<u16>,
    status_interval: Option<std::ffi::OsString>,
    username: Option<std::ffi::OsString>,
    no_password: bool,
    password: bool,
    pg_password: Option<std::ffi::OsString>,
}

// Assuming a Settings trait exists for the 'from' method
trait Settings {
    fn get_binary_dir(&self) -> std::ffi::OsString;
    fn get_host(&self) -> Option<std::ffi::OsString>;
    fn get_port(&self) -> Option<u16>;
    fn get_username(&self) -> Option<std::ffi::OsString>;
    fn get_password(&self) -> Option<std::ffi::OsString>;
}

impl PgBaseBackupBuilder {
    /// Create a new [`PgBaseBackupBuilder`]
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a new [`PgBaseBackupBuilder`] from [Settings]
    pub fn from(settings: &dyn Settings) -> Self {
        Self::new()
            .program_dir(settings.get_binary_dir())
            .host(settings.get_host())
            .port(settings.get_port())
            .username(settings.get_username())
            .pg_password(settings.get_password())
    }

    /// Location of the program binary
    #[must_use]
    pub fn program_dir<P: Into<std::path::PathBuf>>(mut self, path: P) -> Self {
        self.program_dir = Some(path.into());
        self
    }

    /// receive base backup into directory
    #[must_use]
    pub fn pgdata<P: Into<std::path::PathBuf>>(mut self, pgdata: P) -> Self {
        self.pgdata = Some(pgdata.into());
        self
    }

    // Placeholder for other methods like host, port, username, etc.
    // These would typically be defined in the full implementation.
    pub fn host(mut self, host: Option<std::ffi::OsString>) -> Self {
        self.host = host;
        self
    }

    pub fn port(mut self, port: Option<u16>) -> Self {
        self.port = port;
        self
    }

    pub fn username(mut self, username: Option<std::ffi::OsString>) -> Self {
        self.username = username;
        self
    }

    pub fn pg_password(mut self, pg_password: Option<std::ffi::OsString>) -> Self {
        self.pg_password = pg_password;
        self
    }
}

// Default implementation for PgBaseBackupBuilder
impl Default for PgBaseBackupBuilder {
    fn default() -> Self {
        PgBaseBackupBuilder {
            program_dir: None,
            pgdata: None,
            host: None,
            port: None,
            status_interval: None,
            username: None,
            no_password: false,
            password: false,
            pg_password: None,
        }
    }
}

```

--------------------------------

### pg_config Module - PgConfigBuilder

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/pg_config/index

Provides information about the installed version of PostgreSQL. The PgConfigBuilder struct is used to access these details.

```APIDOC
Module: postgresql_commands::pg_config

Struct: PgConfigBuilder

Description: Provides information about the installed version of PostgreSQL.

Usage:
  The `pg_config` utility itself is used to query PostgreSQL installation settings. This Rust struct likely wraps or provides access to similar information programmatically.
```

--------------------------------

### PgBenchBuilder get_program_dir Method

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/pgbench/struct.PgBenchBuilder

Gets the directory location of the program binary. This helps in locating the executable file on the filesystem.

```Rust
fn get_program_dir(&self) -> &[Option<PathBuf>]
```

--------------------------------

### CreateDbBuilder Configuration Methods

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/createdb.rs

Provides methods to configure the creation of a new PostgreSQL database using the CreateDbBuilder. These methods allow setting the program directory, default tablespace, encoding, and enabling command echoing for debugging purposes. The `from` method initializes the builder with settings from a provided `Settings` trait object.

```rust
/// Create a new [`CreateDbBuilder`] from [Settings]
pub fn from(settings: &dyn Settings) -> Self {
    Self::new()
        .program_dir(settings.get_binary_dir())
        .host(settings.get_host())
        .port(settings.get_port())
        .username(settings.get_username())
        .pg_password(settings.get_password())
}

/// Location of the program binary
#[must_use]
pub fn program_dir<P: Into<PathBuf>>(mut self, path: P) -> Self {
    self.program_dir = Some(path.into());
    self
}

/// Default tablespace for the database
#[must_use]
pub fn tablespace<S: AsRef<OsStr>>(mut self, tablespace: S) -> Self {
    self.tablespace = Some(tablespace.as_ref().to_os_string());
    self
}

/// Show the commands being sent to the server
#[must_use]
pub fn echo(mut self) -> Self {
    self.echo = true;
    self
}

/// Encoding for the database
#[must_use]
pub fn encoding<S: AsRef<OsStr>>(mut self, encoding: S) -> Self {
    self.encoding = Some(encoding.as_ref().to_os_string());
    self
}
```

--------------------------------

### Get Command Arguments (CommandBuilder)

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/oid2name/struct.Oid2NameBuilder

Retrieves the arguments intended for the command. These arguments are returned as a vector of OsString, suitable for execution.

```rust
fn get_args(&self) -> Vec<OsString>
```

--------------------------------

### Initialize PostgresBuilder

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/postgres.rs

Demonstrates creating a new `PostgresBuilder` instance and setting the program directory. The `build()` method finalizes the command construction.

```rust
use postgresql_commands::PostgresBuilder;
use std::path::PathBuf;

// Create a new builder and set the program directory to the current directory
let command = PostgresBuilder::new().program_dir(".").build();

// Verify the constructed command string
let expected_path = PathBuf::from(".").join("postgres");
assert_eq!(expected_path, PathBuf::from(command.to_command_string().replace('"', "")));
```

--------------------------------

### Get Program Directory - Rust

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_recvlogical.rs

Retrieves the directory path where the program binary is located. This function returns a reference to an optional PathBuf.

```Rust
fn get_program_dir(&self) -> &Option<PathBuf> {
    &self.program_dir
}
```

--------------------------------

### PgBenchBuilder: Comprehensive configuration

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pgbench.rs

Illustrates the extensive configuration capabilities of the PgBenchBuilder by chaining various methods to set options for initialization, scaling, tables, and execution parameters.

```rust
#[test]
fn test_builder() {
    let command = PgBenchBuilder::new()
        .env("PGDATABASE", "database")
        .initialize()
        .init_steps("steps")
        .fill_factor(10)
        .no_vacuum()
        .quiet()
        .scale(10)
        .foreign_keys()
        .index_tablespace("tablespace")
        .partition_method("method")
        .partitions(10)
        .tablespace("tablespace")
        .unlogged_tables()
        .builtin("name")
        .file("filename")
        .skip_some_updates()
        .select_only()
        .client(10)
        .connect()
        .build();
}
```

--------------------------------

### Get Program File Path (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/pg_amcheck/struct.PgAmCheckBuilder

Retrieves the fully qualified path to the program binary. This method is part of the CommandBuilder trait.

```rust
fn get_program_file(&self) -> PathBuf
```

--------------------------------

### InitDbBuilder Methods

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/initdb.rs

Provides builder methods for constructing and configuring PostgreSQL database initialization commands. Includes methods for creating a new builder, initializing from settings, setting program directory, and configuring authentication methods for local and host connections.

```rust
impl InitDbBuilder {
    /// Create a new [`InitDbBuilder`]
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a new [`InitDbBuilder`] from [Settings]
    pub fn from(settings: &dyn Settings) -> Self {
        Self::new()
            .program_dir(settings.get_binary_dir())
            .username(settings.get_username())
    }

    /// Location of the program binary
    #[must_use]
    pub fn program_dir<P: Into<PathBuf>>(mut self, path: P) -> Self {
        self.program_dir = Some(path.into());
        self
    }

    /// Set the default authentication method for local connections
    #[must_use]
    pub fn auth<S: AsRef<OsStr>>(mut self, auth: S) -> Self {
        self.auth = Some(auth.as_ref().to_os_string());
        self
    }

    /// Set the default authentication method for local TCP/IP connections
    #[must_use]
    pub fn auth_host<S: AsRef<OsStr>>(mut self, auth_host: S) -> Self {
        self.auth_host = Some(auth_host.as_ref().to_os_string());
        self
    }
}
```

--------------------------------

### Configure pg_ctl Version Output

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_ctl.rs

Instructs pg_ctl to output version information and then exit. This is typically used to check the installed PostgreSQL version.

```rust
/// output version information, then exit
#[must_use]
pub fn version(mut self) -> Self {
    self.version = true;
    self
}
```

--------------------------------

### Build pg_upgrade command with all options

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_upgrade.rs

This comprehensive example illustrates the extensive configuration options available for `PgUpgradeBuilder`. It covers setting environment variables, binary directories, data directories, ports, jobs, linking, synchronization, and various command-line flags for `pg_upgrade`.

```rust
let command = PgUpgradeBuilder::new()
    .env("PGDATABASE", "database")
    .old_bindir("old")
    .new_bindir("new")
    .check()
    .old_datadir("old_data")
    .new_datadir("new_data")
    .jobs("10")
    .link()
    .no_sync()
    .old_options("old")
    .new_options("new")
    .old_port(5432)
    .new_port(5433)
    .retain()
    .socketdir("socket")
    .username("user")
    .verbose()
    .version()
    .build();
```

--------------------------------

### Result::as_ref() Examples

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/error/type.Result

Shows how `as_ref()` converts a `&Result<T, E>` into a `Result<&T, &E>`. This allows borrowing the contents of a `Result` without consuming it.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Set pg_ctl Mode

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_ctl.rs

Specifies the operation mode for pg_ctl, such as start, stop, or restart. The 'Mode' enum determines the specific action to be performed.

```rust
/// mode
#[must_use]
pub fn mode(mut self, mode: Mode) -> Self {
    self.mode = Some(mode);
    self
}
```

--------------------------------

### Get Program Name (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/postgres.rs

Returns the static program name for the PostgreSQL command builder. This method is part of the `CommandBuilder` trait implementation.

```rust
/// Get the program name
fn get_program(&self) -> &'static OsStr {
    "postgres".as_ref()
}
```

--------------------------------

### PgDumpAllBuilder: Get Program Name

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_dumpall.rs

Retrieves the static program name associated with this builder, which is 'pg_dumpall'. This method is part of the CommandBuilder trait implementation.

```Rust
/// Get the program name
fn get_program(&self) -> &'static OsStr {
    "pg_dumpall".as_ref()
}
```

--------------------------------

### ClusterDbBuilder: Create from Settings

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/clusterdb/struct.ClusterDbBuilder

Shows how to initialize a ClusterDbBuilder using an existing Settings object. This allows for configuration to be passed in from an external source.

```Rust
use postgresql_commands::clusterdb::ClusterDbBuilder;
use postgresql_commands::traits::Settings;

// Assume 'my_settings' is an object implementing the Settings trait
// let my_settings: &dyn Settings = ...;

// Create a ClusterDbBuilder from provided settings
// let builder = ClusterDbBuilder::from(my_settings);

// Further configuration can be applied to the builder...
```

--------------------------------

### Create pg_waldump from Settings

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_waldump.rs

Initializes a pg_waldump configuration builder from provided settings. It sets the program directory based on the binary directory found in the settings.

```rust
pub fn from(settings: &dyn Settings) -> Self {
    Self::new().program_dir(settings.get_binary_dir())
}
```

--------------------------------

### Get clusterdb Program Name

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/clusterdb.rs

Returns the static program name 'clusterdb'. This method is part of the CommandBuilder trait and identifies the executable being configured.

```rust
fn get_program(&self) -> &'static OsStr {
    "clusterdb".as_ref()
}
```

--------------------------------

### Get Program Binary Path (CommandBuilder)

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/oid2name/struct.Oid2NameBuilder

Returns the absolute path to the program binary that the command will execute. This is useful for verifying the target executable.

```rust
fn get_program_file(&self) -> PathBuf
```

--------------------------------

### Test PgBaseBackupBuilder Configuration (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_basebackup.rs

Demonstrates building a PgBaseBackupBuilder with various configuration options like data directory, format, compression, and target. It showcases the flexibility of the builder for complex command construction.

```Rust
    #[test]
    fn test_builder() {
        let command = PgBaseBackupBuilder::new()
            .env("PGDATABASE", "database")
            .pgdata("pgdata")
            .format("plain")
            .max_rate("100M")
            .write_recovery_conf()
            .target("localhost")
            .tablespace_mapping("tablespace_mapping")
            .waldir("waldir")
            .wal_method("stream")
            .gzip()
            .compress("client")
            .checkpoint("fast")
            .create_slot()
            .label("my_backup")
            .no_clean()
            .no_sync()
            .progress()
            .build();
    }
```

--------------------------------

### DropDbBuilder: Constructing and Testing Commands

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/dropdb.rs

Demonstrates how to use the DropDbBuilder to construct PostgreSQL dropdb commands. Includes examples of building a command from existing settings and verifying its string representation, as well as chaining various builder methods to configure options like host, port, username, and specific flags. It also shows OS-specific command prefix handling.

```rust
    #[test]
    fn test_builder_from() {
        let command = DropDbBuilder::from(&TestSettings).build();
        #[cfg(not(target_os = "windows"))]
        let command_prefix = r#"PGPASSWORD="password" \"./dropdb\" "#;
        #[cfg(target_os = "windows")]
        let command_prefix = r#"\".\\dropdb\" "#;

        assert_eq!(
            format!(
                r#"{command_prefix}"--host" "localhost" "--port" "5432" "--username" "postgres""#
            ),
            command.to_command_string()
        );
    }

    #[test]
    fn test_builder() {
        let command = DropDbBuilder::new()
            .env("PGDATABASE", "database")
            .echo()
            .force()
            .interactive()
            .version()
            .if_exists()
            .help()
            .host("localhost")
            .port(5432)
            .username("postgres")
            .no_password()
            .password()
            .pg_password("password")
            .maintenance_db("postgres")
            .dbname("dbname")
            .build();
        #[cfg(not(target_os = "windows"))]
        let command_prefix = r#"PGDATABASE=\"database\" PGPASSWORD=\"password\" "#;
        #[cfg(target_os = "windows")]
        let command_prefix = r#""#;
    }
```

--------------------------------

### Rust: Test PgIsReadyBuilder from()

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_isready.rs

Tests building a PgIsReady command from existing settings, such as TestSettings. It includes OS-specific handling for command prefixes and verifies the complete command string with arguments like host, port, and username.

```Rust
#[test]
    fn test_builder_from() {
        let command = PgIsReadyBuilder::from(&TestSettings).build();
        #[cfg(not(target_os = "windows"))]
        let command_prefix = r#"./pg_isready" #;
        #[cfg(target_os = "windows")]
        let command_prefix = r#".\\pg_isready" #;

        assert_eq!(
            format!(
                r#"{command_prefix}"--host" "localhost" "--port" "5432" "--username" "postgres"#
            ),
            command.to_command_string()
        );
    }
```

--------------------------------

### Build pg_config Command (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/lib.rs

Provides a builder for the PostgreSQL 'pg_config' command-line utility. This tool displays information about the installed PostgreSQL version and configuration.

```Rust
pub mod pg_config;
```

--------------------------------

### CreateUserBuilder: Test All Options

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/createuser.rs

Demonstrates the comprehensive usage of the CreateUserBuilder by chaining various methods to configure user attributes such as environment variables, roles, privileges, and connection settings.

```rust
#[test]
fn test_builder() {
    let command = CreateUserBuilder::new()
        .env("PGDATABASE", "database")
        .with_admin("admin")
        .connection_limit(10)
        .createdb()
        .no_createdb()
        .echo()
        .member_of("member")
        .inherit()
        .no_inherit()
        .login()
        .no_login()
        .with_member("member")
        .pwprompt()
        .createrole()
        .no_createrole()
        .superuser()
        .build();
}
```

--------------------------------

### Result::ok() Examples

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/error/type.Result

Illustrates converting a `Result<T, E>` into an `Option<T>` using the `ok()` method. This consumes the `Result` and returns `Some(T)` if it was `Ok`, or `None` if it was `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

--------------------------------

### PostgreSQL `pg_ctl` Modes

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_ctl.rs

Defines the different modes for the `pg_ctl` command (e.g., initdb, start, stop) and implements the `Display` trait for string representation.

```rust
enum Mode {
    InitDb,
    Kill,
    LogRotate,
    Promote,
    Restart,
    Reload,
    Start,
    Stop,
    Status,
}

impl Display for Mode {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Mode::InitDb => write!(formatter, "initdb"),
            Mode::Kill => write!(formatter, "kill"),
            Mode::LogRotate => write!(formatter, "logrotate"),
            Mode::Promote => write!(formatter, "promote"),
            Mode::Restart => write!(formatter, "restart"),
            Mode::Reload => write!(formatter, "reload"),
            Mode::Start => write!(formatter, "start"),
            Mode::Stop => write!(formatter, "stop"),
            Mode::Status => write!(formatter, "status"),
        }
    }
}
```

--------------------------------

### Initialize PostgresBuilder from Settings

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/postgres.rs

Shows how to initialize `PostgresBuilder` using existing `TestSettings`. It includes platform-specific handling for command prefixes (e.g., `./postgres` vs. `.\postgres`).

```rust
use postgresql_commands::PostgresBuilder;
// Assuming TestSettings is defined elsewhere and implements necessary traits
// use crate::TestSettings;

// Placeholder for TestSettings for demonstration
struct TestSettings;
impl TestSettings {
    fn host(&self) -> &str { "localhost" }
    fn port(&self) -> u16 { 5432 }
}

let settings = TestSettings;
let command = PostgresBuilder::from(&settings).build();

// Platform-specific command prefix
#[cfg(not(target_os = "windows"))]
let command_prefix = r#"./postgres" "#;
#[cfg(target_os = "windows")]
let command_prefix = r#".\\postgres" "#;

// Expected command string with host and port
let expected_command = format!(r#"{command_prefix}"-h "{}" "-p" "{}""#, settings.host(), settings.port());

assert_eq!(expected_command, command.to_command_string());
```

--------------------------------

### Get psql Program Name (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/psql.rs

Returns the static program name for the `psql` command. This is used internally by the `CommandBuilder` trait to identify the executable.

```Rust
/// Get the program name
fn get_program(&self) -> &'static OsStr {
    "psql".as_ref()
}
```

--------------------------------

### Get pg_waldump Environment Variables

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_waldump.rs

Retrieves the environment variables configured for the pg_waldump command. This function returns a vector of key-value pairs representing the environment.

```rust
fn get_envs(&self) -> Vec<(OsString, OsString)> {
    self.envs.clone()
}
```

--------------------------------

### VacuumDbBuilder: Comprehensive Options Test

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/vacuumdb.rs

Illustrates the usage of various builder methods to configure a vacuumdb command, such as setting environment variables, applying the 'all' option, and specifying limits and database names. This tests the flexibility of the builder pattern.

```rust
#[cfg(test)]
mod tests {
    use super::*;
    use crate::TestSettings;
    use crate::traits::CommandToString;
    use test_log::test;

    #[test]
    fn test_builder() {
        let command = VacuumDbBuilder::new()
            .env("PGDATABASE", "database")
            .all()
            .buffer_usage_limit("buffer_usage_limit")
            .dbname("dbname");
        // Note: The full command string generation is not shown in the provided snippet,
        // but this demonstrates setting multiple options.
    }
}
```

--------------------------------

### Rust: Build PostgreSQL vacuumlo Commands with Builder

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/vacuumlo.rs

Demonstrates how to use the `VacuumLoBuilder` in Rust to construct `vacuumlo` commands. This includes examples of initializing the builder, setting program directory, configuring connection details via settings, and applying various command-line options like environment variables, limits, dry runs, verbosity, version, and help flags.

```Rust
use super::*;
use crate::TestSettings;
use crate::traits::CommandToString;
use test_log::test;
use std::path::PathBuf;

#[test]
fn test_builder_new() {
    let command = VacuumLoBuilder::new().program_dir(".").build();
    assert_eq!(
        PathBuf::from(".").join("vacuumlo"),
        PathBuf::from(command.to_command_string().replace('"', ""))
    );
}

#[test]
fn test_builder_from() {
    let command = VacuumLoBuilder::from(&TestSettings).build();
    #[cfg(not(target_os = "windows"))]
    let command_prefix = r#"PGPASSWORD="password" "./vacuumlo" "#;
    #[cfg(target_os = "windows")]
    let command_prefix = r#"".\\vacuumlo" "#;

    assert_eq!(
        format!(
            r#"{command_prefix}"--host" "localhost" "--port" "5432" "--username" "postgres"#
        ),
        command.to_command_string()
    );
}

#[test]
fn test_builder() {
    let command = VacuumLoBuilder::new()
        .env("PGDATABASE", "database")
        .limit(100)
        .dry_run()
        .verbose()
        .version()
        .help()
        .build();
    // Example assertion for the built command string would go here
    // assert_eq!("expected_command_string", command.to_command_string());
}
```

--------------------------------

### Get pg_ctl program name

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_ctl.rs

Retrieves the static program name for the pg_ctl command. This is a required method for the CommandBuilder trait, identifying the executable to be run.

```rust
/// Get the program name
fn get_program(&self) -> &'static OsStr {
    "pg_ctl".as_ref()
}
```

--------------------------------

### PgConfigBuilder: Get Program Directory

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_config.rs

Implements the get_program_dir method from the CommandBuilder trait. Returns an Option containing the path to the program's directory, if specified.

```rust
/// Location of the program binary
    fn get_program_dir(&self) -> &Option<PathBuf> {
        &self.program_dir
    }
```

--------------------------------

### Build and Format PostgreSQL vacuumlo Command

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/vacuumlo.rs

Demonstrates building a PostgreSQL connection configuration and formatting a 'vacuumlo' command with various options. Includes OS-specific command prefix handling and assertion for command string correctness.

```rust
.host("localhost")
            .port(5432)
            .username("postgres")
            .no_password()
            .password()
            .pg_password("password")
            .build();
        #[cfg(not(target_os = "windows"))]
        let command_prefix = r#"PGDATABASE=\"database\" PGPASSWORD=\"password\" "#;
        #[cfg(target_os = "windows")]
        let command_prefix = String::new();

        assert_eq!(
            format!(
                r#"{command_prefix}\"vacuumlo\" \"--limit\" \"100\" \"--dry-run\" \"--verbose\" \"--version\" \"--help\" \"--host\" \"localhost\" \"--port\" \"5432\" \"--username\" \"postgres\" \"--no-password\" \"--password\""#
            ),
            command.to_command_string()
        );
```

--------------------------------

### PgConfigBuilder: Get Program Name

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_config.rs

Implements the get_program method from the CommandBuilder trait. Returns the static string "pg_config", identifying the executable.

```rust
/// Get the program name
    fn get_program(&self) -> &'static OsStr {
        "pg_config".as_ref()
    }
```

--------------------------------

### CreateDbBuilder: Get Program Name

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/createdb.rs

Implements the CommandBuilder trait to return the static program name 'createdb'. This identifies the executable that the builder is configured to run.

```rust
/// Get the program name
    fn get_program(&self) -> &'static OsStr {
        "createdb".as_ref()
    }
```

--------------------------------

### Test CreateUserBuilder Initialization (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/createuser.rs

A unit test verifying the correct initialization and building of a `CreateUserBuilder`, including setting the program directory and asserting the resulting command path.

```Rust
    #[test]
    fn test_builder_new() {
        let command = CreateUserBuilder::new().program_dir(".").build();
        assert_eq!(
            PathBuf::from(".").join("createuser"),
            command.program_path
        );
    }
```

--------------------------------

### Result::is_err_and() Examples

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/error/type.Result

Shows how to use `is_err_and()` to check if a `Result` is an error and if the error value satisfies a given predicate. It returns `true` only if both conditions are met.

```rust
use std::io::{Error, ErrorKind};

let x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);

let x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, Error> = Ok(123);
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, String> = Err("ownership".to_string());
assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Build pg_verifybackup command with program directory

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/pg_verifybackup.rs

Demonstrates creating a `pg_verifybackup` command using `PgVerifyBackupBuilder::new()` and setting the program directory. It verifies the generated command string against the expected path, handling potential quoting differences.

```Rust
let command = PgVerifyBackupBuilder::new().program_dir(".").build();
assert_eq!(
    PathBuf::from(".").join("pg_verifybackup"),
    PathBuf::from(command.to_command_string().replace('"', ""))
);
```

--------------------------------

### Result::as_mut() Examples

Source: https://docs.rs/postgresql_commands/0.19.0/postgresql_commands/error/type.Result

Illustrates how `as_mut()` converts a `&mut Result<T, E>` into a `Result<&mut T, &mut E>`. This enables mutable borrowing of the contents of a `Result`.

```rust
let mut x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_mut(), Ok(&mut 2));

let mut x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_mut(), Err(&mut "Error"));
```

--------------------------------

### InitDbBuilder: Build and Configure InitDb Commands (Rust)

Source: https://docs.rs/postgresql_commands/0.19.0/src/postgresql_commands/initdb.rs

Demonstrates how to construct and configure `initdb` commands using the `InitDbBuilder`. Includes examples for setting the program directory and specifying user details like username. The `build` method finalizes the command configuration.

```Rust
let command = InitDbBuilder::new().program_dir(".").build();
assert_eq!(
    PathBuf::from(".").join("initdb"),
    PathBuf::from(command.to_command_string().replace('"', ""))
);

let command = InitDbBuilder::from(&TestSettings).build();
#[cfg(not(target_os = "windows"))]
let command_prefix = r#"./initdb" #;
#[cfg(target_os = "windows")]
let command_prefix = r#".\\initdb" #;

assert_eq!(
    format!(r#"{command_prefix}"--username" "postgres"#),
    command.to_command_string()
);
```
Tokens:
Raw