DbClientPg

DbClientPg is a thin wrapper above the native PostgreSQL client designed for using in doix Jobs.

Instances are created by DbPoolPg objects, part of Application. Application developers should never instantiate those objects directly.

Properties

Name	Description
uuid	The unique ID of this client, mainly for logging purposes
raw	The pg.Client instance used by this wrapper
model	a DbModel representing the database structure

Events

Name	Payload	Description
start	{sql, params}	emitted before executing any database query.
error	the error caught	emitted when an error occurs while executing a query
finish		emitted right after the query execution is terminated (one way or another)

Static functions

DbClientPg.normalizeSQL (sql)

Returns the sql string with all comments stripped off and ?s replaced with $1, $2 and so on.

? occurring right after ::jsonb are not replaced (to let use JSONB operators).

Methods

do (sql, params = [])

This asynchronous method executes the given sql with the given params list. Basically it forwards the call to the native client.query returning the same result or throwing the same error.

getScalar (sql, params = [], options = {})

This asynchronous method executes the given sql with the given params list and returns the value of the first (and, normally, the unique) data field of the first record fetched as a corresponding javaScript value (Number, String, Date etc.) For json, jsonb and some other data types the result may be plain Object or Array, but, unlike for getObject and getArray it still means an atomic field value, not a record nor a record set.

For a an empty selection, options.notFound (undefined by default) is returned or thrown (if it is an Error instance).

All records but the first one are discarded. The cursor is closed immediately.

Options

Name	Type	Description
notFound	any	This value is returned or thrown if no record were selected at all.

getObject (sql, params = [], options = {})

This asynchronous method executes the given sql with the given params list and returns the first record fetched as a plain Object or an Array of values.

For a an empty selection, options.notFound ({} by default) is returned or thrown (if it is an Error instance).

All records but the first one are discarded. The cursor is closed immediately.

Options

Name	Type	Description
notFound	any	This value is returned or thrown if no record were selected at all.
rowMode		Same as for getArray, but only have sense for internal use

getArray (sql, params = [], options = {})

This asynchronous method executes the given sql with the given params list and returns the limited portion of the resulting record set as an Array.

The returned value has an extra property [Symbol.for ('columns')]: the array of result column definitions in form of {name, type} objects.

Options

Name	Type	Description
limit	Number	If set, the LIMIT clause is appended to sql (which must not have one)
offset	Number	If set, the OFFSET clause is appended to sql (which must not have one)
maxRows	Number	The maximum rows to be physically fetched, limit (if set) or 1000 by default.
rowMode	undefined, 'array' or 'scalar'	If 'array', the result is the Array of column values, otherwise plain Object (of key-value pairs). If 'scalar', record objects will be replaced by values of the 1st (and, normally, unique) column selected.
isPartial	Boolean	If true, the (sql, params) result may be effectively larger than maxRows: only portion of it will be fetched. By default (and for any isPartial value but true), large result set will cause an Error. This option is reserved for internal use.

getStream (sql, params = [], options = {})

This asynchronous method executes the given sql with the given params list and returns the resulting record set as a Readable stream.

Options

Name	Type	Description
rowMode	undefined or 'array'	If 'array', records are Arrays of column values, otherwise plain Objects (of key-value pairs). Unlike for getArray, 'scalar' option is not supported.