@query-doctor/core 0.2.5 → 0.4.0

package/dist/index.cjs

@@ -392,6 +392,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";
@@ -490,6 +502,9 @@ 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) {
@@ -654,6 +669,9 @@ var Analyzer = class {
           if (colReference.where) {
             index.where = colReference.where;
           }
+          if (colReference.jsonbOperator) {
+            index.jsonbOperator = colReference.jsonbOperator;
+          }
           addIndex(index);
         }
       } else if (tableReference) {
@@ -675,6 +693,9 @@ var Analyzer = class {
           if (colReference.where) {
             index.where = colReference.where;
           }
+          if (colReference.jsonbOperator) {
+            index.jsonbOperator = colReference.jsonbOperator;
+          }
           addIndex(index);
         }
       } else if (fullReference) {
@@ -693,6 +714,9 @@ var Analyzer = class {
         if (colReference.where) {
           index.where = colReference.where;
         }
+        if (colReference.jsonbOperator) {
+          index.jsonbOperator = colReference.jsonbOperator;
+        }
         addIndex(index);
       } else {
         console.error(
@@ -815,7 +839,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;
@@ -829,6 +853,9 @@ var PostgresQueryBuilder = class _PostgresQueryBuilder {
     __publicField(this, "isIntrospection", false);
     __publicField(this, "explainFlags", []);
     __publicField(this, "_preamble", 0);
+    __publicField(this, "parameters", {});
+    // substitution for `limit $1` -> `limit 5`
+    __publicField(this, "limitSubstitution");
   }
   get preamble() {
     return this._preamble;
@@ -862,6 +889,14 @@ var PostgresQueryBuilder = class _PostgresQueryBuilder {
     this.explainFlags = flags;
     return this;
   }
+  parameterize(parameters) {
+    Object.assign(this.parameters, parameters);
+    return this;
+  }
+  replaceLimit(limit) {
+    this.limitSubstitution = limit;
+    return this;
+  }
   build() {
     let commands = this.generateSetCommands();
     commands += this.generateExplain().query;
@@ -890,14 +925,28 @@ var PostgresQueryBuilder = class _PostgresQueryBuilder {
     return commands;
   }
   generateExplain() {
-    let query = "";
+    let finalQuery = "";
     if (this.explainFlags.length > 0) {
-      query += `explain (${this.explainFlags.join(", ")}) `;
+      finalQuery += `explain (${this.explainFlags.join(", ")}) `;
+    }
+    const query = this.substituteQuery();
+    const semicolon = query.endsWith(";") ? "" : ";";
+    const preamble = finalQuery.length;
+    finalQuery += `${query}${semicolon}`;
+    return { query: finalQuery, preamble };
+  }
+  substituteQuery() {
+    let query = this.query;
+    if (this.limitSubstitution !== void 0) {
+      query = query.replace(
+        /limit\s+\$\d+/g,
+        `limit ${this.limitSubstitution}`
+      );
+    }
+    for (const [key, value] of Object.entries(this.parameters)) {
+      query = query.replaceAll(`\\$${key}`, value.toString());
     }
-    const semicolon = this.query.endsWith(";") ? "" : ";";
-    const preamble = query.length;
-    query += `${this.query}${semicolon}`;
-    return { query, preamble };
+    return query;
   }
 };
 
@@ -1272,8 +1321,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);
@@ -1298,6 +1349,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({
@@ -1332,6 +1418,47 @@ var _IndexOptimizer = class _IndexOptimizer {
     const colored = make(import_colorette2.green, import_colorette2.yellow, import_colorette2.magenta, import_colorette2.blue);
     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
    */
@@ -1648,6 +1775,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: [],
@@ -1699,16 +1841,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)
+            )
           });
         }
       }
@@ -2124,14 +2276,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
@@ -2143,6 +2297,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