pg-tx

library1.0.1jsnpmunverified

Transaction wrapper for node-postgres that prevents use-after-release bugs by wrapping the client in a Proxy. Current version 1.0.1, released in 2021. Unlike naive implementations based on Stack Overflow answers, pg-tx throws an error if you attempt to use the client after the transaction ends. Supports automatic savepoints for nested transactions and works with both Pool and PoolClient. Ships TypeScript types. Lightweight with zero dependencies.

database

npm install pg-tx

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-TX

pg-tx

databasejavascriptv1.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.

default export (tx)

✓ import tx from 'pg-tx'

✗ const { tx } = require('pg-tx')

Default export only. Named import will be undefined.

tx function

✓ import tx from 'pg-tx'

✗ import { tx } from 'pg-tx'

Default export is the tx function. Named import is wrong.

TypeScript usage with Pool

✓ import tx from 'pg-tx'; import { Pool } from 'pg'; const pool = new Pool(); await tx(pool, async (db) => { ... })

✗ import * as tx from 'pg-tx'

Works with Pool or PoolClient. The callback receives a proxied client.

Shows basic usage of pg-tx with a Pool transaction transferring funds between accounts.

import tx from 'pg-tx'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.POSTGRES_URL ?? '' }); async function transferFunds(from: string, to: string, amount: number) { await tx(pool, async (db) => { await db.query( 'UPDATE accounts SET balance = balance - $1 WHERE name = $2', [amount, from] ); await db.query( 'UPDATE accounts SET balance = balance + $1 WHERE name = $2', [amount, to] ); }); } transferFunds('Alice', 'Bob', 100).catch(console.error);

Debug

Known issues

gotchaThe callback client (db) is a Proxy that throws on use after the transaction ends. Do NOT store the db reference for later use.

fix

Always use db inside the callback and never keep a reference after the transaction completes.

affects: >=1.0.0

gotchaNested transactions automatically use savepoints. You cannot use BEGIN/COMMIT/ROLLBACK inside a transaction callback; use nested tx() calls instead.

fix

For nested transactions, just call tx(db, ...) inside the callback — it will create a savepoint.

affects: >=1.0.0

gotchaThe db parameter is NOT a PoolClient but a ProxyClient. It shares the same interface but has additional guards. Do not rely on instanceof checks.

fix

Treat db as a PoolClient; it implements the same query, release, etc. methods.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'query')

Importing named export instead of default

fix

Replace 'import { tx } from 'pg-tx'' with 'import tx from 'pg-tx''

TypeError: db is not a function

Attempting to call db as a function instead of using db.query

fix

Use db.query(...) or db.connect() etc. db is an object, not a function.

Error: Client has already been released

Attempting to use the db object after the transaction callback has returned

fix

Move all queries inside the callback. Do not pass db to Promises that outlive the callback.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/golergka/pg-tx ↗

packagepg-tx ↗

homepagehttps://github.com/golergka/pg-tx#readme ↗