@query-doctor/core 0.3.0 → 0.4.1

package/dist/index.js

@@ -27,12 +27,25 @@ function isANode(node) {
 }
 function parseNudges(node, stack) {
   const nudges = [];
-  if (is(node, "A_Star")) {
-    nudges.push({
-      kind: "AVOID_SELECT_STAR",
-      severity: "INFO",
-      message: "Avoid using SELECT *"
-    });
+  if (is(node, "SelectStmt")) {
+    const star = node.SelectStmt.targetList?.find(
+      (target) => {
+        if (!(is(target, "ResTarget") && target.ResTarget.val && is(target.ResTarget.val, "ColumnRef"))) {
+          return false;
+        }
+        return target.ResTarget.val.ColumnRef.fields?.some(
+          (field) => is(field, "A_Star")
+        ) ?? false;
+      }
+    );
+    if (star) {
+      nudges.push({
+        kind: "AVOID_SELECT_STAR",
+        severity: "INFO",
+        message: "Avoid using SELECT *",
+        location: star.ResTarget.location
+      });
+    }
   }
   if (is(node, "FuncCall")) {
     const inWhereClause = stack.some((item) => item === "whereClause");
@@ -42,7 +55,8 @@ function parseNudges(node, stack) {
         nudges.push({
           kind: "AVOID_FUNCTIONS_ON_COLUMNS_IN_WHERE",
           severity: "WARNING",
-          message: "Avoid using functions on columns in WHERE clause"
+          message: "Avoid using functions on columns in WHERE clause",
+          location: node.FuncCall.location
         });
       }
     }
@@ -58,18 +72,24 @@ function parseNudges(node, stack) {
           return is(fromItem, "RangeVar") || is(fromItem, "JoinExpr") && hasActualTablesInJoin(fromItem);
         });
         if (hasActualTables) {
+          const firstTable = node.SelectStmt.fromClause.find(
+            (item) => is(item, "RangeVar")
+          );
+          const fromLocation = firstTable?.RangeVar.location;
           if (!node.SelectStmt.whereClause) {
             nudges.push({
               kind: "MISSING_WHERE_CLAUSE",
               severity: "INFO",
-              message: "Missing WHERE clause"
+              message: "Missing WHERE clause",
+              location: fromLocation
             });
           }
           if (!node.SelectStmt.limitCount) {
             nudges.push({
               kind: "MISSING_LIMIT_CLAUSE",
               severity: "INFO",
-              message: "Missing LIMIT clause"
+              message: "Missing LIMIT clause",
+              location: fromLocation
             });
           }
         }
@@ -85,7 +105,8 @@ function parseNudges(node, stack) {
         nudges.push({
           kind: "USE_IS_NULL_NOT_EQUALS",
           severity: "WARNING",
-          message: "Use IS NULL instead of = or != or <> for NULL comparisons"
+          message: "Use IS NULL instead of = or != or <> for NULL comparisons",
+          location: node.A_Expr.location
         });
       }
     }
@@ -93,10 +114,15 @@ function parseNudges(node, stack) {
     if (isLikeOp && node.A_Expr.rexpr) {
       const patternString = getStringConstantValue(node.A_Expr.rexpr);
       if (patternString && patternString.startsWith("%")) {
+        let stringNode;
+        if (is(node.A_Expr.rexpr, "A_Const")) {
+          stringNode = node.A_Expr.rexpr.A_Const;
+        }
         nudges.push({
           kind: "AVOID_LEADING_WILDCARD_LIKE",
           severity: "WARNING",
-          message: "Avoid using LIKE with leading wildcards"
+          message: "Avoid using LIKE with leading wildcards",
+          location: stringNode?.location
         });
       }
     }
@@ -118,14 +144,15 @@ function parseNudges(node, stack) {
     }
   }
   if (is(node, "SelectStmt") && node.SelectStmt.fromClause && node.SelectStmt.fromClause.length > 1) {
-    const tableCount = node.SelectStmt.fromClause.filter(
+    const tables = node.SelectStmt.fromClause.filter(
       (item) => is(item, "RangeVar")
-    ).length;
-    if (tableCount > 1) {
+    );
+    if (tables.length > 1) {
       nudges.push({
         kind: "MISSING_JOIN_CONDITION",
         severity: "WARNING",
-        message: "Missing JOIN condition"
+        message: "Missing JOIN condition",
+        location: tables[1].RangeVar.location
       });
     }
   }
@@ -135,7 +162,8 @@ function parseNudges(node, stack) {
       nudges.push({
         kind: "CONSIDER_IN_INSTEAD_OF_MANY_ORS",
         severity: "WARNING",
-        message: "Consider using IN instead of many ORs"
+        message: "Consider using IN instead of many ORs",
+        location: node.BoolExpr.location
       });
     }
   }
