postgres-extended

library1.1.3jsnpmunverified

Sweet API wrapper for Postgres on top of `pg-pool`. Provides a higher-level query builder with array and object interpolation, plus table helpers for insert, upsert, and update operations. Version 1.1.3 is the current stable. Release cadence is irregular. Key differentiators: simple API, built-in upsert with conflict handling, and automatic connection pooling via pg-pool. Lightweight alternative to ORMs like Prisma or Sequelize for straightforward database interactions.

database

npm install postgres-extended

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTGRES-EXTENDED

postgres-extended

databasejavascriptv1.1.3

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.

Postgres

✓ import Postgres from 'postgres-extended'

✗ const Postgres = require('postgres-extended')

ESM-only; no default CommonJS export.

database

✓ const { database } = Postgres({...})

✗ const database = Postgres({...})

Postgres returns an object with database and close.

✓ const { close } = Postgres({...})

✗ Postgres({...}).close()

Destructure close from the returned object.

Establishes a connection to Postgres, performs a parameterized query, inserts a row, upserts a row with conflict handling, then closes the pool.

import Postgres from 'postgres-extended'; const { database, close } = Postgres({ host: process.env.PG_HOST ?? 'localhost', port: process.env.PG_PORT ?? 5432, user: process.env.PG_USER ?? 'postgres', password: process.env.PG_PASSWORD ?? '', database: process.env.PG_DATABASE ?? 'test', }); const users = await database.query(` SELECT * FROM users WHERE userId = $1 `, ['1']); const inserted = await database.table('users').insert({ userId: '2', name: 'Alice', }); const upserted = await database.table('users').upsert({ userId: '3', name: 'Bob', email: 'bob@example.com', }, { conflictTarget: 'userId', }); await close();

Debug

Known issues

gotchaThe `database` object returned from `Postgres()` is not a pool; you must call `close()` to release resources.

fix

Always await `close()` when done, preferably in a `finally` block.

affects: >=1.0

gotchaUsing `upsert` without specifying `conflictTarget` will throw an error.

fix

Always include `conflictTarget` in the upsert options object.

affects: >=1.0

gotchaInterpolation style must match the query: use `$1` for array parameters and `@name` for object parameters. Mixing them will cause unexpected results.

fix

Ensure the query uses only one style consistent with the passed parameters.

affects: >=1.0

gotchaThe `insert` and `upsert` methods return an array of rows, not a count or object. If no rows are returned (e.g., due to a RETURNING clause mismatch), the array may be empty.

fix

Always check the length of the returned array before accessing its elements.

affects: >=1.0

Errors

Common errors & fixes

TypeError: Postgres is not a function

Importing incorrectly or using CommonJS require.

fix

Use `import Postgres from 'postgres-extended'` instead of require.

Error: conflictTarget is required for upsert

Missing or undefined conflictTarget in upsert options.

fix

Add `conflictTarget: 'columnName'` (or array) to the options object.

Error: connection pool is closed

Attempting to query after calling `close()`.

fix

Re-create the connection or ensure not to call `close()` before queries finish.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

pg-poolrequiredUnderlying connection pool for Postgres

pgrequiredRequired runtime dependency for Postgres connectivity

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/richytong/postgres ↗

packagepostgres-extended ↗

homepagehttps://github.com/richytong/postgres#readme ↗