PledgeDB WASM

Embedded SQL database with vector search, compiled to WebAssembly.

Building

# Install wasm-pack if you haven't
cargo install wasm-pack

# Build for browser
./build.sh

# Build for Node.js
./build.sh nodejs

# Build for bundlers (webpack, vite, etc.)
./build.sh bundler

The built package will be in pkg/.

Usage (Browser)

import { PledgeDB } from "pledgedb";

// Create in-memory database
const db = new PledgeDB();
db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
db.exec("INSERT INTO users (name) VALUES ('Alice')");

// Query
const result = db.query("SELECT * FROM users");
console.log(result.rows);   // [[1, "Alice"]]
console.log(result.columns); // ["id", "name"]

// Vector search
db.exec("CREATE TABLE items (id INTEGER PRIMARY KEY, embedding VECTOR(3))");
db.exec("INSERT INTO items (embedding) VALUES ([1.0, 0.0, 0.0])");
db.exec("INSERT INTO items (embedding) VALUES ([0.0, 1.0, 0.0])");
db.exec("CREATE VECTOR INDEX idx ON items (embedding) USING HNSW (metric = 'l2')");

const results = db.query("SELECT id FROM items ORDER BY embedding <-> [1.0, 0.0, 0.0] LIMIT 2");

// Persistence — automatic OPFS with IndexedDB fallback
await db.save("mydb");

// Later — load from storage
const db2 = new PledgeDB();
await db2.load("mydb");
const rows = db2.query("SELECT * FROM users");

// Manual persistence (for environments without OPFS/IndexedDB)
const bytes = db.export_data();
const db3 = PledgeDB.from_bytes(bytes);

Usage (Node.js)

const { PledgeDB } = require("pledgedb");

const db = new PledgeDB();
db.exec("CREATE TABLE data (id INTEGER PRIMARY KEY, value TEXT)");
db.exec("INSERT INTO data (value) VALUES ('hello')");

const result = db.query("SELECT * FROM data");
console.log(result);

Usage (Web Worker)

import { PledgeDB } from "pledgedb";

const db = new PledgeDB();
db.exec("CREATE TABLE cache (key TEXT PRIMARY KEY, value TEXT)");

// OPFS is available in Web Workers — save/load works the same
await db.save("cache-db");
await db.load("cache-db");

Persistence

PledgeDB WASM supports automatic persistence via:

1. OPFS (Origin Private File System) — preferred, stores files at opfs:/pledgedb/<name>.pldb
2. IndexedDB — fallback when OPFS is not available

Both are async APIs. Use save() and load() for automatic backend selection:

// Check what's available
console.log(PledgeDB.hasOpfs());       // true if OPFS is available
console.log(PledgeDB.hasIndexedDB());  // true if IndexedDB is available

// Save (automatically picks OPFS or IndexedDB)
await db.save("mydb");  // → "opfs" or "indexeddb"

// Load (automatically picks the same backend)
await db.load("mydb");  // → "opfs", "indexeddb", or "empty"

// Delete saved data
await PledgeDB.deleteSaved("mydb");

For environments without OPFS/IndexedDB (e.g. Cloudflare Workers), use manual persistence:

const bytes = db.export_data();
// Store bytes in KV, R2, or any storage
const db2 = PledgeDB.from_bytes(bytes);

API

new PledgeDB()

Create a new in-memory database.

PledgeDB.from_bytes(data: Uint8Array)

Load a database from previously exported bytes.

db.exec(sql: string): JsResult

Execute a SQL statement. Returns { columns, rows, affected, message }.

db.query(sql: string): JsResult

Alias for exec().

db.tables(): string[]

List all table names.

db.schema(name: string): JsSchema | null

Get the schema for a table.

db.export_data(): Uint8Array

Export raw database bytes for manual persistence.

db.flush(): void

Flush pending writes (no-op in WASM, kept for API compatibility).

db.save(name: string): Promise<string>

Persist to OPFS or IndexedDB. Resolves to "opfs" or "indexeddb".

db.load(name: string): Promise<string>

Load from OPFS or IndexedDB. Resolves to "opfs", "indexeddb", or "empty".

PledgeDB.hasOpfs(): boolean

Check if OPFS is available in the current environment.

PledgeDB.hasIndexedDB(): boolean

Check if IndexedDB is available in the current environment.

PledgeDB.deleteSaved(name: string): Promise<boolean>

Delete a saved database from OPFS and IndexedDB.