sql.parens(fragment, force?)
Wraps SQL fragments in parentheses if it might be needed to prevent ambiguity, or forces parentheses when needed for subqueries or stylistic reasons. Use this method instead of literal parenthesis to avoid excessive parentheses while ensuring syntactic correctness.
Syntax
sql.parens(fragment: SQL, force?: boolean): SQL
Parameters
fragment- The SQL fragment to potentially wrap in parenthesesforce- Optional boolean to force parentheses even if not strictly needed
Return value
Returns a SQL fragment that is wrapped in parentheses if force is true, or
if it might be needed to avoid syntactic ambiguity.
Examples
Basic usage
import sql from "pg-sql2";
// Simple values don't need parentheses
// No parentheses are added to these outputs
const numberQuery = sql.parens(sql.value(123));
console.log(sql.compile(numberQuery).text);
// [123]
const textQuery = sql.parens(sql.identifier("users"));
console.log(sql.compile(textQuery).text);
/// "users"
// Expressions that could be ambiguous get parentheses
const condition = sql`age > 18 AND status = 'active'`;
const query = sql`SELECT * FROM users WHERE ${sql.parens(condition)} OR admin = true`;
console.log(sql.compile(query).text);
// SELECT * FROM users WHERE (age > 18 AND status = 'active') OR admin = true
// Works with nested conditions
const conditions = [sql`age > 18`];
const sqlConditions = sql.join(conditions.map(sql.parens), " AND ");
const query = sql`SELECT * FROM users WHERE ${sql.parens(sqlConditions)} OR admin = true`;
console.log(sql.compile(query).text);
// SELECT * FROM users WHERE (age > 18) OR admin = true
// Changing the conditions to be more complex
// introduces more parentheses to reduce ambiguity
const conditions = [sql`age > 18`, sql`status = 'active'`];
const sqlConditions = sql.join(conditions.map(sql.parens), " AND ");
const query = sql`SELECT * FROM users WHERE ${sql.parens(sqlConditions)} OR admin = true`;
console.log(sql.compile(query).text);
// SELECT * FROM users WHERE ((age > 18) AND (status = 'active')) OR admin = true
Forced parentheses
import sql from "pg-sql2";
// Force parentheses for subqueries
const subquery = sql`SELECT id FROM users WHERE active = true`;
const query = sql`SELECT * FROM orders WHERE user_id IN ${sql.parens(subquery, true)}`;
console.log(sql.compile(query).text);
// SELECT * FROM orders WHERE user_id IN (SELECT id FROM users WHERE active = true)