porsager /postgres
Postgres.js - The Fastest full featured PostgreSQL client
★ 8,767⑂ 408👁 45⑃ 313● 868▤ 49
+1
Daily
8,767
stars
408
forks
45
watchers
313
prs
868
issues
49
releases
README
- 🚀 Fastest full-featured PostgreSQL client
- 🏷 ES6 Tagged Template Strings at the core
- 🏄♀️ Simple surface API
- 🖊️ Dynamic query support
- 🐦 Follow on X
Getting started
Installation
bash
$ npm install postgres
Postgres.js needs Node.js 18 or later, Bun, or Cloudflare Workers. Deno runs it through its Node.js compatibility. It is an ES module with no dependencies.
Upgrading from v3? The API is the same apart from a short list of changes. Read Upgrading from v3 first: parameter types are now decided by the server, which changes how a Date is written to timestamp and date columns outside UTC.
Usage
Create your sql database instance
js
// db.js
import postgres from 'postgres'
const sql = postgres({ / options / }) // will use psql environment variables
export default sql
Simply import for use elsewhere
js
// users.js
import sql from './db.js'
async function getUsersOver(age) {
const users = await sql
select
name,
age
from users
where age ${ age }
// users = Result [{ name: "Walter", age: 80 }, { name: 'Murray', age: 68 }, ...]
return users
}
async function insertUser({ name, age }) {
const users = await sql
insert into users
(name, age)
values
(${ name }, ${ age })
returning name, age
// users = Result [{ name: "Murray", age: 68 }]
return users
}
Dynamic imports and CommonJS
js
const { default: postgres } = await import('postgres')
From CommonJS, on Node.js 20.19 or 22.12 and later, require loads it as well:
js
const postgres = require('postgres').default
Table of Contents
Upgrading from v3
Connection
Queries
Building queries
Advanced query methods
Transactions
Data Transformation
Listen & notify
Realtime subscribe
Numbers, bigint, numeric
Result Array
Connection details
Custom Types
Teardown / Cleanup
Tracing
Error handling
TypeScript support
Reserving connections
Changelog
Connection
postgres([url], [options])
You can use either a postgres:// url connection string or the options to define your database connection properties. Options in the object will override any present in the url. Options will fall back to the same environment variables as psql.
js
const sql = postgres('postgres://username:password@host:port/database', {
host : '', // Postgres ip address[s] or domain name[s]
port : 5432, // Postgres server port[s]
database : '', // Name of database to connect to
username : '', // Username of database user
password : '', // Password of database user
...and more
})
More options can be found in the Connection details section.
Queries
await sql... - Result[]
Postgres.js utilizes Tagged template functions to process query parameters before interpolation. Using tagged template literals benefits developers by:
1. Enforcing safe query generation
2. Giving the sql function powerful utilTop issues
Discussions
#1172What are people using to auto format the template strings?2 comments · 2026-06-11#1141Reconsider TypeScript & in-source comments2 comments · 2026-01-01#1125Is this library still maintained?2 comments · 2025-10-10#1123Instancing of postgres with pgbouncer and pooling1 comments · 2025-10-09#1122Checking PostgreSQL user read/write access across db and schemas from Node.js2 comments · 2025-10-08#1112Parameterized queries with aggregate functions with an array of column names1 comments · 2025-09-18#1111dynamic select columns with JSONB1 comments · 2025-09-17#1107Benchmarking postgres.js vs pg vs pg-native1 comments · 2025-09-06
Latest release
v4.1.1 v4.1.1 2026-11-11Fixed
- A statement sql.begin sends after its own COMMIT or ROLLBACK is rejected (1320). A statement the callback did not await, sent between the transaction's COMMIT or ROLLBACK and the release of its connection, ran outside the transaction, and after a rollback its write was kept. It now rejects with UNSAFE_TRANSACTION, as a statement after the transaction has ended does.
- A command after a select in a multi-statement simple query has no columns (1321). In sql.unsafe('select …; rollback') the ROLLBACK result had the columns of the SELECT before it.
- A query queued behind one with an u