Outside Nuxt

Socket server

nuxt-pglite/socket, the Postgres wire-protocol server, in any Node, Bun or Deno process.

nuxt-pglite/socket is the server behind the development socket. It serves any PGlite instance over the Postgres wire protocol and depends only on PGlite and Node built-ins.

serve.ts

import { createPGliteProvider, definePGliteConfig } from 'nuxt-pglite/core'
import { createPGliteSocketServer } from 'nuxt-pglite/socket'

const pglite = createPGliteProvider(definePGliteConfig({ dataDir: './data' }))
const db = await pglite.use()

const server = await createPGliteSocketServer(db, { port: 5433 }).listen()
console.log(server.url) // postgres://postgres@127.0.0.1:5433/postgres

process.on('SIGINT', async () => {
  await server.close()
  await pglite.close()
  process.exit(0)
})

Terminal

node serve.ts   # Node 24 runs TypeScript directly
bun serve.ts
deno run -A serve.ts

The server neither opens nor closes the instance: it belongs to you. close() disconnects the clients, rolling back their open transactions, stops listening and waits for the statement in progress.

Options

createPGliteSocketServer(db, options):

Option	Type	Default
`host`	`string`	`'127.0.0.1'`	Interface to listen on.
`port`	`number`	`0` (a free port)	Port to listen on.
`path`	`string`		Directory for a Unix socket (`.s.PGSQL.<port>` inside it), instead of `host`.
`maxConnections`	`number`	`Infinity`	Further clients are refused with SQLSTATE `53300`.
`idleInTransactionTimeout`	`number`	`0` (off)	Milliseconds an idle owner may hold a transaction before it is disconnected (`25P03`).
`user`	`string`	`'postgres'`	User name put in `url`. Clients are not authenticated.
`database`	`string`	`'postgres'`	Database name put in `url`. Every name reaches the same database.
`logger`	`(...message) => void`	silent	Receives unexpected connection errors.

The server object

Member
`listen()`	Starts listening; resolves with the server once it does.
`url`	The connection URL. Throws until `listen()` has resolved.
`address`	`{ host, port }` or `{ path, port }` while listening, otherwise `undefined`.
`connections`	The number of open client sockets.
`serve(db)`	Serves `db` from then on, behind the same URL; clients of the previous instance are disconnected.
`refuse(reason, { hint? })`	Disconnects the clients and refuses new ones with SQLSTATE `57P03`, `PGlite is not ready: <reason>`, until the next `serve()`.
`close()`	Disconnects every client and stops listening. The instance stays open.

createPGliteSocketServer(null, options) starts refusing until the first serve(). That is how the development socket keeps its URL while init fails, and how its reset swaps the instance: create the replacement, then serve() it, or refuse() with the error.

How clients share the instance, and where that differs from a real server, is the same as in Nuxt: see the socket's Advanced page.

Config and provider

nuxt-pglite/core, the config helper and the lazy instance provider, usable in any runtime.

Nitro's useDatabase

Point Nitro's experimental database layer at the development socket, with the same connector in production.