pool: Add support for client.release(true) with Symbol.dispose

Add a `destroyOnDispose` property on the client to signal that
`[Symbol.dispose]()` should call `client.release(true)` instead of
`client.release()`.

Author: hyperair

docs/pages/apis/pool.mdx

@@ -187,6 +187,10 @@ assert(pool.idleCount === 0)
 assert(pool.totalCount === 0)
 ```
 
+`client.destroyOnDispose: boolean`
+
+`client[Symbol.dispose]() => void`
+
 Alternatively, pool clients support [Explicit Resource Management](https://tc39.es/proposal-explicit-resource-management/), which means you can use the `using` syntax to release them if your runtime supports it.
 
 ```js
@@ -195,14 +199,23 @@ import { Pool } from 'pg'
 
 const pool = new Pool()
 {
-
   // check out a single client
   using client = await pool.connect()
 
   // client.release() implicitly called at the end of scope
 }
+
+{
+  // check out a single client
+  using client = await pool.connnect()
+  client.destroyOnDispose = true;
+
+  // client.release(true) implicitly called at the end of scope
+}
 ```
 
+If you want the client to be destroyed instead of being returned to the pool at the end of the scope, (i.e. calling `client.release(true)` at the end of the scope), set the `destroyOnRelease` property to `true`.
+
 <Alert>
   <div>
     You <strong>must</strong> release a client when you are finished with it.

packages/pg-pool/index.js

@@ -342,8 +342,9 @@ class Pool extends EventEmitter {
     client.release = this._releaseOnce(client, idleListener)
 
     if (Symbol.dispose) {
+      client.destroyOnDispose = false
       client[Symbol.dispose] = function () {
-        this.release()
+        this.release(this.destroyOnDispose)
       }
     }
 

packages/pg-pool/test/disposable-clients/using.js

@@ -18,3 +18,21 @@ it('supports releasing clients via `using`', async () => {
 
   await pool.end()
 })
+
+it('supports destroying clients via `using`', async () => {
+  const pool = new Pool({ max: 1 })
+  expect(pool.totalCount).to.eql(0)
+
+  {
+    using client = await pool.connect()
+    client.destroyOnDispose = true
+    expect(pool.totalCount).to.eql(1)
+    expect(pool.idleCount).to.eql(0)
+    await client.query('SELECT NOW()')
+  }
+
+  expect(pool.totalCount).to.eql(0)
+  expect(pool.idleCount).to.eql(0)
+
+  await pool.end()
+})