pg-gateway

0.3.0-beta.4 verified Sat Apr 25 auth: no javascript

pg-gateway is a TypeScript library that implements the PostgreSQL wire protocol for the server side, enabling developers to build custom Postgres-compatible proxies, middleware, or gateways. The current version is 0.3.0-beta.4, indicating an early beta stage with potential breaking changes. It focuses on low-level protocol handling, differentiating from higher-level clients like node-postgres by giving direct control over the protocol flow. Releases are infrequent and experimental.

Common errors

error TypeError: PgGateway is not a constructor ↓

cause Importing the default export incorrectly when using CommonJS or mismatched module system.

fix

Use import PgGateway from 'pg-gateway' in ESM, or const PgGateway = require('pg-gateway').default in CommonJS.

error Cannot find module 'pg-gateway' ↓

cause Package not installed or incorrect import path.

fix

Install with npm install pg-gateway and verify the import path is correct.

error Error: The module 'pg-gateway' is not compatible with the 'node' platform ↓

cause Attempting to use in a browser or non-Node environment.

fix

Use only in Node.js; exclude from browser bundles.

Warnings

breaking Beta version 0.3.0 may have breaking changes from earlier alphas. No stable release yet. ↓

fix Pin to a specific version and test upgrades carefully. Consult changelog if available.

gotcha The package is intended for server-side usage only; it does not work in browser environments due to reliance on Node.js net module. ↓

fix Do not import in client-side code; ensure bundler excludes it for browser bundles.

deprecated No known deprecated APIs yet, but as a beta package, certain APIs may be removed later. ↓

fix Watch for updates and migration guides.

Install

npm install pg-gateway

yarn add pg-gateway

pnpm add pg-gateway

Imports

default
wrong
```
const PgGateway = require('pg-gateway')
```
correct
```
import PgGateway from 'pg-gateway'
```
The package is ESM-first but may have a CommonJS fallback. Check package.json exports.

PgGateway

wrong

import PgGateway from 'pg-gateway'

correct

import { PgGateway } from 'pg-gateway'

Named export for the library class.

BackendMessage
wrong
```
import BackendMessage from 'pg-gateway'
```
correct
```
import { BackendMessage } from 'pg-gateway'
```
Named export for backend message types, useful for parsing protocol messages.

Quickstart

Creates a simple TCP server that uses pg-gateway to proxy client connections to a real PostgreSQL instance, demonstrating the primary use case.

import PgGateway from 'pg-gateway';
import net from 'node:net';

const gateway = new PgGateway();
// Create a server that proxies to a real PostgreSQL backend
net.createServer((socket) => {
  gateway.handleClient(socket, {
    backend: { host: 'localhost', port: 5432, user: 'user', password: process.env.PGPASSWORD ?? '' }
  });
}).listen(5433, () => {
  console.log('Gateway listening on 5433');
});