tinypg

library7.0.1jsnpmunverified

Lightweight PostgreSQL client for Node.js that loads SQL from files and uses named parameters with object binding. Current stable version is 7.0.1 (released 2023), maintained actively with monthly patches. Key differentiators: no SQL generation, supports named parameters via colon-prefixed syntax (e.g., :param), automatic parameter validation, transaction support with automatic commit/rollback, and TypeScript types. Requires peer dependency pg (^8.0.0). Ideal for teams that prefer writing raw SQL files over ORMs or query builders.

database

npm install tinypg

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TINYPG

tinypg

databasejavascriptv7.0.1

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.

TinyPg

✓ import { TinyPg } from 'tinypg'

✗ const TinyPg = require('tinypg')

ESM-only since v7; CommonJS require will cause runtime error. Types bundled.

TinyPg (default import)

✓ import TinyPg from 'tinypg'

✗ import { TinyPg } from 'tinypg'

Default import is the class itself. Named import also works but ESM best practice is default.

TinyPgOptions (type)

✓ import type { TinyPgOptions } from 'tinypg'

✗ import { TinyPgOptions } from 'tinypg'

Type-only import to avoid runtime overhead. Only needed for TypeScript.

Create a TinyPg instance using default env vars, run a parameterized query, and log results.

import TinyPg from 'tinypg'; import pg from 'pg'; // Ensure pg is configured (usually via environment variables) const db = new TinyPg(); async function main() { const result = await db.query( `SELECT :name AS greeting`, { name: 'World' } ); console.log(result.rows); // => [ { greeting: 'World' } ] } main().catch(console.error);

Debug

Known issues

breakingVersion 7 dropped CommonJS support; require() will throw 'ERR_REQUIRE_ESM'

fix

Use ESM imports (import or dynamic import()) or stick with tinypg 6.x if CommonJS needed.

affects: >=7.0.0

gotchaNamed parameters use colon syntax (:param), not Postgres $1/$2; mixing both causes unexpected parameter binding

fix

Always use :param in SQL strings. Do not use $1 style placeholders.

affects: >=0.0.0

gotchaParameter validation throws on extra keys in the parameters object; does not ignore unmatched parameters

fix

Ensure the parameters object contains only the keys referenced in the SQL.

affects: >=0.0.0

deprecatedThe .query() method without file loading is not deprecated but .sql() is preferred for file-based queries

fix

Use db.sql('file.key', params) for maintainable SQL files.

affects: all

gotchaTransaction callback receives a new TinyPg instance bound to the same connection; using original db within transaction will not be in the transaction context

fix

Always use the transaction-specific database instance passed to the callback.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'tinypg'

Package not installed or missing peer dependency 'pg'

fix

Run: npm install tinypg pg

TypeError: TinyPg is not a constructor

Using CommonJS require with ESM-only package (v7+)

fix

Use import statement or switch to tinypg v6.x: npm install tinypg@6

Error: Unknown parameter: :unknownParam

SQL contains :unknownParam but no corresponding key in parameters object

fix

Add the missing key to the parameters object or remove the placeholder from SQL.

Error: Parameter :someParam was not used in SQL

Parameters object contains key that doesn't appear in the SQL

fix

Remove the unused key from the parameters object.

Upgrade

Version history

7.0.1latest on npm

Audit

Dependencies

pgrequiredPeer dependency; provides the underlying PostgreSQL client driver

Agent activity

14 hits · last 30 days

node