pg-browser-proxy

library0.1.0jsnpmunverified

pg-browser-proxy v0.1.0 is a lightweight WebSocket-TCP proxy that allows standard PostgreSQL clients (psql, pgAdmin, Drizzle Studio, Prisma Studio) to connect to a Postgres database running in the browser (e.g., PGlite). It creates a TCP server that forwards PostgreSQL wire protocol messages to the browser via WebSocket. Unlike direct in-browser database tools, it enables existing CLI and GUI tools to manage browser-based databases without changes. The proxy is designed for development and testing, with support for custom ports and single-browser-connection limitation.

database

npm install pg-browser-proxy

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-BROWSER-PROXY

pg-browser-proxy

databasejavascriptv0.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

connectProxy

✓ import { connectProxy } from 'pg-browser-proxy'

✗ import connectProxy from 'pg-browser-proxy'

Default export is not available; connectProxy is a named export.

runProxy

✓ import { runProxy } from 'pg-browser-proxy'

✗ const { runProxy } = require('pg-browser-proxy')

The package is ESM-only; CommonJS require will not work. Use dynamic import() if needed.

Type

✓ import type { Options } from 'pg-browser-proxy'

✗ import { Options } from 'pg-browser-proxy'

Options is a type export; import it with `type` to avoid runtime errors.

Creates a PGlite in-browser database and connects it to the proxy, enabling external PostgreSQL clients to interact with it.

import { connectProxy } from 'pg-browser-proxy'; import { PGliteWorker } from '@electric-sql/pglite/worker'; const db = await PGliteWorker.create( new Worker(new URL('./worker', import.meta.url), { type: 'module' }), ); connectProxy((message) => db.execProtocolRaw(message), { tcpPort: 5432, wsPort: 443, }); // Then connect with psql: psql -h localhost -p 5432 -U postgres

Debug

Known issues

gotchaOnly one browser connection is allowed at a time

fix

Ensure only a single browser tab connects the proxy; multiple connections will cause issues.

affects: <=0.1.0

gotchaThe database must handle raw PostgreSQL wire protocol messages for connectProxy to work

fix

Use db.execProtocolRaw() as shown in the example; standard query methods may not work.

affects: <=0.1.0

gotchaTCP port 5432 is default and may conflict with a local PostgreSQL installation

fix

Use -t flag to specify an alternative port: bunx pg-browser-proxy -t 5433

affects: <=0.1.0

gotchaWebSocket port defaults to 443, which requires root/admin privileges on Unix systems

fix

Use -w flag to specify an unprivileged port: bunx pg-browser-proxy -w 8080

affects: <=0.1.0

Errors

Common errors & fixes

Error: listen EACCES: permission denied 0.0.0.0:443

WebSocket server default port 443 requires elevated privileges

fix

Run proxy with a different port: bunx pg-browser-proxy -w 8080

Error: connectProxy is not a function

Importing connectProxy as a default import instead of named import

fix

Use named import: import { connectProxy } from 'pg-browser-proxy'

TypeError: db.execProtocolRaw is not a function

Database instance does not support raw wire protocol (e.g., wrong PGlite export)

fix

Use PGliteWorker from '@electric-sql/pglite/worker' and create worker with correct URL

Error: connect ECONNREFUSED 127.0.0.1:5432

Proxy TCP server is not running or wrong host/port

fix

Start proxy with bunx pg-browser-proxy and ensure tcpPort matches client connection string

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

@electric-sql/pgliterequiredRequired to create the browser-based Postgres instance that the proxy connects to

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/f0rr0/pg-browser-proxy ↗

packagepg-browser-proxy ↗

homepagehttps://github.com/f0rr0/pg-browser-proxy#readme ↗