{"id":43572,"library":"pg-query-stream","title":"pg-query-stream","description":"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.","status":"active","version":"4.15.0","language":"javascript","source_language":"en","source_url":"git://github.com/brianc/node-postgres","tags":["javascript","postgres","query-stream","pg","query","stream","typescript"],"install":[{"cmd":"npm install pg-query-stream","lang":"bash","label":"npm"},{"cmd":"yarn add pg-query-stream","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-query-stream","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; must be installed alongside pg-query-stream to provide the PostgreSQL client.","package":"pg","optional":false}],"imports":[{"note":"Default export (ESM). CommonJS users should use const QueryStream = require('pg-query-stream').","wrong":"import { QueryStream } from 'pg-query-stream'","symbol":"QueryStream","correct":"import QueryStream from 'pg-query-stream'"},{"note":"CommonJS: pg-query-stream exports as a constructor, not a named export.","wrong":"const { QueryStream } = require('pg-query-stream')","symbol":"QueryStream","correct":"const QueryStream = require('pg-query-stream')"}],"quickstart":{"code":"import pg from 'pg';\nimport QueryStream from 'pg-query-stream';\nimport JSONStream from 'JSONStream';\n\nconst pool = new pg.Pool();\n\npool.connect((err, client, done) => {\n  if (err) throw err;\n  const query = new QueryStream('SELECT * FROM generate_series(0, $1) num', [1000000]);\n  const stream = client.query(query);\n  stream.on('end', done);\n  stream.pipe(JSONStream.stringify()).pipe(process.stdout);\n});","lang":"typescript","description":"Shows how to stream a large query result to stdout without blowing up memory."},"warnings":[{"fix":"Ensure you are using the JavaScript client by requiring 'pg' or 'pg.js' explicitly.","message":"pg-query-stream does not work with the native pg bindings (pg.native).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always attach a data listener or pipe the stream. Use the 'end' event to release the client via the done callback.","message":"The stream must be consumed; otherwise the client will hang and the pool connection will not be released.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your PostgreSQL version is 8.2+ and the connection does not use a connection-string parameter that disables cursors.","message":"QueryStream requires a PostgreSQL server that supports cursors (version 8.2 or later).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use stream.destroy() or handle errors/early exits to close the stream properly.","message":"If the stream is not fully consumed, the underlying cursor may not be closed, causing resource leaks.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'4.15.0':53 '8':47 'activ':57 'bind':99 'consum':36 'cursor':28 'data':77 'dataset':85 'effici':30 'etl':75 'excess':37 'export':78 'handl':31 'ideal':73 'integr':40 'interfac':19 'javascript':100 'larg':32,84 'librari':12,45 'limit/offset':63 'maintain':58 'make':71 'manual':60 'memori':38 'nativ':97 'node.js':11 'object':17 'pagin':61 'pg':2,6,44,98,105 'pg-query-stream':1,5 'pipelin':76 'popular':43 'postgr':101 'postgresql':21 'process':83 'provid':14 'queri':3,7,22,103,106 'query-stream':102 'readabl':16 'real':69 'real-tim':68 'requir':90 'result':23,33 'row':66,86,88 'scenario':81 'server':26 'server-sid':25 'set':34 'side':27 'stabl':55 'stream':4,8,18,65,104,107 'support':49 'time':70 'type':51 'typescript':50,108 'unlik':59 'use':24 'version':46,52 'without':35 'work':94","created_at":"2026-06-05T17:00:26.924327+00:00","updated_at":"2026-06-05T17:00:26.924327+00:00","problems":[{"fix":"Run: npm install pg-query-stream","cause":"Missing dependency; pg-query-stream is not installed.","error":"Error: Cannot find module 'pg-query-stream'"},{"fix":"Ensure you do not call client.query() more than once per stream. Reuse the same QueryStream instance.","cause":"The stream was already ended but additional data was pushed, typically due to multiple calls to streaming methods.","error":"Error: stream.push() after EOF"},{"fix":"ESM: import QueryStream from 'pg-query-stream'. CJS: const QueryStream = require('pg-query-stream').","cause":"Using a named import instead of default import in ESM, or destructuring require in CommonJS.","error":"TypeError: QueryStream is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/brianc/node-postgres#readme","github":"git://github.com/brianc/node-postgres","docs":null,"changelog":null,"pypi":null,"npm":"pg-query-stream","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}