add count for reuse of each connection and track connection 'freshness'

[rngadam]

add an internal variable to each client to track how many times the client was reused from the pool.

This has the side-benefit that we can now test to see if the client is a "new" connection and take action on a per connection basis.

For example, plv8 initialization function (called for each new GUC) is set on a per connection basis (before any calls to any plv8 functions) as follows:

SET plv8.start_proc = "docstore"

the client can create an init function:

    function clientInitFunction(client, cb) {
      console.log('calling client init');
      client.query('SET plv8.start_proc = "docstore"', cb);
    }

which is then called on our promise generating connect closure:

  function connect(dsn) {
    DEBUG_ENABLED && console.log('connect called with ' + dsn);
    var deferred = Q.defer();

    pg.connect(dsn, function(err, client, done) {
      if(err) {
        deferred.reject(new Error('error fetching client from pool ' + err));
        return;
      }
      if(client.__pool_count === 1 && clientInitFunction) {
        clientInitFunction(client, function(err) {
          if(err) {
            deferred.reject(new Error('error initing client ' + err));
            return;
          } else {
            deferred.resolve(new Connection(client, done));
            return;
          }
        })
      }
      deferred.resolve(new Connection(client, done));
    });
    return deferred.promise;
  }

Alternatively, I've thought of adding a new event created that would be propagated from pool -> pg but that doesn't really fit with having to wait for the custom initialization to execute before continuing. Adding hooks to add initialization functions to pg would also unnecessarily complicate the code IMO.

[rngadam]

Hello @brianc, was wondering if you thought this change was reasonable? If not, I'd need to look for an alternative solution to my particular need.

[booo]

Why do you use two underscores here? Any special reason for this? Otherwise I would use one to be consistent.

[booo]

Apart from my comment this looks good to me and is a useful addition. I think we should merge this. @brianc what do you think?

[rngadam]

Well, even better would be no underscore at all and making it part of the official "interface" ^_^

I'll go with whatever you prefer.

[rngadam]

Any comments on this @brianc?

[brianc]

Been thinking about this. I think it makes okay sense. Really I'd like the pool.create function to be more extensible so this isn't needed and instead someone can supply their own create function and do whatever they want to their clients. But this is a pretty straight forward change and doesn't hurt anything so I'm cool with it. 👍 One thing though...i'd definitely drop the underscores. I usually use underscores to mark things as private: might change, do not touch. Since this is a client facing feature it's cool to just add it to the 'official' interface.

[rngadam]

done, squashed into one commit.

[brianc]

awesome. thank you so much! I really hate to be a stickler about this kinda thing, but I never use underscored property names in this code base. Everything is poolSize or rowCount for example. For consistency's sake could we make the property named poolCount? 🙏

[rngadam]

done, sorry again, should have figured that out myself!

[rngadam]

Prepared a bit of doc for after the release:
https://github.com/letsface/node-postgres/wiki/Client-Initialization

[rngadam]

Do you want me to make any other changes to this CL?

[brianc]

awesomeness! I'll get this merged and released in short order. :)