PostgreSQL Embedded

To include the PostgreSQL installation archive directly within your application executable, enable the bundled feature.

1. At Compile Time: Set the POSTGRESQL_VERSION environment variable to a specific version (e.g., =17.2.0) to determine which archive to download and include.
2. At Runtime: You must provide an explicit matching version in your Settings object using VersionReq to ensure the runtime uses the bundled version.

If POSTGRESQL_VERSION is not set during build, postgresql_archive::LATEST is used.

To use a custom GitHub source for releases, set the POSTGRESQL_RELEASES_URL environment variable. The repository must follow the structure used by theseus-rs/postgresql_binaries.

use postgresql_embedded::{Result, Settings, VersionReq};
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<()> {
    let settings = Settings {
        version: VersionReq::from_str("=17.2.0")?,
        ..Default::default()
    };
    // Use settings with PostgreSQL::new(settings)
    Ok(())
}

To use postgresql_embedded, you can initialize a PostgreSQL instance, set it up, and start the database process. The library supports both async and blocking APIs. By default, it downloads and installs PostgreSQL during runtime, but you can also enable a bundled feature to include the PostgreSQL archive directly in your binary at compile time.

Key capabilities include:

• Running PostgreSQL on ephemeral ports.
• Unix socket support.
• Fluent configuration via a settings builder.
• URL-based configuration.
• Support for installing PostgreSQL extensions.
• Choice of native-tls or rustls (with AWS-LC or Ring).

use postgresql_embedded::{PostgreSQL, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut postgresql = PostgreSQL::default();
    postgresql.setup().await?;
    postgresql.start().await?;

    let database_name = "test";
    postgresql.create_database(database_name).await?;
    postgresql.database_exists(database_name).await?;
    postgresql.drop_database(database_name).await?;

    postgresql.stop().await
}

Use the SettingsBuilder to fluently construct a Settings object for your embedded PostgreSQL instance. This is the recommended way to customize connection details, installation paths, and server configurations.

Commonly configured fields include:

• host and port: TCP connection details.
• username and password: Database credentials.
• temporary: If true (default), the database is cleaned up on drop.
• configuration: A map of server configuration options (e.g., max_connections).
• socket_dir: Sets a Unix socket directory (Unix-only).

use postgresql_embedded::SettingsBuilder;
use std::path::PathBuf;

let settings = SettingsBuilder::new()
    .host("127.0.0.1")
    .port(5433)
    .username("admin")
    .password("secret")
    .temporary(false)
    .build();

// To configure a Unix socket:
let socket_settings = SettingsBuilder::new()
    .socket_dir(PathBuf::from("/tmp/pg_socket"))
    .build();

The PostgreSQL struct is the primary entrypoint for managing an embedded PostgreSQL instance. It handles the full lifecycle of the database: installation from archives, initialization of the data directory, starting the server, and stopping it.

Lifecycle Management

• setup(): A high-level method that ensures the server is installed (extracting archives if necessary) and initialized (creating the data directory and configuration files).
• start(): Starts the PostgreSQL server. If the port is set to 0, it will bind to a random available port.
• stop(): Gracefully stops the server using pg_ctl in Fast shutdown mode.
• drop(): Automatically stops the server if it is running. If the temporary setting is enabled, it also deletes the data directory, password file, and socket directory.

Database Operations

You can manage individual databases within the embedded instance using these methods:

• create_database(name): Creates a new database.
• database_exists(name): Checks if a database exists.
• drop_database(name): Drops a database if it exists.

Note: Database operations use a connection pool to the bootstrap database (the default superuser database) to execute commands.

```rust
use postgresql_embedded::Settings;
use postgresql_embedded::PostgreSQL;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let settings = Settings::default();
    let mut pg = PostgreSQL::new(settings);

    // 1. Install and initialize
    pg.setup().await?;

    // 2. Start the server
    pg.start().await?;

    // 3. Perform database operations
    pg.create_database("my_app_db").await?;
    
    if pg.database_exists("my_app_db").await? {
        println!("Database is ready!");
    }

    // 4. Stop the server
    pg.stop().await?;

    Ok(())
}
```埋