@inteli.city/node-red-contrib-postgres-async-pg 1.0.1

Node-RED node for async PostgreSQL query execution with concurrency control and Nunjucks templating

npm install @inteli.city/node-red-contrib-postgres-async-pg

async.pg — Node-RED PostgreSQL Async Node

A Node-RED node for executing PostgreSQL queries with controlled concurrency and Nunjucks templating.

Index

1. Overview
2. Features
3. Installation
4. Configuration
5. Usage
6. Templating (Nunjucks)
7. Concurrency Model
8. Message Flow
9. Status Indicator
10. Error Handling
11. Design Principles

1. Overview

async.pg executes a SQL query for each incoming message.

It is designed to:

• control database concurrency
• avoid hidden queues
• provide predictable execution

2. Features

• Asynchronous query execution
• Configurable concurrency limit
• Internal FIFO queue
• Nunjucks-based SQL templating
• PostgreSQL connection pooling (aligned with concurrency)
• Real-time execution status

3. Installation

npm install @inteli.city/node-red-contrib-postgres-async-pg

Or via the Node-RED palette manager, search for async-pg.

4. Configuration

Database config node (postgresDB)

Node properties (async.pg)

5. Usage

1. Add a postgresDB config node with your connection details.
2. Drop an async.pg node onto your flow.
3. Connect it to a postgresDB config node.
4. Write your SQL query in the editor (Nunjucks templating supported).
5. Connect an input and an output node.

On each incoming message, the node renders the SQL template against msg, executes the query, and sets msg.payload to the result rows before forwarding the message.

6. Templating (Nunjucks)

The SQL query is rendered using Nunjucks with the entire msg object as the template context.

SELECT * FROM orders WHERE id = {{ payload.id }};

INSERT INTO events (name, ts)
VALUES ('{{ topic }}', NOW());

Any property on msg is accessible directly by name.

7. Concurrency Model

Max Concurrency is the single source of truth for concurrency in this node.

• It defines how many queries run in parallel.
• The internal PostgreSQL connection pool is sized to the same value (pool.max = maxConcurrency).
• Excess messages are held in an internal FIFO queue and dispatched as slots become free.

This guarantees:

There is no independent pool configuration. The pool is an implementation detail.

8. Message Flow

msg arrives
    │
    ▼
enqueued (FIFO)
    │
    ▼ (slot available)
SQL rendered via Nunjucks
    │
    ▼
query executed
    │
    ▼
msg.payload = result.rows
    │
    ▼
msg forwarded

9. Status Indicator

The node status always follows the format:

<queued> (<running>/<maxConcurrency>)

10. Error Handling

• On query error, node.error(err, msg) is called with the original message.
• The node remains active — the queue continues processing subsequent messages.
• Pool-level errors are also reported via node.error.

11. Design Principles

• Predictability over flexibility — one concurrency knob, no hidden limits.
• No silent buffering — the queue is visible in the status indicator at all times.
• Fail loudly — errors surface immediately via node.error, never swallowed.
• Minimal footprint — no retries, no fallbacks, no extra abstractions.