@@ -151,7 +179,8 @@ function parseNudges(node, stack) {
         nudges.push({
           kind: "REPLACE_LARGE_IN_TUPLE_WITH_ANY_ARRAY",
           message: "`in (...)` queries with large tuples can often be replaced with `= ANY($1)` using a single parameter",
-          severity: "INFO"
+          severity: "INFO",
+          location: node.A_Expr.location
         });
       }
     }
@@ -265,7 +294,7 @@ var Walker = class _Walker {
     this.seenReferences = /* @__PURE__ */ new Map();
     this.shadowedAliases = [];
     this.nudges = [];
-    _Walker.traverse(root, [], (node, stack) => {
+    _Walker.traverse(root, (node, stack) => {
       const nodeNudges = parseNudges(node, stack);
       this.nudges = [...this.nudges, ...nodeNudges];
       if (is2(node, "CommonTableExpr")) {
@@ -343,6 +372,18 @@ var Walker = class _Walker {
           }
         }
       }
+      if (is2(node, "A_Expr") && node.A_Expr.kind === "AEXPR_OP") {
+        const opName = node.A_Expr.name?.[0] && is2(node.A_Expr.name[0], "String") && node.A_Expr.name[0].String.sval;
+        if (opName && (opName === "@>" || opName === "?" || opName === "?|" || opName === "?&")) {
+          const jsonbOperator = opName;
+          if (node.A_Expr.lexpr && is2(node.A_Expr.lexpr, "ColumnRef")) {
+            this.add(node.A_Expr.lexpr, { jsonbOperator });
+          }
+          if (node.A_Expr.rexpr && is2(node.A_Expr.rexpr, "ColumnRef")) {
+            this.add(node.A_Expr.rexpr, { jsonbOperator });
+          }
+        }
+      }
       if (is2(node, "ColumnRef")) {
         for (let i = 0; i < stack.length; i++) {
           const inReturningList = stack[i] === "returningList" && stack[i + 1] === "ResTarget" && stack[i + 2] === "val" && stack[i + 3] === "ColumnRef";
@@ -441,9 +482,15 @@ var Walker = class _Walker {
     if (options?.where) {
       ref.where = options.where;
     }
+    if (options?.jsonbOperator) {
+      ref.jsonbOperator = options.jsonbOperator;
+    }
     this.highlights.push(ref);
   }
-  static traverse(node, stack, callback) {
+  static traverse(node, callback) {
+    _Walker.doTraverse(node, [], callback);
+  }
+  static doTraverse(node, stack, callback) {
     if (isANode2(node)) {
       callback(node, [...stack, getNodeKind(node)]);
     }
@@ -453,15 +500,19 @@ var Walker = class _Walker {
     if (Array.isArray(node)) {
       for (const item of node) {
         if (isANode2(item)) {
-          _Walker.traverse(item, stack, callback);
+          _Walker.doTraverse(item, stack, callback);
         }
       }
     } else if (isANode2(node)) {
       const keys = Object.keys(node);
-      _Walker.traverse(node[keys[0]], [...stack, getNodeKind(node)], callback);
+      _Walker.doTraverse(node[keys[0]], [...stack, getNodeKind(node)], callback);
     } else {
       for (const [key, child] of Object.entries(node)) {
-        _Walker.traverse(child, [...stack, key], callback);
+        _Walker.doTraverse(
+          child,
+          [...stack, key],
+          callback
+        );
       }
     }
   }
@@ -605,6 +656,9 @@ var Analyzer = class {
           if (colReference.where) {
             index.where = colReference.where;
           }
+          if (colReference.jsonbOperator) {
+            index.jsonbOperator = colReference.jsonbOperator;
+          }
           addIndex(index);
         }
       } else if (tableReference) {
@@ -626,6 +680,9 @@ var Analyzer = class {
           if (colReference.where) {
             index.where = colReference.where;
           }
+          if (colReference.jsonbOperator) {
+            index.jsonbOperator = colReference.jsonbOperator;
+          }
           addIndex(index);
         }
       } else if (fullReference) {
@@ -644,6 +701,9 @@ var Analyzer = class {
         if (colReference.where) {
           index.where = colReference.where;
         }
+        if (colReference.jsonbOperator) {
+          index.jsonbOperator = colReference.jsonbOperator;
+        }
         addIndex(index);
       } else {
         console.error(
@@ -766,7 +826,7 @@ async function dropIndex(tx, index) {
 
 // src/sql/indexes.ts
 function isIndexSupported(index) {
-  return index.index_type === "btree";
+  return index.index_type === "btree" || index.index_type === "gin";
 }
 function isIndexProbablyDroppable(index) {
   return !index.is_primary && !index.is_unique;
@@ -1248,8 +1308,10 @@ var _IndexOptimizer = class _IndexOptimizer {
    * Derive the list of indexes [tableA(X, Y, Z), tableB(H, I, J)]
    **/
   indexesToCreate(rootCandidates) {
-    const permutedIndexes = this.groupPotentialIndexColumnsByTable(rootCandidates);
+    const btreeCandidates = rootCandidates.filter((c) => !c.jsonbOperator);
+    const ginCandidates = rootCandidates.filter((c) => c.jsonbOperator);
     const nextStage = [];
+    const permutedIndexes = this.groupPotentialIndexColumnsByTable(btreeCandidates);
     for (const permutation of permutedIndexes.values()) {
       const { table: rawTable, schema: rawSchema, columns } = permutation;
       const permutations = permutationsWithDescendingLength(columns);
@@ -1274,6 +1336,41 @@ var _IndexOptimizer = class _IndexOptimizer {
         });
       }
     }
+    const ginGroups = this.groupGinCandidatesByColumn(ginCandidates);
+    for (const group of ginGroups.values()) {
+      const { schema: rawSchema, table: rawTable, column, operators } = group;
+      const schema = PgIdentifier.fromString(rawSchema);
+      const table = PgIdentifier.fromString(rawTable);
+      const needsKeyExistence = operators.some(
+        (op) => op === "?" || op === "?|" || op === "?&"
+      );
+      const opclass = needsKeyExistence ? void 0 : "jsonb_path_ops";
+      const existingGin = this.ginIndexAlreadyExists(table.toString(), column);
+      if (existingGin) {
+        continue;
+      }
+      const indexName = this.indexName();
+      const candidate = {
+        schema: rawSchema,
+        table: rawTable,
+        column
+      };
+      const definition = this.toGinDefinition({
+        table,
+        schema,
+        column: PgIdentifier.fromString(column),
+        opclass
+      });
+      nextStage.push({
+        name: indexName,
+        schema: schema.toString(),
+        table: table.toString(),
+        columns: [candidate],
+        definition,
+        indexMethod: "gin",
+        opclass
+      });
+    }
     return nextStage;
   }
   toDefinition({
@@ -1308,6 +1405,47 @@ var _IndexOptimizer = class _IndexOptimizer {
     const colored = make(green, yellow, magenta, blue2);
     return { raw, colored };
   }
+  toGinDefinition({
+    schema,
+    table,
+    column,
+    opclass
+  }) {
+    let fullyQualifiedTable;
+    if (schema.toString() === "public") {
+      fullyQualifiedTable = table;
+    } else {
+      fullyQualifiedTable = PgIdentifier.fromParts(schema, table);
+    }
+    const opclassSuffix = opclass ? ` ${opclass}` : "";
+    return `${fullyQualifiedTable} using gin (${column}${opclassSuffix})`;
+  }
+  groupGinCandidatesByColumn(candidates) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const c of candidates) {
+      if (!c.jsonbOperator) continue;
+      const key = `${c.schema}.${c.table}.${c.column}`;
+      const existing = groups.get(key);
+      if (existing) {
+        if (!existing.operators.includes(c.jsonbOperator)) {
+          existing.operators.push(c.jsonbOperator);
+        }
+      } else {
+        groups.set(key, {
+          schema: c.schema,
+          table: c.table,
+          column: c.column,
+          operators: [c.jsonbOperator]
+        });
+      }
+    }
+    return groups;
+  }
+  ginIndexAlreadyExists(table, column) {
+    return this.existingIndexes.find(
+      (index) => index.index_type === "gin" && index.table_name === table && index.index_columns.some((c) => c.name === column)
+    );
+  }
   /**
    * Drop indexes that can be dropped. Ignore the ones that can't
    */
@@ -1624,6 +1762,21 @@ var _Statistics = class _Statistics {
     }
     return "text";
   }
+  /**
+   * PostgreSQL's anyarray columns in pg_statistic can hold arrays of arrays
+   * for columns with array types (e.g. text[], int4[]). These create
+   * multidimensional arrays that can be "ragged" (sub-arrays with different
+   * lengths). jsonb_to_recordset can't reconstruct ragged multidimensional
+   * arrays from JSON, so we need to drop these values.
+   */
+  static safeStavalues(values) {
+    if (!values || values.length === 0) return values;
+    if (values.some((v) => Array.isArray(v))) {
+      console.warn("Discarding ragged multidimensional stavalues array");
+      return null;
+    }
+    return values;
+  }
   async restoreStats17(tx) {
     const warnings = {
       tablesNotInExports: [],
@@ -1675,16 +1828,26 @@ var _Statistics = class _Statistics {
             stanumbers3: stats.stanumbers3,
             stanumbers4: stats.stanumbers4,
             stanumbers5: stats.stanumbers5,
-            stavalues1: stats.stavalues1,
-            stavalues2: stats.stavalues2,
-            stavalues3: stats.stavalues3,
-            stavalues4: stats.stavalues4,
-            stavalues5: stats.stavalues5,
-            _value_type1: this.stavalueKind(stats.stavalues1),
-            _value_type2: this.stavalueKind(stats.stavalues2),
-            _value_type3: this.stavalueKind(stats.stavalues3),
-            _value_type4: this.stavalueKind(stats.stavalues4),
-            _value_type5: this.stavalueKind(stats.stavalues5)
+            stavalues1: _Statistics.safeStavalues(stats.stavalues1),
+            stavalues2: _Statistics.safeStavalues(stats.stavalues2),
+            stavalues3: _Statistics.safeStavalues(stats.stavalues3),
+            stavalues4: _Statistics.safeStavalues(stats.stavalues4),
+            stavalues5: _Statistics.safeStavalues(stats.stavalues5),
+            _value_type1: this.stavalueKind(
+              _Statistics.safeStavalues(stats.stavalues1)
+            ),
+            _value_type2: this.stavalueKind(
+              _Statistics.safeStavalues(stats.stavalues2)
+            ),
+            _value_type3: this.stavalueKind(
+              _Statistics.safeStavalues(stats.stavalues3)
+            ),
+            _value_type4: this.stavalueKind(
+              _Statistics.safeStavalues(stats.stavalues4)
+            ),
+            _value_type5: this.stavalueKind(
+              _Statistics.safeStavalues(stats.stavalues5)
+            )
           });
         }
       }
@@ -2100,14 +2263,16 @@ var _Statistics = class _Statistics {
                       CASE
                           WHEN (indoption[array_position(ix.indkey, a.attnum)] & 1) = 1 THEN 'DESC'
                           ELSE 'ASC'
-                      END)
+                      END,
+                      'opclass', CASE WHEN opc.opcdefault THEN NULL ELSE opc.opcname END)
                   -- Handle expressions
                   ELSE
                       json_build_object('name', pg_get_expr((ix.indexprs)::pg_node_tree, t.oid), 'order',
                       CASE
                           WHEN (indoption[array_position(ix.indkey, k.attnum)] & 1) = 1 THEN 'DESC'
                           ELSE 'ASC'
-                      END)
+                      END,
+                      'opclass', CASE WHEN opc.opcdefault THEN NULL ELSE opc.opcname END)
               END
               ORDER BY array_position(ix.indkey, k.attnum)
           ) AS index_columns
@@ -2119,6 +2284,7 @@ var _Statistics = class _Statistics {
           JOIN pg_am am ON i.relam = am.oid
           LEFT JOIN LATERAL unnest(ix.indkey) WITH ORDINALITY k(attnum, ordinality) ON true
           LEFT JOIN pg_attribute a ON a.attnum = k.attnum AND a.attrelid = t.oid
+          LEFT JOIN pg_opclass opc ON opc.oid = ix.indclass[k.ordinality - 1]
           JOIN pg_namespace n ON t.relnamespace = n.oid
       WHERE
           n.nspname not like 'pg_%' and