This API is available in Profound.js 5.0.0 and later.

Description

pjs.getDB() returns a database connection definition object for one of the connections configured in the databaseConnections configuration option. The object is passed as the first parameter to the SQL and Data APIs to direct them at a connection other than the default.

By default, every SQL and Data API uses the instance's default database connection (the entry in databaseConnections with default: true, or the first entry if none is flagged). pjs.getDB() is only needed when a module must work with a different connection, or when the module needs to inspect the configuration of a connection.

Syntax

var db = pjs.getDB("crm");      // definition object for the named connection "crm"
var db = pjs.getDB();           // definition object for the default connection

Parameters

Database connection name (String, optional) - The name of an entry in the databaseConnections configuration option. If omitted, the definition object for the default database connection is returned.

Return Value

A database connection definition object. The object is passed as the first parameter to the following APIs, followed by the other parameters documented for each API:

The definition object also has a connection property that references the matching entry from the databaseConnections configuration option. This can be used, for example, to check the driver of the connection so that database-specific code can be run.

Exception Handling

An exception is thrown if the database connection name does not match an entry in the configuration.

Examples

Example 1: Run a Query Against a Named Connection

This example runs the same statement first against the default connection and then against the connection named crm. The definition object is simply inserted in front of the normal pjs.query() parameters.

Prerequisite: a connection named crm in the databaseConnections configuration option, and a table CUSTOMERS with a STATUS column in both databases. Substitute your own names.

Select a database connection for pjs.query()

// Runs against the default database connection.
var activeCustomers = pjs.query("SELECT * FROM customers WHERE status = ?", ["A"]);

// Runs against the database connection named "crm".
var crmCustomers = pjs.query(pjs.getDB("crm"), "SELECT * FROM customers WHERE status = ?", ["A"]);

console.log(activeCustomers.length + " customers in the default database, " + crmCustomers.length + " in CRM");

Example 2: Add a Record with the Data API

The Data APIs accept the definition object in the same way. This example adds the same record with pjs.data.add() to the default database and to the crm database.

Select a database connection for pjs.data.add()

var record = {
  id: 123,
  firstname: "Joe",
  lastname: "Customer"
};

// Runs against the default database connection.
pjs.data.add("customers", record);

// Runs against the database connection named "crm".
pjs.data.add(pjs.getDB("crm"), "customers", record);

Example 3: Check the Driver of the Default Connection

The connection property exposes the configuration entry, which makes it possible to branch on the database type when a statement must be written differently for each database. (The pjs.sqlHelper functions can generate database-specific syntax without this kind of branching.)

Read the configuration entry of a connection

// The configuration entry for the default connection.
var connectionInfo = pjs.getDB().connection;

if (connectionInfo.driver === "IBMi") {
  // IBM i Db2-specific code.
}
else if (connectionInfo.driver === "mysql") {
  // MySQL/MariaDB-specific code.
}

pjs.getDB()