client.query()

Run an arbitrary query.

Syntax

client.query(
    query: string | Statement,
    values?: any[],
    options?: QueryOptions
): Promise<QueryResult>;

client.query(
    query: string | Statement, 
    arg?: {
        values?: any[];
    } & QueryOptions
): Promise<QueryResult>;

client.query(
    arg: {
        query: string | Statement;
        values?: any[];
    } & QueryOptions
): Promise<QueryResult>;

type Statement = 
    | SelectStatement 
    | InsertStatement 
    | UpsertStatement 
    | UpdateStatement 
    | DeleteStatement 
    | CreateDatabase 
    | RenameDatabase 
    | AlterDatabase 
    | DropDatabase
    | CreateTable 
    | RenameTable 
    | AlterTable 
    | DropTable;

interface QueryOptions {
    [key: string]: any;
}

type QueryResult = Savepoint | Array<object> | number | null;

Param	Description
query	An SQL query or a Statement instance.
values?	For non-DDL operations, values for parameters in the query.
options?	Extra parameters for the query.

└ QueryOptions

Param	Applicable to	Description
desc	DDL operations	the commit description.
noCreateSavepoint	DDL operations	a disable savepoint creation.
inspect	All operations	Log details of the query to the console.

Return Value

• An array - the query result set - when it's a DQL operation (SELECT) or when it's a DML operation (INSERT, UPDATE, DELETE) with a RETURNING clause
• A number - indicating number of rows processed by the query - when it's a DML operation without a RETURNING clause
• A Savepoint instance (See ➞ Savepoint) or the boolean true when savepoint creation has been disabled via options.noCreateSavepoint - when it's a DDL operation (CREATE, ALTER, DROP, RENAME)
• Null in all other cases

Usage

Call patterns

Three-parameter call pattern:

// Each parameter passed distinctly
await client.query(
    `SELECT * FROM users WHERE name = $1`,
    ['John'],
    options
);

Two-parameter call pattern:

// Values passed via second parameter
await client.query(
    `SELECT * FROM users WHERE name = $1`,
    { values: ['John'], ...options }
);

Single-parameter call pattern:

// Everything in an object
await client.query({
    query: `SELECT * FROM users WHERE name = $1`,
    values: ['John'],
    ...options
});

The QueryOptions object

Pass relevant additional options to a query:

// Inspect query in the console
const rows = await client.query(
    `ALTER TABLE users 
    MODIFY COLUMN id int`,
    { desc: 'Query description', inspect: true }
);

Return types

Run a DML operation (CREATE, ALTER, DROP, RENAME) and get back a reference to the savepoint associated with it (See ➞ Automatic-Schema-Versioning):

// Savepoint as return type
const savepoint = await client.query(
    `ALTER TABLE users
    RENAME TO accounts`
);
console.log(savepoint.versionTag()); // number

await savepoint.rollback(); // true

or a DQL operation (SELECT), and get back a result set:

// Array as return type
const rows = await client.query(
    `SELECT * FROM users
    WHERE id = 4`
);
console.log(rows.length); // 1

or a DML operation (INSERT, UPDATE, DELETE) with a RETURNING clause, and get back a result set:

// Array as return type
const rows = await client.query(
    `INSERT INTO users
    SET name = 'John Doe'
    RETURNING id`
);
console.log(rows.length); // 1

or same DML operation without a RETURNING clause, and get back a number indicating the number of rows processed by the query:

// Number as return type
const rowCount = await client.query(
    `INSERT INTO users
    SET name = 'John Doe'`
);
console.log(rowCount); // 1