Embedded PostgreSQL
Understand database lifetime, persistence, and backup in an embedded PostgreSQL app.
Oliphaunt runs PostgreSQL inside your application or a local process it owns. Your app chooses when the database opens, where its data lives, and when it closes. PostgreSQL supplies SQL execution, transactions, indexes, and recovery.
Choose the data lifetime
| Storage | Use it for | What happens after close |
|---|---|---|
| Native default: temporary directory | Tests, previews, disposable work | Disposable; do not rely on it surviving the process |
| WASIX default: memory filesystem | Tests and disposable browser or host sessions | The data is discarded |
| Persistent directory or browser provider | Application data | Reopen the same storage to use the data again |
Choose persistent storage explicitly before saving user data. Native mobile apps normally use an app-private directory. WASIX browser apps choose IndexedDB or OPFS; desktop WASIX apps can use a directory.
A native persistent database is a managed directory, not a single file. Let the SDK manage its contents. Do not delete database files or open the same root through another database instance.
One handle, one session
Embedded query handles use one PostgreSQL session. Async calls let the application stay responsive, but queries still execute in order on that session. A transaction holds the session until it commits or rolls back.
Use the transaction object supplied to a callback for every operation inside it. Calling the outer database handle from the callback can wait on the transaction that is already using the session.
For independent client sessions and a connection pool, use a native server. WASIX local endpoints accept one connected client at a time.
Store changes safely
PostgreSQL uses write-ahead logging, or WAL, to recover committed changes after an interruption. Native SDKs use PostgreSQL's files directly. Persistent WASIX providers also need to publish changes to their host storage; follow the SDK's persistence contract.
Await operations and close the database explicitly. Mobile operating systems may terminate an app without calling shutdown code, so closing must not be your only persistence mechanism. Keep transactions short and treat an interrupted operation with an unknown result as uncertain; check application state before retrying it.
Back up a database
Use the SDK's backup and restore APIs. A live directory copy can miss files or WAL needed for a consistent database. Restore into a new or empty destination, then open that destination with the required extensions available.
Physical archives belong to their runtime family and require a compatible runtime version. Use a logical SQL dump when moving between native and WASIX runtimes. Backups contain database state; ship extension binaries and resources with the destination application separately.
Use PostgreSQL features
Parameters use PostgreSQL's $1, $2 syntax. Types, casts, constraints, and query planning follow PostgreSQL behavior. Extensions add features such as vector search; select and package an extension before enabling it with SQL.
Use the SDK guides for concrete storage, transaction, and backup examples.