pg-promise v11.10

All documentation here is for the latest official release only.

Initialization Options

Below is the complete list of Initialization Options for the library that can be passed in during the library's initialization:

const initOptions = {/* options as documented below */};

const pgp = require('pg-promise')(initOptions);
Properties:
Name Type Attributes Description
options Object <optional>

Library Initialization Options.

Properties
Name Type Attributes Default Description
pgFormatting boolean <optional>
 false

Redirects all query formatting to the pg driver.

By default (false), the library uses its own advanced query-formatting engine. If you set this option to a truthy value, query formatting will be done entirely by the pg driver, which means you won't be able to use any of the feature-rich query formatting that this library implements, restricting yourself to the very basic $1, $2,... syntax.

This option is dynamic (can be set before or after initialization).
pgNative boolean <optional>
 false

Use Native Bindings. Library pg-native must be included and installed independently, or else there will be an error thrown: Error = Failed to initialize Native Bindings.

This is a static option (can only be set prior to initialization).
promiseLib object | function <optional>
 Promise

Overrides the default (ES6 Promise) promise library for its internal use.

Example below sets to use Bluebird - the best and recommended promise library. It is the fastest one, and supports Long Stack Traces, essential for debugging promises.

const Promise = require('bluebird');
const initOptions = {
    promiseLib: Promise
};
const pgp = require('pg-promise')(initOptions);

All existing promise libraries are supported. The ones with recognizable signature are used automatically, while the rest can be configured via the Promise Adapter.

This is a static option (can only be set prior to initialization).
capSQL boolean <optional>
 false

Capitalizes any SQL generated by the library.

By default, all internal SQL within the library is generated using the low case. If, however, you want all SQL to be capitalized instead, set capSQL = true.

It is purely a cosmetic feature.

This option is dynamic (can be set before or after initialization).
schema string | Array.<string> | null | undefined | function <optional>

Forces change of the default database schema(s) for every fresh connection, i.e. the library will execute SET search_path TO schema_1, schema_2, ... in the background whenever a fresh physical connection is allocated.

Normally, one changes the default schema(s) by changing the database or the role, but sometimes you may want to switch the default schema(s) without persisting the change, and then use this option.

It can be a string, an array of strings, or a callback function that takes dc (database context) as the only parameter (and as this), and returns schema(s) according to the database context. A callback function can also return nothing (undefined or null), if no schema change needed for the specified database context.

The order of schema names matters, so if a table name exists in more than one schema, its default access resolves to the table from the first such schema on the list.

This option is dynamic (can be set before or after initialization).
noWarnings boolean <optional>
 false

Disables all diagnostic warnings in the library (it is ill-advised).

This option is dynamic (can be set before or after initialization).
connect function <optional>

Global event connect handler.

This option is dynamic (can be set before or after initialization).
disconnect function <optional>

Global event disconnect handler.

This option is dynamic (can be set before or after initialization).
query function <optional>

Global event query handler.

This option is dynamic (can be set before or after initialization).
receive function <optional>

Global event receive handler.

This option is dynamic (can be set before or after initialization).
task function <optional>

Global event task handler.

This option is dynamic (can be set before or after initialization).
transact function <optional>

Global event transact handler.

This option is dynamic (can be set before or after initialization).
error function <optional>

Global event error handler.

This option is dynamic (can be set before or after initialization).
extend function <optional>

Global event extend handler.

This option is dynamic (can be set before or after initialization).
Author:
  • Vitaly Tomilov
Source:
See:

Members

(inner, readonly) ParameterizedQuery :ParameterizedQuery

ParameterizedQuery class.

Available as pgp.ParameterizedQuery, before and after initializing the library.

Type:
Source:

(inner, readonly) PreparedStatement :PreparedStatement

PreparedStatement class.

Available as pgp.PreparedStatement, before and after initializing the library.

Type:
Source:

(inner, readonly) PromiseAdapter :PromiseAdapter

PromiseAdapter class.

Available as pgp.PromiseAdapter, before and after initializing the library.

Type:
Source:

(inner, readonly) QueryFile :QueryFile

QueryFile class.

Available as pgp.QueryFile, before and after initializing the library.

Type:
Source:

(inner, readonly) as :formatting

Namespace for all query-formatting functions.

Available as pgp.as, before and after initializing the library.

Type:
Source:
See:

(inner, readonly) end :function

Shuts down all connection pools created in the process, so it can terminate without delay. It is available as pgp.end, after initializing the library.

All Database objects created previously can no longer be used, and their query methods will be rejecting with Error = Connection pool of the database object has been destroyed.

And if you want to shut down only a specific connection pool, you do so via the Database object that owns the pool: db.$pool.end() (see Database.$pool).

For more details see Library de-initialization.

Type:
  • function
Source:

(inner, readonly) errors :errors

errors - namespace for all error types.

Available as pgp.errors, before and after initializing the library.

Type:
Source:

(inner, readonly) helpers :helpers

Namespace for all query-formatting helper functions.

Available as pgp.helpers, after initializing the library.

Type:
Source:
See:

(inner, readonly) minify :external:pg-minify

Instance of the pg-minify library used internally to minify SQL scripts.

Available as pgp.minify, before and after initializing the library.

Type:
Source:

(inner) pg :external:PG

Instance of the pg library that's being used, depending on initialization option pgNative:

  • regular pg module instance, without option pgNative, or equal to false (default)
  • pg module instance with Native Bindings, if option pgNative was set.

Available as pgp.pg, after initializing the library.

Type:
Source:

(inner, readonly) queryResult :queryResult

Query Result Mask enumerator.

Available as pgp.queryResult, before and after initializing the library.

Type:
Source:

(inner, readonly) spex :external:spex

Initialized instance of the spex module, used by the library within tasks and transactions.

Available as pgp.spex, after initializing the library.

Type:
Source:
See:

(inner, readonly) txMode :txMode

Transaction Mode namespace.

Available as pgp.txMode, before and after initializing the library.

Type:
Source:

(inner, readonly) utils :utils

utils - namespace for utility functions.

Available as pgp.utils, before and after initializing the library.

Type:
Source: