Registry / database / serverless-postgres

serverless-postgres

library2.1.2jsnpmunverified

Serverless-postgres is a wrapper for node-postgres (pg) designed for serverless/FaaS environments like AWS Lambda. Current stable version is 2.1.2, released via semantic-release. It manages database connections to prevent 'too many clients' errors by garbage collecting zombie connections and retrying with backoff on failure. Key differentiators: connection filtering via application_name (v2+), automatic connection cleanup, and configurable retry delays. Unlike raw pg, it addresses connection pooling issues in serverless contexts.

database

npm install serverless-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SERVERLESS-POSTGRE

serverless-postgres

databasejavascriptv2.1.2

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.

default (ServerlessClient)

✓ import ServerlessClient from 'serverless-postgres'

✗ const { ServerlessClient } = require('serverless-postgres')

Package exports a single class as default. CommonJS require gives the class directly, not an object.

ServerlessClient (type)

✓ import type { ServerlessClient } from 'serverless-postgres'

✗ import { ServerlessClient } from 'serverless-postgres'

If using TypeScript, the type is exported as a named export. Use type-only import to avoid emitting runtime code.

Config

✓ import type { Config } from 'serverless-postgres'

✗ import { Config } from 'serverless-postgres'

Configuration interface is exported as a type only.

Basic usage of serverless-postgres in an AWS Lambda handler: create client outside handler, connect, query, clean connections.

import ServerlessClient from 'serverless-postgres'; const client = new ServerlessClient({ user: process.env.DB_USER ?? '', host: process.env.DB_HOST ?? '', database: process.env.DB_NAME ?? '', password: process.env.DB_PASSWORD ?? '', port: Number(process.env.DB_PORT) || 5432, debug: false, delayMs: 3000, }); export async function handler(event: any) { await client.connect(); const result = await client.query('SELECT 1+1 AS result'); await client.clean(); return { statusCode: 200, body: JSON.stringify({ message: result.rows[0] }), }; }

Debug

Known issues

breakingIn v2, connection filtering by application_name is introduced. Old clients without application_name may have their connections terminated by clean().

fix

Update existing clients to set application_name explicitly, or use v1.x if filtering is not desired.

affects: >=2.0.0

deprecatedThe .clean() method's behavior changed in v2: it now filters connections by application_name. The old behavior without filtering is deprecated.

fix

If you rely on clean() to kill all idle connections without filtering, set application_name to null or adjust configuration.

affects: >=2.0.0

gotchaThe library sets 'serverless-postgres' as default application_name, which may conflict with other services using the same name.

fix

Set a custom application_name in client config to avoid naming collisions.

affects: >=2.0.0

gotchaUsing .setConfig() after client creation does not apply to existing connections; it only affects subsequent .connect() calls.

fix

Set configuration before calling .connect(), or call .connect() again after .setConfig().

affects: >=1.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL server is not running or port is wrong.

fix

Ensure PostgreSQL is running and correct host/port are supplied.

error: sorry, too many clients already

PostgreSQL max_connections limit reached, often due to unclosed connections.

fix

Ensure client.clean() is called after each invocation. Increase max_connections if needed. Use connection filtering (v2+).

Cannot find module 'pg'

The peer dependency pg is not installed.

fix

Run npm install pg

Upgrade

Version history

2.1.2latest on npm

Audit

Dependencies

pgrequiredWrapper around node-postgres for query execution and connection management

Agent activity

6 hits · last 30 days

node