pg-cache

library3.12.0jsnpmunverified

PostgreSQL connection pool with built-in LRU cache management for Node.js. Version 3.12.0 provides a hybrid pool+cache layer that maintains connections via pg-pool while caching query results using an LRU strategy with configurable TTL and max entries. It automatically evicts stale data, supports parameterized queries, and integrates with TypeScript. Compared to raw pg-pool, pg-cache adds transparent result caching and cache invalidation hooks, reducing repeated DB hits without requiring a separate cache like Redis. Released under active development with monthly updates.

database

npm install pg-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-CACHE

pg-cache

databasejavascriptv3.12.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.

PGCache

✓ import { PGCache } from 'pg-cache'

✗ import PGCache from 'pg-cache'

PGCache is a named export, not default. ESM only since v3.

createPool

✓ import { createPool } from 'pg-cache'

✗ const createPool = require('pg-cache').createPool

CJS require not supported in v3+. Use dynamic import() if needed.

PGCacheOptions

✓ import type { PGCacheOptions } from 'pg-cache'

TypeScript type import, available since v3.10. Use import type for transpile-only.

Creates a PGCache instance with connection pool and LRU cache, performs parameterized queries with automatic caching, demonstrates cache eviction and cleanup.

import { PGCache } from 'pg-cache'; const cache = new PGCache({ pool: { connectionString: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost/db', max: 10 }, cache: { max: 100, ttl: 60_000 } }); async function main() { const query = 'SELECT * FROM users WHERE id = $1'; const params = [1]; // First call - cache miss const result1 = await cache.query(query, params); console.log('First query result:', result1.rows); // Second call - cache hit within TTL const result2 = await cache.query(query, params); console.log('Cached result:', result2.rows); // Force evict specific key cache.del(query, params); // Clear entire cache cache.clear(); // Close pool await cache.end(); } main().catch(console.error);

Debug

Known issues

breakingPGCache is now exported as a named export instead of default export.

fix

Change import { PGCache } from 'pg-cache' (was import PGCache from 'pg-cache').

affects: >=3.0.0

breakingCJS require() no longer supported; package is ESM-only.

fix

Use dynamic import: const { PGCache } = await import('pg-cache').

affects: >=3.0.0

breakingThe 'cache' option now requires explicit 'max' and 'ttl' properties; defaults changed.

fix

Provide cache: { max: number, ttl: number }. Previously defaulted to infinite.

affects: >=2.5.0

deprecatedPGCache constructor's 'pool' option as a pg.Pool instance is deprecated; use pool config object instead.

fix

Pass pool configuration object (e.g., { connectionString, max }) instead of a Pool instance.

affects: >=3.2.0

gotchaQuery cache key is generated from the query string and parameters. Order of parameters matters.

fix

Ensure consistent parameter ordering for cache hits. Use named parameters with placeholder $1, $2, etc.

affects: >=1.0.0

gotchaTTL is checked on access; stale entries are not automatically purged until queried.

fix

Set max cache size to limit memory usage. Call evictStale() periodically if needed.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: pg_cache_1.PGCache is not a constructor

Trying to import PGCache as default export (import PGCache from 'pg-cache') instead of named export.

fix

Use import { PGCache } from 'pg-cache'.

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Using require('pg-cache') in a CommonJS module; package is ESM-only since v3.

fix

Use dynamic import() or switch project to ESM (e.g., set type:"module" in package.json).

Expired cached entry returned despite clear TTL

Cache TTL is checked on access only; stale entries remain until an explicit get() or eviction.

fix

Call cache.evictStale() before query or rely on max size to automatically evict oldest entries.

Peer dependency 'lru-cache' not found

Missing lru-cache package in dependencies. pg-cache requires lru-cache as a peer or direct dependency.

fix

Run npm install lru-cache or update package.json to include it.

Upgrade

Version history

3.12.0latest on npm

Audit

Dependencies

pg-poolrequiredunderlying connection pooling

lru-cacherequiredLRU cache implementation for results

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/constructive-io/constructive ↗

packagepg-cache ↗

homepagehttps://github.com/constructive-io/constructive ↗