You probably want to add an event listener to the pool to catch background errors errors!
+ You probably want to add an event listener to the pool to catch background errors!
Just like other event emitters, if a pool emits an error event and no listeners are added node will emit an
uncaught error and potentially crash your node process.
Care has been taken to normalize between the two, but there might still be edge cases where things behave subtly differently due to the nature of using libpq over handling the binary protocol directly in JavaScript, so it's recommended you chose to either use the JavaScript driver or the native bindings both in development and production. For what its worth: I use the pure JavaScript driver because the JavaScript driver is more portable (doesn't need a compiler), and the pure JavaScript driver is plenty fast.
diff --git a/docs/pages/features/pooling.mdx b/docs/pages/features/pooling.mdx
index 4719150be..ebe2844bc 100644
--- a/docs/pages/features/pooling.mdx
+++ b/docs/pages/features/pooling.mdx
@@ -19,7 +19,7 @@ The easiest and by far most common way to use node-postgres is through a connect
### Good news
-node-postgres ships with built-in connection pooling via the [pg-pool](/api/pool) module.
+node-postgres ships with built-in connection pooling via the [pg-pool](/apis/pool) module.
## Examples
@@ -28,7 +28,8 @@ The client pool allows you to have a reusable pool of clients you can check out,
### Checkout, use, and return
```js
-const { Pool } = require('pg')
+import pg from 'pg'
+const { Pool } = pg
const pool = new Pool()
@@ -39,46 +40,11 @@ pool.on('error', (err, client) => {
process.exit(-1)
})
-// callback - checkout a client
-pool.connect((err, client, done) => {
- if (err) throw err
- client.query('SELECT * FROM users WHERE id = $1', [1], (err, res) => {
- done()
-
- if (err) {
- console.log(err.stack)
- } else {
- console.log(res.rows[0])
- }
- })
-})
-
-// promise - checkout a client
-pool.connect().then((client) => {
- return client
- .query('SELECT * FROM users WHERE id = $1', [1])
- .then((res) => {
- client.release()
- console.log(res.rows[0])
- })
- .catch((err) => {
- client.release()
- console.log(err.stack)
- })
-})
+const client = await pool.connect()
+const res = await client.query('SELECT * FROM users WHERE id = $1', [1])
+console.log(res.rows[0])
-// async/await - check out a client
-;(async () => {
- const client = await pool.connect()
- try {
- const res = await client.query('SELECT * FROM users WHERE id = $1', [1])
- console.log(res.rows[0])
- } catch (err) {
- console.log(err.stack)
- } finally {
- client.release()
- }
-})()
+client.release()
```
@@ -95,44 +61,13 @@ pool.connect().then((client) => {
If you don't need a transaction or you just need to run a single query, the pool has a convenience method to run a query on any available client in the pool. This is the preferred way to query with node-postgres if you can as it removes the risk of leaking a client.
```js
-const { Pool } = require('pg')
-
-const pool = new Pool()
-
-pool.query('SELECT * FROM users WHERE id = $1', [1], (err, res) => {
- if (err) {
- throw err
- }
-
- console.log('user:', res.rows[0])
-})
-```
-
-node-postgres also has built-in support for promises throughout all of its async APIs.
-
-```js
-const { Pool } = require('pg')
-
-const pool = new Pool()
+import pg from 'pg'
+const { Pool } = pg
-pool
- .query('SELECT * FROM users WHERE id = $1', [1])
- .then((res) => console.log('user:', res.rows[0]))
- .catch((err) =>
- setImmediate(() => {
- throw err
- })
- )
-```
-
-Promises allow us to use `async`/`await` in node v8.0 and above (or earlier if you're using babel).
-
-```js
-const { Pool } = require('pg')
const pool = new Pool()
-const { rows } = await pool.query('SELECT * FROM users WHERE id = $1', [1])
-console.log('user:', rows[0])
+const res = await pool.query('SELECT * FROM users WHERE id = $1', [1])
+console.log('user:', res.rows[0])
```
### Shutdown
@@ -140,7 +75,8 @@ console.log('user:', rows[0])
To shut down a pool call `pool.end()` on the pool. This will wait for all checked-out clients to be returned and then shut down all the clients and the pool timers.
```js
-const { Pool } = require('pg')
+import pg from 'pg'
+const { Pool } = pg
const pool = new Pool()
console.log('starting async query')
diff --git a/docs/pages/features/queries.mdx b/docs/pages/features/queries.mdx
index 0deef0d0d..39bcfbe1d 100644
--- a/docs/pages/features/queries.mdx
+++ b/docs/pages/features/queries.mdx
@@ -3,27 +3,14 @@ title: Queries
slug: /features/queries
---
-The api for executing queries supports both callbacks and promises. I'll provide an example for both _styles_ here. For the sake of brevity I am using the `client.query` method instead of the `pool.query` method - both methods support the same API. In fact, `pool.query` delegates directly to `client.query` internally.
+For the sake of brevity I am using the `client.query` method instead of the `pool.query` method - both methods support the same API. In fact, `pool.query` delegates directly to `client.query` internally.
## Text only
If your query has no parameters you do not need to include them to the query method:
```js
-// callback
-client.query('SELECT NOW() as now', (err, res) => {
- if (err) {
- console.log(err.stack)
- } else {
- console.log(res.rows[0])
- }
-})
-
-// promise
-client
- .query('SELECT NOW() as now')
- .then(res => console.log(res.rows[0]))
- .catch(e => console.error(e.stack))
+await client.query('SELECT NOW() as now')
```
## Parameterized query
@@ -34,37 +21,13 @@ If you are passing parameters to your queries you will want to avoid string conc
const text = 'INSERT INTO users(name, email) VALUES($1, $2) RETURNING *'
const values = ['brianc', 'brian.m.carlson@gmail.com']
-// callback
-client.query(text, values, (err, res) => {
- if (err) {
- console.log(err.stack)
- } else {
- console.log(res.rows[0])
- // { name: 'brianc', email: 'brian.m.carlson@gmail.com' }
- }
-})
-
-// promise
-client
- .query(text, values)
- .then(res => {
- console.log(res.rows[0])
- // { name: 'brianc', email: 'brian.m.carlson@gmail.com' }
- })
- .catch(e => console.error(e.stack))
-
-// async/await
-try {
- const res = await client.query(text, values)
- console.log(res.rows[0])
- // { name: 'brianc', email: 'brian.m.carlson@gmail.com' }
-} catch (err) {
- console.log(err.stack)
-}
+const res = await client.query(text, values)
+console.log(res.rows[0])
+// { name: 'brianc', email: 'brian.m.carlson@gmail.com' }
```
+
+
+If you or your company would like to sponsor node-postgres stop by [GitHub Sponsors](https://github.com/sponsors/brianc) and sign up or feel free to [email me](mailto:brian@pecanware.com) if you want to add your logo to the documentation or discuss higher tiers of sponsorship!
# Version compatibility
-node-postgres strives to be compatible with all recent lts versions of node & the most recent "stable" version. At the time of this writing node-postgres is compatible with node 8.x, 10.x, 12.x and 14.x To use node >= 14.x you will need to install `pg@8.2.x` or later due to some internal stream changes on the node 14 branch. Dropping support for an old node lts version will always be considered a breaking change in node-postgres and will be done on _major_ version number changes only, and we will try to keep support for 8.x for as long as reasonably possible.
+node-postgres strives to be compatible with all recent LTS versions of node & the most recent "stable" version. At the time of this writing node-postgres is compatible with node 18.x, 20.x, 22.x, and 24.x.
## Getting started
-This is the simplest possible way to connect, query, and disconnect with async/await:
+The simplest possible way to connect, query, and disconnect is with async/await:
```js
-const { Client } = require('pg')
+import { Client } from 'pg'
const client = new Client()
await client.connect()
@@ -35,18 +52,36 @@ console.log(res.rows[0].message) // Hello world!
await client.end()
```
-And here's the same thing with callbacks:
+### Error Handling
-```js
-const { Client } = require('pg')
+For the sake of simplicity, these docs will assume that the methods are successful. In real life use, make sure to properly handle errors thrown in the methods. A `try/catch` block is a great way to do so:
+
+```ts
+import { Client } from 'pg'
const client = new Client()
+await client.connect()
-client.connect()
+try {
+ const res = await client.query('SELECT $1::text as message', ['Hello world!'])
+ console.log(res.rows[0].message) // Hello world!
+} catch (err) {
+ console.error(err);
+} finally {
+ await client.end()
+}
+```
-client.query('SELECT $1::text as message', ['Hello world!'], (err, res) => {
- console.log(err ? err.stack : res.rows[0].message) // Hello World!
- client.end()
-})
+### Pooling
+
+In most applications you'll wannt to use a [connection pool](/features/pooling) to manage your connections. This is a more advanced topic, but here's a simple example of how to use it:
+
+```js
+import { Pool } from 'pg'
+const pool = new Pool()
+const res = await pool.query('SELECT $1::text as message', ['Hello world!'])
+console.log(res.rows[0].message) // Hello world!
```
Our real-world apps are almost always more complicated than that, and I urge you to read on!
+
+
diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico
new file mode 100644
index 000000000..ab485092f
Binary files /dev/null and b/docs/public/favicon.ico differ
diff --git a/docs/theme.config.js b/docs/theme.config.js
index 263a26945..316ae7145 100644
--- a/docs/theme.config.js
+++ b/docs/theme.config.js
@@ -10,7 +10,6 @@ export default {
docsRepositoryBase: 'https://github.com/brianc/node-postgres/blob/master/docs', // base URL for the docs repository
titleSuffix: ' – node-postgres',
darkMode: true,
- footer: true,
navigation: {
prev: true,
next: true,
@@ -23,15 +22,48 @@ export default {
},
logo: (
<>
-
- node-postgres
+
+ node-postgres
),
+ chat: {
+ link: 'https://discord.gg/4nbb6zJa',
+ },
head: (
<>
-
-
+
+
+
- PostgreSQL does not support parameters for identifiers. If you need to have dynamic database, schema, table, or column names (e.g. in DDL statements) use pg-format package for handling escaping these values to ensure you do not have SQL injection!
+ PostgreSQL does not support parameters for identifiers. If you need to have dynamic database, schema, table, or column names (e.g. in DDL statements) use [pg-format](https://www.npmjs.com/package/pg-format) package for handling escaping these values to ensure you do not have SQL injection!
Parameters passed as the second argument to `query()` will be converted to raw data types using the following rules:
@@ -112,20 +75,8 @@ const query = {
values: ['brianc', 'brian.m.carlson@gmail.com'],
}
-// callback
-client.query(query, (err, res) => {
- if (err) {
- console.log(err.stack)
- } else {
- console.log(res.rows[0])
- }
-})
-
-// promise
-client
- .query(query)
- .then(res => console.log(res.rows[0]))
- .catch(e => console.error(e.stack))
+const res = await client.query(query)
+console.log(res.rows[0])
```
The query config object allows for a few more advanced scenarios:
@@ -142,20 +93,8 @@ const query = {
values: [1],
}
-// callback
-client.query(query, (err, res) => {
- if (err) {
- console.log(err.stack)
- } else {
- console.log(res.rows[0])
- }
-})
-
-// promise
-client
- .query(query)
- .then(res => console.log(res.rows[0]))
- .catch(e => console.error(e.stack))
+const res = await client.query(query)
+console.log(res.rows[0])
```
In the above example the first time the client sees a query with the name `'fetch-user'` it will send a 'parse' request to the PostgreSQL server & execute the query as normal. The second time, it will skip the 'parse' request and send the _name_ of the query to the PostgreSQL server.
@@ -177,29 +116,14 @@ const query = {
rowMode: 'array',
}
-// callback
-client.query(query, (err, res) => {
- if (err) {
- console.log(err.stack)
- } else {
- console.log(res.fields.map(field => field.name)) // ['first_name', 'last_name']
- console.log(res.rows[0]) // ['Brian', 'Carlson']
- }
-})
-
-// promise
-client
- .query(query)
- .then(res => {
- console.log(res.fields.map(field => field.name)) // ['first_name', 'last_name']
- console.log(res.rows[0]) // ['Brian', 'Carlson']
- })
- .catch(e => console.error(e.stack))
+const res = await client.query(query)
+console.log(res.fields.map(field => field.name)) // ['first_name', 'last_name']
+console.log(res.rows[0]) // ['Brian', 'Carlson']
```
### Types
-You can pass in a custom set of type parsers to use when parsing the results of a particular query. The `types` property must conform to the [Types](/api/types) API. Here is an example in which every value is returned as a string:
+You can pass in a custom set of type parsers to use when parsing the results of a particular query. The `types` property must conform to the [Types](/apis/types) API. Here is an example in which every value is returned as a string:
```js
const query = {
diff --git a/docs/pages/features/ssl.mdx b/docs/pages/features/ssl.mdx
index 0428d0549..2c5e7bd9e 100644
--- a/docs/pages/features/ssl.mdx
+++ b/docs/pages/features/ssl.mdx
@@ -25,24 +25,15 @@ const config = {
import { Client, Pool } from 'pg'
const client = new Client(config)
-client.connect(err => {
- if (err) {
- console.error('error connecting', err.stack)
- } else {
- console.log('connected')
- client.end()
- }
-})
+await client.connect()
+console.log('connected')
+await client.end()
const pool = new Pool(config)
-pool
- .connect()
- .then(client => {
- console.log('connected')
- client.release()
- })
- .catch(err => console.error('error connecting', err.stack))
- .then(() => pool.end())
+const pooledClient = await pool.connect()
+console.log('connected')
+pooledClient.release()
+await pool.end()
```
## Usage with `connectionString`
@@ -59,3 +50,17 @@ const config = {
},
}
```
+
+## Channel binding
+
+If the PostgreSQL server offers SCRAM-SHA-256-PLUS (i.e. channel binding) for TLS/SSL connections, you can enable this as follows:
+
+```js
+const client = new Client({ ...config, enableChannelBinding: true})
+```
+
+or
+
+```js
+const pool = new Pool({ ...config, enableChannelBinding: true})
+```
diff --git a/docs/pages/features/transactions.mdx b/docs/pages/features/transactions.mdx
index 408db52f8..4433bd3e4 100644
--- a/docs/pages/features/transactions.mdx
+++ b/docs/pages/features/transactions.mdx
@@ -15,16 +15,10 @@ To execute a transaction with node-postgres you simply execute `BEGIN / COMMIT /
## Examples
-### async/await
-
-Things are considerably more straightforward if you're using async/await:
-
```js
-const { Pool } = require('pg')
+import { Pool } from 'pg'
const pool = new Pool()
-// note: we don't try/catch this because if connecting throws an exception
-// we don't need to dispose of the client (it will be undefined)
const client = await pool.connect()
try {
@@ -43,51 +37,3 @@ try {
client.release()
}
```
-
-### callbacks
-
-node-postgres is a very old library, and still has an optional callback API. Here's an example of doing the same code above, but with callbacks:
-
-```js
-const { Pool } = require('pg')
-const pool = new Pool()
-
-pool.connect((err, client, done) => {
- const shouldAbort = (err) => {
- if (err) {
- console.error('Error in transaction', err.stack)
- client.query('ROLLBACK', (err) => {
- if (err) {
- console.error('Error rolling back client', err.stack)
- }
- // release the client back to the pool
- done()
- })
- }
- return !!err
- }
-
- client.query('BEGIN', (err) => {
- if (shouldAbort(err)) return
- const queryText = 'INSERT INTO users(name) VALUES($1) RETURNING id'
- client.query(queryText, ['brianc'], (err, res) => {
- if (shouldAbort(err)) return
-
- const insertPhotoText = 'INSERT INTO photos(user_id, photo_url) VALUES ($1, $2)'
- const insertPhotoValues = [res.rows[0].id, 's3.bucket.foo']
- client.query(insertPhotoText, insertPhotoValues, (err, res) => {
- if (shouldAbort(err)) return
-
- client.query('COMMIT', (err) => {
- if (err) {
- console.error('Error committing transaction', err.stack)
- }
- done()
- })
- })
- })
- })
-})
-```
-
-..thank goodness for `async/await` yeah?
diff --git a/docs/pages/features/types.mdx b/docs/pages/features/types.mdx
index 65c814bae..36e8b7035 100644
--- a/docs/pages/features/types.mdx
+++ b/docs/pages/features/types.mdx
@@ -4,7 +4,7 @@ title: Data Types
import { Alert } from '/components/alert.tsx'
-PostgreSQL has a rich system of supported [data types](https://www.postgresql.org/docs/9.5/static/datatype.html). node-postgres does its best to support the most common data types out of the box and supplies an extensible type parser to allow for custom type serialization and parsing.
+PostgreSQL has a rich system of supported [data types](https://www.postgresql.org/docs/current/datatype.html). node-postgres does its best to support the most common data types out of the box and supplies an extensible type parser to allow for custom type serialization and parsing.
## strings by default
@@ -21,7 +21,7 @@ console.log(result.rows[0]) // will contain the unparsed string value of each co
### uuid + json / jsonb
-There is no data type in JavaScript for a uuid/guid so node-postgres converts a uuid to a string. JavaScript has great support for JSON and node-postgres converts json/jsonb objects directly into their JavaScript object via [`JSON.parse`](https://github.com/brianc/node-pg-types/blob/master/lib/textParsers.js#L193). Likewise sending an object to the PostgreSQL server via a query from node-postgres, node-posgres will call [`JSON.stringify`](https://github.com/brianc/node-postgres/blob/e5f0e5d36a91a72dda93c74388ac890fa42b3be0/lib/utils.js#L47) on your outbound value, automatically converting it to json for the server.
+There is no data type in JavaScript for a uuid/guid so node-postgres converts a uuid to a string. JavaScript has great support for JSON and node-postgres converts json/jsonb objects directly into their JavaScript object via [`JSON.parse`](https://github.com/brianc/node-pg-types/blob/master/lib/textParsers.js#L193). Likewise sending an object to the PostgreSQL server via a query from node-postgres, node-postgres will call [`JSON.stringify`](https://github.com/brianc/node-postgres/blob/e5f0e5d36a91a72dda93c74388ac890fa42b3be0/lib/utils.js#L47) on your outbound value, automatically converting it to json for the server.
```js
const createTableText = `
diff --git a/docs/pages/guides/_meta.json b/docs/pages/guides/_meta.json
index 3889a0992..777acb4e2 100644
--- a/docs/pages/guides/_meta.json
+++ b/docs/pages/guides/_meta.json
@@ -1,5 +1,6 @@
{
"project-structure": "Suggested Code Structure",
"async-express": "Express with Async/Await",
+ "pool-sizing": "Pool Sizing",
"upgrading": "Upgrading"
}
diff --git a/docs/pages/guides/async-express.md b/docs/pages/guides/async-express.md
index 3be6d955a..a44c15289 100644
--- a/docs/pages/guides/async-express.md
+++ b/docs/pages/guides/async-express.md
@@ -22,21 +22,18 @@ That's the same structure I used in the [project structure](/guides/project-stru
My `db/index.js` file usually starts out like this:
```js
-const { Pool } = require('pg')
+import { Pool } from 'pg'
const pool = new Pool()
-module.exports = {
- query: (text, params) => pool.query(text, params),
-}
+export const query = (text, params) => pool.query(text, params)
```
Then I will install [express-promise-router](https://www.npmjs.com/package/express-promise-router) and use it to define my routes. Here is my `routes/user.js` file:
```js
-const Router = require('express-promise-router')
-
-const db = require('../db')
+import Router from 'express-promise-router'
+import db from '../db.js'
// create a new express-promise-router
// this has the same API as the normal express router except
@@ -44,7 +41,7 @@ const db = require('../db')
const router = new Router()
// export our router to be mounted by the parent application
-module.exports = router
+export default router
router.get('/:id', async (req, res) => {
const { id } = req.params
@@ -57,22 +54,24 @@ Then in my `routes/index.js` file I'll have something like this which mounts eac
```js
// ./routes/index.js
-const users = require('./user')
-const photos = require('./photos')
+import users from './user.js'
+import photos from './photos.js'
-module.exports = (app) => {
+const mountRoutes = (app) => {
app.use('/users', users)
app.use('/photos', photos)
// etc..
}
+
+export default mountRoutes
```
And finally in my `app.js` file where I bootstrap express I will have my `routes/index.js` file mount all my routes. The routes know they're using async functions but because of express-promise-router the main express app doesn't know and doesn't care!
```js
// ./app.js
-const express = require('express')
-const mountRoutes = require('./routes')
+import express from 'express'
+import mountRoutes from './routes.js'
const app = express()
mountRoutes(app)
diff --git a/docs/pages/guides/pool-sizing.md b/docs/pages/guides/pool-sizing.md
new file mode 100644
index 000000000..5c7ddaad8
--- /dev/null
+++ b/docs/pages/guides/pool-sizing.md
@@ -0,0 +1,25 @@
+---
+title: Pool Sizing
+---
+
+If you're using a [pool](/apis/pool) in an application with multiple instances of your service running (common in most cloud/container environments currently), you'll need to think a bit about the `max` parameter of your pool across all services and all _instances_ of all services which are connecting to your Postgres server.
+
+This can get pretty complex depending on your cloud environment. Further nuance is introduced with things like pg-bouncer, RDS connection proxies, etc., which will do some forms of connection pooling and connection multiplexing. So, it's definitely worth thinking about. Let's run through a few setups. While certainly not exhaustive, these examples hopefully prompt you into thinking about what's right for your setup.
+
+## Simple apps, dev mode, fixed instance counts, etc.
+
+If your app isn't running in a k8s style env with containers scaling automatically or lambdas or cloud functions etc., you can do some "napkin math" for the `max` pool config you can use. Let's assume your Postgres instance is configured to have a maximum of 200 connections at any one time. You know your service is going to run on 4 instances. You can set the `max` pool size to 50, but if all your services are saturated waiting on database connections, you won't be able to connect to the database from any mgmt tools or scale up your services without changing config/code to adjust the max size.
+
+In this situation, I'd probably set the `max` to 20 or 25. This lets you have plenty of headroom for scaling more instances and realistically, if your app is starved for db connections, you probably want to take a look at your queries and make them execute faster, or cache, or something else to reduce the load on the database. I worked on a more reporting-heavy application with limited users, but each running 5-6 queries at a time which all took 100-200 milliseconds to run. In that situation, I upped the `max` to 50. Typically, though, I don't bother setting it to anything other than the default of `10` as that's usually _fine_.
+
+## Auto-scaling, cloud-functions, multi-tenancy, etc.
+
+If the number of instances of your services which connect to your database is more dynamic and based on things like load, auto-scaling containers, or running in cloud-functions, you need to be a bit more thoughtful about what your max might be. Often in these environments, there will be another database pooling proxy in front of the database like pg-bouncer or the RDS-proxy, etc. I'm not sure how all these function exactly, and they all have some trade-offs, but let's assume you're not using a proxy. Then I'd be pretty cautious about how large you set any individual pool. If you're running an application under pretty serious load where you need dynamic scaling or lots of lambdas spinning up and sending queries, your queries are likely fast and you should be fine setting the `max` to a low value like 10 -- or just leave it alone, since `10` is the default.
+
+## pg-bouncer, RDS-proxy, etc.
+
+I'm not sure of all the pooling services for Postgres. I haven't used any myself. Throughout the years of working on `pg`, I've addressed issues caused by various proxies behaving differently than an actual Postgres backend. There are also gotchas with things like transactions. On the other hand, plenty of people run these with much success. In this situation, I would just recommend using some small but reasonable `max` value like the default value of `10` as it can still be helpful to keep a few TCP sockets from your services to the Postgres proxy open.
+
+## Conclusion, tl;dr
+
+It's a bit of a complicated topic and doesn't have much impact on things until you need to start scaling. At that point, your number of connections _still_ probably won't be your scaling bottleneck. It's worth thinking about a bit, but mostly I'd just leave the pool size to the default of `10` until you run into troubles: hopefully you never do!
diff --git a/docs/pages/guides/project-structure.md b/docs/pages/guides/project-structure.md
index 742451daa..5f53a4183 100644
--- a/docs/pages/guides/project-structure.md
+++ b/docs/pages/guides/project-structure.md
@@ -11,8 +11,6 @@ Whenever I am writing a project & using node-postgres I like to create a file wi
## example
-_note: I am using callbacks in this example to introduce as few concepts as possible at a time, but the same is doable with promises or async/await_
-
The location doesn't really matter - I've found it usually ends up being somewhat app specific and in line with whatever folder structure conventions you're using. For this example I'll use an express app structured like so:
```
@@ -29,14 +27,12 @@ The location doesn't really matter - I've found it usually ends up being somewha
Typically I'll start out my `db/index.js` file like so:
```js
-const { Pool } = require('pg')
+import { Pool } from 'pg'
const pool = new Pool()
-module.exports = {
- query: (text, params, callback) => {
- return pool.query(text, params, callback)
- },
+export const query = (text, params) => {
+ return pool.query(text, params)
}
```
@@ -45,15 +41,11 @@ That's it. But now everywhere else in my application instead of requiring `pg` d
```js
// notice here I'm requiring my database adapter file
// and not requiring node-postgres directly
-const db = require('../db')
-
-app.get('/:id', (req, res, next) => {
- db.query('SELECT * FROM users WHERE id = $1', [req.params.id], (err, result) => {
- if (err) {
- return next(err)
- }
- res.send(result.rows[0])
- })
+import * as db from '../db/index.js'
+
+app.get('/:id', async (req, res, next) => {
+ const result = await db.query('SELECT * FROM users WHERE id = $1', [req.params.id])
+ res.send(result.rows[0])
})
// ... many other routes in this file
@@ -62,19 +54,16 @@ app.get('/:id', (req, res, next) => {
Imagine we have lots of routes scattered throughout many files under our `routes/` directory. We now want to go back and log every single query that's executed, how long it took, and the number of rows it returned. If we had required node-postgres directly in every route file we'd have to go edit every single route - that would take forever & be really error prone! But thankfully we put our data access into `db/index.js`. Let's go add some logging:
```js
-const { Pool } = require('pg')
+import { Pool } from 'pg'
const pool = new Pool()
-module.exports = {
- query: (text, params, callback) => {
- const start = Date.now()
- return pool.query(text, params, (err, res) => {
- const duration = Date.now() - start
- console.log('executed query', { text, duration, rows: res.rowCount })
- callback(err, res)
- })
- },
+export const query = async (text, params) => {
+ const start = Date.now()
+ const res = await pool.query(text, params)
+ const duration = Date.now() - start
+ console.log('executed query', { text, duration, rows: res.rowCount })
+ return res
}
```
@@ -85,112 +74,57 @@ _note: I didn't log the query parameters. Depending on your application you migh
Now what if we need to check out a client from the pool to run several queries in a row in a transaction? We can add another method to our `db/index.js` file when we need to do this:
```js
-const { Pool } = require('pg')
+import { Pool } from 'pg'
const pool = new Pool()
-module.exports = {
- query: (text, params, callback) => {
- const start = Date.now()
- return pool.query(text, params, (err, res) => {
- const duration = Date.now() - start
- console.log('executed query', { text, duration, rows: res.rowCount })
- callback(err, res)
- })
- },
- getClient: (callback) => {
- pool.connect((err, client, done) => {
- callback(err, client, done)
- })
- },
+export const query = async (text, params) => {
+ const start = Date.now()
+ const res = await pool.query(text, params)
+ const duration = Date.now() - start
+ console.log('executed query', { text, duration, rows: res.rowCount })
+ return res
}
-```
-
-Okay. Great - the simplest thing that could possibly work. It seems like one of our routes that checks out a client to run a transaction is forgetting to call `done` in some situation! Oh no! We are leaking a client & have hundreds of these routes to go audit. Good thing we have all our client access going through this single file. Lets add some deeper diagnostic information here to help us track down where the client leak is happening.
-
-```js
-const { Pool } = require('pg')
-
-const pool = new Pool()
-module.exports = {
- query: (text, params, callback) => {
- const start = Date.now()
- return pool.query(text, params, (err, res) => {
- const duration = Date.now() - start
- console.log('executed query', { text, duration, rows: res.rowCount })
- callback(err, res)
- })
- },
- getClient: (callback) => {
- pool.connect((err, client, done) => {
- const query = client.query
-
- // monkey patch the query method to keep track of the last query executed
- client.query = (...args) => {
- client.lastQuery = args
- return query.apply(client, args)
- }
-
- // set a timeout of 5 seconds, after which we will log this client's last query
- const timeout = setTimeout(() => {
- console.error('A client has been checked out for more than 5 seconds!')
- console.error(`The last executed query on this client was: ${client.lastQuery}`)
- }, 5000)
-
- const release = (err) => {
- // call the actual 'done' method, returning this client to the pool
- done(err)
-
- // clear our timeout
- clearTimeout(timeout)
-
- // set the query method back to its old un-monkey-patched version
- client.query = query
- }
-
- callback(err, client, release)
- })
- },
+export const getClient = () => {
+ return pool.connect()
}
```
-Using async/await:
+Okay. Great - the simplest thing that could possibly work. It seems like one of our routes that checks out a client to run a transaction is forgetting to call `release` in some situation! Oh no! We are leaking a client & have hundreds of these routes to go audit. Good thing we have all our client access going through this single file. Lets add some deeper diagnostic information here to help us track down where the client leak is happening.
```js
-module.exports = {
- async query(text, params) {
- const start = Date.now()
- const res = await pool.query(text, params)
- const duration = Date.now() - start
- console.log('executed query', { text, duration, rows: res.rowCount })
- return res
- },
-
- async getClient() {
- const client = await pool.connect()
- const query = client.query
- const release = client.release
- // set a timeout of 5 seconds, after which we will log this client's last query
- const timeout = setTimeout(() => {
- console.error('A client has been checked out for more than 5 seconds!')
- console.error(`The last executed query on this client was: ${client.lastQuery}`)
- }, 5000)
- // monkey patch the query method to keep track of the last query executed
- client.query = (...args) => {
- client.lastQuery = args
- return query.apply(client, args)
- }
- client.release = () => {
- // clear our timeout
- clearTimeout(timeout)
- // set the methods back to their old un-monkey-patched version
- client.query = query
- client.release = release
- return release.apply(client)
- }
- return client
- },
+export const query = async (text, params) => {
+ const start = Date.now()
+ const res = await pool.query(text, params)
+ const duration = Date.now() - start
+ console.log('executed query', { text, duration, rows: res.rowCount })
+ return res
+}
+
+export const getClient = async () => {
+ const client = await pool.connect()
+ const query = client.query
+ const release = client.release
+ // set a timeout of 5 seconds, after which we will log this client's last query
+ const timeout = setTimeout(() => {
+ console.error('A client has been checked out for more than 5 seconds!')
+ console.error(`The last executed query on this client was: ${client.lastQuery}`)
+ }, 5000)
+ // monkey patch the query method to keep track of the last query executed
+ client.query = (...args) => {
+ client.lastQuery = args
+ return query.apply(client, args)
+ }
+ client.release = () => {
+ // clear our timeout
+ clearTimeout(timeout)
+ // set the methods back to their old un-monkey-patched version
+ client.query = query
+ client.release = release
+ return release.apply(client)
+ }
+ return client
}
```
diff --git a/docs/pages/guides/upgrading.md b/docs/pages/guides/upgrading.md
index 2a1d311a2..6a09d2ec1 100644
--- a/docs/pages/guides/upgrading.md
+++ b/docs/pages/guides/upgrading.md
@@ -5,13 +5,13 @@ slug: /guides/upgrading
# Upgrading to 8.0
-node-postgres at 8.0 introduces a breaking change to ssl-verified connections. If you connect with ssl and use
+node-postgres at 8.0 introduces a breaking change to ssl-verified connections. If you connect with ssl and use
```
const client = new Client({ ssl: true })
```
-and the server's SSL certificate is self-signed, connections will fail as of node-postgres 8.0. To keep the existing behavior, modify the invocation to
+and the server's SSL certificate is self-signed, connections will fail as of node-postgres 8.0. To keep the existing behavior, modify the invocation to
```
const client = new Client({ ssl: { rejectUnauthorized: false } })
@@ -37,7 +37,7 @@ If your application still relies on these they will be _gone_ in `pg@7.0`. In or
// old way, deprecated in 6.3.0:
// connection using global singleton
-pg.connect(function(err, client, done) {
+pg.connect(function (err, client, done) {
client.query(/* etc, etc */)
done()
})
@@ -50,10 +50,10 @@ pg.end()
// new way, available since 6.0.0:
// create a pool
-var pool = new pg.Pool()
+const pool = new pg.Pool()
// connection using created pool
-pool.connect(function(err, client, done) {
+pool.connect(function (err, client, done) {
client.query(/* etc, etc */)
done()
})
@@ -102,11 +102,12 @@ If you do **not** pass a callback `client.query` will return an instance of a `P
`client.query` has always accepted any object that has a `.submit` method on it. In this scenario the client calls `.submit` on the object, delegating execution responsibility to it. In this situation the client also **returns the instance it was passed**. This is how [pg-cursor](https://github.com/brianc/node-pg-cursor) and [pg-query-stream](https://github.com/brianc/node-pg-query-stream) work. So, if you need the event emitter functionality on your queries for some reason, it is still possible because `Query` is an instance of `Submittable`:
```js
-const { Client, Query } = require('pg')
+import pg from 'pg'
+const { Client, Query } = pg
const query = client.query(new Query('SELECT NOW()'))
-query.on('row', row => {})
-query.on('end', res => {})
-query.on('error', res => {})
+query.on('row', (row) => {})
+query.on('end', (res) => {})
+query.on('error', (res) => {})
```
`Query` is considered a public, documented part of the API of node-postgres and this form will be supported indefinitely.
diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx
index 2e14116b5..5a9011b01 100644
--- a/docs/pages/index.mdx
+++ b/docs/pages/index.mdx
@@ -3,6 +3,8 @@ title: Welcome
slug: /
---
+import { Logo } from '/components/logo.tsx'
+
node-postgres is a collection of node.js modules for interfacing with your PostgreSQL database. It has support for callbacks, promises, async/await, connection pooling, prepared statements, cursors, streaming results, C/C++ bindings, rich type parsing, and more! Just like PostgreSQL itself there are a lot of features: this documentation aims to get you up and running quickly and in the right direction. It also tries to provide guides for more advanced & edge-case topics allowing you to tap into the full power of PostgreSQL from node.js.
## Install
@@ -15,18 +17,33 @@ $ npm install pg
node-postgres continued development and support is made possible by the many [supporters](https://github.com/brianc/node-postgres/blob/master/SPONSORS.md).
-If you or your company would like to sponsor node-postgres stop by [github sponsors](https://github.com/sponsors/brianc) and sign up or feel free to [email me](mailto:brian@pecanware.com) if you want to add your logo to the documentation or discuss higher tiers of sponsorship!
+Special thanks to [Medplum](https://www.medplum.com/) for sponsoring node-postgres for a whole year!
+
+
+
+
+
+If you or your company would like to sponsor node-postgres stop by [GitHub Sponsors](https://github.com/sponsors/brianc) and sign up or feel free to [email me](mailto:brian@pecanware.com) if you want to add your logo to the documentation or discuss higher tiers of sponsorship!
# Version compatibility
-node-postgres strives to be compatible with all recent lts versions of node & the most recent "stable" version. At the time of this writing node-postgres is compatible with node 8.x, 10.x, 12.x and 14.x To use node >= 14.x you will need to install `pg@8.2.x` or later due to some internal stream changes on the node 14 branch. Dropping support for an old node lts version will always be considered a breaking change in node-postgres and will be done on _major_ version number changes only, and we will try to keep support for 8.x for as long as reasonably possible.
+node-postgres strives to be compatible with all recent LTS versions of node & the most recent "stable" version. At the time of this writing node-postgres is compatible with node 18.x, 20.x, 22.x, and 24.x.
## Getting started
-This is the simplest possible way to connect, query, and disconnect with async/await:
+The simplest possible way to connect, query, and disconnect is with async/await:
```js
-const { Client } = require('pg')
+import { Client } from 'pg'
const client = new Client()
await client.connect()
@@ -35,18 +52,36 @@ console.log(res.rows[0].message) // Hello world!
await client.end()
```
-And here's the same thing with callbacks:
+### Error Handling
-```js
-const { Client } = require('pg')
+For the sake of simplicity, these docs will assume that the methods are successful. In real life use, make sure to properly handle errors thrown in the methods. A `try/catch` block is a great way to do so:
+
+```ts
+import { Client } from 'pg'
const client = new Client()
+await client.connect()
-client.connect()
+try {
+ const res = await client.query('SELECT $1::text as message', ['Hello world!'])
+ console.log(res.rows[0].message) // Hello world!
+} catch (err) {
+ console.error(err);
+} finally {
+ await client.end()
+}
+```
-client.query('SELECT $1::text as message', ['Hello world!'], (err, res) => {
- console.log(err ? err.stack : res.rows[0].message) // Hello World!
- client.end()
-})
+### Pooling
+
+In most applications you'll wannt to use a [connection pool](/features/pooling) to manage your connections. This is a more advanced topic, but here's a simple example of how to use it:
+
+```js
+import { Pool } from 'pg'
+const pool = new Pool()
+const res = await pool.query('SELECT $1::text as message', ['Hello world!'])
+console.log(res.rows[0].message) // Hello world!
```
Our real-world apps are almost always more complicated than that, and I urge you to read on!
+
+
diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico
new file mode 100644
index 000000000..ab485092f
Binary files /dev/null and b/docs/public/favicon.ico differ
diff --git a/docs/theme.config.js b/docs/theme.config.js
index 263a26945..316ae7145 100644
--- a/docs/theme.config.js
+++ b/docs/theme.config.js
@@ -10,7 +10,6 @@ export default {
docsRepositoryBase: 'https://github.com/brianc/node-postgres/blob/master/docs', // base URL for the docs repository
titleSuffix: ' – node-postgres',
darkMode: true,
- footer: true,
navigation: {
prev: true,
next: true,
@@ -23,15 +22,48 @@ export default {
},
logo: (
<>
-
- node-postgres
+
+ node-postgres
),
+ chat: {
+ link: 'https://discord.gg/4nbb6zJa',
+ },
head: (
<>
-
-
+
+
+