pg-embed

Run a PostgreSQL server locally as part of a Rust application or test suite — no system installation required.

pg-embed downloads precompiled PostgreSQL binaries from zonkyio/embedded-postgres-binaries, caches them on first use, and manages the full server lifecycle (initdb → pg_ctl start → pg_ctl stop). Built on tokio.

Quick start
Extensions
Features
Platform support
Binary cache
Documentation

Quick start

[dependencies]
pg-embed = "1.0"

use std::path::PathBuf;
use std::time::Duration;

use pg_embed::pg_enums::PgAuthMethod;
use pg_embed::pg_errors::Result;
use pg_embed::pg_fetch::{PgFetchSettings, PG_V18};
use pg_embed::postgres::{PgEmbed, PgSettings};

#[tokio::main]
async fn main() -> Result<()> {
    let mut pg = PgEmbed::new(
        PgSettings {
            database_dir:  PathBuf::from("data/db"),
            port:          5432,
            user:          "postgres".to_string(),
            password:      "password".to_string(),
            auth_method:   PgAuthMethod::MD5,
            persistent:    false,
            timeout:       Some(Duration::from_secs(30)),
            migration_dir: None,
        },
        PgFetchSettings { version: PG_V18, ..Default::default() },
    ).await?;

    pg.setup().await?;    // download + unpack + initdb (cached after first run)
    pg.start_db().await?;

    pg.create_database("mydb").await?;

    // postgres://postgres:password@localhost:5432/mydb
    let uri = pg.full_db_uri("mydb");
    println!("Connect at: {uri}");

    pg.stop_db().await?;
    Ok(())
}

Extensions

Third-party extensions (pgvector, PostGIS, etc.) are not included in the precompiled binaries. To install one, point install_extension() at a directory containing the pre-built files for your platform. Call it after setup() and before start_db().

use std::path::Path;

// After pg.setup() and before pg.start_db():
pg.install_extension(Path::new("extensions/pgvector")).await?;
pg.start_db().await?;

// Then activate it inside a database:
// CREATE EXTENSION IF NOT EXISTS vector;

Files are routed by extension:

File type	Destination
`.so`, `.dylib`, `.dll`	`{cache}/lib/`
`.control`, `.sql`	`{cache}/share/postgresql/extension/`
Anything else	Skipped

Pure-SQL extensions (no shared library) work the same way — simply omit the binary.

Features

Capability	API	Feature flag
🔄 Server lifecycle	`setup()`, `start_db()`, `stop_db()`	`rt_tokio`
🧩 Extension installation	`install_extension()`	`rt_tokio`
🗄️ Database management	`create_database()`, `drop_database()`, `database_exists()`	`rt_tokio_migrate`
🚀 Migrations	`migrate()`	`rt_tokio_migrate`

The default feature is rt_tokio_migrate (includes sqlx). For a smaller build without sqlx:

pg-embed = { version = "1.0", default-features = false, features = ["rt_tokio"] }

Additional behaviours included in all builds:

Binary caching — binaries are downloaded once per OS/arch/version and reused across runs.
Automatic shutdown — pg_ctl stop is called on drop if the server is still running.
Concurrent safety — a global lock prevents duplicate downloads when multiple instances initialise simultaneously.