Client

Your main interface point with the PostgreSQL server, the Client is basically a facade on top of the Connection to provide a much more user friendly, "node style" interface for doing all the lovely things you like with PostgreSQL.

• methods
  • connect
  • end
  • query (simple)
  • query (prepared statement)
• events
  • drain
  • error

Constructors

note: Client instances created via the constructor do not participate in connection pooling (this might change in the future...open to suggestions). To take advantage of connection pooling (recommended) please use the pg object.

new Client(string url): Client

Creates a new client from a url based connection string postgres://user:password@host:port/database.

Internally the connection string is parsed and a config object is created with the same defaults as outlined below. All parts of the connection string url are optional. This is handy for use in managed hosting like Heroku.

example

    var client = new Client('postgres://brian:mypassword@localhost:5432/dev');
    var client = new Client('postgres://brian@localhost/dev'); //will use defaults
    var client = new Client(process.env.DATABASE_URL); //something like this should get you running with heroku

new Client(object config) : Client

Creates a new instance of a Client configured via supplied configuration object. In normal instantiation the client will not be connected automatically (requires you to call Client#connect).

parameters

• object config: can contain any of the following optional properties
  • string user:
    • default value: null
    • PostgreSQL user
  • string database:
    • default value: null
    • database to use when connecting to PostgreSQL server
  • string password:
    • default value: null
    • user's password for PostgreSQL server
  • number port:
    • default value: 5432
    • port to use when connecting to PostgreSQL server
    • will support unix domain sockets in future
    • used to initialize underlying net.Stream()
  • string host:
    • default value: null
    • host address of PostgreSQL server
    • used to initialize underlying net.Stream()
  • [Connection] connection:
    • default value: new Connection(config)
    • the Connection object used by client. Only really provided as a config option to aid in testing.

example

    var client = new Client({
      user: 'brianc',
      password: 'boom!'
      database: 'test'
      host: 'example.com'
      port: 5313
    });

Methods

 

### connect() : _null_

Initializes underlying net.Stream() and startup communication with PostgreSQL server including password negotiation.

end() : null

Immediately sends a termination message to the PostgreSQL server and closes the underlying net.Stream(). note: do not call this on a client when the client is managed by a connection pool

query(string text, optional function callback) : Query

Simply: Creates a query object, queues it for execution, and returns it.

In more detail: Adds a Query to the Client's internal query queue. The query is executed as a simple query within PostgresSQL, takes no parameters, and it is parsed, bound, executed, and all rows are streamed backed to the Client in one step within the PostgreSQL server. For more detailed information you can read the PostgreSQL protocol documentation.

parameters

• string text: the query text
• optional function callback: optionally provided function which will be passed the error object (if the query raises an error) or the entire result set buffered into memory. note: do not provide this function for large result sets unless you're okay with loading the entire result set into memory

example

    var client = new Client({user: 'brianc', database: 'test'});
    client.connect();
    //query is executed once connection is established and
    //PostgreSQL server is ready for a query
    var query = client.query("select name from user")
    query.on('row', function(row) {
      console.log(row.name);
    });
    query.on('end', client.end.bind(client));

    //can also provide a callback as the second argument
    //which will buffer all rows into memory.  more info below

### query(_object_ config, _optional function_ callback) : _Query_ ### query(_string_ queryText, _array_ values, _optional function_ callback): _Query_

Creates a (optionally named) query object, queues it for execution, and returns it.

If either name or values is provided within the config object the query will be executed as a prepared statement. Otherwise, it will behave in the same manner as a simple query.

parameters

• object config: can contain any of the following optional properties
  • string text:
    • The text of the query
    • example: select name from user where email = $1
  • string name:
    • The name of the prepared statement
    • Can be used to reference the same statement again later and is used internally to cache and skip the preparation step
  • array values:
    • The values to supply as parameters
    • Values may be any object type supported by the Client
• optional function callback: callback function
  • function callback(object error, object result)
    • Called only if provided
    • buffers all rows into memory before calling
      • rows only buffered if callback is provided
      • can impact memory when buffering large result sets (i.e. do not provide a callback)
    • used as a shortcut instead of subscribing to the 'row' query event

example

    var client = new ...
    var query = client.query({
      text: 'select name from user where email = $1',
      name: 'get user by email',
      values: ['brianc@example.com']
    });
    query.on('row', function() {
      //do something w/ yer row data
    });

    var again = client.query({
      name: 'get user by email',
      values: ['brianc@example.net']
    });

    again.on('row', function() {
      //do something else
    });

    again.on('end', client.end.bind(client));

    var another = client.query("select * from user where name = $1", ["brianc"], function(err, result) {
      if(err != null) {
        throw err;
      }
      var rows = result.rows; //an array of all rows returned from the query
      result.rows.forEach(function(row) {
        console.log(row.name);
      })
    });

Events

### drain :

Raised when the internal query queue has been emptied and all queued queries have been executed. Useful for disconnecting the client after running an undetermined number of queries.

example

    var client = new Client({user: 'brianc', database: 'postgres'});
    client.connect();
    var users = client.query("select * from user");
    var superdoods = client.query("select * from superman");
    client.on('drain', client.end.bind(client));
    //carry on doing whatever it was you wanted with the query results once they return
    users.on('row', function(row){ ...... });

### error : _object_ error

Raised when the client recieves an error message from PostgreSQL or when the underlying stream raises an error. The single parameter passed to the listener will be the error message or error object.

example

    var client = new Client({user: 'not a valid user name', database: 'postgres'});
    client.connect();
    client.on('error', function(error) {
      console.log(error);
    });