pg

pg

pg is an instance of EventEmitter which provides 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
• Events
  • error

example

    var pg = 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)

Connect(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.

If called with only one function argument, uses defaults for connection configuration.

When the client raises its drain event, the client is automatically returned to the pool for reuse.

parameters

• string connectionString
  • a connection string in the format anything://user:password@host:port/database
• object config
  • an object with user, database, password, port, and host properties as described in Client.
• 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.

pg.defaults

The pg object has a set of defaults.

pg.defaults.user

The default user to use when connecting via tcp sockets (md5 or plaintext) if a user is not provided to the individual Client instance. Default value is process.env.USER

pg.defaults.password

The default password to use when connecting via tcp sockets (md5 or plaintext) if a password is not provided to the individual Client instance and PostgreSQL server requires a password. Default value is null

pg.defaults.host

The default host if a host is not provided to the individual Client instance. Can be a domain name, ip address, or path to unix socket folder. Default value is null

pg.defaults.port

The default port if a port is not provided to the individual Client instance. In the case of a unix socket, the port becomes the extension to the socket file. Default value is 5432

pg.defaults.database

The default database to use if a database is not provided to the individual Client instance. Default value is process.env.USER

pg.defaults.poolSize

Number of unique Client objects to maintain in the pool. If this value is set to 0, pooling will be disabled and pg#connect will always return a new client.

Events

'error' : object error, object client

Emitted whenever a pooled client emits an error. An idle client will likely only emit an error when it loses connection to the PostgreSQL server instance, for example when your database crashes (oh no!). The pooled client which emitted the error is automatically removed from the pool and supplied to the callback.