The API documentation for pg.Client does not document client.release. The method is documented elsewhere in the overview of pooling and the API documentation for pg.Pool (see #1302 (comment)), but, due to my inattentive blindness, I had missed that the examples used client.release, not client.end. It would be good if client.release itself was documented as a method on the API documentation for pg.Client, with its own section—even if it simply referred to the section about releaseCallback on the API documentation for pg.Pool.

I ran into this when I had assumed that I could call client.end to release a pool’s connection back to the pool, before I even had realized that client.release existed. Calling pool.end after calling client.end will hang the process (see #1414 (comment)). It would be good if this pitfall was also documented for pg.Client in client.end’s section:

const pg = require('pg');

async function f (callback) {
  const pool = new pg.Pool;
  const connection = await pool.connect();
  await callback(connection);
  await connection.end(); // This should be `await connection.release();`.
  await pool.end(); // Commenting this line would also prevent the hang.
}

(async () => {
  await f(async connection => {
    console.log('X');
  });
  console.log('Y'); // Never runs unless line 8 is commented.
})();