website: pg-sql2 examples in docs (#2746)

Author: benjie

.changeset/legal-apes-beam.md

@@ -0,0 +1,7 @@
+---
+"@dataplan/pg": patch
+"pg-sql2": patch
+---
+
+New: `sql.comment("...", true)` forces comments to be included, even in
+production.

grafast/dataplan-pg/src/steps/pgSelect.ts

@@ -3843,7 +3843,10 @@ function buildQueryParts<TResource extends PgResource<any, any, any, any, any>>(
   const extraSelectIndexes = extraSelects.map((_, i) => i + l);
 
   return {
-    comment: sql.comment(`From ${info.sourceStepDescription}`),
+    comment: sql.comment(
+      `From ${info.sourceStepDescription}`,
+      process.env.DATAPLAN_PG_DEBUG === "1",
+    ),
     selects,
     from,
     joins: info.joins,

utils/pg-sql2/src/index.ts

@@ -33,8 +33,8 @@ const isDev =
   (process.env.GRAPHILE_ENV === "development" ||
     process.env.GRAPHILE_ENV === "test");
 
-const includeComments =
-  typeof process !== "undefined" && process.env.PGSQL2_DEBUG === "1";
+const defaultIncludeComments =
+  isDev || (typeof process !== "undefined" && process.env.PGSQL2_DEBUG === "1");
 
 const nodeInspect: CustomInspectFunction = function (
   this: SQLNode | SQLQuery,
@@ -1099,9 +1099,12 @@ export function placeholder(symbol: symbol, fallback?: SQL): SQL {
   return makePlaceholderNode(symbol, fallback);
 }
 
-export function comment(commentText: string): SQLCommentNode | SQLRawNode {
-  if (includeComments) {
-    return makeCommentNode(commentText);
+export function comment(
+  text: string,
+  include = defaultIncludeComments,
+): SQLCommentNode | SQLRawNode {
+  if (include) {
+    return makeCommentNode(text);
   } else {
     return sql.blank;
   }

utils/website/pg-sql2/api/sql-comment.md

@@ -3,12 +3,17 @@ sidebar_position: 10
 title: "sql.comment()"
 ---
 
-# `sql.comment(text)`
+# `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 but
-can be valuable for debugging and maintenance.
+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`](../development-mode.md) 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`).
 
 :::warning[Do not include user-generated content!]
 
@@ -21,20 +26,21 @@ vulnerable SQL.
 ## Syntax
 
 ```typescript
-sql.comment(text: string): SQL
+sql.comment(text: string, include?: boolean): SQL
 ```
 
 ## Parameters
 
 - `text` - The comment text to include
+- `include` - Optional boolean to force inclusion (`true`) or exclusion (`false`) of the comment regardless of environment. Defaults to `undefined`, which means comments are included only in development mode.
 
 ## Return value
 
 Returns a `SQL` fragment containing the properly formatted SQL comment.
 
 ## Examples
 
-### Document query
+### Leading comment
 
 ```js
 import { sql } from "pg-sql2";
@@ -44,36 +50,15 @@ ${sql.comment("Fetch active users with their order counts")}
 SELECT u.id, COUNT(o.id) as order_count ...
 `;
 
-// `sql.compile(query).text` will be something like:
+console.log(sql.compile(query).text);
 // /* Fetch active users with their order counts */
 // SELECT u.id, COUNT(o.id) as order_count ...
 ```
 
-### Inline comment
+### Dynamic comment content
 
 ```js
-const complexCalculation = sql`
-  ${sql.comment(`Calculate total with shipping and tax at ${parseFloat(taxPercentage)}%`)}
-  (price + ${sql.value(deliveryCharge)}) * ${sql.value(1 + taxPercentage / 100)}
-`;
-
-sql`
-UPDATE orders 
-SET total = ${complexCalculation}
-WHERE id = ${sql.value(orderId)}
-`;
-```
-
-### Conditional comments
-
-```js
-const isDevelopment = process.env.NODE_ENV === "development";
-
 function addDebugComments(query, debugInfo) {
-  if (!isDevelopment) {
-    return query;
-  }
-
   return sql`
     ${sql.comment(`DEBUG: Query generated at ${new Date().toISOString()}`)}
     ${sql.comment(`DEBUG: Filters applied - ${JSON.stringify(debugInfo)}`)}
@@ -87,22 +72,54 @@ const query = addDebugComments(
 );
 ```
 
+### Inline comment
+
+```js
+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
 
 ```js
 // Single line comments become /* comment */
 sql.comment("Single line 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
-//    */
+//  /*
+//    Line 1
+//    Line 2
+//    Line 3
+//  */
 ```

utils/website/pg-sql2/api/sql-compile.md

@@ -44,7 +44,7 @@ await client.query(text, values);
 ### Basic usage
 
 ```js
-import sql from "pg-sql2";
+import { sql } from "pg-sql2";
 
 const userId = 123;
 const status = "active";
@@ -59,14 +59,16 @@ const query = sql`
 const { text, values } = sql.compile(query);
 
 console.log(text);
-// -> SELECT id, name, email FROM users WHERE id = $1 AND status = $2
+// SELECT id, name, email FROM users WHERE id = $1 AND status = $2
 console.log(values);
-// -> [123, 'active']
+// [123, 'active']
 ```
 
 ### Complex example
 
 ```js
+import { sql } from "pg-sql2";
+
 const filters = {
   status: "active",
   minAge: 18,
@@ -91,21 +93,24 @@ const query = sql`
 const compiled = sql.compile(query);
 
 console.log(compiled.text);
-// -> SELECT "id", "name", "email", "role", "created_at"
-//    FROM "users"
-//    WHERE status = $1
-//    AND age >= $2
-//    AND role = ANY($3)
-//    ORDER BY "created_at" DESC
-//    LIMIT 50
+/*  SELECT "id", "name", "email", "role", "created_at"
+    FROM "users"
+    WHERE status = $1
+    AND age >= $2
+    AND role = ANY($3)
+    ORDER BY "created_at" DESC
+    LIMIT 50
+*/
 
 console.log(compiled.values);
-// -> ['active', 18, ['admin', 'user', 'moderator']]
+// ['active', 18, ['admin', 'user', 'moderator']]
 ```
 
 ### With placeholders
 
 ```js
+import { sql } from "pg-sql2";
+
 const $$table = Symbol("table");
 const $$orderBy = Symbol("orderBy");
 
@@ -118,8 +123,9 @@ const query = sql`
 
 // Compile with defaults
 const q1 = sql.compile(query);
+
 console.log(q1.text);
-// -> SELECT * FROM "default_table" ORDER BY id ASC
+// SELECT * FROM "default_table" ORDER BY id ASC
 
 // Compile with placeholder values
 const q2 = sql.compile(query, {
@@ -128,6 +134,7 @@ const q2 = sql.compile(query, {
     [$$orderBy, sql`created_at DESC`],
   ]),
 });
+
 console.log(q2.text);
-// -> SELECT * FROM "users" ORDER BY created_at DESC
+// SELECT * FROM "users" ORDER BY created_at DESC
 ```