@query-doctor/core 0.4.1 → 0.4.2

package/dist/index.d.cts

@@ -0,0 +1,750 @@
+'use client';
+
+import { Node, NullTestType, SortByDir, SortByNulls } from "@pgsql/types";
+import { z } from "zod";
+
+//#region src/sql/pg-identifier.d.ts
+/**
+ * Represents an identifier in postgres that is subject
+ * to quoting rules. The {@link toString} rule behaves
+ * exactly like calling `select quote_ident($1)` in postgres
+ */
+declare class PgIdentifier {
+  private readonly value;
+  private readonly quoted;
+  private constructor();
+  /**
+   * Constructs an identifier from a single part (column or table name).
+   * When quoting identifiers like `select table.col` use {@link fromParts} instead
+   */
+  static fromString(identifier: string): PgIdentifier;
+  /**
+   * Quotes parts of an identifier like `select schema.table.col`.
+   * A separate function is necessary because postgres will treat
+   * `select "HELLO.WORLD"` as a column name. It has to be like
+   * `select "HELLO"."WORLD"` instead.
+   */
+  static fromParts(...identifiers: (string | PgIdentifier)[]): PgIdentifier;
+  toString(): string;
+  toJSON(): string;
+  private static readonly reservedKeywords;
+}
+//#endregion
+//#region src/sql/builder.d.ts
+type PostgresQueryBuilderCommand = "bitmapscan" | "indexscan" | "seqscan";
+declare class PostgresQueryBuilder {
+  private query;
+  private readonly commands;
+  private isIntrospection;
+  private explainFlags;
+  private _preamble;
+  private parameters;
+  private limitSubstitution?;
+  constructor(query: string);
+  get preamble(): number;
+  static createIndex(definition: string, name?: PgIdentifier): PostgresQueryBuilder;
+  enable(command: PostgresQueryBuilderCommand, value?: boolean): this;
+  withQuery(query: string): this;
+  introspect(): this;
+  explain(flags: string[]): this;
+  parameterize(parameters: Record<Parameter, number>): this;
+  replaceLimit(limit: number): this;
+  build(): string;
+  /** Return the "set a=b" parts of the command in the query separate from the explain select ... part */
+  buildParts(): {
+    commands: string;
+    query: string;
+  };
+  private generateSetCommands;
+  private generateExplain;
+  private substituteQuery;
+}
+type Parameter = `$${string}`;
+//#endregion
+//#region src/sql/database.d.ts
+declare const PostgresVersion: z.core.$ZodBranded<z.ZodString, "PostgresVersion">;
+type PostgresVersion = z.infer<typeof PostgresVersion>;
+interface PostgresTransaction {
+  /**
+   * Exec a query and return the result as an array of objects.
+   */
+  exec<T>(query: string, params?: unknown[]): Promise<T[]>;
+}
+/**
+ * A shared interface for all postgres connections.
+ * This is required to allow interop between pglite and regular postgres drivers
+ */
+interface Postgres extends PostgresTransaction {
+  transaction<T>(callback: (tx: PostgresTransaction) => Promise<T>): Promise<T>;
+  cursor?<T>(query: string, params?: unknown[], options?: {
+    size?: number;
+  }): AsyncGenerator<T, void, unknown>;
+  serverNum(): Promise<PostgresVersion>;
+}
+type PostgresConnectionInput = {
+  url: string;
+};
+type PostgresFactory = (input: PostgresConnectionInput) => Postgres;
+declare const StageId: unique symbol;
+type PostgresStageId = number & {
+  [StageId]: "StageId";
+};
+type PostgresStage = "Seq Scan" | "Limit" | "Bitmap Heap Scan" | "Bitmap Index Scan" | "Index Only Scan" | "Index Scan" | "BitmapOr";
+type PostgresExplainStageCommon = {
+  "Node Type": PostgresStage;
+  "Node Id": PostgresStageId;
+  Plans?: PostgresExplainStage[];
+  "Plan Width": number;
+  "Total Cost": number;
+};
+type PostgresExplainStage = (PostgresExplainStageCommon & {
+  "Node Type": "Index Scan";
+  "Index Name": string;
+  "Relation Name": string;
+  Alias: string;
+  "Rows Removed by Filter": number;
+}) | (PostgresExplainStageCommon & {
+  "Node Type": "Seq Scan";
+  "Relation Name": string;
+  Filter?: string;
+  "Actual Rows": number;
+  "Actual Loops": number;
+  "Rows Removed by Filter": number;
+}) | (PostgresExplainStageCommon & {
+  "Node Type": "Bitmap Heap Scan";
+  "Relation Name": string;
+  Filter?: string;
+  "Actual Rows": number;
+  "Actual Loops": number;
+  "Rows Removed by Filter": number;
+}) | (PostgresExplainStageCommon & {
+  "Node Type": "Bitmap Index Scan";
+  "Index Name": string;
+  Filter?: string;
+  "Actual Rows": number;
+  "Actual Loops": number;
+  "Rows Removed by Filter": number;
+}) | (PostgresExplainStageCommon & {
+  "Node Type": "Index Only Scan";
+  "Index Name": string;
+  Filter?: string;
+  "Actual Rows": number;
+  "Actual Loops": number;
+  "Rows Removed by Filter": number;
+}) | PostgresExplainStageCommon;
+type PostgresExplainResult = {
+  "QUERY PLAN": {
+    Plan: PostgresExplainStage;
+  }[];
+};
+/**
+ * Drops a disabled index. Rollsback if it fails for any reason
+ * @returns Did dropping the index succeed?
+ */
+declare function dropIndex(tx: PostgresTransaction, index: PgIdentifier): Promise<boolean>;
+//#endregion
+//#region src/optimizer/statistics.d.ts
+type Path = string;
+declare const StatisticsSource: z.ZodUnion<readonly [z.ZodObject<{
+  kind: z.ZodLiteral<"path">;
+  path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"inline">;
+}, z.core.$strip>]>;
+declare const ExportedStatsStatistics: z.ZodObject<{
+  stawidth: z.ZodNumber;
+  stainherit: z.ZodDefault<z.ZodBoolean>;
+  stadistinct: z.ZodNumber;
+  stanullfrac: z.ZodNumber;
+  stakind1: z.ZodNumber;
+  stakind2: z.ZodNumber;
+  stakind3: z.ZodNumber;
+  stakind4: z.ZodNumber;
+  stakind5: z.ZodNumber;
+  staop1: z.ZodString;
+  staop2: z.ZodString;
+  staop3: z.ZodString;
+  staop4: z.ZodString;
+  staop5: z.ZodString;
+  stacoll1: z.ZodString;
+  stacoll2: z.ZodString;
+  stacoll3: z.ZodString;
+  stacoll4: z.ZodString;
+  stacoll5: z.ZodString;
+  stanumbers1: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+  stanumbers2: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+  stanumbers3: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+  stanumbers4: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+  stanumbers5: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+  stavalues1: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+  stavalues2: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+  stavalues3: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+  stavalues4: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+  stavalues5: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+}, z.core.$strip>;
+declare const ExportedStatsColumns: z.ZodObject<{
+  columnName: z.ZodString;
+  stats: z.ZodNullable<z.ZodObject<{
+    stawidth: z.ZodNumber;
+    stainherit: z.ZodDefault<z.ZodBoolean>;
+    stadistinct: z.ZodNumber;
+    stanullfrac: z.ZodNumber;
+    stakind1: z.ZodNumber;
+    stakind2: z.ZodNumber;
+    stakind3: z.ZodNumber;
+    stakind4: z.ZodNumber;
+    stakind5: z.ZodNumber;
+    staop1: z.ZodString;
+    staop2: z.ZodString;
+    staop3: z.ZodString;
+    staop4: z.ZodString;
+    staop5: z.ZodString;
+    stacoll1: z.ZodString;
+    stacoll2: z.ZodString;
+    stacoll3: z.ZodString;
+    stacoll4: z.ZodString;
+    stacoll5: z.ZodString;
+    stanumbers1: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+    stanumbers2: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+    stanumbers3: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+    stanumbers4: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+    stanumbers5: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+    stavalues1: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+    stavalues2: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+    stavalues3: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+    stavalues4: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+    stavalues5: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const ExportedStatsIndex: z.ZodObject<{
+  indexName: z.ZodString;
+  relpages: z.ZodNumber;
+  reltuples: z.ZodNumber;
+  relallvisible: z.ZodNumber;
+  relallfrozen: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const ExportedStatsV1: z.ZodObject<{
+  tableName: z.ZodString;
+  schemaName: z.ZodString;
+  relpages: z.ZodNumber;
+  reltuples: z.ZodNumber;
+  relallvisible: z.ZodNumber;
+  relallfrozen: z.ZodOptional<z.ZodNumber>;
+  columns: z.ZodNullable<z.ZodArray<z.ZodObject<{
+    columnName: z.ZodString;
+    stats: z.ZodNullable<z.ZodObject<{
+      stawidth: z.ZodNumber;
+      stainherit: z.ZodDefault<z.ZodBoolean>;
+      stadistinct: z.ZodNumber;
+      stanullfrac: z.ZodNumber;
+      stakind1: z.ZodNumber;
+      stakind2: z.ZodNumber;
+      stakind3: z.ZodNumber;
+      stakind4: z.ZodNumber;
+      stakind5: z.ZodNumber;
+      staop1: z.ZodString;
+      staop2: z.ZodString;
+      staop3: z.ZodString;
+      staop4: z.ZodString;
+      staop5: z.ZodString;
+      stacoll1: z.ZodString;
+      stacoll2: z.ZodString;
+      stacoll3: z.ZodString;
+      stacoll4: z.ZodString;
+      stacoll5: z.ZodString;
+      stanumbers1: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stanumbers2: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stanumbers3: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stanumbers4: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stanumbers5: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stavalues1: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      stavalues2: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      stavalues3: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      stavalues4: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      stavalues5: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>>;
+  indexes: z.ZodArray<z.ZodObject<{
+    indexName: z.ZodString;
+    relpages: z.ZodNumber;
+    reltuples: z.ZodNumber;
+    relallvisible: z.ZodNumber;
+    relallfrozen: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const ExportedStats: z.ZodUnion<readonly [z.ZodObject<{
+  tableName: z.ZodString;
+  schemaName: z.ZodString;
+  relpages: z.ZodNumber;
+  reltuples: z.ZodNumber;
+  relallvisible: z.ZodNumber;
+  relallfrozen: z.ZodOptional<z.ZodNumber>;
+  columns: z.ZodNullable<z.ZodArray<z.ZodObject<{
+    columnName: z.ZodString;
+    stats: z.ZodNullable<z.ZodObject<{
+      stawidth: z.ZodNumber;
+      stainherit: z.ZodDefault<z.ZodBoolean>;
+      stadistinct: z.ZodNumber;
+      stanullfrac: z.ZodNumber;
+      stakind1: z.ZodNumber;
+      stakind2: z.ZodNumber;
+      stakind3: z.ZodNumber;
+      stakind4: z.ZodNumber;
+      stakind5: z.ZodNumber;
+      staop1: z.ZodString;
+      staop2: z.ZodString;
+      staop3: z.ZodString;
+      staop4: z.ZodString;
+      staop5: z.ZodString;
+      stacoll1: z.ZodString;
+      stacoll2: z.ZodString;
+      stacoll3: z.ZodString;
+      stacoll4: z.ZodString;
+      stacoll5: z.ZodString;
+      stanumbers1: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stanumbers2: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stanumbers3: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stanumbers4: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stanumbers5: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+      stavalues1: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      stavalues2: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      stavalues3: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      stavalues4: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      stavalues5: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>>;
+  indexes: z.ZodArray<z.ZodObject<{
+    indexName: z.ZodString;
+    relpages: z.ZodNumber;
+    reltuples: z.ZodNumber;
+    relallvisible: z.ZodNumber;
+    relallfrozen: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>;
+}, z.core.$strip>]>;
+type ExportedStats = z.infer<typeof ExportedStats>;
+declare const StatisticsMode: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  kind: z.ZodLiteral<"fromAssumption">;
+  reltuples: z.ZodNumber;
+  relpages: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"fromStatisticsExport">;
+  stats: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    tableName: z.ZodString;
+    schemaName: z.ZodString;
+    relpages: z.ZodNumber;
+    reltuples: z.ZodNumber;
+    relallvisible: z.ZodNumber;
+    relallfrozen: z.ZodOptional<z.ZodNumber>;
+    columns: z.ZodNullable<z.ZodArray<z.ZodObject<{
+      columnName: z.ZodString;
+      stats: z.ZodNullable<z.ZodObject<{
+        stawidth: z.ZodNumber;
+        stainherit: z.ZodDefault<z.ZodBoolean>;
+        stadistinct: z.ZodNumber;
+        stanullfrac: z.ZodNumber;
+        stakind1: z.ZodNumber;
+        stakind2: z.ZodNumber;
+        stakind3: z.ZodNumber;
+        stakind4: z.ZodNumber;
+        stakind5: z.ZodNumber;
+        staop1: z.ZodString;
+        staop2: z.ZodString;
+        staop3: z.ZodString;
+        staop4: z.ZodString;
+        staop5: z.ZodString;
+        stacoll1: z.ZodString;
+        stacoll2: z.ZodString;
+        stacoll3: z.ZodString;
+        stacoll4: z.ZodString;
+        stacoll5: z.ZodString;
+        stanumbers1: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+        stanumbers2: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+        stanumbers3: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+        stanumbers4: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+        stanumbers5: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+        stavalues1: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+        stavalues2: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+        stavalues3: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+        stavalues4: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+        stavalues5: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    indexes: z.ZodArray<z.ZodObject<{
+      indexName: z.ZodString;
+      relpages: z.ZodNumber;
+      reltuples: z.ZodNumber;
+      relallvisible: z.ZodNumber;
+      relallfrozen: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>]>>;
+  source: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"path">;
+    path: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"inline">;
+  }, z.core.$strip>]>;
+}, z.core.$strip>], "kind">;
+type StatisticsMode = z.infer<typeof StatisticsMode>;
+declare class Statistics {
+  private readonly db;
+  readonly postgresVersion: PostgresVersion;
+  readonly ownMetadata: ExportedStats[];
+  readonly mode: StatisticsMode;
+  private readonly exportedMetadata;
+  static readonly defaultStatsMode: StatisticsMode;
+  constructor(db: Postgres, postgresVersion: PostgresVersion, ownMetadata: ExportedStats[], statsMode: StatisticsMode);
+  static statsModeFromAssumption({
+    reltuples,
+    relpages
+  }: {
+    reltuples: number;
+    relpages: number;
+  }): StatisticsMode;
+  /**
+   * Create a statistic mode from stats exported from another database
+   **/
+  static statsModeFromExport(stats: ExportedStats[]): StatisticsMode;
+  static fromPostgres(db: Postgres, statsMode: StatisticsMode): Promise<Statistics>;
+  restoreStats(tx: PostgresTransaction): Promise<{
+    tablesNotInExports: string[];
+    tablesNotInTest: string[];
+    tableNotAnalyzed: string[];
+    statsMissing: {
+      statistic: string;
+      table: string;
+      schema: string;
+      column: string;
+    }[];
+  }>;
+  approximateTotalRows(): number;
+  /**
+   * We have to cast stavaluesN to the correct type
+   * This derives that type for us so it can be used in `array_in`
+   */
+  private stavalueKind;
+  /**
+   * 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.
+   */
+  private static safeStavalues;
+  private restoreStats17;
+  static dumpStats(db: PostgresTransaction, postgresVersion: PostgresVersion, kind: "anonymous" | "full"): Promise<ExportedStats[]>;
+  /**
+   * Returns all indexes in the database.
+   * ONLY handles regular btree indexes
+   */
+  getExistingIndexes(): Promise<IndexedTable[]>;
+}
+type ColumnMetadata = {
+  columnName: string;
+  dataType: string;
+  isNullable: boolean;
+  stats: ColumnStats | null;
+};
+type ColumnStats = {
+  stainherit: boolean;
+  stanullfrac: number;
+  stawidth: number;
+  stadistinct: number;
+  stakind1: number;
+  stakind2: number;
+  stakind3: number;
+  stakind4: number;
+  stakind5: number;
+  staop1: number;
+  staop2: number;
+  staop3: number;
+  staop4: number;
+  staop5: number;
+  stacoll1: number;
+  stacoll2: number;
+  stacoll3: number;
+  stacoll4: number;
+  stacoll5: number;
+  stanumbers1: number;
+  stanumbers2: number;
+  stanumbers3: number;
+  stanumbers4: number;
+  stanumbers5: number;
+};
+type TableMetadata = {
+  tableName: string;
+  schemaName: string;
+  reltuples: number;
+  relpages: number;
+  relallvisible: number;
+  relallfrozen?: number;
+  columns: ColumnMetadata[];
+};
+type TableName = string;
+type TableStats = {
+  tupleEstimate: bigint;
+  pageCount: number;
+};
+type SerializeResult = {
+  schema: TableMetadata[];
+  serialized: string;
+  sampledRecords: Record<TableName, number>;
+};
+type IndexOrder = "ASC" | "DESC";
+type IndexedTable = {
+  index_columns: Array<{
+    name: string;
+    order: IndexOrder;
+    opclass?: string;
+  }>;
+  is_primary: boolean;
+  is_unique: boolean;
+  index_name: string;
+  index_type: "btree" | "gin" | (string & {});
+  schema_name: string;
+  table_name: string;
+};
+//#endregion
+//#region src/optimizer/genalgo.d.ts
+type IndexIdentifier = string;
+type IndexRecommendation = PermutedIndexCandidate & {
+  definition: IndexIdentifier;
+};
+declare class IndexOptimizer {
+  private readonly db;
+  private readonly statistics;
+  private existingIndexes;
+  private readonly config;
+  static prefix: string;
+  constructor(db: Postgres, statistics: Statistics, existingIndexes: IndexedTable[], config?: {
+    trace?: boolean;
+    debug?: boolean;
+  });
+  run(builder: PostgresQueryBuilder, indexes: RootIndexCandidate[], beforeQuery?: (tx: PostgresTransaction) => Promise<void>): Promise<OptimizeResult>;
+  runWithoutIndexes(builder: PostgresQueryBuilder): Promise<{
+    Plan: PostgresExplainStage;
+  }>;
+  /**
+   * Given the current indexes in the optimizer, transform them in some
+   * way to change which indexes will be assumed to exist when optimizing
+   *
+   * @example
+   * ```
+   * // resets indexes
+   * optimizer.transformIndexes(() => [])
+   *
+   * // adds new index
+   * optimizer.transformIndexes(indexes => [...indexes, newIndex])
+   * ```
+   */
+  transformIndexes(f: (indexes: IndexedTable[]) => IndexedTable[]): this;
+  /**
+   * Postgres has a limit of 63 characters for index names.
+   * So we use this to make sure we don't derive it from a list of columns that can
+   * overflow that limit.
+   */
+  private indexName;
+  private indexAlreadyExists;
+  /**
+   * Derive the list of indexes [tableA(X, Y, Z), tableB(H, I, J)]
+   **/
+  private indexesToCreate;
+  private toDefinition;
+  private toGinDefinition;
+  private groupGinCandidatesByColumn;
+  private ginIndexAlreadyExists;
+  /**
+   * Drop indexes that can be dropped. Ignore the ones that can't
+   */
+  private dropExistingIndexes;
+  private whereClause;
+  private nullsOrder;
+  private sortDirection;
+  testQueryWithStats(builder: PostgresQueryBuilder, f?: (tx: PostgresTransaction) => Promise<void>, options?: {
+    params?: unknown[];
+    genericPlan?: boolean;
+  }): Promise<{
+    Plan: PostgresExplainStage;
+  }>;
+  private groupPotentialIndexColumnsByTable;
+  private findUsedIndexes;
+  private replaceUsedIndexesWithDefinition;
+}
+type OptimizeResult = {
+  kind: "ok";
+  baseExplainPlan: PostgresExplainStage;
+  baseCost: number;
+  finalCost: number;
+  newIndexes: Set<string>;
+  existingIndexes: Set<string>;
+  triedIndexes: Map<string, IndexRecommendation>;
+  explainPlan: PostgresExplainStage;
+} | {
+  kind: "zero_cost_plan";
+  explainPlan: PostgresExplainStage;
+};
+type RootIndexCandidate = {
+  schema: string;
+  table: string;
+  column: string;
+  sort?: SortContext;
+  where?: {
+    nulltest?: NullTestType;
+  };
+  jsonbOperator?: JsonbOperator;
+};
+type PermutedIndexCandidate = {
+  schema: string;
+  table: string;
+  columns: RootIndexCandidate[];
+  where?: string;
+  indexMethod?: "btree" | "gin";
+  opclass?: string;
+};
+declare const PROCEED: unique symbol;
+declare const SKIP: unique symbol;
+//#endregion
+//#region src/sql/nudges.d.ts
+type NudgeKind = "LARGE_IMPROVEMENT_FOUND" | "SMALL_IMPROVEMENT_FOUND" | "AVOID_SELECT_STAR" | "AVOID_FUNCTIONS_ON_COLUMNS_IN_WHERE" | "MISSING_WHERE_CLAUSE" | "MISSING_LIMIT_CLAUSE" | "USE_IS_NULL_NOT_EQUALS" | "AVOID_DISTINCT_WITHOUT_REASON" | "MISSING_JOIN_CONDITION" | "AVOID_LEADING_WILDCARD_LIKE" | "CONSIDER_IN_INSTEAD_OF_MANY_ORS" | "REPLACE_LARGE_IN_TUPLE_WITH_ANY_ARRAY" | "PREFER_NOT_EXISTS_OVER_NOT_IN";
+type Nudge = {
+  kind: NudgeKind;
+  severity: "CRITICAL" | "WARNING" | "INFO";
+  message: string;
+  location?: number;
+};
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+/**
+ * Detect nudges for a single node during AST traversal.
+ * Returns an array of nudges found for this node.
+ */
+declare function parseNudges(node: Node, stack: (KeysOfUnion<Node> | string)[]): Nudge[];
+//#endregion
+//#region src/sql/walker.d.ts
+type ColumnReferencePart = {
+  schema?: string; /** the text of the column reference (excluding any potential quotes) */
+  text: string;
+  start?: number;
+  quoted: boolean;
+  alias?: string;
+};
+//#endregion
+//#region src/sql/analyzer.d.ts
+interface DatabaseDriver {
+  query(query: string, params: unknown[]): Promise<unknown[]>;
+}
+declare const ignoredIdentifier = "__qd_placeholder";
+interface SQLCommenterTag {
+  key: string;
+  value: string;
+}
+type SortContext = {
+  dir: SortByDir;
+  nulls: SortByNulls;
+};
+type DiscoveredColumnReference = {
+  /** How often the column reference appears in the query. */frequency: number;
+  /**
+   * Representation of the column reference exactly
+   * as it appears in the query.
+   */
+  representation: string;
+  /**
+   * Parts of the column reference separated by dots in the query.
+   * The table reference (if it exists) is resolved if the query
+   * uses an alias.
+   *
+   * Has 3 different potential configurations (in theory)
+   * `a.b.c` - a column reference with a table and a schema reference
+   * `a.b` - a column reference with a table reference but no schema
+   * `a` - a column reference with no table reference.
+   *
+   * We use a simple array here to allow parsing of any syntactically correct
+   * but logically incorrect query. The checks happen later when we're deriving
+   * potential indexes from parts of a column reference in `deriveIndexes`
+   */
+  parts: ColumnReferencePart[];
+  /**
+   * Whether the column reference is invalid. This
+   */
+  ignored: boolean; /** The position of the column reference in the query. */
+  position: {
+    start: number;
+    end: number;
+  };
+  /**
+   * A sort direction associated by the column reference.
+   * Only relevant to references from sorts
+   */
+  sort?: SortContext;
+  where?: {
+    nulltest?: NullTestType;
+  };
+  jsonbOperator?: JsonbOperator;
+};
+type JsonbOperator = "@>" | "?" | "?|" | "?&";
+/** A function defined by @pgsql/parser */
+type Parser = (query: string) => Promise<unknown>;
+type TableReference = {
+  schema?: string;
+  table: string;
+};
+type AnalysisResult = {
+  indexesToCheck: DiscoveredColumnReference[];
+  ansiHighlightedQuery: string;
+  referencedTables: TableReference[];
+  shadowedAliases: ColumnReferencePart[];
+  tags: SQLCommenterTag[];
+  queryWithoutTags: string;
+  formattedQueryWithoutTags?: string;
+  nudges: Nudge[];
+};
+type SQLCommenterExtraction = {
+  tags: SQLCommenterTag[];
+  queryWithoutTags: string;
+};
+/**
+ * Analyzes a query and returns a list of column references that
+ * should be indexed.
+ *
+ * This should be instantiated once per analyzed query.
+ */
+declare class Analyzer {
+  private readonly parser;
+  constructor(parser: Parser);
+  analyze(query: string, formattedQuery?: string): Promise<AnalysisResult>;
+  deriveIndexes(tables: ExportedStats[], discovered: DiscoveredColumnReference[], referencedTables: TableReference[]): RootIndexCandidate[];
+  private filterReferences;
+  private hasColumn;
+  private colorizeKeywords;
+  /**
+   * Resolves aliases such as `a.b` to `x.b` if `a` is a known
+   * alias to a table called x.
+   *
+   * Ignores all other combination of parts such as `a.b.c`
+   */
+  private resolveTableAliases;
+  private normalize;
+  private extractSqlcommenter;
+}
+//#endregion
+//#region src/sql/indexes.d.ts
+declare function isIndexSupported(index: IndexedTable): boolean;
+/**
+ * Doesn't necessarily decide whether the index can be dropped but can be
+ * used to not even try dropping indexes that _definitely_ cannot be dropped
+ */
+declare function isIndexProbablyDroppable(index: IndexedTable): boolean;
+//#endregion
+//#region src/optimizer/pss-rewriter.d.ts
+/**
+ * Rewriter for pg_stat_statements queries.
+ * Not all queries found in pg_stat_statements can be
+ * directly sent back to the database without first being rewritten.
+ */
+declare class PssRewriter {
+  rewrite(query: string): string;
+  private rewriteKeywordWithParameter;
+  private problematicKeywords;
+}
+//#endregion
+export { AnalysisResult, Analyzer, ColumnMetadata, DatabaseDriver, DiscoveredColumnReference, ExportedStats, ExportedStatsColumns, ExportedStatsIndex, ExportedStatsStatistics, ExportedStatsV1, IndexIdentifier, IndexOptimizer, IndexOrder, IndexRecommendation, IndexedTable, JsonbOperator, Nudge, OptimizeResult, PROCEED, Parameter, Parser, Path, PermutedIndexCandidate, PgIdentifier, Postgres, PostgresConnectionInput, PostgresExplainResult, PostgresExplainStage, PostgresExplainStageCommon, PostgresFactory, PostgresQueryBuilder, PostgresQueryBuilderCommand, PostgresStage, PostgresStageId, PostgresTransaction, PostgresVersion, PssRewriter, RootIndexCandidate, SKIP, SQLCommenterExtraction, SQLCommenterTag, SerializeResult, SortContext, Statistics, StatisticsMode, StatisticsSource, TableMetadata, TableReference, TableStats, dropIndex, ignoredIdentifier, isIndexProbablyDroppable, isIndexSupported, parseNudges };
+//# sourceMappingURL=index.d.cts.map