libpgdump

A Rust library for reading and writing PostgreSQL dump files.

Supports all three pg_dump formats: custom (-Fc), directory (-Fd), and tar (-Ft).

Usage

Add to your Cargo.toml:

[dependencies]
libpgdump = "1"

Load an existing dump

use libpgdump;

let dump = libpgdump::load("backup.dump").unwrap();

println!("Database: {}", dump.dbname());
println!("Server:   {}", dump.server_version());
println!("Entries:  {}", dump.entries().len());

// Iterate over table data
for row in dump.table_data("public", "users").unwrap() {
    println!("{row}");  // tab-separated COPY format
}

// Look up a specific entry
if let Some(entry) = dump.lookup_entry(&libpgdump::ObjectType::Table, "public", "users") {
    println!("Definition: {}", entry.defn.as_deref().unwrap_or(""));
}

Create a new dump

use libpgdump;

let mut dump = libpgdump::new("mydb", "UTF8", "17.0").unwrap();

// Add a table definition
let table_id = dump.add_entry(
    libpgdump::ObjectType::Table,
    Some("public"), Some("users"), Some("postgres"),
    Some("CREATE TABLE public.users (\n    id integer NOT NULL,\n    name text\n);\n"),
    Some("DROP TABLE public.users;\n"),
    None, &[],
).unwrap();

// Add table data
let data_id = dump.add_entry(
    libpgdump::ObjectType::TableData,
    Some("public"), Some("users"), Some("postgres"),
    None, None,
    Some("COPY public.users (id, name) FROM stdin;\n"),
    &[table_id],
).unwrap();

dump.set_entry_data(data_id, b"1\tAlice\n2\tBob\n".to_vec()).unwrap();

// Save with gzip compression
dump.set_compression(libpgdump::CompressionAlgorithm::Gzip);
dump.save("output.dump").unwrap();

Inspect entries

use libpgdump;

let dump = libpgdump::load("backup.dump").unwrap();

for entry in dump.entries() {
    println!(
        "{:>4} {:20} {:10} {}",
        entry.dump_id,
        entry.desc,
        entry.namespace.as_deref().unwrap_or(""),
        entry.tag.as_deref().unwrap_or(""),
    );
}

Error handling

use libpgdump::{self, Error};

match libpgdump::load("backup.dump") {
    Ok(dump) => println!("Loaded {} entries", dump.entries().len()),
    Err(Error::InvalidHeader(msg)) => eprintln!("Not a valid dump: {msg}"),
    Err(Error::UnsupportedVersion(v)) => eprintln!("Unsupported version: {v}"),
    Err(e) => eprintln!("Error: {e}"),
}

Supported features

• Read/write custom (-Fc), directory (-Fd), and tar (-Ft) archives
• Compression: none, gzip, lz4, and zstd
• Archive versions 1.12.0 through 1.16.0 (PostgreSQL 9.0–18)
• Version-aware parsing: handles all format variations across versions
• 60+ object types: tables, indexes, views, functions, constraints, extensions, etc.
• Large object (blob) support
• Weighted topological sort: entries are sorted on save matching pg_dump's dependency-aware ordering
• Programmatic dump creation: build dumps from scratch with the builder API

Format details

Dump::load() auto-detects the format from file type (directory) or magic bytes (PGDMP = custom, ustar = tar).

Custom format (-Fc)

Binary archive: header with magic bytes, version, and compression info; metadata (timestamp, database name, versions); TOC with entry definitions and dependencies; compressed or uncompressed data blocks.

Directory format (-Fd)

A directory containing toc.dat (binary TOC in custom format) and per-entry .dat data files. Supports all compression algorithms.

Tar format (-Ft)

A standard tar archive containing toc.dat and per-entry data files. Does not support compression.

Minimum Rust version

Rust 1.88 or later (edition 2024).

License

BSD-3-Clause