PreparedStatement

new PreparedStatement(name, text, valuesopt) → {PreparedStatement}

Alternative Syntax: PreparedStatement({name, text, values, ...}) ⇒ PreparedStatement

Constructs a new Prepared Statement object.

The alternative syntax supports advanced properties binary, rowMode and rows, which are passed into pg, but not used by the class.

All properties can also be set after the object's construction.

This type extends the basic {name, text, values} object, by replacing it, i.e. when the basic object is used with a query method, a new PreparedStatement object is created implicitly in its place.

The type can be used in place of the query parameter, with any query method directly. And it never throws any error, leaving it for query methods to reject with PreparedStatementError.

The type is available from the library's root: pgp.PreparedStatement.

Parameters:
Name Type Attributes Description
name string

An arbitrary name given to this particular prepared statement. It must be unique within a single session and is subsequently used to execute or deallocate a previously prepared statement.
text string | QueryFile

A non-empty query string or a QueryFile object.

Only the basic variables ($1, $2, etc) can be used in the query, because Prepared Statements are formatted by the database server.
values array <optional>

Query formatting values. When it is not an Array and not null/undefined, it is automatically wrapped into an array.
Source:
See:
Returns:
Type
PreparedStatement
Examples
const PS = require('pg-promise').PreparedStatement;

// Creating a complete Prepared Statement with parameters:
const findUser = new PS('find-user', 'SELECT * FROM Users WHERE id = $1', [123]);

db.one(findUser)
    .then(user => {
        // user found;
    })
    .catch(error => {
        // error;
    });
const PS = require('pg-promise').PreparedStatement;

// Creating a reusable Prepared Statement without values:
const addUser = new PS('add-user', 'INSERT INTO Users(name, age) VALUES($1, $2)');

// setting values explicitly:
addUser.values = ['John', 30];

db.none(addUser)
    .then(() => {
        // user added;
    })
    .catch(error => {
        // error;
    });

// setting values implicitly, by passing them into the query method:
db.none(addUser, ['Mike', 25])
    .then(() => {
        // user added;
    })
    .catch(error => {
        // error;
    });

Members

binary :boolean

Activates binary result mode. The default is the text mode.

Type:
  • boolean
Default Value:
  • undefined
Source:
See:

error :errors.PreparedStatementError

When in an error state, it is set to a PreparedStatementError object. Otherwise, it is undefined.

This property is primarily for internal use by the library.

Type:
Default Value:
  • undefined
Source:

name :string

An arbitrary name given to this particular prepared statement. It must be unique within a single session and is subsequently used to execute or deallocate a previously prepared statement.

Type:
  • string
Source:

rowMode :string

Changes the way data arrives to the client, with only one value supported by pg:

  • rowMode = 'array' will make all data rows arrive as arrays of values. By default, rows arrive as objects.
Type:
  • string
Default Value:
  • undefined
Source:

rows :number

Number of rows to return at a time from a Prepared Statement's portal. The default is 0, which means that all rows must be returned at once.

Type:
  • number
Source:

text :string|QueryFile

A non-empty query string or a QueryFile object.

Changing this property for the same name will have no effect, because queries for Prepared Statements are cached, with name being the cache key.

Type:
Source:

values :array

Query formatting parameters, depending on the type:

  • null / undefined means the query has no formatting parameters
  • Array - it is an array of formatting parameters
  • None of the above, means it is a single formatting value, which is then automatically wrapped into an array
Type:
  • array
Source:

Methods

parse() → {Object|errors.PreparedStatementError}

Parses the current object and returns a simple {name, text, values}, if successful, or else it returns a PreparedStatementError object.

This method is primarily for internal use by the library.

Source:
Returns:
Type
Object | errors.PreparedStatementError

toString(levelopt) → {string}

Creates a well-formatted multi-line string that represents the object's current state.

It is called automatically when writing the object into the console.

Parameters:
Name Type Attributes Default Description
level number <optional>
 0

Nested output level, to provide visual offset.
Source:
Returns:
Type
string