πŸš€ Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more β†’
Socket
DemoInstallSign in
Socket

pgdb-queue

Package Overview
Dependencies
Maintainers
1
Versions
22
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

pgdb-queue

Asynchronous messaging queue using Postgres database.

1.1.2
latest
Source
npm
Version published
Weekly downloads
183
-82.54%
Maintainers
1
Weekly downloads
Β 
Created
Source

pgdb-queue

A lightweight Kafka-style queue built using a PostgreSQL database. Designed for simplicity, performance, and low cost β€” no need for Kafka, Redis, or additional infrastructure.

Ideal for startups and small apps that need reliable background task processing without operational overhead.

πŸš€ Features

  • βœ… Kafka-like producer/consumer API
  • βœ… Uses PostgreSQL for persistence
  • βœ… Efficient LISTEN/NOTIFY-based message wake-up
  • βœ… Zero-polling after queue is drained (saves DB read costs)
  • βœ… Row-level locking using FOR UPDATE SKIP LOCKED
  • βœ… Automatic retries for failed messages
  • βœ… FIFO message ordering
  • βœ… Minimal setup

πŸ“¦ Installation

npm install pgdb-queue

πŸ› οΈ Setup

Before producing or consuming messages, initialize the queue:

import { initQueue } from "pgdb-queue";

await initQueue(
  "postgres://user:password@host:port/database",
  "schemaName.tableName"
);

This sets up the connection pool and ensures the message_queue table exists.

πŸ“€ Producing Messages

import { produce } from "pgdb-queue";

await produce(
  "email-topic",
  JSON.stringify({
    to: "user@example.com",
    subject: "Welcome!",
  })
);

The message must be a string. Use JSON.stringify() to send structured data.

Parameters:

  • topic: string
  • message: string (recommended: JSON.stringify(object))

πŸ“₯ Consume a Single Message (Manual)

This gives you full control (useful in cron jobs or custom workers):

import { consume } from "pgdb-queue";

await consume("email-topic", async (msg, id) => {
  const data = JSON.parse(msg);
  console.log("Received:", data);
  // Your message handler logic
});

πŸ” startConsumer: Auto-Wake Continuous Consumer

Automatically listens for new messages and drains the queue efficiently:

import { startConsumer } from "pgdb-queue";

await startConsumer(
  "email-topic",
  async (msg, id) => {
    const data = JSON.parse(msg);
    console.log("Processing:", data);
    // Your message handler logic
  },
  {
    rateLimitMs: 10,
  }
);

How it saves DB read costs

  • Uses PostgreSQL’s LISTEN/NOTIFY to be notified only when a new message is inserted.
  • Drains messages until the queue is empty.
  • Once the queue is empty, it stops polling β€” and resumes only when a new message is pushed.

No setInterval polling = minimal read overhead.

Perfect for scalable background jobs with low or bursty volume.

πŸ—ƒοΈ Table Schema

The following table is automatically created (if missing):

CREATE TABLE IF NOT EXISTS schemaName.tableName (
  id SERIAL PRIMARY KEY,
  topic TEXT NOT NULL,
  message TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'queued',
  retry_count INTEGER NOT NULL DEFAULT 0,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX  IF NOT EXISTS idx_topic_status ON schemaName.tableName (topic, status);

message is stored as TEXT.

βš™οΈ Roadmap

Planned features:

  • ⏳ Delayed message delivery
  • βš–οΈ Per-topic concurrency limit
  • πŸ‘€ Visibility timeouts
  • πŸ’€ Dead-letter queue for persistent failures

πŸ§ͺ Example Use Cases

  • πŸ“§ Email sending
  • πŸ” Webhook dispatching
  • 🧾 Background jobs (e.g. invoice generation)
  • πŸ”— Microservice coordination
  • πŸ“² Simple job queue for frontend apps (via API)

πŸ“„ License

MIT License
Β© 2025 Shivaji Kumar

Keywords

queue

FAQs

Package last updated on 29 May 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts