Crate powdb 

PowDB — embedded

Run the PowDB engine in-process — no server, no socket. This is the SQLite-shaped front door to the same storage engine, indexes, WAL durability, and PowQL/SQL frontends that the powdb-server crate exposes over the wire. Because there is no network round-trip, single-op latency is the engine’s own cost (~µs), and the database works fully offline — the foundation for local-first apps.

use powdb::{Database, QueryResult, Value};

let mut db = Database::open("./data")?;
db.query("type User { required name: str, age: int }")?;
db.query(r#"insert User { name := "Ada", age := 36 }"#)?;
match db.query("count(User)")? {
    QueryResult::Scalar(Value::Int(n)) => assert_eq!(n, 1),
    other => panic!("unexpected: {other:?}"),
}

Panic safety

The server crate is built crash-only (panic = "abort"): a panic exits the process and a supervisor restarts it, recovering via WAL replay. An embedded host can’t have the database abort it, so every query here is wrapped in std::panic::catch_unwind. A caught panic poisons the handle — further calls return Error::Poisoned — and the handle is dropped without a clean checkpoint (a panic mid-mutation may have left in-memory pages torn; flushing them would persist garbage). Committed data is already durable in the WAL, so reopening the database recovers a consistent state by replay. This is the same crash-only contract, scoped to a handle instead of the process. (catch_unwind only catches when the final binary is built with panic = "unwind", the default for applications and the official Node addon.)

Lossless typed results

Every query method here (Database::query, Database::query_sql, Database::query_readonly, and the *_with_params variants) returns a QueryResult whose rows and scalar are strongly typed Values, not strings. This is the lossless surface: an Value::Int keeps its full i64 range, Value::Bytes keeps its raw bytes, and a JSON null (Value::Json) stays distinct from a missing/absent cell (Value::Empty). String rendering via Value::to_wire_string is a separate, deliberately lossy convenience for display and the legacy string protocol. Prefer the typed Value directly when a distinction matters.

Parameters

Database::query_with_params and Database::query_readonly_with_params bind positional $1..$N placeholders. Parameters are substituted as literal tokens before parsing, so an injection-shaped string is inert data that can never change the query’s shape.

Structs

Database

An in-process PowDB database handle.

Engine

RetainedApplyRequest

Request to apply one already-pulled retained-unit chunk.

RetainedApplyResult

Summary returned after retained-unit chunk apply.

RetainedUnitInput

One retained replication unit accepted by the embedded sync applier.

SyncApplyIdentity

Database identity and format metadata required to apply retained sync units.

Enums

Error

An error from the embedded API.

ParamValue

A bound value supplied for a $N placeholder in crate::parser::parse_with_params.

QueryError

Typed error enum for query execution failures.

QueryResult

The result of executing a query.

TypeId

Type identifier for schema definitions and wire protocol.

Value

A single scalar value. Optional fields use Empty (set-based nullability).

WalSyncMode

Durability mode for the WAL — analogous to SQLite’s PRAGMA synchronous combined with journal_mode=OFF.

Constants

RETAINED_SEGMENT_FORMAT_VERSION

Functions

parse_sync_mode

Parse a JS-/CLI-facing sync-mode name into a WalSyncMode (case insensitive). None for anything other than full / normal / off.

pj1_to_text

Render canonical PJ1 (binary JSON) bytes as canonical JSON text.