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.

• connect
• end
• query (simple)
• query (prepared statement)

Constructor

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.

parameters

• config: [object] can contain any of the following optional properties
  • user: [string]
    • default value: null
    • PostgreSQL user
  • database: [string]
    • default value: null
    • database to use when connecting to PostgreSQL server
  • password: [string]
    • default value: null
    • user's password for PostgreSQL server
  • port: [number]
    • default value: 5432
    • port to use when connecting to PostgreSQL server
    • will support unix domain sockets in future
    • used to initialize underlying net.Stream()
  • host: [string]
    • 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. Will be used in the future when connection pooling is implemented

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. Once the connection is finished, the Client emits the connect event.

 

### end() : _null_

Immediately sends a termination message to the PostgreSQL server and closes the underlying net.Stream().

 

### 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

• text: [string] 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.fields[0]);
    });
    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 manor as a simple query.

parameters

• config: [object] can contain any of the following optional properties
  • text: [string]
    • The text of the query
    • example: select name from user where email = $1 -name: [string]
    • 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
  • values: [array]
    • 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));