pg-query-stream

library4.15.0jsnpmunverified

pg-query-stream is a Node.js library that provides a readable object stream interface for PostgreSQL query results, using server-side cursors to efficiently handle large result sets without consuming excessive memory. It integrates with the popular 'pg' library (version 8+) and supports TypeScript types. Version 4.15.0 is stable and actively maintained. Unlike manual pagination with LIMIT/OFFSET, it streams rows in real-time, making it ideal for ETL pipelines, data exports, or any scenario where processing large datasets row by row is required. It does not work with the native pg bindings.

database

npm install pg-query-stream

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-QUERY-STREAM

pg-query-stream

databasejavascriptv4.15.0

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.

QueryStream

✓ import QueryStream from 'pg-query-stream'

✗ import { QueryStream } from 'pg-query-stream'

Default export (ESM). CommonJS users should use const QueryStream = require('pg-query-stream').

QueryStream

✓ const QueryStream = require('pg-query-stream')

✗ const { QueryStream } = require('pg-query-stream')

CommonJS: pg-query-stream exports as a constructor, not a named export.

Shows how to stream a large query result to stdout without blowing up memory.

import pg from 'pg'; import QueryStream from 'pg-query-stream'; import JSONStream from 'JSONStream'; const pool = new pg.Pool(); pool.connect((err, client, done) => { if (err) throw err; const query = new QueryStream('SELECT * FROM generate_series(0, $1) num', [1000000]); const stream = client.query(query); stream.on('end', done); stream.pipe(JSONStream.stringify()).pipe(process.stdout); });

Debug

Known issues

gotchapg-query-stream does not work with the native pg bindings (pg.native).

fix

Ensure you are using the JavaScript client by requiring 'pg' or 'pg.js' explicitly.

affects: >=1.0.0

gotchaThe stream must be consumed; otherwise the client will hang and the pool connection will not be released.

fix

Always attach a data listener or pipe the stream. Use the 'end' event to release the client via the done callback.

affects: >=1.0.0

gotchaQueryStream requires a PostgreSQL server that supports cursors (version 8.2 or later).

fix

Ensure your PostgreSQL version is 8.2+ and the connection does not use a connection-string parameter that disables cursors.

affects: >=1.0.0

gotchaIf the stream is not fully consumed, the underlying cursor may not be closed, causing resource leaks.

fix

Use stream.destroy() or handle errors/early exits to close the stream properly.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pg-query-stream'

Missing dependency; pg-query-stream is not installed.

fix

Run: npm install pg-query-stream

Error: stream.push() after EOF

The stream was already ended but additional data was pushed, typically due to multiple calls to streaming methods.

fix

Ensure you do not call client.query() more than once per stream. Reuse the same QueryStream instance.

TypeError: QueryStream is not a constructor

Using a named import instead of default import in ESM, or destructuring require in CommonJS.

fix

ESM: import QueryStream from 'pg-query-stream'. CJS: const QueryStream = require('pg-query-stream').

Upgrade

Version history

4.15.0latest on npm

Audit

Dependencies

pgrequiredPeer dependency; must be installed alongside pg-query-stream to provide the PostgreSQL client.

Agent activity

8 hits · last 30 days

node

Resources

githubgit://github.com/brianc/node-postgres ↗

packagepg-query-stream ↗

homepagehttps://github.com/brianc/node-postgres#readme ↗