add support for user lookup function

CHANGELOG.md

@@ -4,6 +4,10 @@ For richer information consult the commit log on github with referenced pull req
 
 We do not include break-fix version release in this file.
 
+## [email protected]
+
+- Emit `release` event when client is returned to [the pool](https://github.com/brianc/node-postgres/pull/2845).
+
 ## [email protected]
 
 - Add support for [stream factory](https://github.com/brianc/node-postgres/pull/2898).

LOCAL_DEV.md

@@ -0,0 +1,43 @@
+# Local development
+
+Steps to install and configure Postgres on Mac for developing against locally
+
+1. Install homebrew
+2. Install postgres
+   ```sh
+   brew install postgresql
+   ```
+3. Create a database
+   ```sh
+   createdb test
+   ```
+4. Create SSL certificates
+   ```sh
+   cd /opt/homebrew/var/postgresql@14
+   openssl genrsa -aes128 2048 > server.key
+   openssl rsa -in server.key -out server.key
+   chmod 400 server.key
+   openssl req -new -key server.key -days 365 -out server.crt -x509
+   cp server.crt root.crt
+   ```
+5. Update config in `/opt/homebrew/var/postgresql@14/postgresql.conf`
+
+   ```conf
+   listen_addresses = '*'
+
+   password_encryption = md5
+
+   ssl = on
+   ssl_ca_file = 'root.crt'
+   ssl_cert_file = 'server.crt'
+   ssl_crl_file = ''
+   ssl_crl_dir = ''
+   ssl_key_file = 'server.key'
+   ssl_ciphers = 'HIGH:MEDIUM:+3DES:!aNULL' # allowed SSL ciphers
+   ssl_prefer_server_ciphers = on
+   ```
+
+6. Start Postgres server
+   ```sh
+   /opt/homebrew/opt/postgresql@14/bin/postgres -D /opt/homebrew/var/postgresql@14
+   ```

README.md

@@ -23,7 +23,7 @@ Each package in this repo should have its own readme more focused on how to deve
 
 ### :star: [Documentation](https://node-postgres.com) :star:
 
-The source repo for the documentation is https://github.com/brianc/node-postgres-docs.
+The source repo for the documentation is available for contribution [here](https://github.com/brianc/node-postgres/tree/master/docs).
 
 ### Features
 
@@ -55,7 +55,7 @@ You can also follow me [@briancarlson](https://twitter.com/briancarlson) if that
 
 ## Sponsorship :two_hearts:
 
-node-postgres's continued development has been made possible in part by generous finanical support from [the community](https://github.com/brianc/node-postgres/blob/master/SPONSORS.md).
+node-postgres's continued development has been made possible in part by generous financial support from [the community](https://github.com/brianc/node-postgres/blob/master/SPONSORS.md).
 
 If you or your company are benefiting from node-postgres and would like to help keep the project financially sustainable [please consider supporting](https://github.com/sponsors/brianc) its development.
 

docs/pages/announcements.mdx

@@ -79,7 +79,7 @@ _If you find `pg` valuable to you or your business please consider [supporting](
 
 After a _very_ long time on my todo list I've ported the docs from my old hand-rolled webapp running on route53 + elb + ec2 + dokku (I know, I went overboard!) to [gatsby](https://www.gatsbyjs.org/) hosted on [netlify](https://www.netlify.com/) which is _so_ much easier to manage. I've released the code at [https://github.com/brianc/node-postgres-docs](https://github.com/brianc/node-postgres-docs) and invite your contributions! Let's make this documentation better together. Any time changes are merged to master on the documentation repo it will automatically deploy.
 
-If you see an error in the docs, big or small, use the "edit on github" button to edit the page & submit a pull request right there. I'll get a new version out ASAP with your changes! If you want to add new pages of documentation open an issue if you need guidance, and I'll help you get started.
+If you see an error in the docs, big or small, use the "edit on GitHub" button to edit the page & submit a pull request right there. I'll get a new version out ASAP with your changes! If you want to add new pages of documentation open an issue if you need guidance, and I'll help you get started.
 
 I want to extend a special **thank you** to all the [supporters](https://github.com/brianc/node-postgres/blob/master/SPONSORS.md) and [contributors](https://github.com/brianc/node-postgres/graphs/contributors) to the project that have helped keep me going through times of burnout or life "getting in the way." ❤️
 
@@ -116,7 +116,7 @@ [email protected]
 To demonstrate the issue & see if you are vunerable execute the following in node:
 
 ```js
-const { Client } = require('pg')
+import { Client } from 'pg'
 const client = new Client()
 client.connect()
 

docs/pages/apis/_meta.json

@@ -3,5 +3,6 @@
   "pool": "pg.Pool",
   "result": "pg.Result",
   "types": "pg.Types",
-  "cursor": "Cursor"
+  "cursor": "Cursor",
+  "utilities": "Utilities"
 }

docs/pages/apis/client.mdx

@@ -29,45 +29,26 @@ type Config = {
 example to create a client with specific connection information:
 
 ```js
-const { Client } = require('pg')
+import { Client } from 'pg'
 
 const client = new Client({
   host: 'my.database-server.com',
   port: 5334,
+  database: 'database-name',
   user: 'database-user',
   password: 'secretpassword!!',
 })
 ```
 
 ## client.connect
 
-Calling `client.connect` with a callback:
-
 ```js
-const { Client } = require('pg')
+import { Client } from 'pg'
 const client = new Client()
-client.connect((err) => {
-  if (err) {
-    console.error('connection error', err.stack)
-  } else {
-    console.log('connected')
-  }
-})
-```
 
-Calling `client.connect` without a callback yields a promise:
-
-```js
-const { Client } = require('pg')
-const client = new Client()
-client
-  .connect()
-  .then(() => console.log('connected'))
-  .catch((err) => console.error('connection error', err.stack))
+await client.connect()
 ```
 
-_note: connect returning a promise only available in [email protected] or above_
-
 ## client.query
 
 ### QueryConfig
@@ -94,77 +75,43 @@ type QueryConfig {
 }
 ```
 
-### callback API
-
 ```ts
-client.query(text: string, values?: any[], callback?: (err: Error, result: QueryResult) => void) => void
-```
-
-**Plain text query with a callback:**
-
-```js
-const { Client } = require('pg')
-const client = new Client()
-client.connect()
-client.query('SELECT NOW()', (err, res) => {
-  if (err) throw err
-  console.log(res)
-  client.end()
-})
+client.query(text: string, values?: any[]) => Promise<Result>
 ```
 
-**Parameterized query with a callback:**
+**Plain text query**
 
 ```js
-const { Client } = require('pg')
+import { Client } from 'pg'
 const client = new Client()
-client.connect()
-client.query('SELECT $1::text as name', ['brianc'], (err, res) => {
-  if (err) throw err
-  console.log(res)
-  client.end()
-})
-```
 
-### Promise API
+await client.connect()
 
-If you call `client.query` with query text and optional parameters but **don't** pass a callback, then you will receive a `Promise` for a query result.
+const result = await client.query('SELECT NOW()')
+console.log(result)
 
-```ts
-client.query(text: string, values?: any[]) => Promise<Result>
+await client.end()
 ```
 
-**Plain text query with a promise**
+**Parameterized query**
 
 ```js
-const { Client } = require('pg')
+import { Client } from 'pg'
 const client = new Client()
-client.connect()
-client
-  .query('SELECT NOW()')
-  .then((result) => console.log(result))
-  .catch((e) => console.error(e.stack))
-  .then(() => client.end())
-```
 
-**Parameterized query with a promise**
+await client.connect()
 
-```js
-const { Client } = require('pg')
-const client = new Client()
-client.connect()
-client
-  .query('SELECT $1::text as name', ['brianc'])
-  .then((result) => console.log(result))
-  .catch((e) => console.error(e.stack))
-  .then(() => client.end())
+const result = await client.query('SELECT $1::text as name', ['brianc'])
+console.log(result)
+
+await client.end()
 ```
 
 ```ts
 client.query(config: QueryConfig) => Promise<Result>
 ```
 
-**client.query with a QueryConfig and a callback**
+**client.query with a QueryConfig**
 
 If you pass a `name` parameter to the `client.query` method, the client will create a [prepared statement](/features/queries#prepared-statements).
 
@@ -176,42 +123,18 @@ const query = {
   rowMode: 'array',
 }
 
-client.query(query, (err, res) => {
-  if (err) {
-    console.error(err.stack)
-  } else {
-    console.log(res.rows) // ['brianc']
-  }
-})
-```
-
-**client.query with a QueryConfig and a Promise**
+const result = await client.query(query)
+console.log(result.rows) // ['brianc']
 
-```js
-const query = {
-  name: 'get-name',
-  text: 'SELECT $1::text',
-  values: ['brianc'],
-  rowMode: 'array',
-}
-
-// promise
-client
-  .query(query)
-  .then((res) => {
-    console.log(res.rows) // ['brianc']
-  })
-  .catch((e) => {
-    console.error(e.stack)
-  })
+await client.end()
 ```
 
 **client.query with a `Submittable`**
 
 If you pass an object to `client.query` and the object has a `.submit` function on it, the client will pass it's PostgreSQL server connection to the object and delegate query dispatching to the supplied object. This is an advanced feature mostly intended for library authors. It is incidentally also currently how the callback and promise based queries above are handled internally, but this is subject to change. It is also how [pg-cursor](https://github.com/brianc/node-pg-cursor) and [pg-query-stream](https://github.com/brianc/node-pg-query-stream) work.
 
 ```js
-const Query = require('pg').Query
+import { Query } from 'pg'
 const query = new Query('select $1::text as name', ['brianc'])
 
 const result = client.query(query)
@@ -221,9 +144,11 @@ assert(query === result) // true
 query.on('row', (row) => {
   console.log('row!', row) // { name: 'brianc' }
 })
+
 query.on('end', () => {
   console.log('query done')
 })
+
 query.on('error', (err) => {
   console.error(err.stack)
 })
@@ -236,25 +161,10 @@ query.on('error', (err) => {
 Disconnects the client from the PostgreSQL server.
 
 ```js
-client.end((err) => {
-  console.log('client has disconnected')
-  if (err) {
-    console.log('error during disconnection', err.stack)
-  }
-})
+await client.end()
+console.log('client has disconnected')
 ```
 
-Calling end without a callback yields a promise:
-
-```js
-client
-  .end()
-  .then(() => console.log('client has disconnected'))
-  .catch((err) => console.error('error during disconnection', err.stack))
-```
-
-_note: end returning a promise is only available in pg7.0 and above_
-
 ## events
 
 ### error
@@ -263,7 +173,7 @@ _note: end returning a promise is only available in pg7.0 and above_
 client.on('error', (err: Error) => void) => void
 ```
 
-When the client is in the process of connecting, dispatching a query, or disconnecting it will catch and foward errors from the PostgreSQL server to the respective `client.connect` `client.query` or `client.end` callback/promise; however, the client maintains a long-lived connection to the PostgreSQL back-end and due to network partitions, back-end crashes, fail-overs, etc the client can (and over a long enough time period _will_) eventually be disconnected while it is idle. To handle this you may want to attach an error listener to a client to catch errors. Here's a contrived example:
+When the client is in the process of connecting, dispatching a query, or disconnecting it will catch and foward errors from the PostgreSQL server to the respective `client.connect` `client.query` or `client.end` promise; however, the client maintains a long-lived connection to the PostgreSQL back-end and due to network partitions, back-end crashes, fail-overs, etc the client can (and over a long enough time period _will_) eventually be disconnected while it is idle. To handle this you may want to attach an error listener to a client to catch errors. Here's a contrived example:
 
 ```js
 const client = new pg.Client()
@@ -300,7 +210,7 @@ type Notification {
 
 ```js
 const client = new pg.Client()
-client.connect()
+await client.connect()
 
 client.query('LISTEN foo')