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.

Contents

• 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:

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

Features

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.

Platform support

OS	Architectures
	amd64, arm64v8 ¹
	amd64, i386, arm32v6, arm32v7, arm64v8, ppc64le
	amd64, i386, arm32v6, arm32v7, arm64v8, ppc64le
	amd64, i386

Supported PostgreSQL versions: 10 – 18 (PG_V10 … PG_V18 constants).

¹ Apple Silicon binaries are available for PostgreSQL 14 and later only.

Binary cache

Binaries are stored at an OS-specific location and reused on subsequent runs:

Documentation

• User Handbook — configuration reference, auth methods, migrations, FAQ
• Technical Handbook — architecture, data flow, module graph, internals
• API reference on docs.rs

License

pg-embed is dual-licensed under MIT / Apache 2.0.

Credits

Precompiled binaries provided by zonkyio/embedded-postgres-binaries, hosted on Maven Central.