You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1691 lines
75 KiB
1691 lines
75 KiB
/*
|
|
* Copyright (c) 2015-present, Vitaly Tomilov
|
|
*
|
|
* See the LICENSE file at the top-level directory of this distribution
|
|
* for licensing information.
|
|
*
|
|
* Removal or modification of this copyright notice is prohibited.
|
|
*/
|
|
|
|
const {Events} = require(`./events`);
|
|
const {assertOptions} = require(`assert-options`);
|
|
const {resultQuery, multiResultQuery, streamQuery} = require(`./special-query`);
|
|
const {ConnectionContext} = require(`./context`);
|
|
const {DatabasePool} = require(`./database-pool`);
|
|
const {queryResult} = require(`./query-result`);
|
|
|
|
const npm = {
|
|
utils: require(`./utils`),
|
|
pubUtils: require(`./utils/public`),
|
|
connect: require(`./connect`),
|
|
query: require(`./query`),
|
|
task: require(`./task`),
|
|
text: require(`./text`)
|
|
};
|
|
|
|
/**
|
|
* @class Database
|
|
* @description
|
|
*
|
|
* Represents the database protocol, extensible via event {@link event:extend extend}.
|
|
* This type is not available directly, it can only be created via the library's base call.
|
|
*
|
|
* **IMPORTANT:**
|
|
*
|
|
* For any given connection, you should only create a single {@link Database} object in a separate module,
|
|
* to be shared in your application (see the code example below). If instead you keep creating the {@link Database}
|
|
* object dynamically, your application will suffer from loss in performance, and will be getting a warning in a
|
|
* development environment (when `NODE_ENV` = `development`):
|
|
*
|
|
* `WARNING: Creating a duplicate database object for the same connection.`
|
|
*
|
|
* If you ever see this warning, rectify your {@link Database} object initialization, so there is only one object
|
|
* per connection details. See the example provided below.
|
|
*
|
|
* See also: property `noWarnings` in {@link module:pg-promise Initialization Options}.
|
|
*
|
|
* Note however, that in special cases you may need to re-create the database object, if its connection pool has been
|
|
* shut-down externally. And in this case the library won't be showing any warning.
|
|
*
|
|
* @param {string|object} cn
|
|
* Database connection details, which can be:
|
|
*
|
|
* - a configuration object
|
|
* - a connection string
|
|
*
|
|
* For details see {@link https://github.com/vitaly-t/pg-promise/wiki/Connection-Syntax Connection Syntax}.
|
|
*
|
|
* The value can be accessed from the database object via property {@link Database.$cn $cn}.
|
|
*
|
|
* @param {*} [dc]
|
|
* Database Context.
|
|
*
|
|
* Any object or value to be propagated through the protocol, to allow implementations and event handling
|
|
* that depend on the database context.
|
|
*
|
|
* This is mainly to facilitate the use of multiple databases which may need separate protocol extensions,
|
|
* or different implementations within a single task / transaction callback, depending on the database context.
|
|
*
|
|
* This parameter also adds uniqueness to the connection context that's used in combination with the connection
|
|
* parameters, i.e. use of unique database context will prevent getting the warning about creating a duplicate
|
|
* Database object.
|
|
*
|
|
* The value can be accessed from the database object via property {@link Database#$dc $dc}.
|
|
*
|
|
* @returns {Database}
|
|
*
|
|
* @see
|
|
*
|
|
* {@link Database#query query},
|
|
* {@link Database#none none},
|
|
* {@link Database#one one},
|
|
* {@link Database#oneOrNone oneOrNone},
|
|
* {@link Database#many many},
|
|
* {@link Database#manyOrNone manyOrNone},
|
|
* {@link Database#any any},
|
|
* {@link Database#func func},
|
|
* {@link Database#proc proc},
|
|
* {@link Database#result result},
|
|
* {@link Database#multiResult multiResult},
|
|
* {@link Database#multi multi},
|
|
* {@link Database#map map},
|
|
* {@link Database#each each},
|
|
* {@link Database#stream stream},
|
|
* {@link Database#task task},
|
|
* {@link Database#taskIf taskIf},
|
|
* {@link Database#tx tx},
|
|
* {@link Database#txIf txIf},
|
|
* {@link Database#connect connect},
|
|
* {@link Database#$config $config},
|
|
* {@link Database#$cn $cn},
|
|
* {@link Database#$dc $dc},
|
|
* {@link Database#$pool $pool},
|
|
* {@link event:extend extend}
|
|
*
|
|
* @example
|
|
* // Proper way to initialize and share the Database object
|
|
*
|
|
* // Loading and initializing the library:
|
|
* const pgp = require('pg-promise')({
|
|
* // Initialization Options
|
|
* });
|
|
*
|
|
* // Preparing the connection details:
|
|
* const cn = 'postgres://username:password@host:port/database';
|
|
*
|
|
* // Creating a new database instance from the connection details:
|
|
* const db = pgp(cn);
|
|
*
|
|
* // Exporting the database object for shared use:
|
|
* module.exports = db;
|
|
*/
|
|
function Database(cn, dc, config) {
|
|
|
|
const dbThis = this,
|
|
$p = config.promise,
|
|
poolConnection = typeof cn === `string` ? {connectionString: cn} : cn,
|
|
pool = new config.pgp.pg.Pool(poolConnection),
|
|
endMethod = pool.end;
|
|
|
|
let destroyed;
|
|
|
|
pool.end = cb => {
|
|
const res = endMethod.call(pool, cb);
|
|
dbThis.$destroy();
|
|
return res;
|
|
};
|
|
|
|
pool.on(`error`, onError);
|
|
|
|
/**
|
|
* @method Database#connect
|
|
*
|
|
* @description
|
|
* Acquires a new or existing connection, depending on the current state of the connection pool, and parameter `direct`.
|
|
*
|
|
* This method creates a shared connection for executing a chain of queries against it. The connection must be released
|
|
* in the end of the chain by calling `done()` on the connection object.
|
|
*
|
|
* Method `done` takes one optional parameter - boolean `kill` flag, to signal the connection pool that you want it to kill
|
|
* the physical connection. This flag is ignored for direct connections, as they always close when released.
|
|
*
|
|
* It should not be used just for chaining queries on the same connection, methods {@link Database#task task} and
|
|
* {@link Database#tx tx} (for transactions) are to be used for that. This method is primarily for special cases, like
|
|
* `LISTEN` notifications.
|
|
*
|
|
* **NOTE:** Even though this method exposes a {@link external:Client Client} object via property `client`,
|
|
* you cannot call `client.end()` directly, or it will print an error into the console:
|
|
* `Abnormal client.end() call, due to invalid code or failed server connection.`
|
|
* You should only call method `done()` to release the connection.
|
|
*
|
|
* @param {object} [options]
|
|
* Connection Options.
|
|
*
|
|
* @param {boolean} [options.direct=false]
|
|
* Creates a new connection directly, as a stand-alone {@link external:Client Client} object, bypassing the connection pool.
|
|
*
|
|
* By default, all connections are acquired from the connection pool. But if you set this option, the library will instead
|
|
* create a new {@link external:Client Client} object directly (separately from the pool), and then call its `connect` method.
|
|
*
|
|
* Note that specifically for direct connections, method `done` returns a {@link external:Promise Promise}, because those connections
|
|
* are closed physically, which may take time.
|
|
*
|
|
* **WARNING:**
|
|
*
|
|
* Do not use this option for regular query execution, because it exclusively occupies one physical channel, and it cannot scale.
|
|
* This option is only suitable for global connection usage, such as event listeners.
|
|
*
|
|
* @param {function} [options.onLost]
|
|
* Notification callback of the lost/broken connection, called with the following parameters:
|
|
* - `err` - the original connectivity error
|
|
* - `e` - error context object, which contains:
|
|
* - `cn` - safe connection string/config (with the password hashed);
|
|
* - `dc` - Database Context, as was used during {@link Database} construction;
|
|
* - `start` - Date/Time (`Date` type) when the connection was established;
|
|
* - `client` - {@link external:Client Client} object that has lost the connection.
|
|
*
|
|
* The notification is mostly valuable with `direct: true`, to be able to re-connect direct/permanent connections by calling
|
|
* method {@link Database#connect connect} again.
|
|
*
|
|
* You do not need to call `done` on lost connections, as it happens automatically. However, if you had event listeners
|
|
* set up on the connection's `client` object, you should remove them to avoid leaks:
|
|
*
|
|
* ```js
|
|
* function onLostConnection(err, e) {
|
|
* e.client.removeListener('my-event', myHandler);
|
|
* }
|
|
* ```
|
|
*
|
|
* For a complete example see $[Robust Listeners].
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object that represents the connection result:
|
|
* - resolves with the complete {@link Database} protocol, extended with:
|
|
* - property `client` of type {@link external:Client Client} that represents the open connection
|
|
* - method `done` that must be called in the end, in order to release the connection (returns a {@link external:Promise Promise}
|
|
* in case of direct connections)
|
|
* - methods `batch`, `page` and `sequence`, same as inside a {@link Task}
|
|
* - rejects with a connection-related error when it fails to connect.
|
|
*
|
|
* @see
|
|
* {@link Database#task Database.task},
|
|
* {@link Database#taskIf Database.taskIf},
|
|
* {@link Database#tx Database.tx},
|
|
* {@link Database#txIf Database.txIf}
|
|
*
|
|
* @example
|
|
*
|
|
* let sco; // shared connection object;
|
|
*
|
|
* db.connect()
|
|
* .then(obj => {
|
|
* // obj.client = new connected Client object;
|
|
*
|
|
* sco = obj; // save the connection object;
|
|
*
|
|
* // execute all the queries you need:
|
|
* return sco.any('SELECT * FROM Users');
|
|
* })
|
|
* .then(data => {
|
|
* // success
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* })
|
|
* .finally(() => {
|
|
* // release the connection, if it was successful:
|
|
* if (sco) {
|
|
* // if you pass `true` into method done, i.e. done(true),
|
|
* // it will make the pool kill the physical connection.
|
|
* sco.done();
|
|
* }
|
|
* });
|
|
*
|
|
*/
|
|
this.connect = function (options) {
|
|
options = options || {};
|
|
const ctx = createContext();
|
|
ctx.cnOptions = options;
|
|
const self = {
|
|
query(query, values, qrm) {
|
|
if (!ctx.db) {
|
|
return $p.reject(new Error(npm.text.queryDisconnected));
|
|
}
|
|
return config.$npm.query.call(this, ctx, query, values, qrm);
|
|
},
|
|
done(kill) {
|
|
if (!ctx.db) {
|
|
throw new Error(npm.text.looseQuery);
|
|
}
|
|
return ctx.disconnect(kill);
|
|
},
|
|
batch(values, opt) {
|
|
return config.$npm.spex.batch.call(this, values, opt);
|
|
},
|
|
page(source, opt) {
|
|
return config.$npm.spex.page.call(this, source, opt);
|
|
},
|
|
sequence(source, opt) {
|
|
return config.$npm.spex.sequence.call(this, source, opt);
|
|
}
|
|
};
|
|
const connection = options.direct ? config.$npm.connect.direct(ctx) : config.$npm.connect.pool(ctx, dbThis);
|
|
return connection
|
|
.then(db => {
|
|
ctx.connect(db);
|
|
self.client = db.client;
|
|
extend(ctx, self);
|
|
return self;
|
|
});
|
|
};
|
|
|
|
/**
|
|
* @method Database#query
|
|
*
|
|
* @description
|
|
* Base query method that executes a generic query, expecting the return data according to parameter `qrm`.
|
|
*
|
|
* It performs the following steps:
|
|
*
|
|
* 1. Validates and formats the query via {@link formatting.format as.format}, according to the `query` and `values` passed in;
|
|
* 2. For a root-level query (against the {@link Database} object), it requests a new connection from the pool;
|
|
* 3. Executes the query;
|
|
* 4. For a root-level query (against the {@link Database} object), it releases the connection back to the pool;
|
|
* 5. Resolves/rejects, according to the data returned from the query and the value of `qrm`.
|
|
*
|
|
* Direct use of this method is not suitable for chaining queries, for performance reasons. It should be done
|
|
* through either task or transaction context, see $[Chaining Queries].
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @param {queryResult} [qrm=queryResult.any]
|
|
* {@link queryResult Query Result Mask}
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object that represents the query result according to `qrm`.
|
|
*/
|
|
this.query = function (query, values, qrm) {
|
|
const self = this, ctx = createContext();
|
|
return config.$npm.connect.pool(ctx, dbThis)
|
|
.then(db => {
|
|
ctx.connect(db);
|
|
return config.$npm.query.call(self, ctx, query, values, qrm);
|
|
})
|
|
.then(data => {
|
|
ctx.disconnect();
|
|
return data;
|
|
})
|
|
.catch(error => {
|
|
ctx.disconnect();
|
|
return $p.reject(error);
|
|
});
|
|
};
|
|
|
|
/**
|
|
* @member {object} Database#$config
|
|
* @readonly
|
|
* @description
|
|
* This is a hidden property, to help integrating type {@link Database} directly with third-party libraries.
|
|
*
|
|
* Properties available in the object:
|
|
* - `pgp` - instance of the entire library after initialization
|
|
* - `options` - the library's {@link module:pg-promise Initialization Options} object
|
|
* - `promiseLib` - instance of the promise library that's used
|
|
* - `promise` - generic promise interface that uses `promiseLib` via 4 basic methods:
|
|
* - `promise((resolve, reject) => {})` - to create a new promise
|
|
* - `promise.resolve(value)` - to resolve with a value
|
|
* - `promise.reject(reason)` - to reject with a reason
|
|
* - `promise.all(iterable)` - to resolve an iterable list of promises
|
|
* - `version` - this library's version
|
|
* - `$npm` _(hidden property)_ - internal module cache
|
|
*
|
|
* @example
|
|
*
|
|
* // Using the promise protocol as configured by pg-promise:
|
|
*
|
|
* const $p = db.$config.promise;
|
|
*
|
|
* const resolvedPromise = $p.resolve('some data');
|
|
* const rejectedPromise = $p.reject('some reason');
|
|
*
|
|
* const newPromise = $p((resolve, reject) => {
|
|
* // call either resolve(data) or reject(reason) here
|
|
* });
|
|
*/
|
|
npm.utils.addReadProp(this, `$config`, config, true);
|
|
|
|
/**
|
|
* @member {string|object} Database#$cn
|
|
* @readonly
|
|
* @description
|
|
* Database connection, as was passed in during the object's construction.
|
|
*
|
|
* This is a hidden property, to help integrating type {@link Database} directly with third-party libraries.
|
|
*
|
|
* @see Database
|
|
*/
|
|
npm.utils.addReadProp(this, `$cn`, cn, true);
|
|
|
|
/**
|
|
* @member {*} Database#$dc
|
|
* @readonly
|
|
* @description
|
|
* Database Context, as was passed in during the object's construction.
|
|
*
|
|
* This is a hidden property, to help integrating type {@link Database} directly with third-party libraries.
|
|
*
|
|
* @see Database
|
|
*/
|
|
npm.utils.addReadProp(this, `$dc`, dc, true);
|
|
|
|
/**
|
|
* @member {external:pg-pool} Database#$pool
|
|
* @readonly
|
|
* @description
|
|
* A $[pg-pool] object associated with the database object, as each {@link Database} creates its own $[pg-pool] instance.
|
|
*
|
|
* This is a hidden property, primarily for integrating type {@link Database} with third-party libraries that support
|
|
* $[pg-pool] directly. Note however, that if you pass the pool object into a library that calls `pool.end()`, you will no longer be able
|
|
* to use this {@link Database} object, and each query method will be rejecting with {@link external:Error Error} =
|
|
* `Connection pool of the database object has been destroyed.`
|
|
*
|
|
* You can also use this object to shut down the pool, by calling `$pool.end()`.
|
|
*
|
|
* For more details see $[Library de-initialization].
|
|
*
|
|
* @see
|
|
* {@link Database}
|
|
* {@link module:pg-promise~end pgp.end}
|
|
*
|
|
* @example
|
|
*
|
|
* // Shutting down the connection pool of this database object,
|
|
* // after all queries have finished in a run-though process:
|
|
*
|
|
* .then(() => {}) // processing the data
|
|
* .catch() => {}) // handling the error
|
|
* .finally(db.$pool.end); // shutting down the pool
|
|
*
|
|
*/
|
|
npm.utils.addReadProp(this, `$pool`, pool, true);
|
|
|
|
/**
|
|
* @member {function} Database.$destroy
|
|
* @readonly
|
|
* @private
|
|
* @description
|
|
* Permanently shuts down the database object.
|
|
*/
|
|
npm.utils.addReadProp(this, `$destroy`, () => {
|
|
if (!destroyed) {
|
|
if (!pool.ending) {
|
|
endMethod.call(pool);
|
|
}
|
|
DatabasePool.unregister(dbThis);
|
|
pool.removeListener(`error`, onError);
|
|
destroyed = true;
|
|
}
|
|
}, true);
|
|
|
|
DatabasePool.register(this);
|
|
|
|
extend(createContext(), this); // extending root protocol;
|
|
|
|
function createContext() {
|
|
return new ConnectionContext({cn, dc, options: config.options});
|
|
}
|
|
|
|
// Optional value-transformation helper:
|
|
function transform(value, cb, thisArg) {
|
|
return typeof cb === `function` ? value.then(data => cb.call(thisArg, data)) : value;
|
|
}
|
|
|
|
////////////////////////////////////////////////////
|
|
// Injects additional methods into an access object,
|
|
// extending the protocol's base method 'query'.
|
|
function extend(ctx, obj) {
|
|
|
|
/**
|
|
* @method Database#none
|
|
* @description
|
|
* Executes a query that expects no data to be returned. If the query returns any data,
|
|
* the method rejects.
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @returns {external:Promise<null>}
|
|
* A promise object that represents the query result:
|
|
* - When no records are returned, it resolves with `null`.
|
|
* - When any data is returned, it rejects with {@link errors.QueryResultError QueryResultError}:
|
|
* - `.message` = `No return data was expected.`
|
|
* - `.code` = {@link errors.queryResultErrorCode.notEmpty queryResultErrorCode.notEmpty}
|
|
*/
|
|
obj.none = function (query, values) {
|
|
return obj.query.call(this, query, values, queryResult.none);
|
|
};
|
|
|
|
/**
|
|
* @method Database#one
|
|
* @description
|
|
* Executes a query that expects exactly 1 row to be returned. When 0 or more than 1 rows are returned,
|
|
* the method rejects.
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @param {function} [cb]
|
|
* Value-transformation callback, to allow in-line value change.
|
|
* When specified, the returned value replaces the original one.
|
|
*
|
|
* The function takes only one parameter - value resolved from the query.
|
|
*
|
|
* @param {*} [thisArg]
|
|
* Value to use as `this` when executing the transformation callback.
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object that represents the query result:
|
|
* - When 1 row is returned, it resolves with that row as a single object.
|
|
* - When no rows are returned, it rejects with {@link errors.QueryResultError QueryResultError}:
|
|
* - `.message` = `No data returned from the query.`
|
|
* - `.code` = {@link errors.queryResultErrorCode.noData queryResultErrorCode.noData}
|
|
* - When multiple rows are returned, it rejects with {@link errors.QueryResultError QueryResultError}:
|
|
* - `.message` = `Multiple rows were not expected.`
|
|
* - `.code` = {@link errors.queryResultErrorCode.multiple queryResultErrorCode.multiple}
|
|
* - Resolves with the new value, if transformation callback `cb` was specified.
|
|
*
|
|
* @see
|
|
* {@link Database#oneOrNone oneOrNone}
|
|
*
|
|
* @example
|
|
*
|
|
* // a query with in-line value transformation:
|
|
* db.one('INSERT INTO Events VALUES($1) RETURNING id', [123], event => event.id)
|
|
* .then(data => {
|
|
* // data = a new event id, rather than an object with it
|
|
* });
|
|
*
|
|
* @example
|
|
*
|
|
* // a query with in-line value transformation + conversion:
|
|
* db.one('SELECT count(*) FROM Users', [], c => +c.count)
|
|
* .then(count => {
|
|
* // count = a proper integer value, rather than an object with a string
|
|
* });
|
|
*
|
|
*/
|
|
obj.one = function (query, values, cb, thisArg) {
|
|
const v = obj.query.call(this, query, values, queryResult.one);
|
|
return transform(v, cb, thisArg);
|
|
};
|
|
|
|
/**
|
|
* @method Database#many
|
|
* @description
|
|
* Executes a query that expects one or more rows to be returned. When the query returns no rows, the method rejects.
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object that represents the query result:
|
|
* - When 1 or more rows are returned, it resolves with the array of rows.
|
|
* - When no rows are returned, it rejects with {@link errors.QueryResultError QueryResultError}:
|
|
* - `.message` = `No data returned from the query.`
|
|
* - `.code` = {@link errors.queryResultErrorCode.noData queryResultErrorCode.noData}
|
|
*/
|
|
obj.many = function (query, values) {
|
|
return obj.query.call(this, query, values, queryResult.many);
|
|
};
|
|
|
|
/**
|
|
* @method Database#oneOrNone
|
|
* @description
|
|
* Executes a query that expects 0 or 1 rows to be returned. It resolves with the row-object when 1 row is returned,
|
|
* or with `null` when nothing is returned. When the query returns more than 1 row, the method rejects.
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @param {function} [cb]
|
|
* Value-transformation callback, to allow in-line value change.
|
|
* When specified, the returned value replaces the original one.
|
|
*
|
|
* The function takes only one parameter - value resolved from the query.
|
|
*
|
|
* @param {*} [thisArg]
|
|
* Value to use as `this` when executing the transformation callback.
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object that represents the query result:
|
|
* - When no rows are returned, it resolves with `null`.
|
|
* - When 1 row is returned, it resolves with that row as a single object.
|
|
* - When multiple rows are returned, it rejects with {@link errors.QueryResultError QueryResultError}:
|
|
* - `.message` = `Multiple rows were not expected.`
|
|
* - `.code` = {@link errors.queryResultErrorCode.multiple queryResultErrorCode.multiple}
|
|
* - Resolves with the new value, if transformation callback `cb` was specified.
|
|
*
|
|
* @see
|
|
* {@link Database#one one},
|
|
* {@link Database#none none},
|
|
* {@link Database#manyOrNone manyOrNone}
|
|
*
|
|
* @example
|
|
*
|
|
* // a query with in-line value transformation:
|
|
* db.oneOrNone('SELECT id FROM Events WHERE type = $1', ['entry'], e => e && e.id)
|
|
* .then(data => {
|
|
* // data = the event id or null (rather than object or null)
|
|
* });
|
|
*
|
|
*/
|
|
obj.oneOrNone = function (query, values, cb, thisArg) {
|
|
const v = obj.query.call(this, query, values, queryResult.one | queryResult.none);
|
|
return transform(v, cb, thisArg);
|
|
};
|
|
|
|
/**
|
|
* @method Database#manyOrNone
|
|
* @description
|
|
* Executes a query that can return any number of rows.
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @returns {external:Promise<Array>}
|
|
* A promise object that represents the query result:
|
|
* - When no rows are returned, it resolves with an empty array.
|
|
* - When 1 or more rows are returned, it resolves with the array of rows.
|
|
*
|
|
* @see
|
|
* {@link Database#any any},
|
|
* {@link Database#many many},
|
|
* {@link Database#none none}
|
|
*
|
|
*/
|
|
obj.manyOrNone = function (query, values) {
|
|
return obj.query.call(this, query, values, queryResult.many | queryResult.none);
|
|
};
|
|
|
|
/**
|
|
* @method Database#any
|
|
* @description
|
|
* Executes a query that can return any number of rows.
|
|
* This is simply a shorter alias for method {@link Database#manyOrNone manyOrNone}.
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @returns {external:Promise<Array>}
|
|
* A promise object that represents the query result:
|
|
* - When no rows are returned, it resolves with an empty array.
|
|
* - When 1 or more rows are returned, it resolves with the array of rows.
|
|
*
|
|
* @see
|
|
* {@link Database#manyOrNone manyOrNone},
|
|
* {@link Database#map map},
|
|
* {@link Database#each each}
|
|
*
|
|
*/
|
|
obj.any = function (query, values) {
|
|
return obj.query.call(this, query, values, queryResult.any);
|
|
};
|
|
|
|
/**
|
|
* @method Database#result
|
|
* @description
|
|
* Executes a query without any expectation for the return data, and resolves with the
|
|
* original $[Result] object when successful.
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @param {function} [cb]
|
|
* Value-transformation callback, to allow in-line value change.
|
|
* When specified, the returned value replaces the original one.
|
|
*
|
|
* The function takes only one parameter - value resolved from the query.
|
|
*
|
|
* @param {*} [thisArg]
|
|
* Value to use as `this` when executing the transformation callback.
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object that represents the query result:
|
|
* - resolves with the original $[Result] object (by default);
|
|
* - resolves with the new value, if transformation callback `cb` was specified.
|
|
*
|
|
* @example
|
|
*
|
|
* // use of value transformation:
|
|
* // deleting rows and returning the number of rows deleted
|
|
* db.result('DELETE FROM Events WHERE id = $1', [123], r => r.rowCount)
|
|
* .then(data => {
|
|
* // data = number of rows that were deleted
|
|
* });
|
|
*
|
|
* @example
|
|
*
|
|
* // use of value transformation:
|
|
* // getting only column details from a table
|
|
* db.result('SELECT * FROM Users LIMIT 0', null, r => r.fields)
|
|
* .then(data => {
|
|
* // data = array of column descriptors
|
|
* });
|
|
*
|
|
*/
|
|
obj.result = function (query, values, cb, thisArg) {
|
|
const v = obj.query.call(this, query, values, resultQuery);
|
|
return transform(v, cb, thisArg);
|
|
};
|
|
|
|
/**
|
|
* @method Database#multiResult
|
|
* @description
|
|
* Executes a multi-query string, without any expectation for the return data, and resolves with an array
|
|
* of the original $[Result] objects when successful.
|
|
*
|
|
* The operation is atomic, i.e. all queries are executed in a single transaction, unless there are explicit
|
|
* `BEGIN/COMMIT` commands included in the query string to divide it into multiple transactions.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Multi-query string to be executed, which can be any of the following types:
|
|
* - A non-empty string that can contain any number of queries
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @returns {external:Promise<external:Result[]>}
|
|
*
|
|
* @see {@link Database#multi multi}
|
|
*
|
|
*/
|
|
obj.multiResult = function (query, values) {
|
|
return obj.query.call(this, query, values, multiResultQuery);
|
|
};
|
|
|
|
/**
|
|
* @method Database#multi
|
|
* @description
|
|
* Executes a multi-query string, without any expectation for the return data, and resolves with an array
|
|
* of arrays of rows when successful.
|
|
*
|
|
* The operation is atomic, i.e. all queries are executed in a single transaction, unless there are explicit
|
|
* `BEGIN/COMMIT` commands included in the query string to divide it into multiple transactions.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Multi-query string to be executed, which can be any of the following types:
|
|
* - A non-empty string that can contain any number of queries
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @returns {external:Promise<Array<Array>>}
|
|
*
|
|
* @see {@link Database#multiResult multiResult}
|
|
*
|
|
* @example
|
|
*
|
|
* // Get data from 2 tables in a single request:
|
|
* const [users, products] = await db.multi('SELECT * FROM users;SELECT * FROM products');
|
|
*
|
|
*/
|
|
obj.multi = function (query, values) {
|
|
return obj.query.call(this, query, values, multiResultQuery)
|
|
.then(data => data.map(a => a.rows));
|
|
};
|
|
|
|
/**
|
|
* @method Database#stream
|
|
* @description
|
|
* Custom data streaming, with the help of $[pg-query-stream].
|
|
*
|
|
* This method doesn't work with the $[Native Bindings], and if option `pgNative`
|
|
* is set, it will reject with `Streaming doesn't work with Native Bindings.`
|
|
*
|
|
* @param {QueryStream} qs
|
|
* Stream object of type $[QueryStream].
|
|
*
|
|
* @param {Database.streamInitCB} initCB
|
|
* Stream initialization callback.
|
|
*
|
|
* It is invoked with the same `this` context as the calling method.
|
|
*
|
|
* @returns {external:Promise}
|
|
* Result of the streaming operation.
|
|
*
|
|
* Once the streaming has finished successfully, the method resolves with
|
|
* `{processed, duration}`:
|
|
* - `processed` - total number of rows processed;
|
|
* - `duration` - streaming duration, in milliseconds.
|
|
*
|
|
* Possible rejections messages:
|
|
* - `Invalid or missing stream object.`
|
|
* - `Invalid stream state.`
|
|
* - `Invalid or missing stream initialization callback.`
|
|
*/
|
|
obj.stream = function (qs, init) {
|
|
return obj.query.call(this, qs, init, streamQuery);
|
|
};
|
|
|
|
/**
|
|
* @method Database#func
|
|
* @description
|
|
* Executes a database function that returns a table, abbreviating the full syntax
|
|
* of `query('SELECT * FROM $1:alias($2:csv)', [funcName, values], qrm)`.
|
|
*
|
|
* @param {string} funcName
|
|
* Name of the function to be executed.
|
|
* When it is not same-case, or contains extended symbols, it is double-quoted, as per the `:alias` filter,
|
|
* which also supports `.`, to auto-split into a composite name.
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Parameters for the function - one value | array of values | function returning value(s).
|
|
*
|
|
* @param {queryResult} [qrm=queryResult.any] - {@link queryResult Query Result Mask}.
|
|
*
|
|
* @returns {external:Promise}
|
|
*
|
|
* A promise object as returned from method {@link Database#query query}, according to parameter `qrm`.
|
|
*
|
|
* @see
|
|
* {@link Database#query query},
|
|
* {@link Database#proc proc}
|
|
*/
|
|
obj.func = function (funcName, values, qrm) {
|
|
return obj.query.call(this, {entity: funcName, type: `func`}, values, qrm);
|
|
};
|
|
|
|
/**
|
|
* @method Database#proc
|
|
* @description
|
|
* Executes a stored procedure by name, abbreviating the full syntax of
|
|
* `oneOrNone('CALL $1:alias($2:csv)', [procName, values], cb, thisArg)`.
|
|
*
|
|
* **NOTE:** This method uses the new `CALL` syntax that requires PostgreSQL v11 or later.
|
|
*
|
|
* @param {string} procName
|
|
* Name of the stored procedure to be executed.
|
|
* When it is not same-case, or contains extended symbols, it is double-quoted, as per the `:alias` filter,
|
|
* which also supports `.`, to auto-split into a composite SQL name.
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Parameters for the procedure - one value | array of values | function returning value(s).
|
|
*
|
|
* @param {function} [cb]
|
|
* Value-transformation callback, to allow in-line value change.
|
|
* When specified, the returned value replaces the original one.
|
|
*
|
|
* The function takes only one parameter - value resolved from the query.
|
|
*
|
|
* @param {*} [thisArg]
|
|
* Value to use as `this` when executing the transformation callback.
|
|
*
|
|
* @returns {external:Promise}
|
|
* When the procedure takes output parameters, a single object is returned, with
|
|
* properties for the output values. Otherwise, the method resolves with `null`.
|
|
* And if the value-transformation callback is provided, it overrides the result.
|
|
*
|
|
* @see
|
|
* {@link Database#func func}
|
|
*/
|
|
obj.proc = function (procName, values, cb, thisArg) {
|
|
const v = obj.query.call(this, {
|
|
entity: procName,
|
|
type: `proc`
|
|
}, values, queryResult.one | queryResult.none);
|
|
return transform(v, cb, thisArg);
|
|
};
|
|
|
|
/**
|
|
* @method Database#map
|
|
* @description
|
|
* Creates a new array with the results of calling a provided function on every element in the array of rows
|
|
* resolved by method {@link Database#any any}.
|
|
*
|
|
* It is a convenience method, to reduce the following code:
|
|
*
|
|
* ```js
|
|
* db.any(query, values)
|
|
* .then(data => {
|
|
* return data.map((row, index, data) => {
|
|
* // return a new element
|
|
* });
|
|
* });
|
|
* ```
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} values
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @param {function} cb
|
|
* Function that produces an element of the new array, taking three arguments:
|
|
* - `row` - the current row object being processed in the array
|
|
* - `index` - the index of the current row being processed in the array
|
|
* - `data` - the original array of rows resolved by method {@link Database#any any}
|
|
*
|
|
* @param {*} [thisArg]
|
|
* Value to use as `this` when executing the callback.
|
|
*
|
|
* @returns {external:Promise<Array>}
|
|
* Resolves with the new array of values returned from the callback.
|
|
*
|
|
* @see
|
|
* {@link Database#any any},
|
|
* {@link Database#each each},
|
|
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map Array.map}
|
|
*
|
|
* @example
|
|
*
|
|
* db.map('SELECT id FROM Users WHERE status = $1', ['active'], row => row.id)
|
|
* .then(data => {
|
|
* // data = array of active user id-s
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* });
|
|
*
|
|
* @example
|
|
*
|
|
* db.tx(t => {
|
|
* return t.map('SELECT id FROM Users WHERE status = $1', ['active'], row => {
|
|
* return t.none('UPDATE Events SET checked = $1 WHERE userId = $2', [true, row.id]);
|
|
* }).then(t.batch);
|
|
* })
|
|
* .then(data => {
|
|
* // success
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* });
|
|
*
|
|
* @example
|
|
*
|
|
* // Build a list of active users, each with the list of user events:
|
|
* db.task(t => {
|
|
* return t.map('SELECT id FROM Users WHERE status = $1', ['active'], user => {
|
|
* return t.any('SELECT * FROM Events WHERE userId = $1', user.id)
|
|
* .then(events=> {
|
|
* user.events = events;
|
|
* return user;
|
|
* });
|
|
* }).then(t.batch);
|
|
* })
|
|
* .then(data => {
|
|
* // success
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* });
|
|
*
|
|
*/
|
|
obj.map = function (query, values, cb, thisArg) {
|
|
return obj.any.call(this, query, values)
|
|
.then(data => data.map(cb, thisArg));
|
|
};
|
|
|
|
/**
|
|
* @method Database#each
|
|
* @description
|
|
* Executes a provided function once per array element, for an array of rows resolved by method {@link Database#any any}.
|
|
*
|
|
* It is a convenience method to reduce the following code:
|
|
*
|
|
* ```js
|
|
* db.any(query, values)
|
|
* .then(data => {
|
|
* data.forEach((row, index, data) => {
|
|
* // process the row
|
|
* });
|
|
* return data;
|
|
* });
|
|
* ```
|
|
*
|
|
* When receiving a multi-query result, only the last result is processed, ignoring the rest.
|
|
*
|
|
* @param {string|function|object} query
|
|
* Query to be executed, which can be any of the following types:
|
|
* - A non-empty query string
|
|
* - A function that returns a query string or another function, i.e. recursive resolution
|
|
* is supported, passing in `values` as `this`, and as the first parameter.
|
|
* - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
|
|
* - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
|
|
* - {@link QueryFile} object
|
|
*
|
|
* @param {array|value|function} [values]
|
|
* Query formatting parameter(s), or a function that returns it.
|
|
*
|
|
* When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
|
|
* - a single value - to replace all `$1` occurrences
|
|
* - an array of values - to replace all `$1`, `$2`, ... variables
|
|
* - an object - to apply $[Named Parameters] formatting
|
|
*
|
|
* When `query` is a Prepared Statement or a Parameterized Query (or their class types),
|
|
* and `values` is not `null` or `undefined`, it is automatically set within such object,
|
|
* as an override for its internal `values`.
|
|
*
|
|
* @param {function} cb
|
|
* Function to execute for each row, taking three arguments:
|
|
* - `row` - the current row object being processed in the array
|
|
* - `index` - the index of the current row being processed in the array
|
|
* - `data` - the array of rows resolved by method {@link Database#any any}
|
|
*
|
|
* @param {*} [thisArg]
|
|
* Value to use as `this` when executing the callback.
|
|
*
|
|
* @returns {external:Promise<Array<Object>>}
|
|
* Resolves with the original array of rows.
|
|
*
|
|
* @see
|
|
* {@link Database#any any},
|
|
* {@link Database#map map},
|
|
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach Array.forEach}
|
|
*
|
|
* @example
|
|
*
|
|
* db.each('SELECT id, code, name FROM Events', [], row => {
|
|
* row.code = parseInt(row.code);
|
|
* })
|
|
* .then(data => {
|
|
* // data = array of events, with 'code' converted into integer
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* });
|
|
*
|
|
*/
|
|
obj.each = function (query, values, cb, thisArg) {
|
|
return obj.any.call(this, query, values)
|
|
.then(data => {
|
|
data.forEach(cb, thisArg);
|
|
return data;
|
|
});
|
|
};
|
|
|
|
/**
|
|
* @method Database#task
|
|
* @description
|
|
* Executes a callback function with automatically managed connection.
|
|
*
|
|
* When invoked on the root {@link Database} object, the method allocates the connection from the pool,
|
|
* executes the callback, and once finished - releases the connection back to the pool.
|
|
* However, when invoked inside another task or transaction, the method reuses the parent connection.
|
|
*
|
|
* This method should be used whenever executing more than one query at once, so the allocated connection
|
|
* is reused between all queries, and released only after the task has finished (see $[Chaining Queries]).
|
|
*
|
|
* The callback function is called with one parameter - database protocol (same as `this`), extended with methods
|
|
* {@link Task#batch batch}, {@link Task#page page}, {@link Task#sequence sequence}, plus property {@link Task#ctx ctx} -
|
|
* the task context object. See class {@link Task} for more details.
|
|
*
|
|
* @param {string|number|Object} [options]
|
|
* This parameter is optional, and presumed skipped when the first parameter is a function (`cb` parameter).
|
|
*
|
|
* When it is of type `string` or `number`, it is assumed to be option `tag` passed in directly. Otherwise,
|
|
* it is expected to be an object with options as listed below.
|
|
*
|
|
* @param {} [options.tag]
|
|
* Traceable context for the task (see $[tags]).
|
|
*
|
|
* @param {function} cb
|
|
* Task callback function, to return the result that will determine either success or failure for the operation.
|
|
*
|
|
* The function can be either the first of the second parameter passed into the method.
|
|
*
|
|
* It also can be an ES7 `async` function.
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object with the result from the callback function.
|
|
*
|
|
* @see
|
|
* {@link Task},
|
|
* {@link Database#taskIf taskIf},
|
|
* {@link Database#tx tx},
|
|
* $[tags],
|
|
* $[Chaining Queries]
|
|
*
|
|
* @example
|
|
*
|
|
* db.task('my-task', t => {
|
|
* // t.ctx = task context object
|
|
*
|
|
* return t.one('SELECT id FROM Users WHERE name = $1', 'John')
|
|
* .then(user => {
|
|
* return t.any('SELECT * FROM Events WHERE userId = $1', user.id);
|
|
* });
|
|
* })
|
|
* .then(data => {
|
|
* // success
|
|
* // data = as returned from the task's callback
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* });
|
|
*
|
|
* @example
|
|
*
|
|
* // using an ES7 syntax for the callback:
|
|
* db.task('my-task', async t {
|
|
* // t.ctx = task context object
|
|
*
|
|
* const user = await t.one('SELECT id FROM Users WHERE name = $1', 'John');
|
|
* return t.any('SELECT * FROM Events WHERE userId = $1', user.id);
|
|
* })
|
|
* .then(data => {
|
|
* // success
|
|
* // data = as returned from the task's callback
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* });
|
|
*
|
|
*/
|
|
obj.task = function () {
|
|
const args = npm.pubUtils.taskArgs(arguments);
|
|
assertOptions(args.options, [`tag`]);
|
|
return taskProcessor.call(this, args, false);
|
|
};
|
|
|
|
/**
|
|
* @method Database#taskIf
|
|
* @description
|
|
* Executes a conditional task that results in an actual new {@link Database#task task}, if either condition is met or
|
|
* when it is necessary (on the top level), or else it reuses the current connection context.
|
|
*
|
|
* The default condition is `not in task or transaction`, to start a task only if currently not inside another task or transaction,
|
|
* which is the same as calling the following:
|
|
*
|
|
* ```js
|
|
* db.taskIf({cnd: t => !t.ctx}, cb => {})
|
|
* ```
|
|
*
|
|
* It can be useful, if you want to simplify/reduce the task + log events footprint, by creating new tasks only when necessary.
|
|
*
|
|
* @param {string|number|Object} [options]
|
|
* This parameter is optional, and presumed skipped when the first parameter is a function (`cb` parameter).
|
|
*
|
|
* When it is of type `string` or `number`, it is assumed to be option `tag` passed in directly. Otherwise,
|
|
* it is expected to be an object with options as listed below.
|
|
*
|
|
* @param {} [options.tag]
|
|
* Traceable context for the task/transaction (see $[tags]).
|
|
*
|
|
* @param {boolean|function} [options.cnd]
|
|
* Condition for creating a ({@link Database#task task}), if it is met.
|
|
* It can be either a simple boolean, or a callback function that takes the task context as `this` and as the first parameter.
|
|
*
|
|
* Default condition (when it is not specified):
|
|
*
|
|
* ```js
|
|
* {cnd: t => !t.ctx}
|
|
* ```
|
|
*
|
|
* @param {function} cb
|
|
* Task callback function, to return the result that will determine either success or failure for the operation.
|
|
*
|
|
* The function can be either the first or the second parameter passed into the method.
|
|
*
|
|
* It also can be an ES7 `async` function.
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object with the result from the callback function.
|
|
*
|
|
* @see
|
|
* {@link Task},
|
|
* {@link Database#task Database.task},
|
|
* {@link Database#tx Database.tx},
|
|
* {@link Database#txIf Database.txIf},
|
|
* {@link TaskContext}
|
|
*
|
|
*/
|
|
obj.taskIf = function () {
|
|
const args = npm.pubUtils.taskArgs(arguments);
|
|
assertOptions(args.options, [`tag`, `cnd`]);
|
|
try {
|
|
let cnd = args.options.cnd;
|
|
if (`cnd` in args.options) {
|
|
cnd = typeof cnd === `function` ? cnd.call(obj, obj) : !!cnd;
|
|
} else {
|
|
cnd = !obj.ctx; // create task, if it is the top level
|
|
}
|
|
// reusable only if condition fails, and not top-level:
|
|
args.options.reusable = !cnd && !!obj.ctx;
|
|
} catch (e) {
|
|
return $p.reject(e);
|
|
}
|
|
return taskProcessor.call(this, args, false);
|
|
};
|
|
|
|
/**
|
|
* @method Database#tx
|
|
* @description
|
|
* Executes a callback function as a transaction, with automatically managed connection.
|
|
*
|
|
* When invoked on the root {@link Database} object, the method allocates the connection from the pool,
|
|
* executes the callback, and once finished - releases the connection back to the pool.
|
|
* However, when invoked inside another task or transaction, the method reuses the parent connection.
|
|
*
|
|
* A transaction wraps a regular {@link Database#task task} into additional queries:
|
|
* - it executes `BEGIN` just before invoking the callback function
|
|
* - it executes `COMMIT`, if the callback didn't throw any error or return a rejected promise
|
|
* - it executes `ROLLBACK`, if the callback did throw an error or return a rejected promise
|
|
* - it executes corresponding `SAVEPOINT` commands when the method is called recursively.
|
|
*
|
|
* The callback function is called with one parameter - database protocol (same as `this`), extended with methods
|
|
* {@link Task#batch batch}, {@link Task#page page}, {@link Task#sequence sequence}, plus property {@link Task#ctx ctx} -
|
|
* the transaction context object. See class {@link Task} for more details.
|
|
*
|
|
* Note that transactions should be chosen over tasks only where necessary, because unlike regular tasks,
|
|
* transactions are blocking operations.
|
|
*
|
|
* @param {string|number|Object} [options]
|
|
* This parameter is optional, and presumed skipped when the first parameter is a function (`cb` parameter).
|
|
*
|
|
* When it is of type `string` or `number`, it is assumed to be option `tag` passed in directly. Otherwise,
|
|
* it is expected to be an object with options as listed below.
|
|
*
|
|
* @param {} [options.tag]
|
|
* Traceable context for the transaction (see $[tags]).
|
|
*
|
|
* @param {txMode.TransactionMode} [options.mode]
|
|
* Transaction Configuration Mode - extends the transaction-opening command with additional configuration.
|
|
*
|
|
* @param {function} cb
|
|
* Transaction callback function, to return the result that will determine either success or failure for the operation.
|
|
*
|
|
* The function can be either the first of the second parameter passed into the method.
|
|
*
|
|
* It also can be an ES7 `async` function.
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object with the result from the callback function.
|
|
*
|
|
* @see
|
|
* {@link Task},
|
|
* {@link Database#task Database.task},
|
|
* {@link Database#taskIf Database.taskIf},
|
|
* {@link TaskContext},
|
|
* $[tags],
|
|
* $[Chaining Queries]
|
|
*
|
|
* @example
|
|
*
|
|
* db.tx('my-transaction', t => {
|
|
* // t.ctx = transaction context object
|
|
*
|
|
* return t.one('INSERT INTO Users(name, age) VALUES($1, $2) RETURNING id', ['Mike', 25])
|
|
* .then(user => {
|
|
* return t.batch([
|
|
* t.none('INSERT INTO Events(userId, name) VALUES($1, $2)', [user.id, 'created']),
|
|
* t.none('INSERT INTO Events(userId, name) VALUES($1, $2)', [user.id, 'login'])
|
|
* ]);
|
|
* });
|
|
* })
|
|
* .then(data => {
|
|
* // success
|
|
* // data = as returned from the transaction's callback
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* });
|
|
*
|
|
* @example
|
|
*
|
|
* // using an ES7 syntax for the callback:
|
|
* db.tx('my-transaction', async t {
|
|
* // t.ctx = transaction context object
|
|
*
|
|
* const user = await t.one('INSERT INTO Users(name, age) VALUES($1, $2) RETURNING id', ['Mike', 25]);
|
|
* return t.none('INSERT INTO Events(userId, name) VALUES($1, $2)', [user.id, 'created']);
|
|
* })
|
|
* .then(data => {
|
|
* // success
|
|
* // data = as returned from the transaction's callback
|
|
* })
|
|
* .catch(error => {
|
|
* // error
|
|
* });
|
|
*
|
|
*/
|
|
obj.tx = function () {
|
|
const args = npm.pubUtils.taskArgs(arguments);
|
|
assertOptions(args.options, [`tag`, `mode`]);
|
|
return taskProcessor.call(this, args, true);
|
|
};
|
|
|
|
/**
|
|
* @method Database#txIf
|
|
* @description
|
|
* Executes a conditional transaction that results in an actual transaction ({@link Database#tx tx}), if the condition is met,
|
|
* or else it executes a regular {@link Database#task task}.
|
|
*
|
|
* The default condition is `not in transaction`, to start a transaction only if currently not in transaction,
|
|
* or else start a task, which is the same as calling the following:
|
|
*
|
|
* ```js
|
|
* db.txIf({cnd: t => !t.ctx || !t.ctx.inTransaction}, cb => {})
|
|
* ```
|
|
*
|
|
* It is useful when you want to avoid $[Nested Transactions] - savepoints.
|
|
*
|
|
* @param {string|number|Object} [options]
|
|
* This parameter is optional, and presumed skipped when the first parameter is a function (`cb` parameter).
|
|
*
|
|
* When it is of type `string` or `number`, it is assumed to be option `tag` passed in directly. Otherwise,
|
|
* it is expected to be an object with options as listed below.
|
|
*
|
|
* @param {} [options.tag]
|
|
* Traceable context for the task/transaction (see $[tags]).
|
|
*
|
|
* @param {txMode.TransactionMode} [options.mode]
|
|
* Transaction Configuration Mode - extends the transaction-opening command with additional configuration.
|
|
*
|
|
* @param {boolean|function} [options.cnd]
|
|
* Condition for opening a transaction ({@link Database#tx tx}), if it is met, or a {@link Database#task task} when the condition is not met.
|
|
* It can be either a simple boolean, or a callback function that takes the task/tx context as `this` and as the first parameter.
|
|
*
|
|
* Default condition (when it is not specified):
|
|
*
|
|
* ```js
|
|
* {cnd: t => !t.ctx || !t.ctx.inTransaction}
|
|
* ```
|
|
*
|
|
* @param {boolean|function} [options.reusable=false]
|
|
* When `cnd` is/returns false, reuse context of the current task/transaction, if one exists.
|
|
* It can be either a simple boolean, or a callback function that takes the task/tx context as `this`
|
|
* and as the first parameter.
|
|
*
|
|
* By default, when `cnd` is/returns false, the method creates a new task. This option tells
|
|
* the method to reuse the current task/transaction context, and not create a new task.
|
|
*
|
|
* This option is ignored when executing against the top level of the protocol, because on
|
|
* that level, if no transaction is suddenly needed, a new task becomes necessary.
|
|
*
|
|
* @param {function} cb
|
|
* Transaction/task callback function, to return the result that will determine either
|
|
* success or failure for the operation.
|
|
*
|
|
* The function can be either the first or the second parameter passed into the method.
|
|
*
|
|
* It also can be an ES7 `async` function.
|
|
*
|
|
* @returns {external:Promise}
|
|
* A promise object with the result from the callback function.
|
|
*
|
|
* @see
|
|
* {@link Task},
|
|
* {@link Database#task Database.task},
|
|
* {@link Database#taskIf Database.taskIf},
|
|
* {@link Database#tx Database.tx},
|
|
* {@link TaskContext}
|
|
*
|
|
*/
|
|
obj.txIf = function () {
|
|
const args = npm.pubUtils.taskArgs(arguments);
|
|
assertOptions(args.options, [`tag`, `mode`, `cnd`, `reusable`]);
|
|
try {
|
|
let cnd;
|
|
if (`cnd` in args.options) {
|
|
cnd = args.options.cnd;
|
|
cnd = typeof cnd === `function` ? cnd.call(obj, obj) : !!cnd;
|
|
} else {
|
|
cnd = !obj.ctx || !obj.ctx.inTransaction;
|
|
}
|
|
args.options.cnd = cnd;
|
|
const reusable = args.options.reusable;
|
|
args.options.reusable = !cnd && obj.ctx && typeof reusable === `function` ? reusable.call(obj, obj) : !!reusable;
|
|
} catch (e) {
|
|
return $p.reject(e);
|
|
}
|
|
return taskProcessor.call(this, args, args.options.cnd);
|
|
};
|
|
|
|
// Task method;
|
|
// Resolves with result from the callback function;
|
|
function taskProcessor(params, isTX) {
|
|
|
|
if (typeof params.cb !== `function`) {
|
|
return $p.reject(new TypeError(`Callback function is required.`));
|
|
}
|
|
|
|
if (params.options.reusable) {
|
|
return config.$npm.task.callback(obj.ctx, obj, params.cb, config);
|
|
}
|
|
|
|
const taskCtx = ctx.clone(); // task context object;
|
|
if (isTX) {
|
|
taskCtx.txLevel = taskCtx.txLevel >= 0 ? (taskCtx.txLevel + 1) : 0;
|
|
}
|
|
taskCtx.inTransaction = taskCtx.txLevel >= 0;
|
|
taskCtx.level = taskCtx.level >= 0 ? (taskCtx.level + 1) : 0;
|
|
taskCtx.cb = params.cb; // callback function;
|
|
taskCtx.mode = params.options.mode; // transaction mode;
|
|
if (this !== obj) {
|
|
taskCtx.context = this; // calling context object;
|
|
}
|
|
|
|
const tsk = new config.$npm.task.Task(taskCtx, params.options.tag, isTX, config);
|
|
taskCtx.taskCtx = tsk.ctx;
|
|
extend(taskCtx, tsk);
|
|
|
|
if (taskCtx.db) {
|
|
// reuse existing connection;
|
|
npm.utils.addReadProp(tsk.ctx, `useCount`, taskCtx.db.useCount);
|
|
addServerVersion(tsk.ctx, taskCtx.db.client);
|
|
return config.$npm.task.execute(taskCtx, tsk, isTX, config);
|
|
}
|
|
|
|
// connection required;
|
|
return config.$npm.connect.pool(taskCtx, dbThis)
|
|
.then(db => {
|
|
taskCtx.connect(db);
|
|
npm.utils.addReadProp(tsk.ctx, `useCount`, db.useCount);
|
|
addServerVersion(tsk.ctx, db.client);
|
|
return config.$npm.task.execute(taskCtx, tsk, isTX, config);
|
|
})
|
|
.then(data => {
|
|
taskCtx.disconnect();
|
|
return data;
|
|
})
|
|
.catch(error => {
|
|
taskCtx.disconnect();
|
|
return $p.reject(error);
|
|
});
|
|
}
|
|
|
|
function addServerVersion(target, client) {
|
|
// Exclude else-case from coverage, because it can only occur with Native Bindings.
|
|
// istanbul ignore else
|
|
if (client.serverVersion) {
|
|
npm.utils.addReadProp(target, `serverVersion`, client.serverVersion);
|
|
}
|
|
}
|
|
|
|
// lock all default properties to read-only,
|
|
// to prevent override by the client.
|
|
npm.utils.lock(obj, false, ctx.options);
|
|
|
|
// extend the protocol;
|
|
Events.extend(ctx.options, obj, ctx.dc);
|
|
|
|
// freeze the protocol permanently;
|
|
npm.utils.lock(obj, true, ctx.options);
|
|
}
|
|
|
|
}
|
|
|
|
// this event only happens when the connection is lost physically,
|
|
// which cannot be tested automatically; removing from coverage:
|
|
// istanbul ignore next
|
|
function onError(err) {
|
|
// this client was never seen by pg-promise, which
|
|
// can happen if it failed to initialize
|
|
if (!err.client.$ctx) {
|
|
return;
|
|
}
|
|
const ctx = err.client.$ctx;
|
|
Events.error(ctx.options, err, {
|
|
cn: npm.utils.getSafeConnection(ctx.cn),
|
|
dc: ctx.dc
|
|
});
|
|
}
|
|
|
|
module.exports = config => {
|
|
const npmLocal = config.$npm;
|
|
npmLocal.connect = npmLocal.connect || npm.connect(config);
|
|
npmLocal.query = npmLocal.query || npm.query(config);
|
|
npmLocal.task = npmLocal.task || npm.task(config);
|
|
return Database;
|
|
};
|
|
|
|
/**
|
|
* @callback Database.streamInitCB
|
|
* @description
|
|
* Stream initialization callback, used by {@link Database#stream Database.stream}.
|
|
*
|
|
* @param {external:Stream} stream
|
|
* Stream object to initialize streaming.
|
|
*
|
|
* @example
|
|
* const QueryStream = require('pg-query-stream');
|
|
* const JSONStream = require('JSONStream');
|
|
*
|
|
* // you can also use pgp.as.format(query, values, options)
|
|
* // to format queries properly, via pg-promise;
|
|
* const qs = new QueryStream('SELECT * FROM users');
|
|
*
|
|
* db.stream(qs, stream => {
|
|
* // initiate streaming into the console:
|
|
* stream.pipe(JSONStream.stringify()).pipe(process.stdout);
|
|
* })
|
|
* .then(data => {
|
|
* console.log('Total rows processed:', data.processed,
|
|
* 'Duration in milliseconds:', data.duration);
|
|
* })
|
|
* .catch(error => {
|
|
* // error;
|
|
* });
|
|
*/
|
|
|
|
/**
|
|
* @external Stream
|
|
* @see https://nodejs.org/api/stream.html
|
|
*/
|
|
|
|
/**
|
|
* @external pg-pool
|
|
* @alias pg-pool
|
|
* @see https://github.com/brianc/node-pg-pool
|
|
*/
|
|
|
|
/**
|
|
* @external Result
|
|
* @see https://node-postgres.com/api/result
|
|
*/
|
|
|