postgres-uno

v2.1.0

Published

3 years ago

An ES6 Class for connecting to Postgresql with a single connection

Downloads

0High
0Medium
0Low

wildbillh

postgres postgresql single connection class es6 node-postgres

postgres-uno

Synopsis

The postgres-uno module supplies an ES6 class that provides a single database connection to a Postgresql server. This class is an promise-enabled encapsulation of the node-postgres (pg) module. See the documentation of the node-postgres module for additional features; https://github.com/brianc/node-postgres.

Code Example

let PostgresUno = require ('postgres-uno');

// Define connection objects and strings. Either can be used.
let dbConfigObject = {
    user: 'nodejs-test',
    host: 'localhost',
    port: 5432,
    password: 'nodejs-test',
    database: 'nodejs-test'
};

// Get and instance of the class
let db = new PostgresUno();

db.connect(dbConfigObject)
.then ( () => {
    return db.query("select now() as thedate");
})
.then( (results) => {
    console.log(results.rows);
    // [ anonymous { thedate: 2016-10-31T18:16:24.859Z } ]
    return db.disconnect();
})
.then ( () => {
    console.log('normal exit');
})
.catch ( (err) => {
    console.log(err);
    return db.disconnect();
});

Other Features

The class is also an emitter. The following events can be listened for:

connect
disconnect
error
query
results (turned off by default)
warning

The emitter behavior can be toggled through the emitControl setter. The default value of this object is:

    {connect: true, 
    disconnect: true, 
    error: true, 
    query: true, 
    results: false, 
    warning: true}

Installation

npm install postgres-uno --save

Documentation

PostgresUno

Class that provides a single database connection to a Postgres server. This class uses the node-postgres module for it's underlying connection. The pg.Client property is exposed for those wanting to use advanced features. All class methods other than the getter above, return a Promise. See the node-postgres documentation: https://github.com/brianc/node-postgres for more information.

Kind: global class

PostgresUno
- new PostgresUno()
- instance
  - .pgClient ⇒ object
  - .emitControl ⇒ object
  - .emitControl
  - .connect(config) ⇒ Promise
  - .disconnect() ⇒ Promise
  - .query(sql) ⇒ Promise
  - "error"
  - "warning"
  - "connect"
  - "disconnect"
  - "query"
  - "results"
- static
  - ~~.decryptPass(encryptedPass) ⇒ string~~
  - .decryptPassIV(encryptedPass) ⇒ string
  - ~~.encryptPass(clearPass) ⇒ string~~
  - .encryptPassIV(clearPass) ⇒ string
  - .escapeDoubleQuotes(source) ⇒ string
  - .escapeSingleQuotes(source) ⇒ string
  - .stringOrNull(source) ⇒ String
  - .numberOrNull(source) ⇒ Number | String

new PostgresUno()

Create a new instance of the class.

postgresUno.pgClient ⇒ object

Getter that returns the underlying node-postgres client object. This is useful for using advanced features of the former module, not exposed by this class.

Kind: instance property of PostgresUno

postgresUno.emitControl ⇒ object

Getter that returns the underlying emit control object. By default all emits other than results, are turned on.

Kind: instance property of PostgresUno

postgresUno.emitControl

Setter for the emit control object. Be default, emits occur for connect, disconnect, query and warning (results and error is turned off). For performance reasons, these can be turned off by the user. Example: to disable query and results emits only, set the value as such: {connect: true, disconnect: true, error: true, query: true, results: false, warning: true}

Kind: instance property of PostgresUno

| Param | Type | | --- | --- | | emitObject | object |

postgresUno.connect(config) ⇒ Promise

Connect to a server using the provided query string or connect object. If the connect fails, the method rejects and an error event is emitted. If connect is called more than once, the new connection will be honored, but a warning event will be emitted. A connect event is emitted when resolved. The parameters to this function can be an object or a string of the form: 'postgresql://user:password@host:port/database' can be passed.

Kind: instance method of PostgresUno
Emits: error, warning, connect
Fulfil:
Reject: string - error message

| Param | Type | Default | Description | | --- | --- | --- | --- | | config | object | | Passes the DB login parameters to the class in object or string form. | | config.host | string | | | | config.user | string | | | | config.password | string | | | | [config.port] | number | 5432 | | | [config.database] | string | null | | | [config.string] | string | null | | | [config.encrypted] | boolean | false | | | [config.encryptedUser] | boolean | false | |

postgresUno.disconnect() ⇒ Promise

Used to disconnect from the Database. All cleanup procedures should call this. Typically your node process will not end normally if there is still a connection open. A disconnect event if emitted on successful call.

Kind: instance method of PostgresUno
Emits: disconnect
Fulfil:
Reject: string - error message

postgresUno.query(sql) ⇒ Promise

Submit sql or ddl to be applied to the server. When resolved, the promise contains a results object. The format is documented somewhat in the return documentation below. If an error is detected, the method rejects and an error event is emitted. By default the query event is emitted when this method is called. The results event is emitted when the method resolves, but this feature is off by default.

Kind: instance method of PostgresUno
Emits: error, query, results
Fulfil: { rows: [{col1: val, col2: val], fields: ["col1", "col2"], rowCount: Number, command: String} }
Reject: string - error message

| Param | Type | Description | | --- | --- | --- | | sql | String | Valid SQL or DDL to apply to the DB |

"error"

If an error is detected during connect(), disconnect() or query() calls, the method rejects the promise and an error event is emitted. It can be useful to listen to this event for easy debugging.