feat: pool adds gracefulExit to end gracefully

[HQidea]

As we discussed at #1803, this pull request adds an option to pool's creation,

var pool = common.createPool({
  // ...
  gracefulExit: true
});

If gracefulExit is true, every pool.getConnection or pool.query called before pool.end will success. If false, only commands / queries already in progress will complete, others will throw an error.

[dougwilson]

A couple comments and looks like the coverage check failed because there are uncovered cose paths introduced in this change. If you need help coming up with a test at all, let me know and I can lend a hand :)

[dougwilson]

I think the exact details of how the graceful end works here would be useful, as I remember that was the initial confusion here. As far as I can tell, this implementation will still let checked out connections queue new queries if there is at least one connection in the middle of being established, since the QUIT commands are not queued on all the connections until there is no connection in the aquiring state, is that intentional?

[HQidea]

Yes, it's intentional. I think graceful exit means finishing all queries called before end, so I make that happen.

[dougwilson]

Right, but my comment was that your code is still sometimes allowing queries to be called after end. Is the call to end a hard stop, or should new queries still be allowed to get scheduled? The other issue is that under the acquiring condition, it will sometimes then stop the checked out connections from continuing to query and sometimes not.

[HQidea]

Right, but my comment was that your code is still sometimes allowing queries to be called after end. Is the call to end a hard stop, or should new queries still be allowed to get scheduled?

Only queries have been called before end would be allowed to execute, new queries after end would not be allowed no matter whether there is any checked out connection in the pool

The other issue is that under the acquiring condition, it will sometimes then stop the checked out connections from continuing to query and sometimes not.

When will the acquiring condition will happen?

[dougwilson]

Please add documentation for the new queued argument.

[HQidea]

This queued argument is a private argument, is it appropriate to add documentation to README.md?

[dougwilson]

There is no such thing as a private argument -- the user can simply pass in the value. Just not documenting it doesn't make it private. If the argument is there, it needs to be documented.

[dougwilson]

Can you add at least one test that tests the issue you were having: in a pool of size n, have n connections already in use and then call pool.query so that is pending in the queue. Then call pool.end with the graceful and release those connections to let the pool.query get picked off the queue and ran even though .end was already called.

[HQidea]

Sorry to fix late, and a test case as you requested was added.

[SpraxDev]

I'd love to see this feature. Any progress on that?

[HQidea]

@dougwilson I updated the Readme.md because of conflicts. So is there any chance to merge this pr?
If you require any further information, please let me know.

[dougwilson]

Hi @HQidea I really apologize on this one. I looked over the state of the PR when @Sprax2013 commented trying to remember why it wasn't merged. I got to work and found the reason in some notes I had: I meant to update the PR to pass options through the PoolCluster, which wraps around Pool so they could utilize the new end options added here.

I completely lost track of that, and I'm sorry for that.

[HQidea]

Hi @dougwilson I added the option to PoolCluster.end. And should I add the option to PoolCluster.remove too?