Registry / devops / wait-for-postgres

wait-for-postgres

library1.5.3jsnpmunverified

A CLI tool and Node.js module that polls a PostgreSQL server until a connection succeeds or a custom query returns valid results. Version 1.5.3 is stable, with infrequent releases. It is lightweight (no production dependencies) and synchronous by default, distinguishing it from async-oriented alternatives like pg-pool or custom loops. Suitable for Docker entrypoints, CI scripts, and deployment automation.

devops

npm install wait-for-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WAIT-FOR-POSTGRES

wait-for-postgres

devopsjavascriptv1.5.3

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.

wait

✓ import { wait } from 'wait-for-postgres'

✗ import wait from 'wait-for-postgres'

Named export, not default. ESM requires Node >= 12 with 'type':'module' or .mjs extension.

wait

✓ const { wait } = require('wait-for-postgres')

✗ const wait = require('wait-for-postgres')

CommonJS destructuring required because module exports an object.

WaitForPostgres

✓ // No class export; use the 'wait' function directly

✗ const WaitForPostgres = require('wait-for-postgres').WaitForPostgres

This package has no class. Common error assuming a constructor.

Waits for Postgres to accept connections using environment variables for config.

const { wait } = require('wait-for-postgres'); const config = { username: process.env.PGUSER ?? 'postgres', password: process.env.PGPASSWORD ?? '', host: process.env.PGHOST ?? 'localhost', port: parseInt(process.env.PGPORT ?? '5432'), database: process.env.PGDATABASE ?? 'postgres', query: 'SELECT 1', quiet: false }; wait(config).then(() => { console.log('PostgreSQL is ready!'); }).catch((err) => { console.error('Failed to connect:', err); });

Debug

Known issues

breakingThe package waits indefinitely by default if never connected — no timeout option for the whole wait loop.

fix

Use a wrapper with setTimeout or kill the process externally.

affects: >=0.0.0

gotchaSensitive credentials (password) are exposed in process list if passed as CLI arguments.

fix

Use environment variables or a config file for passwords.

affects: >=0.0.0

deprecatedThe package does not support promise cancellation or AbortSignal.

fix

Use a more modern alternative like pg-pool or custom async loop with AbortController.

affects: <=1.5.3

gotchaThe 'query' option is run once after connection — failures cause the promise to reject, not retry.

fix

Ensure your query is idempotent and always succeeds on a valid connection.

affects: >=0.0.0

gotchaDoes not distinguish between connection errors and query errors — both reject the promise.

fix

Wrap wait() in additional error handling to differentiate.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'wait-for-postgres'

Package not installed or not in node_modules.

fix

Run 'npm install wait-for-postgres' in your project directory.

wait is not a function

Importing without destructuring CommonJS export.

fix

Use 'const { wait } = require('wait-for-postgres')'

ECONNREFUSED

PostgreSQL is not running or not accessible at the specified host:port.

fix

Verify your database is started and connection parameters (host, port) are correct.

Upgrade

Version history

1.5.3latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client used to connect and run queries

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/joeledwards/node-wait-for-postgres ↗

packagewait-for-postgres ↗

homepagehttps://github.com/joeledwards/node-wait-for-postgres#readme ↗