simple-postgres

library5.0.0jsnpmunverified

A minimal PostgreSQL interface for Node.js (v5.0.0) that eliminates boilerplate by automatically connecting via the DATABASE_URL environment variable. It provides a small set of helper functions (query, rows, row, value, column) with automatic parameterization to prevent SQL injection, and supports template string queries for readability. Simple-postgres focuses on simplicity: no ORM, no query builder, no connection pool configuration, and no initialization required. It is trusted in production and has good test coverage. Alternative to node-postgres but with a much smaller API surface.

database

npm install simple-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIMPLE-POSTGRES

simple-postgres

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

default

✓ import db from 'simple-postgres'

✗ const db = require('simple-postgres');

simple-postgres is ESM-only since v5.0.0. CommonJS require() will error.

query

✓ import db from 'simple-postgres'; db.query(...)

✗ import { query } from 'simple-postgres';

The default export is an object with all methods. Named imports are not available.

identifier

✓ import db from 'simple-postgres'; db.identifier('table_name')

✗ import { identifier } from 'simple-postgres';

db.identifier is a method on the default export, not a standalone named export.

Shows basic usage: setting up, inserting, querying rows/values, and template string mode.

import db from 'simple-postgres' // Ensure DATABASE_URL is set, e.g., postgres://user:pass@localhost/mydb // Insert a row safely await db.query('INSERT INTO accounts (name) VALUES ($1)', ['ACME']) // Query rows let accounts = await db.rows('SELECT * FROM accounts') console.log(accounts) // Query single row let account = await db.row('SELECT * FROM accounts WHERE id = $1', [1]) console.log(account.name) // Query single value let count = await db.value('SELECT COUNT(*) FROM accounts') console.log(count) // Template string mode (no parentheses around backticks) let type = 'pancake' let result = await db.value` SELECT COUNT(*) FROM breakfast WHERE type = ${type} ` console.log(result)

Debug

Known issues

breakingsimple-postgres v5.0.0 is ESM-only. CommonJS require() will throw an error.

fix

Use import syntax (import db from 'simple-postgres') or switch to dynamic import().

affects: >=5.0.0

gotchaDo NOT use parentheses around template string literals. db.value(`SELECT ... ${var}`) treats the template as a regular string and will not properly parameterize the query, leading to SQL injection.

fix

Use template literals without parentheses: db.value`SELECT ... ${var}`

affects: >=1.0.0

gotchadb.row() does not automatically add LIMIT 1. If the query returns multiple rows, only the first is returned, but no error is thrown.

fix

Explicitly add LIMIT 1 to your SQL query if you expect only one row.

affects: >=1.0.0

deprecatedThe DATABASE_URL environment variable is the only supported configuration. There is no support for connection pooling, custom credentials, or multiple databases.

fix

Set DATABASE_URL before running your application. For advanced config, consider using node-postgres directly.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find package 'simple-postgres' imported from ...

Module not installed or ESM-only package used via CommonJS require().

fix

Run 'npm install simple-postgres' and ensure your project uses ES modules (type: 'module' in package.json or use .mjs extension).

TypeError: db.query is not a function

Using named import ({ query }) instead of default import.

fix

Use 'import db from 'simple-postgres'' instead of 'import { query } from 'simple-postgres''.

Error: connect ECONNREFUSED 127.0.0.1:5432

DATABASE_URL not set or database not running.

fix

Set the DATABASE_URL environment variable or ensure PostgreSQL is running on localhost:5432.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

pgrequiredsimple-postgres uses the `pg` module under the hood for all PostgreSQL connectivity.

Agent activity

11 hits · last 30 days

node