pglite-rs ships a bundled postgres-pglite runtime. Single-process mode starts the engine on one dedicated thread. Async calls send wire-protocol messages to that thread and decode PostgreSQL responses into Rust rows.

Single process

Rust task

exec/query/transaction

Channel

frontend wire bytes

Engine thread

postgres-pglite runtime

Rows

backend wire decoded

Open constraints

Single-process mode uses a process-wide guard. Opening a second in-process PGlite returns Error::AlreadyOpen. Reopening after the engine booted is not supported in that mode.

Use multi-process mode when one application needs real concurrent sessions.

Serialization

Single-process exec, query, transaction, and copy calls take an internal async lock. Multi-process mode skips that lock because it uses pooled backend connections.

Data directory

open() initializes the data directory on first use. open_temp() creates a temporary directory and removes it when dropped.

Locale provider

PGliteOptions.locale_provider can be Libc or Icu. An ICU data directory must be reopened with an ICU build.