Query

Not to be created directly from its constructor, the Query is returned from Client#query. It functions primarily as an EventEmitter allowing you to handle returned rows.

• events
  • row
  • error
  • end

Events

### Row : (__object__ row, __object__ result)

Emitted by the query whenever a row is received from the PostgreSQL server upon query execution.

The event listeners get two arguments:

• row: The parsed, type-coerced row. It is a simple key/value Object.
• result: A special Result object that can be used to accumulate rows.

examples

    var query = client.query('SELECT name, age as user_age FROM users');
    query.on('row', function(row) {
      console.log('user "%s" is %d years old', row.name, row.user_age);
    });

    var query = client.query('SELECT name, age as user_age FROM users');
    query.on('row', function(row, result) {
      result.addRow(row);
    });

### Error : (__object__ error)

Emitted by the query when an error is encountered within the context of query execution, the event listeners are passed the error event from the PostgreSQL server.

If the Query object was created with an optional callback function, the error event will not fire. This prevents you from having to handle the error both in the callback function and on the event listener.

note: If this event (or any event with the name 'error') is not handled it will propagate to the global event loop. This can potentially crash your node process. This is standard node.js behavior..

examples

no callback function

    var query = client.query('SELECT asdfasdfasdf');
    query.on('error', function(error) {
      //handle the error
    });

callback function

    var query = client.query('SELECT LAKJDLSKJF', function(err, result) {
      //err is the error returned from the PostgreSQL server
      //handle the error here
    });
    query.on('error', function() {
      //this code will never execute
      assert.ok(false, "This will never be called because you supplied the optional query callback function");
    })

### End

Emitted by the query when all rows have been returned successfully. In the case of an error this event will not be emitted. When the end event fires query's execution is finished and it is no longer interacting with the connection.

The end event listeners get one argument, which is the Result object.

examples

    var query = client.query('select name from person');
    var rows = [];
    query.on('row', function(row) {
      //fired once for each row returned
      rows.push(row);
    });
    query.on('end', function(result) {
      //fired once and only once, after the last row has been returned and after all 'row' events are emitted
      //in this example, the 'rows' array now contains an ordered set of all the rows which we received from postgres
      console.log(result.rowCount + ' rows were received');
    })

### Result object

Available to the row and end events, shows the result of the query. It has the following properties:

• command: The sql command that was executed (e.g. "SELECT", "UPDATE", etc.)
• rowCount: The number of rows affected by the SQL statement (more information)
• oid: The oid returned
• rows: An array of rows (if the addRow command is used)

It also has the following method:

• addRow(row): Appends the row object to the Result.rows array. Normally this is the row object returned by the row event, but it can be anything you want.

example

    var query = client.query('select name from person');
    query.on('row', function(row, result) {
      result.addRow(row);
    });
    query.on('end', function(result) {
      console.log(result.rows.length + ' rows were received');
    });

Prepared statements

Using Prepared Statements is a very convenient way of running repeated queries with different parameters.