Explicit Resource Management for pg pool client

[hyperair]

Add support for Explicit Resource Management for pg.Pool clients.

This is implemented using [Symbol.dispose] instead of [Symbol.asyncDispose] because client.release() is a synchronous function, not async.

Additionally, add a second property client.destroyOnDispose so that Symbol.dispose supports calling client.release(true). This is useful for a usecase that changes connection parameters in a way that is troublesome to reset upon release to the pool, e.g.

const pool = new Pool({
    database: 'foo',
    user: 'foo',
    password: 'foo',
    port: 5432,

    statement_timeout: 10_000,
});

async function getSlowClient() {
    const client = await pool.connect();
    await client.query("SET statement_timeout = 0");
    client.destroyOnDispose = true;
}

async function performReallySlowQuery() {
    using client = await getSlowClient();

    client.query(`select pg_sleep_for('30 minutes')`);
}

Fixes: #3515

Note: This PR has been rebased on top of #3662, so there are some irrelevant commits until that PR is merged.

[hyperair]

Hmm, looks like eslint needs to be upgraded before it'll parse the using test

[charmander]

Not sure about destroyOnDispose, i.e. whether its job is common enough to justify it and whether it’s the best API for the job. Would suggest initializing to false if kept. Note .release(true) continues to work for error cases given that double release is a no-op; I recognize that it doesn’t satisfy the use case you mentioned. Maybe release the feature without that API initially, since it can be added easily?

Edit: Sorry, I don’t know where I got that from – we haven’t even done PooledClient yet.

[charmander]

I think this would normally go on the prototype, but pg-pool’s approach is already a bit messy (it’s lacking a PooledClient object that’s specific to one acquisition operation) so it’s also not the end of the world if the patch goes in as-is.

[hyperair]

Agreed, and that's why I implemented it like this.

@types/pg has a PooledClient type with the release signature, and I intend to make a PR there to add the [Symbol.dispose] addition later.

[hyperair]

Not sure about destroyOnDispose, i.e. whether its job is common enough to justify it and whether it’s the best API for the job. Would suggest initializing to false if kept. Note .release(true) continues to work for error cases given that double release is a no-op; I recognize that it doesn’t satisfy the use case you mentioned. Maybe release the feature without that API initially, since it can be added easily?

Yeah I wasn't sure about the API either but I couldn't think of a better way to do it. Maybe a client.setError() to set an error state that client.release() acknowledges as well?

That said, unfortunately I don't think relying on double-release is workable either, because the second release, which will be called from within Symbol.dispose will throw. Even if [Symbol.dispose]() wraps that in a try-catch to swallow the error, needing to put the client.release(true) in a finally clause obviates any purpose of using the using syntax.