Build With Rust

Install

Add the crate and let the SDK resolve released runtime assets and helpers through configuration:

[dependencies]
oliphaunt = "0.1"

Open and query

Create a builder, choose storage, select exact extensions, open, query, and close.

use oliphaunt::{Extension, Oliphaunt};

async fn open_database() -> oliphaunt::Result<()> {
    let db = Oliphaunt::builder()
        .path(".oliphaunt")
        .native_direct()
        .extension(Extension::Vector)
        .open()
        .await?;

    let rows = db.query("SELECT 1::text AS value").await?;
    assert_eq!(rows.get_text(0, "value")?, Some("1"));

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

Keep the opened Oliphaunt handle in application state. Cloned handles point to the same executor. Use server mode when the app needs a connection pool or independent PostgreSQL client sessions.

Create app data

Use typed helpers for application queries and keep the database handle in Tauri state, an async service, or another app-owned dependency container:

db.execute(
    r#"
    CREATE TABLE IF NOT EXISTS notes (
        id bigserial PRIMARY KEY,
        title text NOT NULL,
        body text NOT NULL,
        created_at timestamptz NOT NULL DEFAULT now()
    )
    "#,
)
.await?;

db.query_params(
    "INSERT INTO notes (title, body) VALUES ($1, $2) RETURNING id::text AS id",
    ["First note", "Stored in an embedded PostgreSQL root"],
)
.await?;

let notes = db
    .query("SELECT id, title FROM notes ORDER BY id DESC LIMIT 20")
    .await?;

Expose app-specific commands to a Tauri webview instead of exposing raw database handles directly to frontend code.

Configure

Configure engine mode, root, durability, startup identity, selected extensions, runtime assets, broker executable, and server executable through the builder. Use a persistent app-owned directory for user data. Temporary roots are useful for tests and short-lived tools.

Choose a mode

NativeDirect runs one serialized embedded session in the process. It gives the lowest round-trip latency and rejects pool sizes above one.

NativeBroker talks to a local helper process. Use it for desktop apps that need process isolation, crash recovery, or several roots managed by one application.

NativeServer starts a PostgreSQL-compatible server process. Use it when psql, pg_dump, ORMs, or true independent client sessions matter.

Handle lifecycle

Direct-mode work queues fairly on one owner executor. Transactions pin the physical session until commit or rollback. close() rejects queued work, waits for active work, then closes or detaches from the selected runtime. Use explicit cancellation for long-running SQL.

Select extensions

Select exact SQL extension names before open. There are no packs, aliases, or implicit selectors. If you select vector, the generated artifacts include vector and only its declared dependencies.

Back up and restore

Use SDK backup and restore APIs instead of copying PostgreSQL directories from application code. The SDK validates formats, target roots, locks, and restore options before materializing data.