sql.comment(text, include)
Creates an SQL comment fragment that can be embedded in queries. Comments are useful for documenting query logic, adding debugging information, or providing context for complex operations.
Comments are ignored during SQL execution by default but
can be valuable for debugging and maintenance. By default, comments only appear when
GRAPHILE_ENV=development is set, but you can force
them to appear by setting include to true (or force them to be hidden via
include set to false).
Do not include user-generated content!
We do our best to ensure comments are escaped properly, but be cautious to not include user-generated content in comments, as this could lead to malformed or vulnerable SQL.
Syntax
sql.comment(text: string, include?: boolean): SQL
Parameters
text- The comment text to includeinclude- Optional boolean to force inclusion (true) or exclusion (false) of the comment regardless of environment. Defaults toundefined, which means comments are included only in development mode.
Return value
Returns a SQL fragment containing the properly formatted SQL comment.
Examples
Leading comment
import { sql } from "pg-sql2";
const query = sql`
${sql.comment("Fetch active users with their order counts")}
SELECT u.id, COUNT(o.id) as order_count ...
`;
console.log(sql.compile(query).text);
// /* Fetch active users with their order counts */
// SELECT u.id, COUNT(o.id) as order_count ...
Dynamic comment content
function addDebugComments(query, debugInfo) {
return sql`
${sql.comment(`DEBUG: Query generated at ${new Date().toISOString()}`)}
${sql.comment(`DEBUG: Filters applied - ${JSON.stringify(debugInfo)}`)}
${query}
`;
}
const query = addDebugComments(
sql`SELECT * FROM users WHERE status = ${sql.value("active")}`,
{ status: "active", timestamp: Date.now() },
);
Inline comment
import { sql } from "pg-sql2";
const taxPercentage = 20.0;
const deliveryCharge = 1.99;
const orderId = 123;
const complexCalculation = sql`
${sql.comment(`Calculate total with shipping and tax at ${parseFloat(taxPercentage)}%`)}
(price + ${sql.value(deliveryCharge)}) * ${sql.value(1 + taxPercentage / 100)}
`;
const query = sql`
UPDATE orders
SET total = ${complexCalculation}
WHERE id = ${sql.value(orderId)}
`;
console.log(sql.compile(query).text);
// UPDATE orders
// SET total =
// /* Calculate total with shipping and tax at 20% */
// (price + $1) * $2
// WHERE id = $3
console.log(sql.compile(query).values);
// The values of $1, $2 and $3:
// [1.99, 1.2, 123]
Comment formatting
// Single line comments become /* comment */
sql.comment("Single line comment");
// /* Single line comment */
// Multi-line comments preserve formatting
sql.comment(`
Line 1
Line 2
Line 3
`);
// /*
// Line 1
// Line 2
// Line 3
// */