pg-promise v10
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);
Parameters:
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). |
noLocking |
boolean
|
<optional>
|
false
|
Prevents protocol locking.
By default, the library locks much of its protocol to read-only access, as a fool-proof mechanism.
Specifically for the extend event this serves as a protection against overriding existing
properties or trying to set them at the wrong time.
If this provision gets in the way of using a mock-up framework for your tests, you can force
the library to deactivate most of the locks by setting noLocking = true within the options.
This option is dynamic (can be set before or after initialization). However, changing it after the library's
initialization will not affect Database objects that have already been created. |
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:
-
- Source:
- See:
-
- end,
as,
errors,
helpers,
minify,
ParameterizedQuery,
PreparedStatement,
pg,
QueryFile,
queryResult,
spex,
txMode,
utils
Members
(inner, readonly) as :formatting
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:
- 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
Type:
- Source:
- See:
-
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, readonly) ParameterizedQuery :ParameterizedQuery
ParameterizedQuery class.
Available as pgp.ParameterizedQuery
, before and after initializing the library.
Type:
- Source:
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) 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) queryResult :queryResult
Query Result Mask enumerator.
Available as pgp.queryResult
, before and after initializing the library.
Type:
- Source:
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: