Dump, Restore, And Upgrade

oliphaunt-wasix uses the WASIX pg_dump binary from the shipped portable runtime asset for portable SQL exports, restores, and version-to-version upgrades.

Choose The Right Export Format

Use logical dumps when you need:

• a portable SQL export;
• an upgrade path between oliphaunt-wasix releases;
• a way to move data between different roots safely.

Use physical data-dir archives when you need:

• a same-version clone;
• a same-runtime restore into another oliphaunt-wasix root;
• a fast local snapshot of the current cluster state.

Use logical dumps for cross-version upgrades. Keep physical archives for same-version clones and restores.

Direct API

Dump an already-open Oliphaunt database to SQL:

use oliphaunt_wasix::{PgDumpOptions, Oliphaunt};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut db = Oliphaunt::temporary()?;
    db.exec("CREATE TABLE items(value TEXT)", None)?;
    db.exec("INSERT INTO items VALUES ('alpha')", None)?;

    let sql = db.dump_sql(PgDumpOptions::new())?;
    assert!(sql.contains("INSERT INTO"));

    db.close()?;
    Ok(())
}

Get UTF-8 bytes instead:

use oliphaunt_wasix::{PgDumpOptions, Oliphaunt};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut db = Oliphaunt::temporary()?;
    let bytes = db.dump_bytes(PgDumpOptions::new())?;
    assert!(!bytes.is_empty());
    db.close()?;
    Ok(())
}

Direct dumps run against the already-open embedded backend. If you need to dump as a different user or from a different database, start a OliphauntServer and use the server dump path instead.

Server API

Dump through a local Postgres endpoint when another part of your workflow already uses OliphauntServer:

use oliphaunt_wasix::{PgDumpOptions, OliphauntServer};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = OliphauntServer::temporary_tcp()?;
    let sql = server.dump_sql(PgDumpOptions::new().arg("--schema-only"))?;
    assert!(!sql.is_empty());
    server.shutdown()?;
    Ok(())
}

Use a TCP endpoint for OliphauntServer::dump_sql(...).

PgDumpOptions

PgDumpOptions controls the managed parts of the dump command:

use oliphaunt_wasix::PgDumpOptions;

let options = PgDumpOptions::new()
    .username("postgres")
    .database("template1")
    .args(["--schema-only", "--quote-all-identifiers"]);

Useful passthrough flags include dump-shaping options such as:

• --schema-only
• --quote-all-identifiers
• -n <schema>
• -t <table>

Managed connection and output flags are reserved by the API: --file, --format, --host, --port, --username, --dbname, and --jobs are configured by Oliphaunt instead of arg(...) or args(...).

CLI

Dump a persistent root:

oliphaunt-wasix-dump --root ./.oliphaunt

Pass through normal pg_dump shaping flags after --:

oliphaunt-wasix-dump --root ./.oliphaunt -- --schema-only
oliphaunt-wasix-dump --root ./.oliphaunt -- --quote-all-identifiers

Restore

Restore a logical dump by executing the SQL against a new database:

use oliphaunt_wasix::{PgDumpOptions, Oliphaunt};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut source = Oliphaunt::temporary()?;
    source.exec("CREATE TABLE items(value TEXT)", None)?;
    source.exec("INSERT INTO items VALUES ('alpha')", None)?;
    let dump_sql = source.dump_sql(PgDumpOptions::new())?;

    let mut restored = Oliphaunt::temporary()?;
    restored.exec(&dump_sql, None)?;

    source.close()?;
    restored.close()?;
    Ok(())
}

For same-version root copies, prefer dump_data_dir() / load_data_dir_archive(...) or try_clone().

Upgrade Guidance

Use logical dump and restore when upgrading between oliphaunt-wasix versions or changing shipped runtime assets:

1. Open the old database with the old crate/runtime.
2. Create a logical dump with dump_sql(...) or oliphaunt-wasix-dump.
3. Open a fresh database with the new crate/runtime.
4. Execute the dump SQL into the new database.

Use logical dumps for general upgrades. Physical data-dir archives are for the same runtime family and database format.