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.

Kind: event emitted by PostgresUno

"warning"

The warning event is only emitted when the connect method is called more than one time.

Kind: event emitted by PostgresUno

"connect"

The connect event is only emitted when the connect method resolves.

Kind: event emitted by PostgresUno

"disconnect"

The disconnect event is only emitted when the disconnect method resolves.

Kind: event emitted by PostgresUno

"query"

The query event is emitted when the query method is called, but before the submission to the db. The object emitted has a Query property containing the sql. This is often useful for debugging purposes.

Kind: event emitted by PostgresUno

"results"

The results event is emitted when the query method has resolved. The event contains the results object. This emit is off by default. Use the emitControl setter to change the value, if desired.

Kind: event emitted by PostgresUno

PostgresUno.decryptPass(encryptedPass) ⇒ string

Deprecated

Used to provide a simple decryption algorithm for user and password. This method is deprecated. You should use decryptPassIV instead.

Kind: static method of PostgresUno
Returns: string - - decoded password

Param	Type	Description
encryptedPass	string	Should be an hex encoded, encrypted string.

PostgresUno.decryptPassIV(encryptedPass) ⇒ string

Used to provide a simple decryption algorithm for user and password.

Kind: static method of PostgresUno
Returns: string - - decoded password

Param	Type	Description
encryptedPass	string	Should be an hex encoded, encrypted string.

PostgresUno.encryptPass(clearPass) ⇒ string

Deprecated

Provides a simple mechanism for the user to encrypt a password. Note this is not a secure mechanism by any means. It just allows the db config to be stored locally without a clear text password. Note: this method is deprecated.

Kind: static method of PostgresUno
Returns: string - - hex encoded, encrypted password

Param	Type
clearPass	string

PostgresUno.encryptPassIV(clearPass) ⇒ string

Provides a simple mechanism for the user to encrypt a password. Note this is not a secure mechanism by any means. It just allows the db config to be stored locally without a clear text password.

Kind: static method of PostgresUno
Returns: string - - hex encoded, encrypted password

Param	Type
clearPass	string

PostgresUno.escapeDoubleQuotes(source) ⇒ string

Escape double quotes in the target string.

Kind: static method of PostgresUno
Returns: string - the string with double quotes escaped

Param	Type
source	string

PostgresUno.escapeSingleQuotes(source) ⇒ string

Escape single quotes in the target string.

Kind: static method of PostgresUno
Returns: string - the string with single quotes escaped.

Param	Type
source	string

PostgresUno.stringOrNull(source) ⇒ String

If source is null, return string 'null', Escape single quotes.

Kind: static method of PostgresUno

Param	Type
source	String | null

PostgresUno.numberOrNull(source) ⇒ Number | String

If source is null, return string 'null'.

Kind: static method of PostgresUno

Param	Type
source	Number | null