porsager /postgres

Postgres.js - The Fastest full featured PostgreSQL client

★ 8,767⑂ 408👁 45⑃ 313● 868▤ 49
JavaScriptUnlicenseCreated 2019-11-22
下载:v4.1.1v4.1.1 ↓4.1.12026-11-11
+1
日增长
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 util

Top issues

Discussions

Latest release

v4.1.1 v4.1.1 2026-11-11
Fixed

- 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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON