@steadybrew/postgresjs 4.5.0 โ 4.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -1725
- package/docs/api.md +1609 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,1781 +1,127 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
- **Fixes reported Postgres.js bugs:** 40 open upstream issues, from queries receiving another query's rows to hung pools and crashed processes, each covered by a regression test. See [the list](#fixed-postgresjs-issues).
|
|
6
|
-
- **Built for serverless and connection poolers:** bounded connection retries with backoff, idle connections replaced when a frozen instance resumes, pool statistics from `sql.stats()`, and an adapter for Vercel Fluid. Query timeouts and cancellable pool waits are next on the [roadmap](ROADMAP.md).
|
|
7
|
-
- **Switch with one line:** your code and the libraries that import `postgres` keep working. See [Switching from Postgres.js](#switching-from-postgresjs).
|
|
8
|
-
|
|
9
|
-
---
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img width="440" height="180" alt="Postgres.js" src="postgresjs.svg">
|
|
3
|
+
</p>
|
|
10
4
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- [๐ Fastest full-featured node & deno client](https://github.com/porsager/postgres-benchmarks#results)
|
|
14
|
-
- ๐ท ES6 Tagged Template Strings at the core
|
|
15
|
-
- ๐โโ๏ธ Simple surface API
|
|
16
|
-
- ๐๏ธ Dynamic query support
|
|
17
|
-
|
|
18
|
-
<br clear="all">
|
|
19
|
-
|
|
20
|
-
## Compatibility
|
|
5
|
+
# Postgres.js by Steady Brew
|
|
21
6
|
|
|
22
7
|
[](https://github.com/steadybrew/postgresjs/actions/workflows/test.yml?query=branch%3Amain)
|
|
23
8
|
|
|
24
|
-
**
|
|
25
|
-
|
|
26
|
-
| Runtime | PostgreSQL | Notes |
|
|
27
|
-
| --- | --- | --- |
|
|
28
|
-
| Node 22, 24 and 26, ESM and CJS | 15โ18 | |
|
|
29
|
-
| Deno 1.46.3 | 17 | No Deno 2 claim |
|
|
30
|
-
| Cloudflare Workers (workerd) | 17 | A "Stream was cancelled" rejection on socket close remains ([#1196](https://github.com/porsager/postgres/issues/1196), [#1202](https://github.com/porsager/postgres/issues/1202)) |
|
|
31
|
-
| Bun | | Best effort, not tested in CI |
|
|
32
|
-
|
|
33
|
-
[The test workflow](https://github.com/steadybrew/postgresjs/blob/main/.github/workflows/test.yml) defines which pairs run on each push. Supabase PostgreSQL and Supabase Edge are separate environments; Deno 1.46.3 coverage does not imply Deno 2 or hosted Supabase Edge.
|
|
34
|
-
|
|
35
|
-
## Switching from Postgres.js
|
|
9
|
+
**Keep the [Postgres.js](https://github.com/porsager/postgres) API by [Rasmus Porsager](https://github.com/porsager) and get critical fixes and new features:**
|
|
36
10
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
11
|
+
- **Correctness fixes.** Queries get the right results, transactions stay isolated, and rollbacks are reported as failures.
|
|
12
|
+
- **Fewer hangs and crashes.** Fixes for stuck queries, shutdown hangs and crashes after disconnects.
|
|
13
|
+
- **Pool monitoring.** See busy connections, idle connections and waiting queries with `sql.stats()`.
|
|
14
|
+
- **Faster queries behind poolers.** Removes an extra network round trip for supported values (opt-in).
|
|
15
|
+
- **Vercel Fluid Compute support.** Reuse connections between requests and close idle ones before suspension to avoid connection leaks.
|
|
40
16
|
|
|
41
|
-
|
|
17
|
+
**[50+ reported upstream bugs fixed](docs/fixed-issues.md)**, with regression tests.
|
|
42
18
|
|
|
43
|
-
|
|
19
|
+
[Start a new project](#start-a-new-project) ยท [Switch from Postgres.js](#switching-from-postgresjs) ยท [Why this fork](#why-this-fork) ยท [API reference](docs/api.md) ยท [Roadmap](ROADMAP.md)
|
|
44
20
|
|
|
45
|
-
|
|
46
|
-
// sentry-postgres.mjs
|
|
47
|
-
import { SENTRY_RUNTIME_INSTRUMENTATIONS } from '@sentry/server-utils/orchestrion/config'
|
|
21
|
+
<a id="install"></a>
|
|
48
22
|
|
|
49
|
-
|
|
50
|
-
if (instrumentation.module.name === 'postgres')
|
|
51
|
-
instrumentation.module.versionRange = '>=3.0.0 <5'
|
|
52
|
-
}
|
|
53
|
-
```
|
|
23
|
+
## Start a new project
|
|
54
24
|
|
|
55
25
|
```sh
|
|
56
|
-
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
This covers Sentry's runtime hook, not its bundler plugins. With pnpm, add `@sentry/server-utils` at the same version as `@sentry/node` so the file can import it.
|
|
60
|
-
|
|
61
|
-
## Upgrading to 4.0.0
|
|
62
|
-
|
|
63
|
-
Version 4.0.0 fixes connection startup, reservations, reconnects, shutdown, transaction ownership, and built-in array handling. When upgrading from Postgres.js 3.4 or `@steadybrew/postgresjs` 3.x:
|
|
64
|
-
|
|
65
|
-
- Upgrade to **Node.js 22 or newer** before installing.
|
|
66
|
-
- Keep queries within the reservation or transaction that owns them. Reserved handles used after `release()`, and transaction handles used after completion, reject with `CONNECTION_ENDED`. A handle whose connection has closed cannot run queries on a reconnected session.
|
|
67
|
-
- Pass a non-empty string without NUL characters to transaction `sql.prepare(name)`. Invalid names throw `INVALID_TRANSACTION_NAME`.
|
|
68
|
-
- If you use `fetch_types: false`, review code that expects built-in arrays as raw strings: supported built-in arrays are now decoded as JavaScript arrays. SQL `NULL` elements become JavaScript `null`; quoted `"NULL"` text remains a string.
|
|
69
|
-
|
|
70
|
-
See the [changelog](./CHANGELOG.md#breaking-changes-and-migration) for the full migration notes and fixes.
|
|
71
|
-
|
|
72
|
-
## Fixed Postgres.js issues
|
|
73
|
-
|
|
74
|
-
Bugs and feature requests from [porsager/postgres](https://github.com/porsager/postgres) that this fork fixes, whether reported in an issue or in a pull request suggesting a fix, and the version that fixed them. Each fix has a test that reproduces the report, except [#1100](https://github.com/porsager/postgres/issues/1100), which rests on a production measurement, and [#1154](https://github.com/porsager/postgres/issues/1154), whose test reproduces the reported stack without a known trigger. The [changelog](./CHANGELOG.md) has the details.
|
|
75
|
-
|
|
76
|
-
<details>
|
|
77
|
-
<summary>54 bugs and 7 feature requests</summary>
|
|
78
|
-
|
|
79
|
-
**Wrong results and data safety**
|
|
80
|
-
|
|
81
|
-
| Issue | What happens now | Since |
|
|
82
|
-
| --- | --- | --- |
|
|
83
|
-
| [#1082](https://github.com/porsager/postgres/issues/1082), [#729](https://github.com/porsager/postgres/issues/729) | A query whose values fail to serialize rejects on its own; the query running alongside no longer gets its error, and the next query no longer gets another query's rows | 4.3.0 |
|
|
84
|
-
| [#1216](https://github.com/porsager/postgres/issues/1216) | A transaction handle whose connection closed rejects with `CONNECTION_CLOSED` instead of running inside the next user's transaction, so it can't read their rows through row-level security. | 4.0.0 |
|
|
85
|
-
| [#1248](https://github.com/porsager/postgres/issues/1248) | Statements in a `sql.begin()` callback after its connection closes reject instead of running outside the transaction | 4.0.0 |
|
|
86
|
-
| [#1204](https://github.com/porsager/postgres/issues/1204) | A transaction's connection is not handed to another `sql.begin()` when its socket drains late, so one transaction's `COMMIT` can't commit another's unfinished writes. | 4.0.0 |
|
|
87
|
-
| [#1217](https://github.com/porsager/postgres/issues/1217) | `sql.begin()` rejects with `TRANSACTION_ROLLED_BACK` when the server rolled back the COMMIT | 4.4.0 |
|
|
88
|
-
| [#1249](https://github.com/porsager/postgres/issues/1249), [#1226](https://github.com/porsager/postgres/issues/1226), [#1223](https://github.com/porsager/postgres/issues/1223) | The first query after a reconnect no longer rejects with an error from the closed session | 4.0.0 |
|
|
89
|
-
| [#789](https://github.com/porsager/postgres/issues/789) | `sql.array()` infers the right array type on first use | 4.0.0 |
|
|
90
|
-
| [#1049](https://github.com/porsager/postgres/issues/1049), [#1124](https://github.com/porsager/postgres/issues/1124) | `NULL` elements in arrays parse as `null`, not `NaN` or the string `"NULL"` | 4.0.0 |
|
|
91
|
-
| [#1252](https://github.com/porsager/postgres/issues/1252) | Cancelling a pipelined query that hasn't started no longer gives the next query its result | 4.1.0 |
|
|
92
|
-
| [#1253](https://github.com/porsager/postgres/issues/1253), [#1181](https://github.com/porsager/postgres/issues/1181), [#1119](https://github.com/porsager/postgres/issues/1119) | A query no longer gets empty slots at the start of its result after the previous query on the connection failed or was cancelled partway through its rows | 4.5.0 |
|
|
93
|
-
|
|
94
|
-
**Hangs**
|
|
95
|
-
|
|
96
|
-
| Issue | What happens now | Since |
|
|
97
|
-
| --- | --- | --- |
|
|
98
|
-
| [#751](https://github.com/porsager/postgres/issues/751), [#1219](https://github.com/porsager/postgres/issues/1219), [#1203](https://github.com/porsager/postgres/issues/1203) | `sql.reserve()` on a pool that hasn't opened a connection yet resolves, with or without `fetch_types` and on Cloudflare Workers | 4.0.0 |
|
|
99
|
-
| [#1195](https://github.com/porsager/postgres/issues/1195), [#1199](https://github.com/porsager/postgres/issues/1199) | A reservation survives its connection being terminated by the server, and the pool recovers after it is released | 4.0.0 |
|
|
100
|
-
| [#1186](https://github.com/porsager/postgres/issues/1186) | Queries queued on a reserved or transaction handle settle when its connection closes | 4.0.0 |
|
|
101
|
-
| [#1097](https://github.com/porsager/postgres/issues/1097), [#1130](https://github.com/porsager/postgres/issues/1130), [#1242](https://github.com/porsager/postgres/issues/1242), [#861](https://github.com/porsager/postgres/issues/861) | `sql.end()` resolves after a disconnect, after a failed query and after a connection closes inside `sql.begin()`, and waits for queries queued in the pool | 4.0.0 |
|
|
102
|
-
| [#1246](https://github.com/porsager/postgres/issues/1246) | A query sent between a socket error and its close settles, and a transaction reset mid-statement no longer loses a pool connection | 4.1.0 |
|
|
103
|
-
| [#1193](https://github.com/porsager/postgres/issues/1193) | A connection closed during startup settles its first query instead of reconnecting in a tight loop | 4.0.0 |
|
|
104
|
-
| [#1234](https://github.com/porsager/postgres/issues/1234) | Concurrent queries in `sql.begin()` after a column type change roll the transaction back and return the connection to the pool | 4.4.0 |
|
|
105
|
-
| [#1255](https://github.com/porsager/postgres/issues/1255), [#1261](https://github.com/porsager/postgres/issues/1261) | A reserved connection whose `max_lifetime` passed is closed when released, and `sql.end()` called before the release resolves | 4.0.0 |
|
|
106
|
-
| [#1016](https://github.com/porsager/postgres/pull/1016) | Queries no longer hang after a `COPY ... TO STDOUT` whose reader fell behind | 4.5.0 |
|
|
107
|
-
|
|
108
|
-
**Crashes**
|
|
109
|
-
|
|
110
|
-
| Issue | What happens now | Since |
|
|
111
|
-
| --- | --- | --- |
|
|
112
|
-
| [#1154](https://github.com/porsager/postgres/issues/1154), [#1208](https://github.com/porsager/postgres/issues/1208), [#1133](https://github.com/porsager/postgres/issues/1133) | A reserved or transaction connection that the server or network closes rejects its later statements, and `sql.begin()`'s own `ROLLBACK` or `COMMIT`, with `CONNECTION_CLOSED` instead of crashing the process with `Cannot read properties of null (reading 'write')`. | 4.0.0 |
|
|
113
|
-
| [#1192](https://github.com/porsager/postgres/issues/1192), [#1205](https://github.com/porsager/postgres/issues/1205), [#1086](https://github.com/porsager/postgres/issues/1086) | A failed or cancelled type query at startup rejects the query instead of crashing the process | 4.0.0 |
|
|
114
|
-
| [#1088](https://github.com/porsager/postgres/issues/1088) | Timers no longer fail on Cloudflare Workers | 4.0.0 |
|
|
115
|
-
| [#1227](https://github.com/porsager/postgres/issues/1227) | Assigning `err.stack` on a query error no longer throws on Node 22 and newer | 4.5.0 |
|
|
116
|
-
| [#1009](https://github.com/porsager/postgres/pull/1009) | The `camel` and `pascal` transforms no longer throw on a column name ending with an underscore | 4.5.0 |
|
|
117
|
-
|
|
118
|
-
**Reconnects and failover**
|
|
119
|
-
|
|
120
|
-
| Issue | What happens now | Since |
|
|
121
|
-
| --- | --- | --- |
|
|
122
|
-
| [#1179](https://github.com/porsager/postgres/issues/1179) | Failed connection attempts back off instead of the whole pool retrying at once | 4.0.0 |
|
|
123
|
-
| [#1250](https://github.com/porsager/postgres/issues/1250) | A connection closed with a statement still buffered reconnects, instead of failing every later statement with `CONNECT_TIMEOUT` | 4.0.0 |
|
|
124
|
-
| [#1174](https://github.com/porsager/postgres/issues/1174), [#815](https://github.com/porsager/postgres/issues/815), [#988](https://github.com/porsager/postgres/issues/988) | With several hosts, retries move to the next host, a connect timeout fails over, and `prefer-standby` falls back to a primary | 4.0.0 |
|
|
125
|
-
|
|
126
|
-
**Transactions, notices and subscriptions**
|
|
127
|
-
|
|
128
|
-
| Issue | What happens now | Since |
|
|
129
|
-
| --- | --- | --- |
|
|
130
|
-
| [#823](https://github.com/porsager/postgres/issues/823), [#1189](https://github.com/porsager/postgres/issues/1189), [#1210](https://github.com/porsager/postgres/issues/1210) | `sql.begin()` no longer fails with `UNSAFE_TRANSACTION` or sends a second `BEGIN` on a busy connection when transactions and queries run concurrently, at the pipeline limit, under write backpressure or with `max_pipeline: 0` | 4.0.0 |
|
|
131
|
-
| [#1063](https://github.com/porsager/postgres/issues/1063) | `onnotice: false` silences notices | 4.4.0 |
|
|
132
|
-
| [#1087](https://github.com/porsager/postgres/issues/1087) | `sql.subscribe()` no longer adds a listener on each subscribe or loses changes after a transform throws | 4.4.0 |
|
|
133
|
-
|
|
134
|
-
**TypeScript**
|
|
135
|
-
|
|
136
|
-
| Issue | What happens now | Since |
|
|
137
|
-
| --- | --- | --- |
|
|
138
|
-
| [#1158](https://github.com/porsager/postgres/issues/1158), [#1177](https://github.com/porsager/postgres/pull/1177) | `sslnegotiation` is in the option types | 4.5.0 |
|
|
139
|
-
| [#968](https://github.com/porsager/postgres/pull/968) | `socket` is in the option types | 4.5.0 |
|
|
140
|
-
| [#703](https://github.com/porsager/postgres/issues/703), [#1194](https://github.com/porsager/postgres/pull/1194) | `new PostgresError('message')` sets the message, as with `Error`, and the types declare both the message and the fields forms | 4.5.0 |
|
|
141
|
-
|
|
142
|
-
**Feature requests**
|
|
143
|
-
|
|
144
|
-
| Issue | What you get | Since |
|
|
145
|
-
| --- | --- | --- |
|
|
146
|
-
| [#443](https://github.com/porsager/postgres/issues/443), [#908](https://github.com/porsager/postgres/issues/908) | `sql.stats()` reports connections in use and idle, and queries waiting | 4.3.0 |
|
|
147
|
-
| [#1100](https://github.com/porsager/postgres/issues/1100) | An `onidle` callback and the `@steadybrew/postgresjs/vercel` adapter | 4.2.0 |
|
|
148
|
-
| [#1164](https://github.com/porsager/postgres/issues/1164) | Built-in array types are decoded, and plain JavaScript arrays are sent, with `fetch_types: false` | 4.0.0 |
|
|
149
|
-
| [#886](https://github.com/porsager/postgres/issues/886), [#1094](https://github.com/porsager/postgres/issues/1094) | `await using` ends a pool and releases a reserved connection when it goes out of scope | 4.5.0 |
|
|
150
|
-
| [#1225](https://github.com/porsager/postgres/issues/1225) | Queries with values in one round trip instead of two, opt-in with `parameter_types: 'client'` | 4.5.0 |
|
|
151
|
-
|
|
152
|
-
Bun isn't tested here, so Bun-only reports such as [#1066](https://github.com/porsager/postgres/issues/1066) aren't listed; the same crash on Node is [#1208](https://github.com/porsager/postgres/issues/1208).
|
|
153
|
-
|
|
154
|
-
</details>
|
|
155
|
-
|
|
156
|
-
## Getting started
|
|
157
|
-
|
|
158
|
-
<br>
|
|
159
|
-
<img height="220" width="458" alt="Good UX with Postgres.js" src="https://raw.githubusercontent.com/porsager/postgres/master/demo.gif">
|
|
160
|
-
<br>
|
|
161
|
-
|
|
162
|
-
### Installation
|
|
163
|
-
```bash
|
|
164
|
-
$ npm install @steadybrew/postgresjs
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
### Usage
|
|
168
|
-
Create your `sql` database instance
|
|
169
|
-
```js
|
|
170
|
-
// db.js
|
|
171
|
-
import postgres from '@steadybrew/postgresjs'
|
|
172
|
-
|
|
173
|
-
const sql = postgres({ /* options */ }) // will use psql environment variables
|
|
174
|
-
|
|
175
|
-
export default sql
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
Simply import for use elsewhere
|
|
179
|
-
```js
|
|
180
|
-
// users.js
|
|
181
|
-
import sql from './db.js'
|
|
182
|
-
|
|
183
|
-
async function getUsersOver(age) {
|
|
184
|
-
const users = await sql`
|
|
185
|
-
select
|
|
186
|
-
name,
|
|
187
|
-
age
|
|
188
|
-
from users
|
|
189
|
-
where age > ${ age }
|
|
190
|
-
`
|
|
191
|
-
// users = Result [{ name: "Walter", age: 80 }, { name: 'Murray', age: 68 }, ...]
|
|
192
|
-
return users
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
async function insertUser({ name, age }) {
|
|
197
|
-
const users = await sql`
|
|
198
|
-
insert into users
|
|
199
|
-
(name, age)
|
|
200
|
-
values
|
|
201
|
-
(${ name }, ${ age })
|
|
202
|
-
returning name, age
|
|
203
|
-
`
|
|
204
|
-
// users = Result [{ name: "Murray", age: 68 }]
|
|
205
|
-
return users
|
|
206
|
-
}
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
#### ESM dynamic imports
|
|
210
|
-
|
|
211
|
-
The library can be used with ESM dynamic imports as well as shown here.
|
|
212
|
-
|
|
213
|
-
```js
|
|
214
|
-
const { default: postgres } = await import('@steadybrew/postgresjs')
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
## Table of Contents
|
|
218
|
-
|
|
219
|
-
* [Upgrading to 4.0.0](#upgrading-to-400)
|
|
220
|
-
* [Connection](#connection)
|
|
221
|
-
* [Queries](#queries)
|
|
222
|
-
* [Building queries](#building-queries)
|
|
223
|
-
* [Advanced query methods](#advanced-query-methods)
|
|
224
|
-
* [Transactions](#transactions)
|
|
225
|
-
* [Data Transformation](#data-transformation)
|
|
226
|
-
* [Listen & notify](#listen--notify)
|
|
227
|
-
* [Realtime subscribe](#realtime-subscribe)
|
|
228
|
-
* [Numbers, bigint, numeric](#numbers-bigint-numeric)
|
|
229
|
-
* [Parameter types](#parameter-types)
|
|
230
|
-
* [Result Array](#result-array)
|
|
231
|
-
* [Connection details](#connection-details)
|
|
232
|
-
* [Custom Types](#custom-types)
|
|
233
|
-
* [Teardown / Cleanup](#teardown--cleanup)
|
|
234
|
-
* [Error handling](#error-handling)
|
|
235
|
-
* [TypeScript support](#typescript-support)
|
|
236
|
-
* [Reserving connections](#reserving-connections)
|
|
237
|
-
* [Changelog](./CHANGELOG.md)
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
## Connection
|
|
241
|
-
|
|
242
|
-
### `postgres([url], [options])`
|
|
243
|
-
|
|
244
|
-
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.
|
|
245
|
-
|
|
246
|
-
```js
|
|
247
|
-
const sql = postgres('postgres://username:password@host:port/database', {
|
|
248
|
-
host : '', // Postgres ip address[s] or domain name[s]
|
|
249
|
-
port : 5432, // Postgres server port[s]
|
|
250
|
-
database : '', // Name of database to connect to
|
|
251
|
-
username : '', // Username of database user
|
|
252
|
-
password : '', // Password of database user
|
|
253
|
-
...and more
|
|
254
|
-
})
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
More options can be found in the [Connection details section](#connection-details).
|
|
258
|
-
|
|
259
|
-
## Queries
|
|
260
|
-
|
|
261
|
-
### ```await sql`...` -> Result[]```
|
|
262
|
-
|
|
263
|
-
Postgres.js utilizes [Tagged template functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates) to process query parameters **before** interpolation. Using tagged template literals benefits developers by:
|
|
264
|
-
|
|
265
|
-
1. **Enforcing** safe query generation
|
|
266
|
-
2. Giving the ` sql`` ` function powerful [utility](#dynamic-inserts) and [query building](#building-queries) features.
|
|
267
|
-
|
|
268
|
-
Any generic value will be serialized as described in [Parameter types](#parameter-types), and replaced by a PostgreSQL protocol placeholder `$1, $2, ...`. The values are then sent separately to PostgreSQL, which handles escaping & casting.
|
|
269
|
-
|
|
270
|
-
All queries will return a `Result` array, with objects mapping column names to each row.
|
|
271
|
-
|
|
272
|
-
```js
|
|
273
|
-
const xs = await sql`
|
|
274
|
-
insert into users (
|
|
275
|
-
name, age
|
|
276
|
-
) values (
|
|
277
|
-
'Murray', 68
|
|
278
|
-
)
|
|
279
|
-
|
|
280
|
-
returning *
|
|
281
|
-
`
|
|
282
|
-
|
|
283
|
-
// xs = [{ user_id: 1, name: 'Murray', age: 68 }]
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
> Please note that queries are first executed when `awaited` โ or instantly by using [`.execute()`](#execute).
|
|
287
|
-
|
|
288
|
-
### Query parameters
|
|
289
|
-
|
|
290
|
-
Parameters are automatically extracted and handled by the database so that SQL injection isn't possible. No special handling is necessary, simply use tagged template literals as usual.
|
|
291
|
-
|
|
292
|
-
```js
|
|
293
|
-
const name = 'Mur'
|
|
294
|
-
, age = 60
|
|
295
|
-
|
|
296
|
-
const users = await sql`
|
|
297
|
-
select
|
|
298
|
-
name,
|
|
299
|
-
age
|
|
300
|
-
from users
|
|
301
|
-
where
|
|
302
|
-
name like ${ name + '%' }
|
|
303
|
-
and age > ${ age }
|
|
304
|
-
`
|
|
305
|
-
// users = [{ name: 'Murray', age: 68 }]
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
> Be careful with quotation marks here. Because Postgres infers column types, you do not need to wrap your interpolated parameters in quotes like `'${name}'`. This will cause an error because the tagged template replaces `${name}` with `$1` in the query string, leaving Postgres to do the interpolation. If you wrap that in a string, Postgres will see `'$1'` and interpret it as a string as opposed to a parameter.
|
|
309
|
-
|
|
310
|
-
### Dynamic column selection
|
|
311
|
-
|
|
312
|
-
```js
|
|
313
|
-
const columns = ['name', 'age']
|
|
314
|
-
|
|
315
|
-
await sql`
|
|
316
|
-
select
|
|
317
|
-
${ sql(columns) }
|
|
318
|
-
from users
|
|
319
|
-
`
|
|
320
|
-
|
|
321
|
-
// Which results in:
|
|
322
|
-
select "name", "age" from users
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
### Dynamic inserts
|
|
326
|
-
|
|
327
|
-
```js
|
|
328
|
-
const user = {
|
|
329
|
-
name: 'Murray',
|
|
330
|
-
age: 68
|
|
331
|
-
}
|
|
332
|
-
|
|
333
|
-
await sql`
|
|
334
|
-
insert into users ${
|
|
335
|
-
sql(user, 'name', 'age')
|
|
336
|
-
}
|
|
337
|
-
`
|
|
338
|
-
|
|
339
|
-
// Which results in:
|
|
340
|
-
insert into users ("name", "age") values ($1, $2)
|
|
341
|
-
|
|
342
|
-
// The columns can also be given with an array
|
|
343
|
-
const columns = ['name', 'age']
|
|
344
|
-
|
|
345
|
-
await sql`
|
|
346
|
-
insert into users ${
|
|
347
|
-
sql(user, columns)
|
|
348
|
-
}
|
|
349
|
-
`
|
|
350
|
-
```
|
|
351
|
-
|
|
352
|
-
**You can omit column names and simply execute `sql(user)` to get all the fields from the object as columns**. Be careful not to allow users to supply columns that you do not want to be inserted.
|
|
353
|
-
|
|
354
|
-
#### Multiple inserts in one query
|
|
355
|
-
If you need to insert multiple rows at the same time it's also much faster to do it with a single `insert`. Simply pass an array of objects to `sql()`.
|
|
356
|
-
|
|
357
|
-
```js
|
|
358
|
-
const users = [{
|
|
359
|
-
name: 'Murray',
|
|
360
|
-
age: 68,
|
|
361
|
-
garbage: 'ignore'
|
|
362
|
-
},
|
|
363
|
-
{
|
|
364
|
-
name: 'Walter',
|
|
365
|
-
age: 80
|
|
366
|
-
}]
|
|
367
|
-
|
|
368
|
-
await sql`insert into users ${ sql(users, 'name', 'age') }`
|
|
369
|
-
|
|
370
|
-
// Is translated to:
|
|
371
|
-
insert into users ("name", "age") values ($1, $2), ($3, $4)
|
|
372
|
-
|
|
373
|
-
// Here you can also omit column names which will use object keys as columns
|
|
374
|
-
await sql`insert into users ${ sql(users) }`
|
|
375
|
-
|
|
376
|
-
// Which results in:
|
|
377
|
-
insert into users ("name", "age") values ($1, $2), ($3, $4)
|
|
378
|
-
```
|
|
379
|
-
|
|
380
|
-
### Dynamic columns in updates
|
|
381
|
-
This is also useful for update queries
|
|
382
|
-
```js
|
|
383
|
-
const user = {
|
|
384
|
-
id: 1,
|
|
385
|
-
name: 'Murray',
|
|
386
|
-
age: 68
|
|
387
|
-
}
|
|
388
|
-
|
|
389
|
-
await sql`
|
|
390
|
-
update users set ${
|
|
391
|
-
sql(user, 'name', 'age')
|
|
392
|
-
}
|
|
393
|
-
where user_id = ${ user.id }
|
|
394
|
-
`
|
|
395
|
-
|
|
396
|
-
// Which results in:
|
|
397
|
-
update users set "name" = $1, "age" = $2 where user_id = $3
|
|
398
|
-
|
|
399
|
-
// The columns can also be given with an array
|
|
400
|
-
const columns = ['name', 'age']
|
|
401
|
-
|
|
402
|
-
await sql`
|
|
403
|
-
update users set ${
|
|
404
|
-
sql(user, columns)
|
|
405
|
-
}
|
|
406
|
-
where user_id = ${ user.id }
|
|
407
|
-
`
|
|
408
|
-
```
|
|
409
|
-
|
|
410
|
-
### Multiple updates in one query
|
|
411
|
-
To create multiple updates in a single query, it is necessary to use arrays instead of objects to ensure that the order of the items correspond with the column names.
|
|
412
|
-
```js
|
|
413
|
-
const users = [
|
|
414
|
-
[1, 'John', 34],
|
|
415
|
-
[2, 'Jane', 27],
|
|
416
|
-
]
|
|
417
|
-
|
|
418
|
-
await sql`
|
|
419
|
-
update users set name = update_data.name, age = (update_data.age)::int
|
|
420
|
-
from (values ${sql(users)}) as update_data (id, name, age)
|
|
421
|
-
where users.id = (update_data.id)::int
|
|
422
|
-
returning users.id, users.name, users.age
|
|
423
|
-
`
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
### Dynamic values and `where in`
|
|
427
|
-
Value lists can also be created dynamically, making `where in` queries simple too.
|
|
428
|
-
```js
|
|
429
|
-
const users = await sql`
|
|
430
|
-
select
|
|
431
|
-
*
|
|
432
|
-
from users
|
|
433
|
-
where age in ${ sql([68, 75, 23]) }
|
|
434
|
-
`
|
|
26
|
+
npm install @steadybrew/postgresjs
|
|
435
27
|
```
|
|
436
28
|
|
|
437
|
-
or
|
|
438
|
-
```js
|
|
439
|
-
const [{ a, b, c }] = await sql`
|
|
440
|
-
select
|
|
441
|
-
*
|
|
442
|
-
from (values ${ sql(['a', 'b', 'c']) }) as x(a, b, c)
|
|
443
|
-
`
|
|
444
|
-
```
|
|
445
|
-
|
|
446
|
-
## Building queries
|
|
447
|
-
|
|
448
|
-
Postgres.js features a simple dynamic query builder by conditionally appending/omitting query fragments.
|
|
449
|
-
It works by nesting ` sql`` ` fragments within other ` sql`` ` calls or fragments. This allows you to build dynamic queries safely without risking sql injections through usual string concatenation.
|
|
450
|
-
|
|
451
|
-
### Partial queries
|
|
452
|
-
```js
|
|
453
|
-
const olderThan = x => sql`and age > ${ x }`
|
|
454
|
-
|
|
455
|
-
const filterAge = true
|
|
456
|
-
|
|
457
|
-
await sql`
|
|
458
|
-
select
|
|
459
|
-
*
|
|
460
|
-
from users
|
|
461
|
-
where name is not null ${
|
|
462
|
-
filterAge
|
|
463
|
-
? olderThan(50)
|
|
464
|
-
: sql``
|
|
465
|
-
}
|
|
466
|
-
`
|
|
467
|
-
// Which results in:
|
|
468
|
-
select * from users where name is not null
|
|
469
|
-
// Or
|
|
470
|
-
select * from users where name is not null and age > 50
|
|
471
|
-
```
|
|
472
|
-
|
|
473
|
-
### Dynamic filters
|
|
474
|
-
```js
|
|
475
|
-
await sql`
|
|
476
|
-
select
|
|
477
|
-
*
|
|
478
|
-
from users ${
|
|
479
|
-
id
|
|
480
|
-
? sql`where user_id = ${ id }`
|
|
481
|
-
: sql``
|
|
482
|
-
}
|
|
483
|
-
`
|
|
484
|
-
|
|
485
|
-
// Which results in:
|
|
486
|
-
select * from users
|
|
487
|
-
// Or
|
|
488
|
-
select * from users where user_id = $1
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
### Dynamic ordering
|
|
492
|
-
|
|
493
|
-
```js
|
|
494
|
-
const id = 1
|
|
495
|
-
const order = {
|
|
496
|
-
username: 'asc'
|
|
497
|
-
created_at: 'desc'
|
|
498
|
-
}
|
|
499
|
-
await sql`
|
|
500
|
-
select
|
|
501
|
-
*
|
|
502
|
-
from ticket
|
|
503
|
-
where account = ${ id }
|
|
504
|
-
order by ${
|
|
505
|
-
Object.entries(order).flatMap(([column, order], i) =>
|
|
506
|
-
[i ? sql`,` : sql``, sql`${ sql(column) } ${ order === 'desc' ? sql`desc` : sql`asc` }`]
|
|
507
|
-
)
|
|
508
|
-
}
|
|
509
|
-
`
|
|
510
|
-
```
|
|
511
|
-
|
|
512
|
-
### SQL functions
|
|
513
|
-
Using keywords or calling functions dynamically is also possible by using ``` sql`` ``` fragments.
|
|
514
|
-
```js
|
|
515
|
-
const date = null
|
|
516
|
-
|
|
517
|
-
await sql`
|
|
518
|
-
update users set updated_at = ${ date || sql`now()` }
|
|
519
|
-
`
|
|
520
|
-
|
|
521
|
-
// Which results in:
|
|
522
|
-
update users set updated_at = now()
|
|
523
|
-
```
|
|
524
|
-
|
|
525
|
-
### Table names
|
|
526
|
-
Dynamic identifiers like table names and column names is also supported like so:
|
|
527
|
-
```js
|
|
528
|
-
const table = 'users'
|
|
529
|
-
, column = 'id'
|
|
530
|
-
|
|
531
|
-
await sql`
|
|
532
|
-
select ${ sql(column) } from ${ sql(table) }
|
|
533
|
-
`
|
|
534
|
-
|
|
535
|
-
// Which results in:
|
|
536
|
-
select "id" from "users"
|
|
537
|
-
```
|
|
538
|
-
|
|
539
|
-
### Quick primer on interpolation
|
|
540
|
-
|
|
541
|
-
Here's a quick oversight over all the ways to do interpolation in a query template string:
|
|
542
|
-
|
|
543
|
-
| Interpolation syntax | Usage | Example |
|
|
544
|
-
| ------------- | ------------- | ------------- |
|
|
545
|
-
| `${ sql`` }` | for keywords or sql fragments | ``await sql`SELECT * FROM users ${sql`order by age desc` }` `` |
|
|
546
|
-
| `${ sql(string) }` | for identifiers | ``await sql`SELECT * FROM ${sql('table_name')` `` |
|
|
547
|
-
| `${ sql([] or {}, ...) }` | for helpers | ``await sql`INSERT INTO users ${sql({ name: 'Peter'})}` `` |
|
|
548
|
-
| `${ 'somevalue' }` | for values | ``await sql`SELECT * FROM users WHERE age = ${42}` `` |
|
|
549
|
-
|
|
550
|
-
## Advanced query methods
|
|
551
|
-
|
|
552
|
-
### Cursors
|
|
553
|
-
|
|
554
|
-
#### ```await sql``.cursor([rows = 1], [fn])```
|
|
555
|
-
|
|
556
|
-
Use cursors if you need to throttle the amount of rows being returned from a query. You can use a cursor either as an [async iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) or with a callback function. For a callback function new results won't be requested until the promise / async callback function has resolved.
|
|
557
|
-
|
|
558
|
-
##### callback function
|
|
559
|
-
```js
|
|
560
|
-
await sql`
|
|
561
|
-
select
|
|
562
|
-
*
|
|
563
|
-
from generate_series(1,4) as x
|
|
564
|
-
`.cursor(async([row]) => {
|
|
565
|
-
// row = { x: 1 }
|
|
566
|
-
await http.request('https://example.com/wat', { row })
|
|
567
|
-
})
|
|
568
|
-
```
|
|
569
|
-
|
|
570
|
-
##### for await...of
|
|
571
|
-
```js
|
|
572
|
-
// for await...of
|
|
573
|
-
const cursor = sql`select * from generate_series(1,4) as x`.cursor()
|
|
574
|
-
|
|
575
|
-
for await (const [row] of cursor) {
|
|
576
|
-
// row = { x: 1 }
|
|
577
|
-
await http.request('https://example.com/wat', { row })
|
|
578
|
-
}
|
|
579
|
-
```
|
|
580
|
-
|
|
581
|
-
A single row will be returned by default, but you can also request batches by setting the number of rows desired in each batch as the first argument to `.cursor`:
|
|
582
|
-
```js
|
|
583
|
-
await sql`
|
|
584
|
-
select
|
|
585
|
-
*
|
|
586
|
-
from generate_series(1,1000) as x
|
|
587
|
-
`.cursor(10, async rows => {
|
|
588
|
-
// rows = [{ x: 1 }, { x: 2 }, ... ]
|
|
589
|
-
await Promise.all(rows.map(row =>
|
|
590
|
-
http.request('https://example.com/wat', { row })
|
|
591
|
-
))
|
|
592
|
-
})
|
|
593
|
-
```
|
|
594
|
-
|
|
595
|
-
If an error is thrown inside the callback function no more rows will be requested and the outer promise will reject with the thrown error.
|
|
596
|
-
|
|
597
|
-
You can close the cursor early either by calling `break` in the `for await...of` loop, or by returning the token `sql.CLOSE` from the callback function.
|
|
598
|
-
|
|
599
|
-
```js
|
|
600
|
-
await sql`
|
|
601
|
-
select * from generate_series(1,1000) as x
|
|
602
|
-
`.cursor(row => {
|
|
603
|
-
return Math.random() > 0.9 && sql.CLOSE // or sql.END
|
|
604
|
-
})
|
|
605
|
-
```
|
|
606
|
-
|
|
607
|
-
### Instant iteration
|
|
608
|
-
|
|
609
|
-
#### ```await sql``.forEach(fn)```
|
|
610
|
-
|
|
611
|
-
If you want to handle rows returned by a query one by one, you can use `.forEach` which returns a promise that resolves once there are no more rows.
|
|
612
|
-
```js
|
|
613
|
-
await sql`
|
|
614
|
-
select created_at, name from events
|
|
615
|
-
`.forEach(row => {
|
|
616
|
-
// row = { created_at: '2019-11-22T14:22:00Z', name: 'connected' }
|
|
617
|
-
})
|
|
618
|
-
|
|
619
|
-
// No more rows
|
|
620
|
-
```
|
|
621
|
-
|
|
622
|
-
### Query Descriptions
|
|
623
|
-
#### ```await sql``.describe() -> Result[]```
|
|
624
|
-
|
|
625
|
-
Rather than executing a given query, `.describe` will return information utilized in the query process. This information can include the query identifier, column types, etc.
|
|
626
|
-
|
|
627
|
-
This is useful for debugging and analyzing your Postgres queries. Furthermore, **`.describe` will give you access to the final generated query string that would be executed.**
|
|
628
|
-
|
|
629
|
-
### Rows as Array of Values
|
|
630
|
-
#### ```sql``.values()```
|
|
631
|
-
|
|
632
|
-
Using `.values` will return rows as an array of values for each column, instead of objects.
|
|
633
|
-
|
|
634
|
-
This can be useful to receive identically named columns, or for specific performance/transformation reasons. The column definitions are still included on the result array, plus access to parsers for each column.
|
|
635
|
-
|
|
636
|
-
### Rows as Raw Array of Buffers
|
|
637
|
-
#### ```sql``.raw()```
|
|
638
|
-
|
|
639
|
-
Using `.raw` will return rows as an array with `Buffer` values for each column, instead of objects.
|
|
640
|
-
|
|
641
|
-
This can be useful for specific performance/transformation reasons. The column definitions are still included on the result array, plus access to parsers for each column.
|
|
29
|
+
Or, for Drizzle or Kysely, use the alias:
|
|
642
30
|
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
Using a file for a query is also supported with optional parameters to use if the file includes `$1, $2, etc`
|
|
647
|
-
|
|
648
|
-
```js
|
|
649
|
-
const result = await sql.file('query.sql', ['Murray', 68])
|
|
650
|
-
```
|
|
651
|
-
|
|
652
|
-
### Multiple statements in one query
|
|
653
|
-
#### ```await sql``.simple()```
|
|
654
|
-
|
|
655
|
-
The postgres wire protocol supports ["simple"](https://www.postgresql.org/docs/current/protocol-flow.html#id-1.10.6.7.4) and ["extended"](https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY) queries. "simple" queries supports multiple statements, but does not support any dynamic parameters. "extended" queries support parameters but only one statement. To use "simple" queries you can use
|
|
656
|
-
```sql``.simple()```. That will create it as a simple query.
|
|
657
|
-
|
|
658
|
-
```js
|
|
659
|
-
await sql`select 1; select 2;`.simple()
|
|
660
|
-
```
|
|
661
|
-
|
|
662
|
-
### Copy to/from as Streams
|
|
663
|
-
|
|
664
|
-
Postgres.js supports [`COPY ...`](https://www.postgresql.org/docs/14/sql-copy.html) queries, which are exposed as [Node.js streams](https://nodejs.org/api/stream.html).
|
|
665
|
-
|
|
666
|
-
#### ```await sql`copy ... from stdin`.writable() -> Writable```
|
|
667
|
-
|
|
668
|
-
```js
|
|
669
|
-
import { pipeline } from 'node:stream/promises'
|
|
670
|
-
|
|
671
|
-
// Stream of users with the default tab delimitated cells and new-line delimitated rows
|
|
672
|
-
const userStream = Readable.from([
|
|
673
|
-
'Murray\t68\n',
|
|
674
|
-
'Walter\t80\n'
|
|
675
|
-
])
|
|
676
|
-
|
|
677
|
-
const query = await sql`copy users (name, age) from stdin`.writable()
|
|
678
|
-
await pipeline(userStream, query);
|
|
679
|
-
```
|
|
680
|
-
|
|
681
|
-
#### ```await sql`copy ... to stdout`.readable() -> Readable```
|
|
682
|
-
|
|
683
|
-
##### Using Stream Pipeline
|
|
684
|
-
```js
|
|
685
|
-
import { pipeline } from 'node:stream/promises'
|
|
686
|
-
import { createWriteStream } from 'node:fs'
|
|
687
|
-
|
|
688
|
-
const readableStream = await sql`copy users (name, age) to stdout`.readable()
|
|
689
|
-
await pipeline(readableStream, createWriteStream('output.tsv'))
|
|
690
|
-
// output.tsv content: `Murray\t68\nWalter\t80\n`
|
|
691
|
-
```
|
|
692
|
-
|
|
693
|
-
##### Using `for await...of`
|
|
694
|
-
```js
|
|
695
|
-
const readableStream = await sql`
|
|
696
|
-
copy (
|
|
697
|
-
select name, age
|
|
698
|
-
from users
|
|
699
|
-
where age = 68
|
|
700
|
-
) to stdout
|
|
701
|
-
`.readable()
|
|
702
|
-
for await (const chunk of readableStream) {
|
|
703
|
-
// chunk.toString() === `Murray\t68\n`
|
|
704
|
-
}
|
|
705
|
-
```
|
|
706
|
-
|
|
707
|
-
> **NOTE** This is a low-level API which does not provide any type safety. To make this work, you must match your [`copy query` parameters](https://www.postgresql.org/docs/14/sql-copy.html) correctly to your [Node.js stream read or write](https://nodejs.org/api/stream.html) code. Ensure [Node.js stream backpressure](https://nodejs.org/en/learn/modules/backpressuring-in-streams) is handled correctly to avoid memory exhaustion.
|
|
708
|
-
|
|
709
|
-
A `COPY` holds its connection until it finishes. Postgres.js cannot tell that a simple-protocol query is a `COPY` until the server answers, so it sends nothing behind a simple query whose text contains the word `copy` (`sql.unsafe()` or `sql.file()` without parameters, `.simple()`, `.readable()`, `.writable()`). Queries sent through `sql` meanwhile run on another connection or wait for one. When every connection is running a `COPY` that has not been ended, for example with `max: 1`, queries, `sql.reserve()` and `sql.begin()` through `sql` reject with `COPY_IN_PROGRESS` instead, because only that `COPY` finishing could free a connection. Statements on a `sql.reserve()` or `sql.begin()` handle reject with `COPY_IN_PROGRESS` while its `COPY` runs.
|
|
710
|
-
|
|
711
|
-
### Canceling Queries in Progress
|
|
712
|
-
|
|
713
|
-
Postgres.js supports, [canceling queries in progress](https://www.postgresql.org/docs/7.1/protocol-protocol.html#AEN39000). It works by opening a new connection with a protocol level startup message to cancel the current query running on a specific connection. That means there is no guarantee that the query will be canceled, and due to the possible race conditions it might even result in canceling another query. This is fine for long running queries, but in the case of high load and fast queries it might be better to simply ignore results instead of canceling.
|
|
714
|
-
|
|
715
|
-
```js
|
|
716
|
-
const query = sql`select pg_sleep(100)`.execute()
|
|
717
|
-
setTimeout(() => query.cancel(), 100)
|
|
718
|
-
const result = await query
|
|
719
|
-
```
|
|
720
|
-
|
|
721
|
-
A cancelled query rejects with code `57014`. A cancel can arrive too late, in which case the query may still complete, or fail with its own error. `query.cancel()` resolves once the cancel request has been sent. A cancelled query you don't await does not cause an unhandled rejection.
|
|
722
|
-
|
|
723
|
-
### Execute
|
|
724
|
-
|
|
725
|
-
#### ```await sql``.execute()```
|
|
726
|
-
|
|
727
|
-
The lazy Promise implementation in Postgres.js is what allows it to distinguish [Nested Fragments](#building-queries) from the main outer query. This also means that queries are always executed at the earliest in the following tick. If you have a specific need to execute the query in the same tick, you can call `.execute()`
|
|
728
|
-
|
|
729
|
-
### Unsafe raw string queries
|
|
730
|
-
|
|
731
|
-
<details>
|
|
732
|
-
<summary>Advanced unsafe use cases</summary>
|
|
733
|
-
|
|
734
|
-
### `await sql.unsafe(query, [args], [options]) -> Result[]`
|
|
735
|
-
|
|
736
|
-
If you know what you're doing, you can use `unsafe` to pass any string you'd like to postgres. Please note that this can lead to SQL injection if you're not careful.
|
|
737
|
-
|
|
738
|
-
```js
|
|
739
|
-
sql.unsafe('select ' + danger + ' from users where id = ' + dragons)
|
|
31
|
+
```sh
|
|
32
|
+
npm install postgres@npm:@steadybrew/postgresjs@^4
|
|
740
33
|
```
|
|
741
34
|
|
|
742
|
-
By default, `sql.unsafe` assumes the `query` string is sufficiently dynamic that prepared statements do not make sense, and so defaults them to off. If you'd like to re-enable prepared statements, you can pass `{ prepare: true }`.
|
|
743
|
-
|
|
744
|
-
You can also nest `sql.unsafe` within a safe `sql` expression. This is useful if only part of your fraction has unsafe elements.
|
|
745
|
-
|
|
746
35
|
```js
|
|
747
|
-
|
|
748
|
-
const triggerFnName = 'on_friend_created'
|
|
749
|
-
const eventType = 'insert'
|
|
750
|
-
const schema_name = 'app'
|
|
751
|
-
const table_name = 'friends'
|
|
36
|
+
import postgres from '@steadybrew/postgresjs' // or 'postgres' with the alias
|
|
752
37
|
|
|
753
|
-
|
|
754
|
-
create or replace trigger ${sql(triggerName)}
|
|
755
|
-
after ${sql.unsafe(eventType)} on ${sql.unsafe(`${schema_name}.${table_name}`)}
|
|
756
|
-
for each row
|
|
757
|
-
execute function ${sql(triggerFnName)}()
|
|
758
|
-
`
|
|
38
|
+
const sql = postgres(process.env.DATABASE_URL)
|
|
759
39
|
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
`
|
|
40
|
+
const minAge = 18
|
|
41
|
+
const users = await sql`select name, age from users where age >= ${ minAge }`
|
|
763
42
|
```
|
|
764
43
|
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
## Transactions
|
|
768
|
-
|
|
769
|
-
#### BEGIN / COMMIT `await sql.begin([options = ''], fn) -> fn()`
|
|
770
|
-
|
|
771
|
-
Use `sql.begin` to start a new transaction. Postgres.js will reserve a connection for the transaction and supply a scoped `sql` instance for all transaction uses in the callback function. `sql.begin` will resolve with the returned value from the callback function.
|
|
772
|
-
|
|
773
|
-
`BEGIN` is automatically sent with the optional options, and if anything fails `ROLLBACK` will be called so the connection can be released and execution can continue.
|
|
774
|
-
|
|
775
|
-
```js
|
|
776
|
-
const [user, account] = await sql.begin(async sql => {
|
|
777
|
-
const [user] = await sql`
|
|
778
|
-
insert into users (
|
|
779
|
-
name
|
|
780
|
-
) values (
|
|
781
|
-
'Murray'
|
|
782
|
-
)
|
|
783
|
-
returning *
|
|
784
|
-
`
|
|
44
|
+
## Switching from Postgres.js
|
|
785
45
|
|
|
786
|
-
|
|
787
|
-
insert into accounts (
|
|
788
|
-
user_id
|
|
789
|
-
) values (
|
|
790
|
-
${ user.user_id }
|
|
791
|
-
)
|
|
792
|
-
returning *
|
|
793
|
-
`
|
|
46
|
+
**Check first.** The [migration codemod](codemod/README.md) reports required changes, behaviour differences to review and useful fixes, with file and line. It changes nothing:
|
|
794
47
|
|
|
795
|
-
|
|
796
|
-
|
|
48
|
+
```sh
|
|
49
|
+
npx @steadybrew/postgresjs-migrate .
|
|
797
50
|
```
|
|
798
51
|
|
|
799
|
-
|
|
52
|
+
**Then migrate with Codemod:**
|
|
800
53
|
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
```js
|
|
804
|
-
const result = await sql.begin(sql => [
|
|
805
|
-
sql`update ...`,
|
|
806
|
-
sql`update ...`,
|
|
807
|
-
sql`insert ...`
|
|
808
|
-
])
|
|
54
|
+
```sh
|
|
55
|
+
npx codemod @steadybrew/postgresjs-migrate
|
|
809
56
|
```
|
|
810
57
|
|
|
811
|
-
|
|
58
|
+
Run it from your project root. It checks again, switches dependencies and overrides to the fork, and removes patches already covered by the fork. Your source code and imports stay unchanged. Run your package manager's install afterwards to update the lockfile.
|
|
812
59
|
|
|
813
|
-
|
|
814
|
-
sql.begin('read write', async sql => {
|
|
815
|
-
const [user] = await sql`
|
|
816
|
-
insert into users (
|
|
817
|
-
name
|
|
818
|
-
) values (
|
|
819
|
-
'Murray'
|
|
820
|
-
)
|
|
821
|
-
`
|
|
60
|
+
<a id="upgrading-to-400"></a>
|
|
822
61
|
|
|
823
|
-
|
|
824
|
-
sql`
|
|
825
|
-
insert into accounts (
|
|
826
|
-
user_id
|
|
827
|
-
) values (
|
|
828
|
-
${ user.user_id }
|
|
829
|
-
)
|
|
830
|
-
`
|
|
831
|
-
).catch(err => {
|
|
832
|
-
// Account could not be created. ROLLBACK SAVEPOINT is called because we caught the rejection.
|
|
833
|
-
})) || []
|
|
62
|
+
See the [migration guide](docs/upgrading.md) for behaviour changes, manual installation and the direct npm CLI.
|
|
834
63
|
|
|
835
|
-
|
|
836
|
-
})
|
|
837
|
-
.then(([user, account]) => {
|
|
838
|
-
// great success - COMMIT succeeded
|
|
839
|
-
})
|
|
840
|
-
.catch(() => {
|
|
841
|
-
// not so good - ROLLBACK was called
|
|
842
|
-
})
|
|
843
|
-
```
|
|
64
|
+
### Drizzle, Kysely and tracing
|
|
844
65
|
|
|
66
|
+
The alias above works with `drizzle-orm/postgres-js`, `drizzle-kit`, `kysely-postgres-js` and dd-trace. The codemod sets it up for existing projects, preserving `import postgres from 'postgres'`.
|
|
845
67
|
|
|
846
|
-
|
|
68
|
+
**Sentry needs an extra step:** add the [tracing preload](docs/upgrading.md#tracing) to retain automatic database spans. The codemod flags Sentry but does **not** apply this adjustment.
|
|
847
69
|
|
|
848
|
-
|
|
849
|
-
instead of being committed.
|
|
70
|
+
## Security
|
|
850
71
|
|
|
851
|
-
|
|
72
|
+
Published from GitHub Actions through npm trusted publishing, with provenance and maintainer approval using two-factor authentication. No stored npm token, runtime dependencies or registry install scripts. Verify with `npm audit signatures`.
|
|
852
73
|
|
|
853
|
-
|
|
854
|
-
sql.begin('read write', async sql => {
|
|
855
|
-
const [user] = await sql`
|
|
856
|
-
insert into users (
|
|
857
|
-
name
|
|
858
|
-
) values (
|
|
859
|
-
'Murray'
|
|
860
|
-
)
|
|
861
|
-
`
|
|
74
|
+
[Changes since upstream 3.4.9](https://github.com/steadybrew/postgresjs/compare/v3.4.9...main) ยท [Report a vulnerability](SECURITY.md) ยท [Unlicense](UNLICENSE)
|
|
862
75
|
|
|
863
|
-
|
|
864
|
-
})
|
|
865
|
-
```
|
|
76
|
+
## Compatibility
|
|
866
77
|
|
|
867
|
-
|
|
78
|
+
Releases pass the [test matrix](.github/workflows/test.yml) before publishing:
|
|
868
79
|
|
|
869
|
-
|
|
80
|
+
| Runtime | PostgreSQL tested |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| Node.js 22, 24 and 26, ESM and CommonJS | 15โ18 |
|
|
83
|
+
| Deno 1.46.3 | 17 |
|
|
84
|
+
| Cloudflare Workers (workerd) | 17 |
|
|
870
85
|
|
|
871
|
-
|
|
86
|
+
TypeScript declarations are included; use `@types/node` 22+ or `skipLibCheck`.
|
|
872
87
|
|
|
873
|
-
|
|
874
|
-
* For PascalCase - `postgres.pascal`, `postgres.toPascal`, `postgres.fromPascal`
|
|
875
|
-
* For Kebab-Case - `postgres.kebab`, `postgres.toKebab`, `postgres.fromKebab`
|
|
88
|
+
Older Node.js versions may work but aren't tested. The package declares `engines.node: >=22`, so package managers may warn or reject installation on older versions.
|
|
876
89
|
|
|
877
|
-
|
|
90
|
+
Hosted Supabase Edge Functions are deployed in production with this fork, outside the CI matrix. Standalone Deno 2 is unverified. Bun is best effort, without CI coverage. Cloudflare Workers has a known socket-close rejection ([#1196](https://github.com/porsager/postgres/issues/1196), [#1202](https://github.com/porsager/postgres/issues/1202)).
|
|
878
91
|
|
|
879
|
-
|
|
92
|
+
## Why this fork
|
|
880
93
|
|
|
881
|
-
|
|
882
|
-
// Transform the column names to and from camel case
|
|
883
|
-
const sql = postgres({ transform: postgres.camel })
|
|
94
|
+
As many of my deployments are on serverless, I ran into some Postgres.js limitations that made it harder to use it reliably. I moved a couple of projects off it and patched others to compare the pros and cons.
|
|
884
95
|
|
|
885
|
-
|
|
886
|
-
await sql`INSERT INTO camel_case ${ sql([{ aTest: 1, bTest: 1 }]) }`
|
|
887
|
-
const data = await sql`SELECT ${ sql('aTest', 'bTest') } FROM camel_case`
|
|
96
|
+
But I also realised that even for a small team of one, there is a clear path to updating and fixing Postgres.js, and I decided to bring those changes, whether from local patches, parked issues or PRs, to the benefit of the wider community.
|
|
888
97
|
|
|
889
|
-
|
|
890
|
-
```
|
|
98
|
+
The aim of this fork is to move faster while keeping rigorous review, automate broader, tedious testing, welcome community contributions, and make a library I enjoy using work better for everyone.
|
|
891
99
|
|
|
892
|
-
|
|
100
|
+
### Fixed Postgres.js issues
|
|
893
101
|
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
await sql`CREATE TABLE IF NOT EXISTS camel_case (a_test INTEGER)`
|
|
900
|
-
await sql`INSERT INTO camel_case ${ sql([{ a_test: 1 }]) }`
|
|
901
|
-
const data = await sql`SELECT a_test FROM camel_case`
|
|
902
|
-
|
|
903
|
-
console.log(data) // [ { aTest: 1 } ]
|
|
904
|
-
```
|
|
905
|
-
|
|
906
|
-
```js
|
|
907
|
-
// Transform the column names only from camel case
|
|
908
|
-
// (for interpolated inserts, updates, and selects)
|
|
909
|
-
const sql = postgres({ transform: postgres.fromCamel })
|
|
910
|
-
|
|
911
|
-
await sql`CREATE TABLE IF NOT EXISTS camel_case (a_test INTEGER)`
|
|
912
|
-
await sql`INSERT INTO camel_case ${ sql([{ aTest: 1 }]) }`
|
|
913
|
-
const data = await sql`SELECT ${ sql('aTest') } FROM camel_case`
|
|
914
|
-
|
|
915
|
-
console.log(data) // [ { a_test: 1 } ]
|
|
916
|
-
```
|
|
917
|
-
|
|
918
|
-
> Note that Postgres.js does not rewrite the static parts of the tagged template strings. So to transform column names in your queries, the `sql()` helper must be used - eg. `${ sql('columnName') }` as in the examples above.
|
|
919
|
-
|
|
920
|
-
### Transform `undefined` Values
|
|
921
|
-
|
|
922
|
-
By default, Postgres.js will throw the error `UNDEFINED_VALUE: Undefined values are not allowed` when undefined values are passed
|
|
923
|
-
|
|
924
|
-
```js
|
|
925
|
-
// Transform the column names to and from camel case
|
|
926
|
-
const sql = postgres({
|
|
927
|
-
transform: {
|
|
928
|
-
undefined: null
|
|
929
|
-
}
|
|
930
|
-
})
|
|
931
|
-
|
|
932
|
-
await sql`CREATE TABLE IF NOT EXISTS transform_undefined (a_test INTEGER)`
|
|
933
|
-
await sql`INSERT INTO transform_undefined ${ sql([{ a_test: undefined }]) }`
|
|
934
|
-
const data = await sql`SELECT a_test FROM transform_undefined`
|
|
935
|
-
|
|
936
|
-
console.log(data) // [ { a_test: null } ]
|
|
937
|
-
```
|
|
938
|
-
|
|
939
|
-
To combine with the built in transform functions, spread the transform in the `transform` object:
|
|
940
|
-
|
|
941
|
-
```js
|
|
942
|
-
// Transform the column names to and from camel case
|
|
943
|
-
const sql = postgres({
|
|
944
|
-
transform: {
|
|
945
|
-
...postgres.camel,
|
|
946
|
-
undefined: null
|
|
947
|
-
}
|
|
948
|
-
})
|
|
949
|
-
|
|
950
|
-
await sql`CREATE TABLE IF NOT EXISTS transform_undefined (a_test INTEGER)`
|
|
951
|
-
await sql`INSERT INTO transform_undefined ${ sql([{ aTest: undefined }]) }`
|
|
952
|
-
const data = await sql`SELECT ${ sql('aTest') } FROM transform_undefined`
|
|
953
|
-
|
|
954
|
-
console.log(data) // [ { aTest: null } ]
|
|
955
|
-
```
|
|
956
|
-
|
|
957
|
-
### Custom Transform Functions
|
|
958
|
-
|
|
959
|
-
To specify your own transformation functions, you can use the `column`, `value` and `row` options inside of `transform`, each an object possibly including `to` and `from` keys:
|
|
960
|
-
|
|
961
|
-
* `to`: The function to transform the outgoing query column name to, i.e `SELECT ${ sql('aName') }` to `SELECT a_name` when using `postgres.toCamel`.
|
|
962
|
-
* `from`: The function to transform the incoming query result column name to, see example below.
|
|
963
|
-
|
|
964
|
-
> Both parameters are optional, if not provided, the default transformation function will be used.
|
|
965
|
-
|
|
966
|
-
```js
|
|
967
|
-
// Implement your own functions, look at postgres.toCamel, etc
|
|
968
|
-
// as a reference:
|
|
969
|
-
// https://github.com/porsager/postgres/blob/4241824ffd7aa94ffb482e54ca9f585d9d0a4eea/src/types.js#L310-L328
|
|
970
|
-
function transformColumnToDatabase() { /* ... */ }
|
|
971
|
-
function transformColumnFromDatabase() { /* ... */ }
|
|
972
|
-
|
|
973
|
-
const sql = postgres({
|
|
974
|
-
transform: {
|
|
975
|
-
column: {
|
|
976
|
-
to: transformColumnToDatabase,
|
|
977
|
-
from: transformColumnFromDatabase,
|
|
978
|
-
},
|
|
979
|
-
value: { /* ... */ },
|
|
980
|
-
row: { /* ... */ }
|
|
981
|
-
}
|
|
982
|
-
})
|
|
983
|
-
```
|
|
984
|
-
|
|
985
|
-
## Listen & notify
|
|
986
|
-
|
|
987
|
-
When you call `.listen`, a dedicated connection will be created to ensure that you receive notifications instantly. This connection will be used for any further calls to `.listen`. The connection will automatically reconnect according to a backoff reconnection pattern to not overload the database server.
|
|
988
|
-
|
|
989
|
-
### Listen `await sql.listen(channel, onnotify, [onlisten]) -> { state }`
|
|
990
|
-
`.listen` takes the channel name, a function to handle each notify, and an optional function to run every time listen is registered and ready (happens on initial connect and reconnects). It returns a promise which resolves once the `LISTEN` query to Postgres completes, or if there is already a listener active. If either function throws, the error is rethrown as an uncaught exception, and the other listeners and the returned promise are not affected.
|
|
991
|
-
|
|
992
|
-
```js
|
|
993
|
-
await sql.listen('news', payload => {
|
|
994
|
-
const json = JSON.parse(payload)
|
|
995
|
-
console.log(json.this) // logs 'is'
|
|
996
|
-
})
|
|
997
|
-
```
|
|
998
|
-
|
|
999
|
-
The optional `onlisten` method is great to use for a very simply queue mechanism:
|
|
1000
|
-
|
|
1001
|
-
```js
|
|
1002
|
-
await sql.listen(
|
|
1003
|
-
'jobs',
|
|
1004
|
-
(x) => run(JSON.parse(x)),
|
|
1005
|
-
( ) => sql`select unfinished_jobs()`.forEach(run)
|
|
1006
|
-
)
|
|
1007
|
-
|
|
1008
|
-
function run(job) {
|
|
1009
|
-
// And here you do the work you please
|
|
1010
|
-
}
|
|
1011
|
-
```
|
|
1012
|
-
### Notify `await sql.notify(channel, payload) -> Result[]`
|
|
1013
|
-
Notify can be done as usual in SQL, or by using the `sql.notify` method.
|
|
1014
|
-
```js
|
|
1015
|
-
sql.notify('news', JSON.stringify({ no: 'this', is: 'news' }))
|
|
1016
|
-
```
|
|
1017
|
-
|
|
1018
|
-
## Realtime subscribe
|
|
1019
|
-
|
|
1020
|
-
Postgres.js implements the logical replication protocol of PostgreSQL to support subscription to real-time updates of `insert`, `update` and `delete` operations.
|
|
1021
|
-
|
|
1022
|
-
> **NOTE** To make this work you must [create the proper publications in your database](https://www.postgresql.org/docs/current/sql-createpublication.html), enable logical replication by setting `wal_level = logical` in `postgresql.conf` and connect using either a replication or superuser.
|
|
1023
|
-
|
|
1024
|
-
### Quick start
|
|
1025
|
-
|
|
1026
|
-
#### Create a publication (eg. in migration)
|
|
1027
|
-
```sql
|
|
1028
|
-
CREATE PUBLICATION alltables FOR ALL TABLES
|
|
1029
|
-
```
|
|
1030
|
-
|
|
1031
|
-
#### Subscribe to updates
|
|
1032
|
-
```js
|
|
1033
|
-
const sql = postgres({ publications: 'alltables' })
|
|
1034
|
-
|
|
1035
|
-
const { unsubscribe } = await sql.subscribe(
|
|
1036
|
-
'insert:events',
|
|
1037
|
-
(row, { command, relation, key, old }) => {
|
|
1038
|
-
// Callback function for each row change
|
|
1039
|
-
// tell about new event row over eg. websockets or do something else
|
|
1040
|
-
},
|
|
1041
|
-
() => {
|
|
1042
|
-
// Callback on initial connect and potential reconnects
|
|
1043
|
-
},
|
|
1044
|
-
(error) => {
|
|
1045
|
-
// Callback on connection errors and changes that could not be decoded
|
|
1046
|
-
}
|
|
1047
|
-
)
|
|
1048
|
-
```
|
|
1049
|
-
|
|
1050
|
-
If any of these callbacks throws, the error is rethrown as an uncaught exception, and other subscribers and the replication stream are not affected.
|
|
1051
|
-
|
|
1052
|
-
`onerror` is called with errors of the replication connection, after which the subscription reconnects on a new replication slot and calls `onsubscribe` again (these are also logged with `console.error`, and changes committed while it was disconnected are not delivered; if the reconnect itself fails, it is retried with backoff, its error is logged with `console.error` and passed to `onerror`, and it never ends the process), and with errors thrown while a change is decoded by a [transform](#data-transformation) or a custom type parser. Such a change is skipped, and the replication stream and later changes carry on. A decode error goes only to the subscriptions that would have received the change, matched by operation and table; a subscription filtered by key gets every skipped change of its table, as the key is read from the decoded row, even if the table has no primary key. If a column name transform throws, each change of that table is skipped and reported until the server describes the table again, for example after `ALTER TABLE`. If one of the matching subscriptions has no `onerror`, the error is rethrown once as an uncaught exception, which ends the process under Node's default handling. `onerror` stays registered across reconnects until `unsubscribe()`.
|
|
1053
|
-
|
|
1054
|
-
### Subscribe pattern
|
|
1055
|
-
|
|
1056
|
-
You can subscribe to specific operations, tables, or even rows with primary keys.
|
|
1057
|
-
|
|
1058
|
-
#### `operation` `:` `schema` `.` `table` `=` `primary_key`
|
|
1059
|
-
|
|
1060
|
-
**`operation`** is one of ``` * | insert | update | delete ``` and defaults to `*`
|
|
1061
|
-
|
|
1062
|
-
**`schema`** defaults to `public`
|
|
1063
|
-
|
|
1064
|
-
**`table`** is a specific table name and defaults to `*`
|
|
1065
|
-
|
|
1066
|
-
**`primary_key`** can be used to only subscribe to specific rows
|
|
1067
|
-
|
|
1068
|
-
### Examples
|
|
1069
|
-
|
|
1070
|
-
```js
|
|
1071
|
-
sql.subscribe('*', () => /* everything */ )
|
|
1072
|
-
sql.subscribe('insert', () => /* all inserts */ )
|
|
1073
|
-
sql.subscribe('*:users', () => /* all operations on the public.users table */ )
|
|
1074
|
-
sql.subscribe('delete:users', () => /* all deletes on the public.users table */ )
|
|
1075
|
-
sql.subscribe('update:users=1', () => /* all updates on the users row with a primary key = 1 */ )
|
|
1076
|
-
```
|
|
1077
|
-
|
|
1078
|
-
## Numbers, bigint, numeric
|
|
1079
|
-
|
|
1080
|
-
`Number` in javascript is only able to represent 2<sup>53</sup>-1 safely which means that types in PostgreSQLs like `bigint` and `numeric` won't fit into `Number`.
|
|
1081
|
-
|
|
1082
|
-
Since Node.js v10.4 we can use [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) to match the PostgreSQL type `bigint` which is returned for eg. `count(*)`. Unfortunately, it doesn't work with `JSON.stringify` out of the box, so Postgres.js will return it as a string.
|
|
1083
|
-
|
|
1084
|
-
If you want to use `BigInt` you can add this custom type:
|
|
1085
|
-
|
|
1086
|
-
```js
|
|
1087
|
-
const sql = postgres({
|
|
1088
|
-
types: {
|
|
1089
|
-
bigint: postgres.BigInt
|
|
1090
|
-
}
|
|
1091
|
-
})
|
|
1092
|
-
```
|
|
1093
|
-
|
|
1094
|
-
There is currently no guaranteed way to handle `numeric` / `decimal` types in native Javascript. **These [and similar] types will be returned as a `string`**. The best way in this case is to use [custom types](#custom-types).
|
|
1095
|
-
|
|
1096
|
-
## Parameter types
|
|
1097
|
-
|
|
1098
|
-
A `$1` placeholder has a type that PostgreSQL infers from the SQL around it (the column it is compared to or inserted into, a function argument, a cast). Postgres.js has to turn each JavaScript value into text for that type, and `parameter_types` chooses how.
|
|
1099
|
-
|
|
1100
|
-
Some values carry a type Postgres.js can tell from the JavaScript value: `Date`, `Buffer` / `Uint8Array`, booleans, `bigint`, and anything wrapped in `sql.typed(value, oid)`, `sql.types.*`, `sql.json` or `sql.array` with elements. They are serialized for that type and sent in a single round trip, in every mode. Everything else (strings, numbers, plain objects, `sql.typed(value)` without an OID, an empty `sql.array([])`, arrays) has no such type. `null` is always SQL `NULL`.
|
|
1101
|
-
|
|
1102
|
-
### `parameter_types: 'server'` (default)
|
|
1103
|
-
|
|
1104
|
-
For a value whose type Postgres.js cannot tell, it first asks PostgreSQL for the type of the placeholder, which costs an extra round trip on every query with `prepare: false` and the first time each connection runs that SQL with `prepare: true`, and then serializes the value for that type. This has consequences worth knowing:
|
|
1105
|
-
|
|
1106
|
-
- a string sent to a `json` or `jsonb` placeholder is sent as JSON, so `'{"a":1}'` is stored as a JSON string, not an object
|
|
1107
|
-
- a string or number sent to a `date`, `timestamp` or `timestamptz` placeholder goes through `new Date(x).toISOString()`, where a date-only string such as `'2020-01-02'` is read as UTC and a date-and-time string without an offset such as `'2020-01-02T10:00'` is read in the Node.js process time zone (`TZ`)
|
|
1108
|
-
- anything other than `true` sent to a `boolean` placeholder is stored as `false`, including the strings `'true'` and `'t'` and the number `1`
|
|
1109
|
-
- a string sent to a `bytea` placeholder is sent as hex of its UTF-8 bytes
|
|
1110
|
-
- a custom type registered in `types` with a `from` list runs its `serialize` function
|
|
1111
|
-
|
|
1112
|
-
### `parameter_types: 'client'`
|
|
1113
|
-
|
|
1114
|
-
The JavaScript value decides how it is serialized and PostgreSQL parses the text, so a query with values is one round trip:
|
|
1115
|
-
|
|
1116
|
-
- a string is sent unchanged as text
|
|
1117
|
-
- a number is sent as its JavaScript text (`'' + n`)
|
|
1118
|
-
- a plain object (prototype `Object.prototype` or `null`) is sent as `JSON.stringify(x)`
|
|
1119
|
-
- any other object (Decimal, Luxon, moment, URL, class instances) is sent as `'' + x`
|
|
1120
|
-
- `null` is SQL `NULL`; `undefined` is handled as before
|
|
1121
|
-
- a value with a type Postgres.js can tell from the JavaScript value is serialized for that type, as with `'server'`
|
|
1122
|
-
- an array whose elements have no such type still makes Postgres.js ask PostgreSQL for the placeholder's type first, because only PostgreSQL knows whether the placeholder is an array, JSON or a custom type; that query takes the extra round trip
|
|
1123
|
-
|
|
1124
|
-
What this changes compared to `'server'`:
|
|
1125
|
-
|
|
1126
|
-
| Value | Type PostgreSQL infers for the placeholder | `'server'` | `'client'` |
|
|
1127
|
-
| --- | --- | --- | --- |
|
|
1128
|
-
| string | json, jsonb | sent as JSON: stores a JSON string | parsed as JSON; text that is not JSON is rejected |
|
|
1129
|
-
| string | boolean | always `false` | PostgreSQL boolean input (`'t'`, `'yes'`, `'on'`, `'1'` are true); invalid text is rejected |
|
|
1130
|
-
| string | date, timestamp, timestamptz | `new Date(s).toISOString()`: date-only strings are read as UTC, date-and-time strings without an offset in the Node.js process time zone (`TZ`) | parsed by PostgreSQL in the PostgreSQL session's `TimeZone` setting; `date` and `timestamp` ignore an explicit offset |
|
|
1131
|
-
| string | bytea | hex of the UTF-8 bytes | bytea text input; differs only for strings containing backslashes |
|
|
1132
|
-
| string, number | a custom type registered in `types` with a `from` list | the type's `serialize` | sent unchanged as text |
|
|
1133
|
-
| number | json, jsonb | `JSON.stringify` (`NaN` and `Infinity` become `null`) | the number's text (`NaN` and `Infinity` are rejected) |
|
|
1134
|
-
| number | boolean | `false` | `1` is true, `0` is false, anything else is rejected |
|
|
1135
|
-
| number | date, timestamp, timestamptz | `new Date(ms)` | rejected, except `Infinity`; a 6- or 8-digit number is read as a `YYMMDD` or `YYYYMMDD` date |
|
|
1136
|
-
| plain object | json, jsonb | `JSON.stringify` or your json `serialize` | `JSON.stringify` |
|
|
1137
|
-
| plain object | text | `[object Object]` | JSON text |
|
|
1138
|
-
| plain object | a custom type registered in `types` with a `from` list | the type's `serialize` | JSON text, normally rejected |
|
|
1139
|
-
| class instance | json, jsonb | `JSON.stringify`, so `toJSON` applies | `'' + x` |
|
|
1140
|
-
| class instance | date, timestamp, timestamptz | `new Date(x)` | `'' + x`, normally rejected |
|
|
1141
|
-
|
|
1142
|
-
`time`, `timetz` and `interval` placeholders have no serializer in either mode: strings and numbers are sent unchanged as text.
|
|
1143
|
-
|
|
1144
|
-
In practice:
|
|
1145
|
-
|
|
1146
|
-
- pass `new Date(ms)` for epoch numbers, and set `connection: { timezone }` so date strings are read in the time zone you expect
|
|
1147
|
-
- pass `sql.json(s)` for a JSON string value, and `sql.types.name(v)` or `sql.typed(v, oid)` for a custom type; a custom type's `serialize` also runs for a whole array bound to that type, never for a plain value
|
|
1148
|
-
- `NaN`, `Infinity` and `-0` are sent as `NaN`, `Infinity` and `0`, and PostgreSQL's input rules for the placeholder's type decide
|
|
1149
|
-
|
|
1150
|
-
Run `'warn'` first to see which of your queries are affected.
|
|
1151
|
-
|
|
1152
|
-
**Planned for 5.0:** `'client'` becomes the default. Pass `parameter_types: 'server'` to keep the 4.x behaviour.
|
|
1153
|
-
|
|
1154
|
-
### `parameter_types: 'warn'`
|
|
1155
|
-
|
|
1156
|
-
`'warn'` behaves exactly like `'server'`, and also reports every query in which a value would be sent differently by `'client'`. The report goes to `ontypemismatch`, or to `console.warn` when it is not set:
|
|
1157
|
-
|
|
1158
|
-
```js
|
|
1159
|
-
const sql = postgres({
|
|
1160
|
-
parameter_types: 'warn',
|
|
1161
|
-
ontypemismatch: ({ query, parameters }) => {
|
|
1162
|
-
// parameters: [{ position: 2, oid: 3802, typeof: 'string' }]
|
|
1163
|
-
// position is the $n number, oid the type PostgreSQL inferred for the placeholder
|
|
1164
|
-
}
|
|
1165
|
-
})
|
|
1166
|
-
```
|
|
1167
|
-
|
|
1168
|
-
With `debug: true` each entry also carries `serverText` and `clientText`, the two texts that were compared; `clientText` is the error when the `'client'` mode would throw. A query is reported on every execution that has a difference; sample in `ontypemismatch` if that is too much. `'warn'` serializes each untyped value twice and compares the strings. The option can also be set with `?parameter_types=warn` in the connection URL or `PGPARAMETER_TYPES`.
|
|
1169
|
-
|
|
1170
|
-
`'warn'` compares the serialized text, not the stored value, so a report does not always mean the stored value would change.
|
|
1171
|
-
|
|
1172
|
-
These reported cases store the same value under both modes:
|
|
1173
|
-
|
|
1174
|
-
- `0`, `'0'`, `'false'`, `'no'` and `'off'` sent to a `boolean` placeholder (the texts differ, both store `false`)
|
|
1175
|
-
- a date string with an explicit offset sent to a `timestamptz` placeholder, as long as it has no more than millisecond precision (`toISOString()` truncates microseconds, so a string with microseconds stores a different value under `'server'`)
|
|
1176
|
-
- a string without backslashes sent to a `bytea` placeholder
|
|
1177
|
-
|
|
1178
|
-
These reported cases store a different value, or are rejected, under `'client'`:
|
|
1179
|
-
|
|
1180
|
-
- `1`, `'t'`, `'true'`, `'yes'`, `'on'` and `'1'` sent to a `boolean` placeholder (stored `false` today, `true` under `'client'`)
|
|
1181
|
-
- a date string with an explicit offset sent to a `timestamp` or `date` placeholder (`'server'` converts to UTC first, `'client'` drops the offset)
|
|
1182
|
-
- a string sent to a `json` or `jsonb` placeholder, a plain object sent to a `text` placeholder, and a number sent to a date, timestamp or boolean placeholder
|
|
1183
|
-
- a string or number sent to a custom type registered in `types` with a `from` list, which skips its `serialize`
|
|
1184
|
-
|
|
1185
|
-
Date strings without an explicit offset:
|
|
1186
|
-
|
|
1187
|
-
| String | Placeholder | Stored the same under both modes when |
|
|
1188
|
-
| --- | --- | --- |
|
|
1189
|
-
| date and time, such as `'2020-01-02T10:00'` | `timestamptz` | the Node.js process time zone and the PostgreSQL session's `TimeZone` setting match |
|
|
1190
|
-
| date only, such as `'2020-01-02'` | `timestamptz` | the PostgreSQL session's `TimeZone` setting is UTC |
|
|
1191
|
-
| date and time | `timestamp` or `date` | the Node.js process runs in UTC (`'server'` stores the UTC wall time, `'client'` stores the text as written) |
|
|
1192
|
-
|
|
1193
|
-
## Result Array
|
|
1194
|
-
|
|
1195
|
-
The `Result` Array returned from queries is a custom array allowing for easy destructuring or passing on directly to JSON.stringify or general Array usage. It includes the following properties.
|
|
1196
|
-
|
|
1197
|
-
### .count
|
|
1198
|
-
|
|
1199
|
-
The `count` property is the number of affected rows returned by the database. This is useful for insert, update and delete operations to know the number of rows since .length will be 0 in these cases if not using `RETURNING ...`.
|
|
1200
|
-
|
|
1201
|
-
### .command
|
|
1202
|
-
|
|
1203
|
-
The `command` run by the query - eg. one of `SELECT`, `UPDATE`, `INSERT`, `DELETE`
|
|
1204
|
-
|
|
1205
|
-
### .columns
|
|
1206
|
-
|
|
1207
|
-
The `columns` returned by the query useful to determine types, or map to the result values when using `.values()`
|
|
1208
|
-
|
|
1209
|
-
```js
|
|
1210
|
-
{
|
|
1211
|
-
name : String, // Column name,
|
|
1212
|
-
type : oid, // PostgreSQL oid column type
|
|
1213
|
-
parser: Function // The function used by Postgres.js for parsing
|
|
1214
|
-
}
|
|
1215
|
-
```
|
|
1216
|
-
|
|
1217
|
-
### .statement
|
|
1218
|
-
|
|
1219
|
-
The `statement` contains information about the statement implicitly created by Postgres.js.
|
|
1220
|
-
|
|
1221
|
-
```js
|
|
1222
|
-
{
|
|
1223
|
-
name : String, // The auto generated statement name
|
|
1224
|
-
string : String, // The actual query string executed
|
|
1225
|
-
types : [oid], // An array of oid expected as input parameters
|
|
1226
|
-
columns : [Column] // Array of columns - same as Result.columns
|
|
1227
|
-
}
|
|
1228
|
-
```
|
|
1229
|
-
|
|
1230
|
-
### .state
|
|
1231
|
-
|
|
1232
|
-
This is the state `{ pid, secret }` of the connection that executed the query.
|
|
1233
|
-
|
|
1234
|
-
## Connection details
|
|
1235
|
-
|
|
1236
|
-
### All Postgres options
|
|
1237
|
-
|
|
1238
|
-
```js
|
|
1239
|
-
const sql = postgres('postgres://username:password@host:port/database', {
|
|
1240
|
-
host : '', // Postgres ip address[es] or domain name[s]
|
|
1241
|
-
port : 5432, // Postgres server port[s]
|
|
1242
|
-
path : '', // unix socket path (usually '/tmp')
|
|
1243
|
-
database : '', // Name of database to connect to
|
|
1244
|
-
username : '', // Username of database user
|
|
1245
|
-
password : '', // Password of database user
|
|
1246
|
-
ssl : false, // true, prefer, require, tls.connect options
|
|
1247
|
-
sslnegotiation : null, // direct
|
|
1248
|
-
max : 10, // Max number of connections
|
|
1249
|
-
max_lifetime : null, // Max lifetime in seconds (more info below)
|
|
1250
|
-
idle_timeout : 0, // Idle connection timeout in seconds
|
|
1251
|
-
connect_timeout : 30, // Connect timeout in seconds
|
|
1252
|
-
prepare : true, // Automatic creation of prepared statements
|
|
1253
|
-
types : [], // Array of custom types, see more below
|
|
1254
|
-
onnotice : fn, // Default console.log, set false to silence NOTICE
|
|
1255
|
-
onparameter : fn, // (key, value) when server param change
|
|
1256
|
-
onidle : fn, // (connId) when a connection returns to the pool idle
|
|
1257
|
-
debug : fn, // Is called with (connection, query, params, types)
|
|
1258
|
-
socket : fn, // fn returning custom socket to use
|
|
1259
|
-
transform : {
|
|
1260
|
-
undefined : undefined, // Transforms undefined values (eg. to null)
|
|
1261
|
-
column : fn, // Transforms incoming column names
|
|
1262
|
-
value : fn, // Transforms incoming row values
|
|
1263
|
-
row : fn // Transforms entire rows
|
|
1264
|
-
},
|
|
1265
|
-
connection : {
|
|
1266
|
-
application_name : 'postgres.js', // Default application_name
|
|
1267
|
-
... // Other connection parameters, see https://www.postgresql.org/docs/current/runtime-config-client.html
|
|
1268
|
-
},
|
|
1269
|
-
target_session_attrs : null, // Which kind of server to connect to, see
|
|
1270
|
-
// Multi-host connections below
|
|
1271
|
-
fetch_types : true, // Automatically fetches types on connect
|
|
1272
|
-
// on initial connection.
|
|
1273
|
-
parameter_types : 'server', // 'client' or 'warn', see Parameter types (PGPARAMETER_TYPES)
|
|
1274
|
-
ontypemismatch : fn, // Called by parameter_types: 'warn', default console.warn
|
|
1275
|
-
})
|
|
1276
|
-
```
|
|
1277
|
-
|
|
1278
|
-
The `onnotice`, `onparameter`, `ontypemismatch`, `onnotify`, `onclose`, `onidle` and `debug` callbacks passed in the options are called synchronously from inside the driver. If one throws, the error is rethrown as an uncaught exception and the connection and its queries are not affected; under Node's default handling that ends the process.
|
|
1279
|
-
|
|
1280
|
-
Note that `max_lifetime = 60 * (30 + Math.random() * 30)` by default. This resolves to an interval between 30 and 60 minutes to optimize for the benefits of prepared statements **and** working nicely with Linux's OOM killer.
|
|
1281
|
-
|
|
1282
|
-
### Dynamic passwords
|
|
1283
|
-
|
|
1284
|
-
When clients need to use alternative authentication schemes such as access tokens or connections to databases with rotating passwords, provide either a synchronous or asynchronous function that will resolve the dynamic password value at connection time.
|
|
1285
|
-
|
|
1286
|
-
```js
|
|
1287
|
-
const sql = postgres(url, {
|
|
1288
|
-
// Other connection config
|
|
1289
|
-
...
|
|
1290
|
-
// Password function for the database user
|
|
1291
|
-
password : async () => await signer.getAuthToken(),
|
|
1292
|
-
})
|
|
1293
|
-
```
|
|
1294
|
-
|
|
1295
|
-
### SSL
|
|
1296
|
-
|
|
1297
|
-
Although [vulnerable to MITM attacks](https://security.stackexchange.com/a/229297/174913), a common configuration for the `ssl` option for some cloud providers is to set `rejectUnauthorized` to `false` (if `NODE_ENV` is `production`):
|
|
1298
|
-
|
|
1299
|
-
```js
|
|
1300
|
-
const sql =
|
|
1301
|
-
process.env.NODE_ENV === 'production'
|
|
1302
|
-
? // "Unless you're using a Private or Shield Heroku Postgres database, Heroku Postgres does not currently support verifiable certificates"
|
|
1303
|
-
// https://help.heroku.com/3DELT3RK/why-can-t-my-third-party-utility-connect-to-heroku-postgres-with-ssl
|
|
1304
|
-
postgres({ ssl: { rejectUnauthorized: false } })
|
|
1305
|
-
: postgres()
|
|
1306
|
-
```
|
|
1307
|
-
|
|
1308
|
-
For more information regarding `ssl` with `postgres`, check out the [Node.js documentation for tls](https://nodejs.org/dist/latest-v16.x/docs/api/tls.html#new-tlstlssocketsocket-options).
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
|
-
### Multi-host connections - High Availability (HA)
|
|
1312
|
-
|
|
1313
|
-
Multiple connection strings can be passed to `postgres()` in the form of `postgres('postgres://localhost:5432,localhost:5433', ...)`. This works the same as native the `psql` command. Read more at [multiple host URIs](https://www.postgresql.org/docs/13/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS).
|
|
1314
|
-
|
|
1315
|
-
Connections will be attempted in order of the specified hosts/ports. On a successful connection, all retries will be reset. This ensures that hosts can come up and down seamlessly.
|
|
1316
|
-
|
|
1317
|
-
`target_session_attrs` (or `PGTARGETSESSIONATTRS`) picks which kind of server to connect to. The values and their meaning are libpq's:
|
|
1318
|
-
|
|
1319
|
-
| Value | Connects to |
|
|
1320
|
-
|---|---|
|
|
1321
|
-
| `null` (default) | any server |
|
|
1322
|
-
| `'read-write'` | a server that accepts writes: not a hot standby, and `default_transaction_read_only` off |
|
|
1323
|
-
| `'primary'` | a server that is not a hot standby, even if `default_transaction_read_only` is on |
|
|
1324
|
-
| `'read-only'` | a hot standby, or a server with `default_transaction_read_only` on |
|
|
1325
|
-
| `'standby'` | a hot standby |
|
|
1326
|
-
| `'prefer-standby'` | a hot standby if any host is one, otherwise any server |
|
|
1327
|
-
|
|
1328
|
-
During a failover or an upgrade, `'read-write'` and `'primary'` wait for the promoted server instead of connecting to a standby whose writes would fail. Read traffic that should keep using standbys during the switch belongs on `'prefer-standby'` or no `target_session_attrs` at all.
|
|
1329
|
-
|
|
1330
|
-
With several hosts, a host that answers but is the wrong kind is skipped and the next one is tried at once; if every host answers and none matches, the connection fails immediately with `TARGET_SESSION_ATTRS`. With a single host, or when some host fails to connect, it keeps retrying, bounded by `connect_timeout` per host, because a failover may be in progress.
|
|
1331
|
-
|
|
1332
|
-
### The Connection Pool
|
|
1333
|
-
|
|
1334
|
-
Connections are created lazily once a query is created. This means that simply doing const `sql = postgres(...)` won't have any effect other than instantiating a new `sql` instance.
|
|
1335
|
-
|
|
1336
|
-
> No connection will be made until a query is made.
|
|
1337
|
-
|
|
1338
|
-
For example:
|
|
1339
|
-
|
|
1340
|
-
```js
|
|
1341
|
-
const sql = postgres() // no connections are opened
|
|
1342
|
-
|
|
1343
|
-
await sql`...` // one connection is now opened
|
|
1344
|
-
await sql`...` // previous opened connection is reused
|
|
1345
|
-
|
|
1346
|
-
// two connections are opened now
|
|
1347
|
-
await Promise.all([
|
|
1348
|
-
sql`...`,
|
|
1349
|
-
sql`...`
|
|
1350
|
-
])
|
|
1351
|
-
```
|
|
1352
|
-
|
|
1353
|
-
> When there are high amount of concurrent queries, `postgres` will open as many connections as needed up until `max` number of connections is reached. By default `max` is 10. This can be changed by setting `max` in the `postgres()` call. Example - `postgres('connectionURL', { max: 20 })`.
|
|
1354
|
-
|
|
1355
|
-
This means that we get a much simpler story for error handling and reconnections. Queries will be sent over the wire immediately on the next available connection in the pool. Connections are automatically taken out of the pool if you start a transaction using `sql.begin()`, and automatically returned to the pool once your transaction is done.
|
|
1356
|
-
|
|
1357
|
-
Any query which was already sent over the wire will be rejected if the connection is lost. It'll automatically defer to the error handling you have for that query, and since connections are lazy it'll automatically try to reconnect the next time a query is made. The benefit of this is no weird generic "onerror" handler that tries to get things back to normal, and also simpler application code since you don't have to handle errors out of context.
|
|
1358
|
-
|
|
1359
|
-
There are no guarantees about queries executing in order unless using a transaction with `sql.begin()` or setting `max: 1`. Of course doing a series of queries, one awaiting the other will work as expected, but that's just due to the nature of js async/promise handling, so it's not necessary for this library to be concerned with ordering.
|
|
1360
|
-
|
|
1361
|
-
Since this library automatically creates prepared statements, it also has a default max lifetime for connections to prevent memory bloat on the database itself. This is a random interval for each connection between 45 and 90 minutes. This allows multiple connections to independently come up and down without affecting the service.
|
|
1362
|
-
|
|
1363
|
-
### Pool stats
|
|
1364
|
-
|
|
1365
|
-
`sql.stats()` returns a snapshot of the pool as a plain object, ready to log, serialise from a health endpoint or map to metrics gauges:
|
|
1366
|
-
|
|
1367
|
-
```js
|
|
1368
|
-
sql.stats()
|
|
1369
|
-
// { max: 10, totalCount: 7, idleCount: 2, waitingCount: 3,
|
|
1370
|
-
// activeCount: 4, availableCount: 5,
|
|
1371
|
-
// busyCount: 3, reservedCount: 1, connectingCount: 1, closingCount: 0,
|
|
1372
|
-
// executingCount: 4, listenCount: 1, subscribeCount: 0 }
|
|
1373
|
-
```
|
|
1374
|
-
|
|
1375
|
-
| Field | Meaning |
|
|
1376
|
-
|---|---|
|
|
1377
|
-
| `max` | The `max` option |
|
|
1378
|
-
| `totalCount` | Connections that exist: connecting, idle or in use |
|
|
1379
|
-
| `idleCount` | Connections with a live session that are not in use. A connection released while its reserved handle still has queries in flight is idle with `executingCount` above 0 |
|
|
1380
|
-
| `waitingCount` | Issued queries and `reserve()` or `begin()` calls that are not running yet: those in the pool queue, those held by a connection that is still opening, those pipelined behind a connection's running query, and those a reserved handle or transaction has queued behind its own connection |
|
|
1381
|
-
| `activeCount` | `busyCount + reservedCount`, connections in use |
|
|
1382
|
-
| `availableCount` | `idleCount` plus the slots the pool can still open (`max - totalCount - closingCount`): connections a query can get without waiting behind other work |
|
|
1383
|
-
| `busyCount` | Pool connections running queries, including connections at the pipeline limit |
|
|
1384
|
-
| `reservedCount` | Connections held by `reserve()` or `begin()` |
|
|
1385
|
-
| `connectingCount` | Connections opening a session |
|
|
1386
|
-
| `closingCount` | Connections draining or closing. They are not in `totalCount`, but still hold a pool slot until closed |
|
|
1387
|
-
| `executingCount` | Queries the server is running right now, at most one per connection, on pool and reserved connections alike. It includes the queries the driver runs while a connection starts, and a `COPY` for its whole duration |
|
|
1388
|
-
| `listenCount` | Connections held by the internal `sql.listen()` pool (0 or 1) |
|
|
1389
|
-
| `subscribeCount` | Connections held by the internal `sql.subscribe()` pool (0 or 1) |
|
|
1390
|
-
|
|
1391
|
-
`totalCount` and `idleCount` have the same meaning as in node-postgres. `waitingCount` is node-postgres's `waitingCount` extended to queries pipelined on connections and queued in leases, and it includes queries sent with `sql` directly, as `pool.query()` does there. Once the pool is at `max`, Postgres.js pipelines new queries onto busy connections, so waiting work can sit on a connection rather than in the pool queue; `waitingCount` counts it too, so `executingCount + waitingCount` covers all issued work that has not finished. Every snapshot satisfies `totalCount === idleCount + busyCount + reservedCount + connectingCount` and `totalCount + closingCount <= max`, the remainder being slots the pool has not opened.
|
|
1392
|
-
|
|
1393
|
-
`listenCount` and `subscribeCount` are counted outside `max`, and the other fields only describe the `max` pool connections. A reserved connection's `stats()` returns the same snapshot, but `sql` inside `sql.begin()` and savepoints has no `stats()`, so call it on the main `sql`.
|
|
1394
|
-
|
|
1395
|
-
The pool is saturated when `waitingCount > 0 && availableCount === 0`: every connection is in use and more work is waiting. Saturation alone is not a reason to fail a health check, because a single pipelined query on a fully used pool, including a transaction pipelining its own statements, is enough to meet it. A health endpoint should compare `waitingCount` against a limit the application chooses:
|
|
1396
|
-
|
|
1397
|
-
```js
|
|
1398
|
-
import http from 'node:http'
|
|
1399
|
-
|
|
1400
|
-
const MAX_WAITING = 100
|
|
1401
|
-
|
|
1402
|
-
http.createServer((req, res) => {
|
|
1403
|
-
const stats = sql.stats()
|
|
1404
|
-
const overloaded = stats.availableCount === 0 && stats.waitingCount > MAX_WAITING
|
|
1405
|
-
|
|
1406
|
-
res.writeHead(overloaded ? 503 : 200, { 'content-type': 'application/json' })
|
|
1407
|
-
res.end(JSON.stringify(stats))
|
|
1408
|
-
}).listen(8080)
|
|
1409
|
-
```
|
|
1410
|
-
|
|
1411
|
-
How much waiting work is acceptable depends on the query durations and the latency the application can tolerate, so the limit has no universal value.
|
|
1412
|
-
|
|
1413
|
-
Change events and a running total of finished queries are planned together with the diagnostics events, so for now take snapshots on a timer or on request.
|
|
1414
|
-
|
|
1415
|
-
### Connection timeout
|
|
1416
|
-
|
|
1417
|
-
By default, connections will not close until `.end()` is called. However, it may be useful to have them close automatically when:
|
|
1418
|
-
|
|
1419
|
-
- re-instantiating multiple ` sql`` ` instances
|
|
1420
|
-
- using Postgres.js in a Serverless environment (Lambda, etc.)
|
|
1421
|
-
- using Postgres.js with a database service that automatically closes connections after some time (see [`ECONNRESET` issue](https://github.com/porsager/postgres/issues/179))
|
|
1422
|
-
|
|
1423
|
-
This can be done using the `idle_timeout` or `max_lifetime` options. These configuration options specify the number of seconds to wait before automatically closing an idle connection and the maximum time a connection can exist, respectively. Both are also checked when an idle connection is handed out, so an idle connection that is past either limit (for example after a serverless instance was frozen) is closed instead of being used.
|
|
1424
|
-
|
|
1425
|
-
For example, to close a connection that has either been idle for 20 seconds or existed for more than 30 minutes:
|
|
1426
|
-
|
|
1427
|
-
```js
|
|
1428
|
-
const sql = postgres({
|
|
1429
|
-
idle_timeout: 20,
|
|
1430
|
-
max_lifetime: 60 * 30
|
|
1431
|
-
})
|
|
1432
|
-
```
|
|
1433
|
-
|
|
1434
|
-
### Vercel Fluid Compute
|
|
1435
|
-
|
|
1436
|
-
On Vercel's Fluid Compute an instance can be suspended while a connection sits idle and before `idle_timeout` has closed it, which leaves the connection open on the server. `attachDatabasePool` from `@vercel/functions` keeps the instance alive until idle connections have closed. Pass it the pool through `vercelPool`:
|
|
1437
|
-
|
|
1438
|
-
```js
|
|
1439
|
-
import postgres from '@steadybrew/postgresjs'
|
|
1440
|
-
import { vercelPool } from '@steadybrew/postgresjs/vercel'
|
|
1441
|
-
import { attachDatabasePool } from '@vercel/functions'
|
|
1442
|
-
|
|
1443
|
-
const sql = postgres({ idle_timeout: 5 })
|
|
1444
|
-
attachDatabasePool(vercelPool(sql))
|
|
1445
|
-
```
|
|
1446
|
-
|
|
1447
|
-
`vercelPool` requires `idle_timeout` to be a number of seconds. It hooks into the `onidle` option, which is called with the connection id each time a connection returns to the pool idle and its idle timer starts, and it keeps any `onidle` you set yourself. If `onidle` throws, the error is rethrown as an uncaught exception and the connection is not affected. A connection that was frozen past `idle_timeout` anyway is closed when it is next handed out (see [Connection timeout](#connection-timeout)).
|
|
1448
|
-
|
|
1449
|
-
### Cloudflare Workers support
|
|
1450
|
-
|
|
1451
|
-
Postgres.js has built-in support for the [TCP socket API](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/) in Cloudflare Workers, which is [on-track](https://github.com/wintercg/proposal-sockets-api) to be standardized and adopted in Node.js and other JavaScript runtimes, such as Deno.
|
|
1452
|
-
|
|
1453
|
-
You can use Postgres.js directly in a Worker, or to benefit from connection pooling and query caching, via the [Hyperdrive](https://developers.cloudflare.com/hyperdrive/learning/connect-to-postgres/#driver-examples) service available to Workers by passing the Hyperdrive `connectionString` when creating a new `postgres` client as follows:
|
|
1454
|
-
|
|
1455
|
-
```ts
|
|
1456
|
-
// Requires Postgres.js 3.4.0 or later
|
|
1457
|
-
import postgres from '@steadybrew/postgresjs'
|
|
1458
|
-
|
|
1459
|
-
interface Env {
|
|
1460
|
-
HYPERDRIVE: Hyperdrive;
|
|
1461
|
-
}
|
|
1462
|
-
|
|
1463
|
-
export default async fetch(req: Request, env: Env, ctx: ExecutionContext) {
|
|
1464
|
-
// The Postgres.js library accepts a connection string directly
|
|
1465
|
-
const sql = postgres(env.HYPERDRIVE.connectionString)
|
|
1466
|
-
const results = await sql`SELECT * FROM users LIMIT 10`
|
|
1467
|
-
return Response.json(results)
|
|
1468
|
-
}
|
|
1469
|
-
```
|
|
1470
|
-
|
|
1471
|
-
In `wrangler.toml` you will need to enable the `nodejs_compat` compatibility flag to allow Postgres.js to operate in the Workers environment:
|
|
1472
|
-
|
|
1473
|
-
```toml
|
|
1474
|
-
compatibility_flags = ["nodejs_compat"]
|
|
1475
|
-
```
|
|
1476
|
-
|
|
1477
|
-
### Auto fetching of array types
|
|
1478
|
-
|
|
1479
|
-
Postgres.js automatically fetches array-type information when each connection initializes.
|
|
1480
|
-
|
|
1481
|
-
If you have revoked access to `pg_catalog` this feature will no longer work and will need to be disabled.
|
|
1482
|
-
|
|
1483
|
-
You can disable catalog discovery by setting `fetch_types` to `false`. A fixed set of 22 common built-in array types still supports parsing and serialization, including text, numeric, boolean, JSON, date, UUID, and byte arrays. This changes earlier `fetch_types: false` behavior, which returned built-in arrays as raw strings. Other built-in, user-defined, and extension arrays still require discovery or explicit type handlers.
|
|
1484
|
-
|
|
1485
|
-
SQL `NULL` elements are returned as JavaScript `null`; a quoted text element `"NULL"` remains a string. Explicit array parsers and serializers are preserved independently. Catalog discovery with `fetch_types: true` remains per connection; this change does not cache catalog metadata.
|
|
1486
|
-
|
|
1487
|
-
Column, value, and row transforms apply to application query results; initialization metadata retains its original shape.
|
|
1488
|
-
|
|
1489
|
-
### Environmental variables
|
|
1490
|
-
|
|
1491
|
-
It is also possible to connect to the database without a connection string or any options. Postgres.js will fall back to the common environment variables used by `psql` as in the table below:
|
|
1492
|
-
|
|
1493
|
-
```js
|
|
1494
|
-
const sql = postgres()
|
|
1495
|
-
```
|
|
1496
|
-
|
|
1497
|
-
| Option | Environment Variables |
|
|
1498
|
-
| ------------------ | ------------------------ |
|
|
1499
|
-
| `host` | `PGHOST` |
|
|
1500
|
-
| `port` | `PGPORT` |
|
|
1501
|
-
| `database` | `PGDATABASE` |
|
|
1502
|
-
| `username` | `PGUSERNAME` or `PGUSER` |
|
|
1503
|
-
| `password` | `PGPASSWORD` |
|
|
1504
|
-
| `application_name` | `PGAPPNAME` |
|
|
1505
|
-
| `idle_timeout` | `PGIDLE_TIMEOUT` |
|
|
1506
|
-
| `connect_timeout` | `PGCONNECT_TIMEOUT` |
|
|
1507
|
-
| `parameter_types` | `PGPARAMETER_TYPES` |
|
|
1508
|
-
|
|
1509
|
-
### Prepared statements
|
|
1510
|
-
|
|
1511
|
-
Prepared statements will automatically be created for any queries where it can be inferred that the query is static. This can be disabled by using the `prepare: false` option. For instance โ this is useful when [using PGBouncer in `transaction mode`](https://github.com/porsager/postgres/issues/93#issuecomment-656290493).
|
|
1512
|
-
|
|
1513
|
-
With `prepare: false`, `parameter_types: 'client'` sends queries with values in one round trip, unless a value is an untyped array; see [Parameter types](#parameter-types).
|
|
1514
|
-
|
|
1515
|
-
**update**: [since 1.21.0](https://www.pgbouncer.org/2023/10/pgbouncer-1-21-0)
|
|
1516
|
-
PGBouncer supports protocol-level named prepared statements when [configured
|
|
1517
|
-
properly](https://www.pgbouncer.org/config.html#max_prepared_statements)
|
|
1518
|
-
|
|
1519
|
-
## Custom Types
|
|
1520
|
-
|
|
1521
|
-
You can add ergonomic support for custom types, or simply use `sql.typed(value, type)` inline, where type is the PostgreSQL `oid` for the type and the correctly serialized string. _(`oid` values for types can be found in the `pg_catalog.pg_type` table.)_
|
|
1522
|
-
|
|
1523
|
-
Adding Query helpers is the cleanest approach which can be done like this:
|
|
1524
|
-
|
|
1525
|
-
```js
|
|
1526
|
-
const sql = postgres({
|
|
1527
|
-
types: {
|
|
1528
|
-
rect: {
|
|
1529
|
-
// The pg_types oid to pass to the db along with the serialized value.
|
|
1530
|
-
to : 1337,
|
|
1531
|
-
|
|
1532
|
-
// An array of pg_types oids to handle when parsing values coming from the db.
|
|
1533
|
-
from : [1337],
|
|
1534
|
-
|
|
1535
|
-
//Function that transform values before sending them to the db.
|
|
1536
|
-
serialize : ({ x, y, width, height }) => [x, y, width, height],
|
|
1537
|
-
|
|
1538
|
-
// Function that transforms values coming from the db.
|
|
1539
|
-
parse : ([x, y, width, height]) => { x, y, width, height }
|
|
1540
|
-
}
|
|
1541
|
-
}
|
|
1542
|
-
})
|
|
1543
|
-
|
|
1544
|
-
// Now you can use sql.typed.rect() as specified above
|
|
1545
|
-
const [custom] = await sql`
|
|
1546
|
-
insert into rectangles (
|
|
1547
|
-
name,
|
|
1548
|
-
rect
|
|
1549
|
-
) values (
|
|
1550
|
-
'wat',
|
|
1551
|
-
${ sql.typed.rect({ x: 13, y: 37, width: 42, height: 80 }) }
|
|
1552
|
-
)
|
|
1553
|
-
returning *
|
|
1554
|
-
`
|
|
1555
|
-
|
|
1556
|
-
// custom = { name: 'wat', rect: { x: 13, y: 37, width: 42, height: 80 } }
|
|
1557
|
-
|
|
1558
|
-
```
|
|
1559
|
-
|
|
1560
|
-
With `parameter_types: 'client'` a type's `serialize` runs for `sql.typed.name(v)` and for a whole array bound to that type, not for a plain value; see [Parameter types](#parameter-types).
|
|
1561
|
-
|
|
1562
|
-
### Custom socket
|
|
1563
|
-
|
|
1564
|
-
Easily do in-process ssh tunneling to your database by providing a custom socket for Postgres.js to use. The function (optionally async) must return a socket-like duplex stream.
|
|
1565
|
-
|
|
1566
|
-
Here's a sample using [ssh2](https://github.com/mscdex/ssh2)
|
|
1567
|
-
|
|
1568
|
-
```js
|
|
1569
|
-
import ssh2 from 'ssh2'
|
|
1570
|
-
|
|
1571
|
-
const sql = postgres({
|
|
1572
|
-
...options,
|
|
1573
|
-
socket: ({ host: [host], port: [port] }) => new Promise((resolve, reject) => {
|
|
1574
|
-
const ssh = new ssh2.Client()
|
|
1575
|
-
ssh
|
|
1576
|
-
.on('error', reject)
|
|
1577
|
-
.on('ready', () =>
|
|
1578
|
-
ssh.forwardOut('127.0.0.1', 12345, host, port,
|
|
1579
|
-
(err, socket) => err ? reject(err) : resolve(socket)
|
|
1580
|
-
)
|
|
1581
|
-
)
|
|
1582
|
-
.connect(sshOptions)
|
|
1583
|
-
})
|
|
1584
|
-
})
|
|
1585
|
-
```
|
|
1586
|
-
|
|
1587
|
-
## Teardown / Cleanup
|
|
1588
|
-
|
|
1589
|
-
To ensure proper teardown and cleanup on server restarts use `await sql.end()` before `process.exit()`.
|
|
1590
|
-
|
|
1591
|
-
Calling `sql.end()` will reject new queries and return a Promise which resolves when all queries are finished and the underlying connections are closed. If a `{ timeout }` option is provided any pending queries will be rejected once the timeout (in seconds) is reached and the connections will be destroyed.
|
|
1592
|
-
|
|
1593
|
-
With explicit resource management the pool ends itself at the end of a scope:
|
|
1594
|
-
|
|
1595
|
-
```js
|
|
1596
|
-
async function main() {
|
|
1597
|
-
await using sql = postgres()
|
|
1598
|
-
await sql`select 1`
|
|
1599
|
-
}
|
|
1600
|
-
```
|
|
1601
|
-
|
|
1602
|
-
This calls `sql.end()` when the scope exits, so it suits scripts and jobs, not a shared client at a module's top level. The syntax needs Node.js 24+ or TypeScript 5.2+.
|
|
1603
|
-
|
|
1604
|
-
#### Sample shutdown using [Prexit](https://github.com/porsager/prexit)
|
|
1605
|
-
|
|
1606
|
-
```js
|
|
1607
|
-
import prexit from 'prexit'
|
|
1608
|
-
|
|
1609
|
-
prexit(async () => {
|
|
1610
|
-
await sql.end({ timeout: 5 })
|
|
1611
|
-
await new Promise(r => server.close(r))
|
|
1612
|
-
})
|
|
1613
|
-
```
|
|
1614
|
-
|
|
1615
|
-
## Reserving connections
|
|
1616
|
-
|
|
1617
|
-
### `await sql.reserve()`
|
|
1618
|
-
|
|
1619
|
-
The `reserve` method pulls out a connection from the pool, and returns a client that wraps the single connection. This can be used for running queries on an isolated connection.
|
|
1620
|
-
|
|
1621
|
-
```ts
|
|
1622
|
-
const reserved = await sql.reserve()
|
|
1623
|
-
await reserved`select * from users`
|
|
1624
|
-
await reserved.release()
|
|
1625
|
-
```
|
|
1626
|
-
|
|
1627
|
-
### `reserved.release()`
|
|
1628
|
-
|
|
1629
|
-
Once you have finished with the reserved connection, call `release` to add it back to the pool.
|
|
1630
|
-
|
|
1631
|
-
```js
|
|
1632
|
-
using reserved = await sql.reserve()
|
|
1633
|
-
await reserved`select * from users`
|
|
1634
|
-
```
|
|
1635
|
-
|
|
1636
|
-
A `using` or `await using` declaration calls `release()` when the scope exits.
|
|
1637
|
-
|
|
1638
|
-
After release, queries through that reserved handle reject with `CONNECTION_ENDED`. Call `sql.reserve()` again to acquire a new handle. A reserved handle whose connection has closed cannot be reused after reconnect.
|
|
1639
|
-
|
|
1640
|
-
## Error handling
|
|
1641
|
-
|
|
1642
|
-
Errors are all thrown to related queries and never globally. Errors coming from database itself are always in the [native Postgres format](https://www.postgresql.org/docs/current/errcodes-appendix.html), and the same goes for any [Node.js errors](https://nodejs.org/api/errors.html#errors_common_system_errors) eg. coming from the underlying connection.
|
|
1643
|
-
|
|
1644
|
-
Query errors will contain a stored error with the origin of the query to aid in tracing errors.
|
|
1645
|
-
|
|
1646
|
-
Query errors will also contain the `query` string and the `parameters`. These are not enumerable to avoid accidentally leaking confidential information in logs. To log these it is required to specifically access `error.query` and `error.parameters`, or set `debug: true` in options.
|
|
1647
|
-
|
|
1648
|
-
There are also the following errors specifically for this library.
|
|
1649
|
-
|
|
1650
|
-
##### UNSAFE_TRANSACTION
|
|
1651
|
-
> Only use sql.begin or max: 1
|
|
1652
|
-
|
|
1653
|
-
To ensure statements in a transaction runs on the same connection (which is required for them to run inside the transaction), you must use [`sql.begin(...)`](#transactions) or only allow a single connection in options (`max: 1`).
|
|
1654
|
-
|
|
1655
|
-
##### UNDEFINED_VALUE
|
|
1656
|
-
> Undefined values are not allowed
|
|
1657
|
-
|
|
1658
|
-
Postgres.js won't accept `undefined` as values in tagged template queries since it becomes ambiguous what to do with the value. If you want to set something to null, use `null` explicitly.
|
|
1659
|
-
|
|
1660
|
-
##### MESSAGE_NOT_SUPPORTED
|
|
1661
|
-
> X (X) is not supported
|
|
1662
|
-
|
|
1663
|
-
Whenever a message is received from Postgres which is not supported by this library. Feel free to file an issue if you think something is missing.
|
|
1664
|
-
|
|
1665
|
-
##### MAX_PARAMETERS_EXCEEDED
|
|
1666
|
-
> Max number of parameters (65534) exceeded
|
|
1667
|
-
|
|
1668
|
-
The postgres protocol doesn't allow more than 65534 (16bit) parameters. If you run into this issue there are various workarounds such as using `sql([...])` to escape values instead of passing them as parameters.
|
|
1669
|
-
|
|
1670
|
-
##### SASL_SIGNATURE_MISMATCH
|
|
1671
|
-
> Message type X not supported
|
|
1672
|
-
|
|
1673
|
-
When using SASL authentication the server responds with a signature at the end of the authentication flow which needs to match the one on the client. This is to avoid [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). If you receive this error the connection was canceled because the server did not reply with the expected signature.
|
|
1674
|
-
|
|
1675
|
-
##### NOT_TAGGED_CALL
|
|
1676
|
-
> Query not called as a tagged template literal
|
|
1677
|
-
|
|
1678
|
-
Making queries has to be done using the sql function as a [tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates). This is to ensure parameters are serialized and passed to Postgres as query parameters with correct types and to avoid SQL injection.
|
|
1679
|
-
|
|
1680
|
-
##### SSL_NOT_SUPPORTED
|
|
1681
|
-
> The server does not support SSL connections
|
|
1682
|
-
|
|
1683
|
-
The server answered the SSL request with a refusal while `ssl` is set to `require` (or another mode that does not fall back to plain text). The attempt fails at once for a single host. Use `ssl: 'prefer'` to fall back to an unencrypted connection, or enable SSL on the server.
|
|
1684
|
-
|
|
1685
|
-
##### TARGET_SESSION_ATTRS
|
|
1686
|
-
> No host matched target_session_attrs=read-write: localhost:5432 is read-only
|
|
1687
|
-
|
|
1688
|
-
No host satisfied [`target_session_attrs`](#connection-details). This error is the `cause` of the `CONNECTION_CLOSED` error the query rejects with, so retry logic keyed on `CONNECTION_CLOSED` keeps working; read `err.cause.code` and `err.cause.message` for the reason. The message names the requested value and each host with the reason it was rejected. With several hosts, the connection fails at once when every host answered and none matched; if any host failed for another reason (refused, closed, timed out), the client keeps retrying until `connect_timeout` instead, since a failover may be in progress. With a single host, the client keeps retrying until `connect_timeout` before failing, because a single endpoint that is read-only is often in the middle of a failover, for example a cluster DNS name that still points at the old primary.
|
|
1689
|
-
|
|
1690
|
-
##### AUTH_TYPE_NOT_IMPLEMENTED
|
|
1691
|
-
> Auth type X not implemented
|
|
1692
|
-
|
|
1693
|
-
Postgres supports many different authentication types. This one is not supported.
|
|
1694
|
-
|
|
1695
|
-
##### CONNECTION_CLOSED
|
|
1696
|
-
> write CONNECTION_CLOSED host:port
|
|
1697
|
-
|
|
1698
|
-
This error is thrown if the connection was closed, or could not be opened, without an error of its own. When the server or the network ended the session, or no host matched `target_session_attrs`, the underlying error is available as `err.cause`.
|
|
1699
|
-
|
|
1700
|
-
##### CONNECTION_ENDED
|
|
1701
|
-
> write CONNECTION_ENDED host:port
|
|
1702
|
-
|
|
1703
|
-
This error is thrown if the user has called [`sql.end()`](#teardown--cleanup) and performed a query afterward.
|
|
1704
|
-
|
|
1705
|
-
A reserved `sql` used after `release()`, or a transaction `sql` used after `begin()` has committed, rolled back or prepared, also rejects with `CONNECTION_ENDED`.
|
|
1706
|
-
|
|
1707
|
-
##### CONNECTION_DESTROYED
|
|
1708
|
-
> write CONNECTION_DESTROYED host:port
|
|
1709
|
-
|
|
1710
|
-
This error is thrown for any queries that were pending when the timeout to [`sql.end({ timeout: X })`](#teardown--cleanup) was reached.
|
|
1711
|
-
|
|
1712
|
-
##### CONNECT_TIMEOUT
|
|
1713
|
-
> write CONNECT_TIMEOUT host:port
|
|
1714
|
-
|
|
1715
|
-
The timeout applies to each connection attempt and covers socket creation, TCP and TLS negotiation, authentication, session checks and type discovery. When an attempt times out, the next host is tried. The acquisition as a whole is bounded by `connect_timeout` multiplied by the number of hosts, measured from the first attempt; time spent waiting on an inherited reconnect delay is not counted. Set it with `connect_timeout` or `PGCONNECT_TIMEOUT` (30 seconds by default); zero disables both limits. The same value also bounds a graceful close: if the server does not close the socket within `connect_timeout` seconds after `end()` sends Terminate, the connection is closed anyway; zero leaves a graceful close unbounded.
|
|
1716
|
-
|
|
1717
|
-
If the only attempt times out, the error is `CONNECT_TIMEOUT`. Once earlier attempts have failed, exhausting the overall budget reports the earlier error, such as the last server error or `CONNECTION_CLOSED`. With a single host, a socket or socket factory error rejects the query once; with several hosts, errors keep cycling through the hosts with backoff until the budget is spent. Queries already sent to the server are not replayed.
|
|
1718
|
-
|
|
1719
|
-
##### COPY_IN_PROGRESS
|
|
1720
|
-
> You cannot execute queries during copy
|
|
1721
|
-
|
|
1722
|
-
This error is thrown for a statement on a `sql.reserve()` or `sql.begin()` handle while its copy operation (writable / readable) runs, including statements sent before the server started it. A query, `sql.reserve()` or `sql.begin()` through `sql` gets it when every connection is running a copy operation whose writable has not been ended; otherwise it waits for a connection.
|
|
1723
|
-
|
|
1724
|
-
##### TRANSACTION_ROLLED_BACK
|
|
1725
|
-
> The server rolled the transaction back instead of committing it
|
|
1726
|
-
|
|
1727
|
-
This error is thrown by `sql.begin()` when the server answers the final `COMMIT` (or `PREPARE TRANSACTION`) with `ROLLBACK`, because the transaction was aborted by a statement whose error the callback did not surface, such as a failing query that was not awaited. Nothing was committed. When such a query's error was already recorded, it is the error's `cause`.
|
|
1728
|
-
|
|
1729
|
-
## TypeScript support
|
|
1730
|
-
|
|
1731
|
-
`postgres` has TypeScript support. You can pass a row list type for your queries in this way:
|
|
1732
|
-
```ts
|
|
1733
|
-
interface User {
|
|
1734
|
-
id: number
|
|
1735
|
-
name: string
|
|
1736
|
-
}
|
|
1737
|
-
|
|
1738
|
-
const users = await sql<User[]>`SELECT * FROM users`
|
|
1739
|
-
users[0].id // ok => number
|
|
1740
|
-
users[1].name // ok => string
|
|
1741
|
-
users[0].invalid // fails: `invalid` does not exists on `User`
|
|
1742
|
-
```
|
|
1743
|
-
|
|
1744
|
-
However, be sure to check the array length to avoid accessing properties of `undefined` rows:
|
|
1745
|
-
```ts
|
|
1746
|
-
const users = await sql<User[]>`SELECT * FROM users WHERE id = ${id}`
|
|
1747
|
-
if (!users.length)
|
|
1748
|
-
throw new Error('Not found')
|
|
1749
|
-
return users[0]
|
|
1750
|
-
```
|
|
1751
|
-
|
|
1752
|
-
You can also prefer destructuring when you only care about a fixed number of rows.
|
|
1753
|
-
In this case, we recommend you to prefer using tuples to handle `undefined` properly:
|
|
1754
|
-
```ts
|
|
1755
|
-
const [user]: [User?] = await sql`SELECT * FROM users WHERE id = ${id}`
|
|
1756
|
-
if (!user) // => User | undefined
|
|
1757
|
-
throw new Error('Not found')
|
|
1758
|
-
return user // => User
|
|
1759
|
-
|
|
1760
|
-
// NOTE:
|
|
1761
|
-
const [first, second]: [User?] = await sql`SELECT * FROM users WHERE id = ${id}` // fails: `second` does not exist on `[User?]`
|
|
1762
|
-
const [first, second] = await sql<[User?]>`SELECT * FROM users WHERE id = ${id}` // don't fail : `second: User | undefined`
|
|
1763
|
-
```
|
|
102
|
+
- **Transactions keep their own connection.** Fixes connection reuse that could commit another transaction's unfinished writes or let a disconnected handle read another user's rows through RLS. [#1204](https://github.com/porsager/postgres/issues/1204), [#1216](https://github.com/porsager/postgres/issues/1216)
|
|
103
|
+
- **Each query gets its own result.** Fixes pipelined queries receiving another query's rows or error, and results with empty slots after a failed query. [#1082](https://github.com/porsager/postgres/issues/1082), [#1252](https://github.com/porsager/postgres/issues/1252), [#1253](https://github.com/porsager/postgres/issues/1253)
|
|
104
|
+
- **Rollbacks aren't reported as successful commits.** `sql.begin()` rejects when the server rolls back the commit. [#1217](https://github.com/porsager/postgres/issues/1217)
|
|
105
|
+
- **Fewer hangs and crashes.** Fixes reservations and shutdown hanging after disconnects, queries stuck after a slow `COPY` reader, and closed transaction handles crashing the process. [#1195](https://github.com/porsager/postgres/issues/1195), [#1097](https://github.com/porsager/postgres/issues/1097), [#1016](https://github.com/porsager/postgres/pull/1016), [#1208](https://github.com/porsager/postgres/issues/1208)
|
|
106
|
+
- **Recover after outages.** Failed connections [wait before retrying](docs/api.md#connection-timeout), avoiding a burst of simultaneous retries. With [multiple hosts](docs/api.md#multi-host-connections---high-availability-ha), the client tries another server and can wait for a writable primary.
|
|
1764
107
|
|
|
1765
|
-
|
|
108
|
+
[50+ bug fixes and test coverage โ](docs/fixed-issues.md)
|
|
1766
109
|
|
|
1767
|
-
|
|
110
|
+
### Faster queries behind poolers
|
|
1768
111
|
|
|
1769
|
-
|
|
112
|
+
With `prepare: false`, parameterized queries can pay for an extra network round trip. The opt-in [`parameter_types: 'client'`](docs/api.md#parameter-types) removes it for supported values. In one production app behind the Supabase pooler, median query time fell from **5.3 ms to 3.1 ms** over a day on each mode. Results depend on your workload; p99 was unchanged. Use `'warn'` first to check for serialization differences.
|
|
1770
113
|
|
|
1771
|
-
|
|
1772
|
-
- https://github.com/lukeed/ley
|
|
1773
|
-
- https://github.com/JAForbes/pgmg
|
|
114
|
+
### New features
|
|
1774
115
|
|
|
1775
|
-
|
|
116
|
+
- **See pool pressure.** [`sql.stats()`](docs/api.md#pool-stats) reports busy and idle connections and waiting queries.
|
|
117
|
+
- **Handle serverless suspension.** Expired idle connections are replaced on resume; the [Vercel Fluid Compute adapter](docs/api.md#vercel-fluid-compute) keeps instances alive until idle connections close.
|
|
118
|
+
- **Automatic cleanup.** [`await using`](docs/api.md#teardown--cleanup) closes a pool and `using` releases a reserved connection when its scope ends. Requires Node.js 24+ or TypeScript 5.2+.
|
|
119
|
+
- **Arrays without startup discovery.** With [`fetch_types: false`](docs/api.md#auto-fetching-of-array-types), common built-in arrays still parse and serialize without a catalog query.
|
|
1776
120
|
|
|
1777
|
-
|
|
121
|
+
## Documentation
|
|
1778
122
|
|
|
1779
|
-
|
|
123
|
+
- [API reference](docs/api.md) โ queries, transactions, types, options and errors. Also shipped in the npm package at `docs/api.md` for editors and code assistants.
|
|
124
|
+
- [Migration guide](docs/upgrading.md) โ switching, behaviour changes and tracing.
|
|
125
|
+
- [Changelog](CHANGELOG.md) ยท [Roadmap](ROADMAP.md) ยท [Contributing](CONTRIBUTING.md)
|
|
1780
126
|
|
|
1781
|
-
|
|
127
|
+
Based on [Postgres.js](https://github.com/porsager/postgres) by [Rasmus Porsager](https://github.com/porsager). Thank you to its creator and everyone contributing fixes and reproductions.
|