pg

pg

pg is an object which provides Client life-cycle management and client pooling. It exports a 'helper function' to retrieve Client instances from a pool of available clients. You can bypass the pg object all together and create Client objects via their constructor; however, each Client represents an open connection to your PostgreSQL server instance. If you attempt to create and connect more Client objects than supported connections to your PostgreSQL server you will encounter errors. This becomes especially painful if you manually instantiate a new Client object per each http request to a web server. Once you receive more simultaneous requests to your web server than your PostgresSQL server can maintain you will be in a bad place...so it's recommended unless you have a particular case, use the pg object to create clients.

• Methods
  • connect
  • end
• Properties
  • defaults

example

    require('pg');
    
    var connectionString = "pg://brian:1234@localhost/postgres"
    pg.connect(connectionString, function(err, client) {
      client.query('SELECT name FROM users WHERE email = $1', ['brian@example.com'], function(err, result) {
        assert.equal('brianc', result.rows[0].name);
      });
    });

Methods

Connect(string connectionString, function callback)

Connect(object config, function callback)

The connect method retrieves a Client from the client pool, or if all pooled clients are busy and the pool is not full, the connect method will create a new client passing its first argument directly to the Client constructor. In either case, your supplied callback will only be called when the Client is ready to issue queries or an error is encountered. The callback will be called once and only once for each invocation of connect. The first parameter passed to connect currently functions as the key used in pooling clients; therefore, using two different connection strings will result in two separate pools being created.

parameters

• string connectionString
  • a connection string in the format anything://user:password@host:port/database
• function callback
  • called exactly once for one of the following reasons
    • new client is created and connected to PostgreSQL
    • an existing client is returned to the internal client pool
    • an error is encountered during connection
  • callback parameters
    • object _error: error object
      • if there is no error, this will be null
    • object Client : postgres-node client object ready for queries
      • if there is an error, this object will be null

end(optional string poolKey)

Disconnects all clients within a pool if poolKey is provided, or disconnects all clients in all pools. Not very clean and can potentially interrupt query executions. Primarily used during testing to allow the node process to shutdown after all the tests are executed. I'm currently evaluating routes for cleaning up and shutting down client pools as gracefully as possible.