possu

library3.0.0jsnpmunverified

A small companion library for node-postgres that reduces boilerplate by using tagged template literals for SQL queries, with automatic result row/column unwrapping. Current stable version 3.0.0, released periodically. Key differentiators: Promise-based API, runtime SQL injection prevention via tagged templates, built-in transaction and savepoint handling with retry on serialization failures/deadlocks, first-class TypeScript support, and not a framework – works directly with pg.Pool/pg.PoolClient.

database

npm install possu

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSSU

possu

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

sql

✓ import { sql } from 'possu'

✗ const sql = require('possu').sql

ESM-only since v3. Use default import for CommonJS: const possu = require('possu'); const { sql } = possu;

query

✓ import { query } from 'possu'

✗ import query from 'possu'

query is a named export, not default.

withTransaction

✓ import { withTransaction } from 'possu'

✗ const withTransaction = require('possu').withTransaction

Named export. CommonJS usage: const { withTransaction } = require('possu');

queryOne

✓ import { queryOne } from 'possu'

Throws if no rows returned.

queryMaybeOne

✓ import { queryMaybeOne } from 'possu'

Returns row or undefined.

Shows a basic query selecting one row by id using tagged template literal and automatic unwrapping.

import { Pool } from 'pg'; import { query, queryMaybeOne, sql } from 'possu'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? '' }); async function getUser(id: number) { const client = await pool.connect(); try { const user = await queryMaybeOne(client, sql`SELECT * FROM users WHERE id = ${id}`); console.log(user?.name ?? 'Not found'); } finally { client.release(); } } getUser(1).catch(console.error);

Debug

Known issues

breakingpossu v3 drops CommonJS support – only ESM imports work. require() will fail.

fix

Use import syntax and set type: 'module' in package.json, or use dynamic import().

affects: >=3.0.0

breakingThe `sql` function no longer accepts string concatenation – must be used as a tagged template literal. Passing a plain string will throw at runtime.

fix

Use sql`SELECT * FROM users` instead of sql('SELECT * FROM users')

affects: >=1.0.0

deprecatedThe `queryOne` function without specifying column name may be deprecated in future. Use explicit column selection in SQL.

fix

Prefer sql`SELECT name FROM users` and let possu unwrap automatically.

affects: >=2.0.0

gotchaAsync generators (for-await-of) are not supported; query results are arrays, not iterables.

fix

Use for (const row of result) instead of for await (const row of result).

affects: >=1.0.0

gotchaNested `sql` calls can lead to unexpected parameter numbering if not used carefully. Each `sql` tag creates independent numbered placeholders.

fix

Always combine nested sql calls as arguments to parent sql tag – not concatenated strings.

affects: >=1.0.0

Errors

Common errors & fixes

Error: sql is not a function

Using sql as a regular function instead of a tagged template literal, or importing incorrectly (named vs default).

fix

Use sql`...` syntax or import { sql } from 'possu'.

TypeError: pool.query is not a function

Passing a PoolClient or Pool directly to query instead of using the pool's query method.

fix

Call query(poolClient, sql`...`) – possu expects a client/pool as first argument, not the pool's method.

Cannot find module 'possu'

Package not installed, or using CommonJS require with ESM-only package (v3+).

fix

Install with npm install possu, and use import syntax. For older Node, use dynamic import or downgrade to v2.

Error: The query must be created with the sql tag

Passing a raw string instead of a SqlQuery object to query/execute functions.

fix

Wrap your SQL string with sql`...`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

pgrequiredPeer dependency – possu is built on and expects node-postgres Pool/Client instances.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/sluukkonen/possu ↗

packagepossu ↗

homepagehttps://github.com/sluukkonen/possu ↗