English for PGlite Developers

PGlite conversations mix Postgres vocabulary with browser-runtime concerns — persistence backend, single-connection model — so a backend developer used to a networked Postgres instance needs new terms for what changes when the database runs client-side.

Key Vocabulary

Postgres compiled to WASM — PGlite’s core mechanism: an actual build of the Postgres server compiled to WebAssembly, so it’s running real Postgres, not an emulation or a subset reimplementation. “This isn’t a Postgres-like API — it’s Postgres compiled to WASM, so extensions and SQL features behave exactly like server Postgres would.”

In-browser persistence — PGlite’s ability to keep database state across page reloads by writing to a browser storage backend like IndexedDB, rather than losing all data on refresh. “Enable in-browser persistence for the demo — otherwise every page refresh wipes the sample data we just loaded.”

Single-connection model — PGlite’s constraint of supporting one active connection at a time per instance, a deliberate trade-off since it isn’t running as a networked multi-client server. “Don’t try to open two tabs against the same PGlite instance expecting them to share a live connection — the single-connection model doesn’t support that.”

Local-first — an application architecture where the primary database lives on the client and can sync to a server, rather than the client always depending on a network round-trip to a remote database. “We’re building this as local-first — PGlite handles reads and writes instantly offline, and sync to the server happens in the background.”

Persistence backend — the storage layer PGlite writes to for durability, typically IndexedDB in the browser or the filesystem in Node, configurable depending on the runtime. “Switch the persistence backend to the filesystem for the Node test suite — IndexedDB isn’t available outside a browser context.”

Common Phrases

• “Is this actually Postgres compiled to WASM, or are we relying on a compatibility shim that might not support this feature?”
• “Do we need in-browser persistence here, or is this genuinely a throwaway, per-session database?”
• “Is the single-connection model going to be a problem if we open multiple tabs against the same instance?”
• “Should this feature be local-first, or does it need to always hit the server for consistency?”
• “Which persistence backend is this environment using — IndexedDB or filesystem?”

Example Sentences

Debugging a data-loss complaint: “Users lose their work on refresh because in-browser persistence was never enabled — the instance was running purely in memory the whole time.”

Explaining an architecture choice: “We used PGlite for the offline mode specifically because it’s Postgres compiled to WASM — our existing SQL queries and extensions work unmodified instead of needing a rewrite for a lighter embedded database.”

Reviewing a pull request: “This assumes multiple concurrent connections to the same PGlite instance — the single-connection model means we need to serialize these calls instead.”

Professional Tips

• Emphasize Postgres compiled to WASM when justifying PGlite over a lighter embedded database — it means real SQL feature parity, not a reduced dialect.
• Call out the single-connection model early in architecture discussions — it shapes how multi-tab or multi-worker scenarios need to be designed.
• Use local-first deliberately to describe the overall architecture, not just “offline support” — it implies the client is the primary source of truth, with sync as secondary.
• Specify the persistence backend explicitly in setup docs — a silent mismatch between IndexedDB and filesystem is a common source of “it worked in the browser but not in tests” confusion.

Practice Exercise

1. Explain why “Postgres compiled to WASM” is a stronger claim than “a Postgres-compatible database.”
2. Describe a scenario where the single-connection model would cause a bug if not accounted for.
3. Write a sentence explaining local-first architecture to a teammate used to always-online apps.