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

&nbps;

### query(_string_ text) : _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

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));

### query(_object_ config) : _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

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));

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);
    });