Choose a native runtime mode
Choose direct embedding, process isolation, or a local server for your application.
Native Rust and desktop TypeScript offer three runtime modes. Swift, Kotlin, and React Native also offer mobile broker integration. Choose a mode based on process isolation and the number of database sessions your application needs.
| Mode | Database runs in | Access | Choose it when |
|---|---|---|---|
| Direct | Your application process | SDK query handle, one session | You want embedded queries with the fewest moving parts |
| Broker | A helper process | SDK query handle, one session | You need to isolate database execution from your app process |
| Server | A server process | PostgreSQL connection string | You need a driver, ORM, pool, or independent sessions |
Direct
Direct mode is the default. The SDK manages a resident native backend in the application process. Keep one application-owned database handle and share it according to your language's concurrency rules.
The first successful direct open binds the process to that root and configuration. Closing the handle releases the logical session; it does not unload PostgreSQL or let the process switch roots. Reopen the same root with compatible settings, or use broker/server mode for multiple roots. In direct mode, mobile apps switch to restored data on a subsequent process launch.
In Rust, the synchronous handle blocks the calling thread. Use AsyncOliphaunt for async tasks. Swift, Kotlin, and JavaScript expose async APIs; those APIs serialize database work rather than creating a session per call.
Broker
Broker mode moves execution into a helper process while retaining the SDK query API. It is available in native Rust and desktop TypeScript, and through platform-specific setup on iOS 26+ and Android. See mobile broker setup.
If the helper exits unexpectedly, the database handle becomes unusable. Close it and open a new handle on the same persistent directory. PostgreSQL recovers committed data from WAL. The SDK does not replay a failed operation, because its commit outcome may be unknown.
Package the helper executable and runtime resources with your app. Use the package's normal resource resolution unless your deployment layout requires an explicit path.
Server
Server mode returns a lifecycle handle with a PostgreSQL connection string. Connect with a PostgreSQL driver or ORM to run queries; the server handle itself does not provide the embedded query API.
Keep the server handle alive for as long as clients use it. At shutdown, stop accepting application work, close client connections and pools, then close the server. A copied connection string does not keep the server running.
See Rust runtime recipes or TypeScript runtime recipes. For a desktop webview, see Use with Tauri.
WASIX endpoints
WASIX SDKs have their own local endpoint on socket-capable hosts. It serves one connected client at a time; it is not a replacement for a native server with independent sessions. Browser apps do not expose a TCP listener.