Advanced

PGlite is a single Postgres backend: one session, one connection's worth of state. The socket lets many clients use it by taking turns, and resets what each client leaves behind. For the usual development workload (an app's pool, a migration tool, psql), this behaves like a server. The details below matter when something does not.

One owner at a time

A client owns the database for the length of a transaction or pipeline; the others queue until it is done. The process's own db.query() / db.transaction() calls (a server action, the DevTools SQL box) queue the same way, so neither side's statements land inside the other's transaction.

An owner that stays idle inside a transaction or pipeline for longer than idleInTransactionTimeout is disconnected, which rolls its transaction back and lets the queue move. It is off by default; set it if a crashed tool or a forgotten BEGIN in psql can stall your app.

Session state

When a client disconnects, what it set up in the session is dropped, as a real server would: its settings, temp tables, advisory locks, prepared statements and LISTEN subscriptions. The settings the process set before the socket started (for example a SET search_path in init) are kept.

Notifications reach the clients that ran LISTEN on the channel, and no others.

Known differences

Inherent to sharing one session:

• COPY … FROM STDIN is refused with SQLSTATE 0A000: PGlite cannot run it.
• LISTEN / UNLISTEN and SQL-level PREPARE / EXECUTE / DEALLOCATE are recognised as single statements, the way drivers send them. LISTEN takes effect regardless of the transaction it ran in.
• Temp tables and advisory locks taken by the process itself are released when any client disconnects.
• Connections are not authenticated, and every database name reaches the same database.

The config file outside the bundle

The socket imports server/pglite.config.ts in the Nuxt process through jiti, not through Nuxt's bundler, with the app's aliases: ~~, #pglite/migrations and the aliases of other modules resolve as they do in the server bundle. definePGliteServerConfig is provided as a global while it loads, so a file written for the server works unchanged; other auto-imports are not available there.

When init fails

The instance is created, and init (migrations, seeding) run, when nuxt dev starts. If either fails, the dev server keeps running: the error is logged, the socket listens at its usual URL with its variables exported, and every client is refused with a FATAL 57P03 (cannot_connect_now) error, PGlite is not ready: <the error>, whose hint points at the fix. Your app's routes then fail with that message rather than with a connection error, and the DevTools tab shows the reason.

Restart nuxt dev once the cause is fixed (a change to the config file restarts it), or run the reset-database action to start from an empty database.

Bun and Deno

The socket uses only Node built-ins (node:net, node:fs), so it runs wherever nuxt dev does, including Bun and Deno. It has been tested with pg, postgres.js, psql and drizzle-kit push on all three. To serve PGlite without Nuxt, see Outside Nuxt.