pgdb-queue

library1.1.2jsnpmunverified

pgdb-queue v1.1.2 is a lightweight, Kafka-style asynchronous message queue built on PostgreSQL, eliminating the need for Kafka, Redis, or additional infrastructure. It uses PostgreSQL's LISTEN/NOTIFY for efficient, zero-polling wake-ups after draining, and row-level locking with FOR UPDATE SKIP LOCKED for concurrency. The library is ideal for startups or small apps needing reliable background processing with minimal operational overhead. It ships TypeScript types and provides a simple producer/consumer API with automatic retries and FIFO ordering.

messaging

npm install pgdb-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGDB-QUEUE

pgdb-queue

messagingjavascriptv1.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.

initQueue

✓ import { initQueue } from 'pgdb-queue'

✗ const initQueue = require('pgdb-queue').initQueue

ESM-only; CommonJS require must use default import or named property access.

produce

✓ import { produce } from 'pgdb-queue'

✗ const produce = require('pgdb-queue').produce

Named export; use destructured import in ESM.

startConsumer

✓ import { startConsumer } from 'pgdb-queue'

✗ import startConsumer from 'pgdb-queue'

startConsumer is a named export, not default. TypeScript users must use named import.

Demonstrates initializing the queue, producing a JSON message, and starting a continuous consumer with auto-wake via LISTEN/NOTIFY.

import { initQueue, produce, startConsumer } from 'pgdb-queue'; // Initialize queue (table autocreated) await initQueue( process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb', 'public.message_queue' ); // Produce a message await produce('email-topic', JSON.stringify({ to: 'user@example.com', subject: 'Welcome!' })); // Start consumer with auto-wake await startConsumer('email-topic', async (msg: string, id: number) => { const data = JSON.parse(msg); console.log(`Processing message ${id}:`, data); }, { rateLimitMs: 10 });

Debug

Known issues

gotchaMessages must be string type; use JSON.stringify for non-string data.

fix

Wrap objects with JSON.stringify() before producing.

affects: >=1.0.0

gotchainitQueue must be called before any produce/consume/startConsumer.

fix

Ensure initQueue is awaited exactly once at startup.

affects: >=1.0.0

gotchaTable name must include schema (e.g., 'public.my_queue'), not just table name.

fix

Use 'schema.table' format when passing table name to initQueue.

affects: >=1.0.0

deprecatedconsume() is a manual consumer; prefer startConsumer() for continuous processing.

fix

Use startConsumer() for automatic wake and drainage.

affects: >=1.0.0

Errors

Common errors & fixes

Error: listen is not a function

Missing or incorrect pg client version or pool not initialized via initQueue.

fix

Ensure initQueue completes before any other operations.

error: relation "public.message_queue" does not exist

initQueue was not called or table creation failed due to missing schema.

fix

Call await initQueue(...) with correct schema-qualified table name.

TypeError: Cannot read properties of undefined (reading 'query')

initQueue failed or pool not initialized.

fix

Check database connection string and ensure initQueue resolves successfully.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client driver required for database connectivity

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/SHIVAJIKUMAR007/dbqueue ↗

packagepgdb-queue ↗

homepagehttps://github.com/SHIVAJIKUMAR007/dbqueue#readme ↗