Have PgExecutor intelligently share connections

[benjie]

Description

Previously each PgSelectStep would effectively grab its own withPgClient and execute the query and return the results, releasing the client. This meant each step had the begin; select set_config(...); ...; commit; overhead - 4 DB roundtrips per step. With PostGraphile's inlining this was generally reasonably efficient because you'd normally only have one or two actual fetch steps; but if you have queries with a lot of root fields or otherwise requiring many PgSelectStep the cost of these many clients can outweigh the gains of the parallelism V5's model enables.

To solve this, PgExecutor will now intelligently distribute queries across connections: similar queries will go to the same connection so that they can make use of shared prepared statements and caches, different queries will spread across multiple clients (default: 3) to enable the benefits of parallelism whilst limiting maximum client consumption from the pool.

Performance impact

Max PG client parallelism is reduced:

• a lot of slow queries might take longer to complete
• lots of fast queries should complete faster due to lower overheads

Security impact

Reduces client exhaustion by capping the number of database clients that a particular request will use for Pg{Select,Union}Step.

Checklist

• My code matches the project's code style and yarn lint:fix passes.
• I've added tests for the new feature, and yarn test passes.
• I have detailed the new feature in the relevant documentation.
• I have added this feature to 'Pending' in the RELEASE_NOTES.md file (if one exists).
• If this is a breaking change I've explained why.

[changeset-bot]

🦋 Changeset detected

Latest commit: e8709d1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
grafast	Patch
graphile-build-pg	Minor
postgraphile	Minor
@dataplan/pg	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[benjie]

I've reviewed the source and am happy with it. Still need to review the tests and make sure there's enough tests (in particular our tests currently run everything through a single client, we really need to test multiclient).