Integration

This document is the guidelines for integrating pg-promise with reusable libraries.

standard approach

The standard way is by adding pg-promise as a dependency in your package.json.

advantages:

• isolated use of promise libraries
• coding strictly for the referenced version of pg-promise
• providing your own Initialization Options

disadvantages:

• requires separate database connection parameters
• requires creation of a separate instance of the Database object

If the client module creates its own Database object from the same connection parameters, it will result in a duplicate Database object warning, as explained in the Database API.

via db parameter

You can accept db - Database object as a parameter, to use it directly. And you can access all pg-promise features via property db.$config.

advantages:

• consistent use of the Initialization Options, as configured by the client
• no dependencies: reusing pg-promise and the promise library as configured by the client
• no duplicate Database objects, optimal use of the connection and event listeners

disadvantages:

• cannot set your own Initialization Options, and you can break the client's code, if you try
• can only use the basic promise methods as exposed via db.$config.promise

mixed approach

You can support pg-promise through explicit dependencies (for the default), and via db parameter as a optional override.

This is the recommended approach, because it can suit the needs of both client types:

• clients that use pg-promise internally will be able to pass in db as a parameter
• clients that do not use pg-promise internally will rely on your library's defaults

extras

promises

When using pg-promise via db parameter, you have access to the underlying layer of promises:

• db.$config.promiseLib - the promise library as configured by the client
• db.$config.promise - the basic promise interface as used by pg-promise

If you want to provide compatibility with any promise library configured by pg-promise client, you have to rely on the available basic promise interface:

var $p = db.$config.promise; // your basic promise interface

// for a new promise object:
return $p(function(resolve, reject) {
   // call resolve/reject as required
});

// for a resolved promise:
return $p.resolve(value);

// for a rejected promise:
return $p.reject(reason);

There are no other methods in the basic promise interface beside the ones shown above.

version

If you want to enforce the minimum-version requirement on the db parameter, you can use the following function:

// Compares a version-parameter to pg-promise database object version,
// and returns the comparison result:
//  -1: database object version is older
//   1: database object version is newer
//   0: the same versions
//
// NOTE: It will always return -1 for pg-promise prior to 4.4.8,
// starting from which the version can be determined precisely.
//
// Parameter 'version' is a string from '0' to '999.999.999'
//
function comparePGPVersion(db, version) {

    if (!db || !db.constructor || db.constructor.name !== 'Database') {
        throw new TypeError("Parameter 'db' is invalid.");
    }

    var valid;
    if (typeof version === 'string') {
        var m = version.match(/([0-9]{1,3})(\.[0-9]{1,3}){0,2}/);
        valid = m && m[0] === version;
    }

    if (!valid) {
        throw new TypeError("Parameter 'version' is invalid.");
    }

    if (!db.$config || !db.$config.version) {
        return -1;
    }

    var v1 = parse(db.$config.version), v2 = parse(version);

    var i = 0;
    do {
        if (v1[i] < v2[i]) {
            return -1;
        }
        if (v1[i] > v2[i]) {
            return 1;
        }
    } while (++i < 3);

    return 0;

    function parse(ver) {
        var a = ver.split('.').map(function (v) {
            return parseInt(v);
        });
        return a.concat(new Array(3 - a.length).fill(0));
    }
}