postgresai 0.14.0-dev.55 → 0.14.0-dev.56

package/dist/bin/postgres-ai.js

@@ -13064,7 +13064,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.14.0-dev.55",
+  version: "0.14.0-dev.56",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -13090,7 +13090,7 @@ var package_default = {
   },
   scripts: {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
-    build: `bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))"`,
+    build: `bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql`,
     prepublishOnly: "npm run build",
     start: "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
@@ -15887,7 +15887,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.14.0-dev.55";
+var version = "0.14.0-dev.56";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -15916,7 +15916,7 @@ var package_default2 = {
   },
   scripts: {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
-    build: `bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))"`,
+    build: `bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql`,
     prepublishOnly: "npm run build",
     start: "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
@@ -23474,10 +23474,9 @@ function resolveBaseUrls2(opts, cfg, defaults2 = {}) {
 
 // lib/init.ts
 import { randomBytes } from "crypto";
-import { URL as URL2 } from "url";
+import { URL as URL2, fileURLToPath } from "url";
 import * as fs3 from "fs";
 import * as path3 from "path";
-var __dirname = "/builds/postgres-ai/postgres_ai/cli/lib";
 var DEFAULT_MONITORING_USER = "postgres_ai_mon";
 function sslModeToConfig(mode) {
   if (mode.toLowerCase() === "disable")
@@ -23558,9 +23557,11 @@ async function connectWithSslFallback(ClientClass, adminConn, verbose) {
   }
 }
 function sqlDir() {
+  const currentFile = fileURLToPath(import.meta.url);
+  const currentDir = path3.dirname(currentFile);
   const candidates = [
-    path3.resolve(__dirname, "..", "sql"),
-    path3.resolve(__dirname, "..", "..", "sql")
+    path3.resolve(currentDir, "..", "sql"),
+    path3.resolve(currentDir, "..", "..", "sql")
   ];
   for (const candidate of candidates) {
     if (fs3.existsSync(candidate)) {
@@ -24517,6 +24518,7 @@ where
     quote_ident(pci.relname) as tag_index_name,
     quote_ident(pct.relname) as tag_table_name,
     coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,
+    pg_get_indexdef(pidx.indexrelid) as index_definition,
     pg_relation_size(pidx.indexrelid) index_size_bytes,
     ((
       select count(1)
@@ -25154,6 +25156,7 @@ async function getInvalidIndexes(client, pgMajorVersion = 16) {
       relation_name: String(transformed.relation_name || ""),
       index_size_bytes: indexSizeBytes,
       index_size_pretty: formatBytes(indexSizeBytes),
+      index_definition: String(transformed.index_definition || ""),
       supports_fk: toBool(transformed.supports_fk)
     };
   });

package/dist/sql/01.role.sql

@@ -0,0 +1,16 @@
+-- Role creation / password update (template-filled by cli/lib/init.ts)
+--
+-- Always uses a race-safe pattern (create if missing, then always alter to set the password):
+--   do $$ begin
+--     if not exists (select 1 from pg_catalog.pg_roles where rolname = '...') then
+--       begin
+--         create user "..." with password '...';
+--       exception when duplicate_object then
+--         null;
+--       end;
+--     end if;
+--     alter user "..." with password '...';
+--   end $$;
+{{ROLE_STMT}}
+
+

package/dist/sql/02.permissions.sql

@@ -0,0 +1,37 @@
+-- Required permissions for postgres_ai monitoring user (template-filled by cli/lib/init.ts)
+
+-- Allow connect
+grant connect on database {{DB_IDENT}} to {{ROLE_IDENT}};
+
+-- Standard monitoring privileges
+grant pg_monitor to {{ROLE_IDENT}};
+grant select on pg_catalog.pg_index to {{ROLE_IDENT}};
+
+-- Create postgres_ai schema for our objects
+create schema if not exists postgres_ai;
+grant usage on schema postgres_ai to {{ROLE_IDENT}};
+
+-- For bloat analysis: expose pg_statistic via a view
+create or replace view postgres_ai.pg_statistic as
+select
+    n.nspname as schemaname,
+    c.relname as tablename,
+    a.attname,
+    s.stanullfrac as null_frac,
+    s.stawidth as avg_width,
+    false as inherited
+from pg_catalog.pg_statistic s
+join pg_catalog.pg_class c on c.oid = s.starelid
+join pg_catalog.pg_namespace n on n.oid = c.relnamespace
+join pg_catalog.pg_attribute a on a.attrelid = s.starelid and a.attnum = s.staattnum
+where a.attnum > 0 and not a.attisdropped;
+
+grant select on postgres_ai.pg_statistic to {{ROLE_IDENT}};
+
+-- Hardened clusters sometimes revoke PUBLIC on schema public
+grant usage on schema public to {{ROLE_IDENT}};
+
+-- Keep search_path predictable; postgres_ai first so our objects are found
+alter user {{ROLE_IDENT}} set search_path = postgres_ai, "$user", public, pg_catalog;
+
+

package/dist/sql/03.optional_rds.sql

@@ -0,0 +1,6 @@
+-- Optional permissions for RDS Postgres / Aurora (best effort)
+
+create extension if not exists rds_tools;
+grant execute on function rds_tools.pg_ls_multixactdir() to {{ROLE_IDENT}};
+
+

package/dist/sql/04.optional_self_managed.sql

@@ -0,0 +1,8 @@
+-- Optional permissions for self-managed Postgres (best effort)
+
+grant execute on function pg_catalog.pg_stat_file(text) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_stat_file(text, boolean) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_ls_dir(text) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_ls_dir(text, boolean, boolean) to {{ROLE_IDENT}};
+
+

package/dist/sql/05.helpers.sql

@@ -0,0 +1,415 @@
+-- Helper functions for postgres_ai monitoring user (template-filled by cli/lib/init.ts)
+-- These functions use SECURITY DEFINER to allow the monitoring user to perform
+-- operations they don't have direct permissions for.
+
+/*
+ * pgai_explain_generic
+ *
+ * Function to get generic explain plans with optional HypoPG index testing.
+ * Requires: PostgreSQL 16+ (for generic_plan option), HypoPG extension (optional).
+ *
+ * Usage examples:
+ *   -- Basic generic plan
+ *   select postgres_ai.explain_generic('select * from users where id = $1');
+ *
+ *   -- JSON format
+ *   select postgres_ai.explain_generic('select * from users where id = $1', 'json');
+ *
+ *   -- Test a hypothetical index
+ *   select postgres_ai.explain_generic(
+ *     'select * from users where email = $1',
+ *     'text',
+ *     'create index on users (email)'
+ *   );
+ */
+create or replace function postgres_ai.explain_generic(
+  in query text,
+  in format text default 'text',
+  in hypopg_index text default null,
+  out result text
+)
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  v_line record;
+  v_lines text[] := '{}';
+  v_explain_query text;
+  v_hypo_result record;
+  v_version int;
+  v_hypopg_available boolean;
+begin
+  -- Check PostgreSQL version (generic_plan requires 16+)
+  select current_setting('server_version_num')::int into v_version;
+
+  if v_version < 160000 then
+    raise exception 'generic_plan requires PostgreSQL 16+, current version: %',
+      current_setting('server_version');
+  end if;
+
+  -- Check if HypoPG extension is available
+  if hypopg_index is not null then
+    select exists(
+      select 1 from pg_extension where extname = 'hypopg'
+    ) into v_hypopg_available;
+
+    if not v_hypopg_available then
+      raise exception 'HypoPG extension is required for hypothetical index testing but is not installed';
+    end if;
+
+    -- Create hypothetical index
+    select * into v_hypo_result from hypopg_create_index(hypopg_index);
+    raise notice 'Created hypothetical index: % (oid: %)',
+      v_hypo_result.indexname, v_hypo_result.indexrelid;
+  end if;
+
+  -- Build and execute explain query based on format
+  -- Output is preserved exactly as EXPLAIN returns it
+  begin
+    if lower(format) = 'json' then
+      v_explain_query := 'explain (verbose, settings, generic_plan, format json) ' || query;
+      execute v_explain_query into result;
+    else
+      v_explain_query := 'explain (verbose, settings, generic_plan) ' || query;
+      for v_line in execute v_explain_query loop
+        v_lines := array_append(v_lines, v_line."QUERY PLAN");
+      end loop;
+      result := array_to_string(v_lines, e'\n');
+    end if;
+  exception when others then
+    -- Clean up hypothetical index before re-raising
+    if hypopg_index is not null then
+      perform hypopg_reset();
+    end if;
+    raise;
+  end;
+
+  -- Clean up hypothetical index
+  if hypopg_index is not null then
+    perform hypopg_reset();
+  end if;
+end;
+$$;
+
+comment on function postgres_ai.explain_generic(text, text, text) is
+  'Returns generic EXPLAIN plan with optional HypoPG index testing (requires PG16+)';
+
+-- Grant execute to the monitoring user
+grant execute on function postgres_ai.explain_generic(text, text, text) to {{ROLE_IDENT}};
+
+/*
+ * table_describe
+ *
+ * Collects comprehensive information about a table for LLM analysis.
+ * Returns a compact text format with:
+ * - Table metadata (type, size estimates)
+ * - Columns (name, type, nullable, default)
+ * - Indexes
+ * - Constraints (PK, FK, unique, check)
+ * - Maintenance stats (vacuum/analyze times)
+ *
+ * Usage:
+ *   select postgres_ai.table_describe('public.users');
+ *   select postgres_ai.table_describe('my_table');  -- uses search_path
+ */
+create or replace function postgres_ai.table_describe(
+  in table_name text,
+  out result text
+)
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  v_oid oid;
+  v_schema text;
+  v_table text;
+  v_relkind char;
+  v_relpages int;
+  v_reltuples float;
+  v_lines text[] := '{}';
+  v_line text;
+  v_rec record;
+  v_constraint_count int := 0;
+begin
+  -- Resolve table name to OID (handles schema-qualified and search_path)
+  v_oid := table_name::regclass::oid;
+
+  -- Get basic table info
+  select
+    n.nspname,
+    c.relname,
+    c.relkind,
+    c.relpages,
+    c.reltuples
+  into v_schema, v_table, v_relkind, v_relpages, v_reltuples
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+  where c.oid = v_oid;
+
+  -- Validate object type - only tables, views, and materialized views are supported
+  if v_relkind not in ('r', 'p', 'v', 'm', 'f') then
+    raise exception 'table_describe does not support % (relkind=%)',
+      case v_relkind
+        when 'i' then 'indexes'
+        when 'I' then 'partitioned indexes'
+        when 'S' then 'sequences'
+        when 't' then 'TOAST tables'
+        when 'c' then 'composite types'
+        else format('objects of type "%s"', v_relkind)
+      end,
+      v_relkind;
+  end if;
+
+  -- Header
+  v_lines := array_append(v_lines, format('Table: %I.%I', v_schema, v_table));
+  v_lines := array_append(v_lines, format('Type: %s | relpages: %s | reltuples: %s',
+    case v_relkind
+      when 'r' then 'table'
+      when 'p' then 'partitioned table'
+      when 'v' then 'view'
+      when 'm' then 'materialized view'
+      when 'f' then 'foreign table'
+    end,
+    v_relpages,
+    case when v_reltuples < 0 then '-1' else v_reltuples::bigint::text end
+  ));
+
+  -- Vacuum/analyze stats (only for tables and materialized views, not views)
+  if v_relkind in ('r', 'p', 'm', 'f') then
+    select
+      format('Vacuum: %s (auto: %s) | Analyze: %s (auto: %s)',
+        coalesce(to_char(last_vacuum at time zone 'UTC', 'YYYY-MM-DD HH24:MI:SS UTC'), 'never'),
+        coalesce(to_char(last_autovacuum at time zone 'UTC', 'YYYY-MM-DD HH24:MI:SS UTC'), 'never'),
+        coalesce(to_char(last_analyze at time zone 'UTC', 'YYYY-MM-DD HH24:MI:SS UTC'), 'never'),
+        coalesce(to_char(last_autoanalyze at time zone 'UTC', 'YYYY-MM-DD HH24:MI:SS UTC'), 'never')
+      )
+    into v_line
+    from pg_stat_all_tables
+    where relid = v_oid;
+
+    if v_line is not null then
+      v_lines := array_append(v_lines, v_line);
+    end if;
+  end if;
+
+  v_lines := array_append(v_lines, '');
+
+  -- Columns
+  v_lines := array_append(v_lines, 'Columns:');
+  for v_rec in
+    select
+      a.attname,
+      format_type(a.atttypid, a.atttypmod) as data_type,
+      a.attnotnull,
+      (select pg_get_expr(d.adbin, d.adrelid, true)
+       from pg_attrdef d
+       where d.adrelid = a.attrelid and d.adnum = a.attnum and a.atthasdef) as default_val,
+      a.attidentity,
+      a.attgenerated
+    from pg_attribute a
+    where a.attrelid = v_oid
+      and a.attnum > 0
+      and not a.attisdropped
+    order by a.attnum
+  loop
+    v_line := format('  %s %s', v_rec.attname, v_rec.data_type);
+
+    if v_rec.attnotnull then
+      v_line := v_line || ' NOT NULL';
+    end if;
+
+    if v_rec.attidentity = 'a' then
+      v_line := v_line || ' GENERATED ALWAYS AS IDENTITY';
+    elsif v_rec.attidentity = 'd' then
+      v_line := v_line || ' GENERATED BY DEFAULT AS IDENTITY';
+    elsif v_rec.attgenerated = 's' then
+      v_line := v_line || format(' GENERATED ALWAYS AS (%s) STORED', v_rec.default_val);
+    elsif v_rec.default_val is not null then
+      v_line := v_line || format(' DEFAULT %s', v_rec.default_val);
+    end if;
+
+    v_lines := array_append(v_lines, v_line);
+  end loop;
+
+  -- View definition (for views and materialized views)
+  if v_relkind in ('v', 'm') then
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Definition:');
+    v_line := pg_get_viewdef(v_oid, true);
+    if v_line is not null then
+      -- Indent the view definition
+      v_line := '  ' || replace(v_line, e'\n', e'\n  ');
+      v_lines := array_append(v_lines, v_line);
+    end if;
+  end if;
+
+  -- Indexes (tables, partitioned tables, and materialized views can have indexes)
+  if v_relkind in ('r', 'p', 'm') then
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Indexes:');
+    for v_rec in
+      select
+        i.relname as index_name,
+        pg_get_indexdef(i.oid) as index_def,
+        ix.indisprimary,
+        ix.indisunique
+      from pg_index ix
+      join pg_class i on i.oid = ix.indexrelid
+      where ix.indrelid = v_oid
+      order by ix.indisprimary desc, ix.indisunique desc, i.relname
+    loop
+      v_line := '  ';
+      if v_rec.indisprimary then
+        v_line := v_line || 'PRIMARY KEY: ';
+      elsif v_rec.indisunique then
+        v_line := v_line || 'UNIQUE: ';
+      else
+        v_line := v_line || 'INDEX: ';
+      end if;
+      -- Extract just the column part from index definition
+      v_line := v_line || v_rec.index_name || ' ' ||
+        regexp_replace(v_rec.index_def, '^CREATE.*INDEX.*ON.*USING\s+\w+\s*', '');
+      v_lines := array_append(v_lines, v_line);
+    end loop;
+
+    if not exists (select 1 from pg_index where indrelid = v_oid) then
+      v_lines := array_append(v_lines, '  (none)');
+    end if;
+  end if;
+
+  -- Constraints (only tables can have constraints)
+  if v_relkind in ('r', 'p', 'f') then
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Constraints:');
+    v_constraint_count := 0;
+
+    for v_rec in
+      select
+        conname,
+        contype,
+        pg_get_constraintdef(oid, true) as condef
+      from pg_constraint
+      where conrelid = v_oid
+        and contype != 'p'  -- skip primary key (shown with indexes)
+      order by
+        case contype when 'f' then 1 when 'u' then 2 when 'c' then 3 else 4 end,
+        conname
+    loop
+      v_constraint_count := v_constraint_count + 1;
+      v_line := '  ';
+      case v_rec.contype
+        when 'f' then v_line := v_line || 'FK: ';
+        when 'u' then v_line := v_line || 'UNIQUE: ';
+        when 'c' then v_line := v_line || 'CHECK: ';
+        else v_line := v_line || v_rec.contype || ': ';
+      end case;
+      v_line := v_line || v_rec.conname || ' ' || v_rec.condef;
+      v_lines := array_append(v_lines, v_line);
+    end loop;
+
+    if v_constraint_count = 0 then
+      v_lines := array_append(v_lines, '  (none)');
+    end if;
+
+    -- Foreign keys referencing this table
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Referenced by:');
+    v_constraint_count := 0;
+
+    for v_rec in
+      select
+        conname,
+        conrelid::regclass::text as from_table,
+        pg_get_constraintdef(oid, true) as condef
+      from pg_constraint
+      where confrelid = v_oid
+        and contype = 'f'
+      order by conrelid::regclass::text, conname
+    loop
+      v_constraint_count := v_constraint_count + 1;
+      v_lines := array_append(v_lines, format('  %s.%s %s',
+        v_rec.from_table, v_rec.conname, v_rec.condef));
+    end loop;
+
+    if v_constraint_count = 0 then
+      v_lines := array_append(v_lines, '  (none)');
+    end if;
+  end if;
+
+  -- Partition info (if partitioned table or partition)
+  if v_relkind = 'p' then
+    -- This is a partitioned table - show partition key and partitions
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Partitioning:');
+
+    select format('  %s BY %s',
+      case partstrat
+        when 'r' then 'RANGE'
+        when 'l' then 'LIST'
+        when 'h' then 'HASH'
+        else partstrat
+      end,
+      pg_get_partkeydef(v_oid)
+    )
+    into v_line
+    from pg_partitioned_table
+    where partrelid = v_oid;
+
+    if v_line is not null then
+      v_lines := array_append(v_lines, v_line);
+    end if;
+
+    -- List partitions
+    v_constraint_count := 0;
+    for v_rec in
+      select
+        c.oid::regclass::text as partition_name,
+        pg_get_expr(c.relpartbound, c.oid) as partition_bound,
+        c.relpages,
+        c.reltuples
+      from pg_inherits i
+      join pg_class c on c.oid = i.inhrelid
+      where i.inhparent = v_oid
+      order by c.oid::regclass::text
+    loop
+      v_constraint_count := v_constraint_count + 1;
+      v_lines := array_append(v_lines, format('  %s: %s (relpages: %s, reltuples: %s)',
+        v_rec.partition_name, v_rec.partition_bound,
+        v_rec.relpages,
+        case when v_rec.reltuples < 0 then '-1' else v_rec.reltuples::bigint::text end
+      ));
+    end loop;
+
+    v_lines := array_append(v_lines, format('  Total partitions: %s', v_constraint_count));
+
+  elsif exists (select 1 from pg_inherits where inhrelid = v_oid) then
+    -- This is a partition - show parent and bound
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Partition of:');
+
+    select format('  %s FOR VALUES %s',
+      i.inhparent::regclass::text,
+      pg_get_expr(c.relpartbound, c.oid)
+    )
+    into v_line
+    from pg_inherits i
+    join pg_class c on c.oid = i.inhrelid
+    where i.inhrelid = v_oid;
+
+    if v_line is not null then
+      v_lines := array_append(v_lines, v_line);
+    end if;
+  end if;
+
+  result := array_to_string(v_lines, e'\n');
+end;
+$$;
+
+comment on function postgres_ai.table_describe(text) is
+  'Returns comprehensive table information in compact text format for LLM analysis';
+
+grant execute on function postgres_ai.table_describe(text) to {{ROLE_IDENT}};
+
+

package/dist/sql/sql/01.role.sql

@@ -0,0 +1,16 @@
+-- Role creation / password update (template-filled by cli/lib/init.ts)
+--
+-- Always uses a race-safe pattern (create if missing, then always alter to set the password):
+--   do $$ begin
+--     if not exists (select 1 from pg_catalog.pg_roles where rolname = '...') then
+--       begin
+--         create user "..." with password '...';
+--       exception when duplicate_object then
+--         null;
+--       end;
+--     end if;
+--     alter user "..." with password '...';
+--   end $$;
+{{ROLE_STMT}}
+
+

package/dist/sql/sql/02.permissions.sql

@@ -0,0 +1,37 @@
+-- Required permissions for postgres_ai monitoring user (template-filled by cli/lib/init.ts)
+
+-- Allow connect
+grant connect on database {{DB_IDENT}} to {{ROLE_IDENT}};
+
+-- Standard monitoring privileges
+grant pg_monitor to {{ROLE_IDENT}};
+grant select on pg_catalog.pg_index to {{ROLE_IDENT}};
+
+-- Create postgres_ai schema for our objects
+create schema if not exists postgres_ai;
+grant usage on schema postgres_ai to {{ROLE_IDENT}};
+
+-- For bloat analysis: expose pg_statistic via a view
+create or replace view postgres_ai.pg_statistic as
+select
+    n.nspname as schemaname,
+    c.relname as tablename,
+    a.attname,
+    s.stanullfrac as null_frac,
+    s.stawidth as avg_width,
+    false as inherited
+from pg_catalog.pg_statistic s
+join pg_catalog.pg_class c on c.oid = s.starelid
+join pg_catalog.pg_namespace n on n.oid = c.relnamespace
+join pg_catalog.pg_attribute a on a.attrelid = s.starelid and a.attnum = s.staattnum
+where a.attnum > 0 and not a.attisdropped;
+
+grant select on postgres_ai.pg_statistic to {{ROLE_IDENT}};
+
+-- Hardened clusters sometimes revoke PUBLIC on schema public
+grant usage on schema public to {{ROLE_IDENT}};
+
+-- Keep search_path predictable; postgres_ai first so our objects are found
+alter user {{ROLE_IDENT}} set search_path = postgres_ai, "$user", public, pg_catalog;
+
+

package/dist/sql/sql/03.optional_rds.sql

@@ -0,0 +1,6 @@
+-- Optional permissions for RDS Postgres / Aurora (best effort)
+
+create extension if not exists rds_tools;
+grant execute on function rds_tools.pg_ls_multixactdir() to {{ROLE_IDENT}};
+
+

package/dist/sql/sql/04.optional_self_managed.sql

@@ -0,0 +1,8 @@
+-- Optional permissions for self-managed Postgres (best effort)
+
+grant execute on function pg_catalog.pg_stat_file(text) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_stat_file(text, boolean) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_ls_dir(text) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_ls_dir(text, boolean, boolean) to {{ROLE_IDENT}};
+
+

package/dist/sql/sql/05.helpers.sql

@@ -0,0 +1,415 @@
+-- Helper functions for postgres_ai monitoring user (template-filled by cli/lib/init.ts)
+-- These functions use SECURITY DEFINER to allow the monitoring user to perform
+-- operations they don't have direct permissions for.
+
+/*
+ * pgai_explain_generic
+ *
+ * Function to get generic explain plans with optional HypoPG index testing.
+ * Requires: PostgreSQL 16+ (for generic_plan option), HypoPG extension (optional).
+ *
+ * Usage examples:
+ *   -- Basic generic plan
+ *   select postgres_ai.explain_generic('select * from users where id = $1');
+ *
+ *   -- JSON format
+ *   select postgres_ai.explain_generic('select * from users where id = $1', 'json');
+ *
+ *   -- Test a hypothetical index
+ *   select postgres_ai.explain_generic(
+ *     'select * from users where email = $1',
+ *     'text',
+ *     'create index on users (email)'
+ *   );
+ */
+create or replace function postgres_ai.explain_generic(
+  in query text,
+  in format text default 'text',
+  in hypopg_index text default null,
+  out result text
+)
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  v_line record;
+  v_lines text[] := '{}';
+  v_explain_query text;
+  v_hypo_result record;
+  v_version int;
+  v_hypopg_available boolean;
+begin
+  -- Check PostgreSQL version (generic_plan requires 16+)
+  select current_setting('server_version_num')::int into v_version;
+
+  if v_version < 160000 then
+    raise exception 'generic_plan requires PostgreSQL 16+, current version: %',
+      current_setting('server_version');
+  end if;
+
+  -- Check if HypoPG extension is available
+  if hypopg_index is not null then
+    select exists(
+      select 1 from pg_extension where extname = 'hypopg'
+    ) into v_hypopg_available;
+
+    if not v_hypopg_available then
+      raise exception 'HypoPG extension is required for hypothetical index testing but is not installed';
+    end if;
+
+    -- Create hypothetical index
+    select * into v_hypo_result from hypopg_create_index(hypopg_index);
+    raise notice 'Created hypothetical index: % (oid: %)',
+      v_hypo_result.indexname, v_hypo_result.indexrelid;
+  end if;
+
+  -- Build and execute explain query based on format
+  -- Output is preserved exactly as EXPLAIN returns it
+  begin
+    if lower(format) = 'json' then
+      v_explain_query := 'explain (verbose, settings, generic_plan, format json) ' || query;
+      execute v_explain_query into result;
+    else
+      v_explain_query := 'explain (verbose, settings, generic_plan) ' || query;
+      for v_line in execute v_explain_query loop
+        v_lines := array_append(v_lines, v_line."QUERY PLAN");
+      end loop;
+      result := array_to_string(v_lines, e'\n');
+    end if;
+  exception when others then
+    -- Clean up hypothetical index before re-raising
+    if hypopg_index is not null then
+      perform hypopg_reset();
+    end if;
+    raise;
+  end;
+
+  -- Clean up hypothetical index
+  if hypopg_index is not null then
+    perform hypopg_reset();
+  end if;
+end;
+$$;
+
+comment on function postgres_ai.explain_generic(text, text, text) is
+  'Returns generic EXPLAIN plan with optional HypoPG index testing (requires PG16+)';
+
+-- Grant execute to the monitoring user
+grant execute on function postgres_ai.explain_generic(text, text, text) to {{ROLE_IDENT}};
+
+/*
+ * table_describe
+ *
+ * Collects comprehensive information about a table for LLM analysis.
+ * Returns a compact text format with:
+ * - Table metadata (type, size estimates)
+ * - Columns (name, type, nullable, default)
+ * - Indexes
+ * - Constraints (PK, FK, unique, check)
+ * - Maintenance stats (vacuum/analyze times)
+ *
+ * Usage:
+ *   select postgres_ai.table_describe('public.users');
+ *   select postgres_ai.table_describe('my_table');  -- uses search_path
+ */
+create or replace function postgres_ai.table_describe(
+  in table_name text,
+  out result text
+)
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  v_oid oid;
+  v_schema text;
+  v_table text;
+  v_relkind char;
+  v_relpages int;
+  v_reltuples float;
+  v_lines text[] := '{}';
+  v_line text;
+  v_rec record;
+  v_constraint_count int := 0;
+begin
+  -- Resolve table name to OID (handles schema-qualified and search_path)
+  v_oid := table_name::regclass::oid;
+
+  -- Get basic table info
+  select
+    n.nspname,
+    c.relname,
+    c.relkind,
+    c.relpages,
+    c.reltuples
+  into v_schema, v_table, v_relkind, v_relpages, v_reltuples
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+  where c.oid = v_oid;
+
+  -- Validate object type - only tables, views, and materialized views are supported
+  if v_relkind not in ('r', 'p', 'v', 'm', 'f') then
+    raise exception 'table_describe does not support % (relkind=%)',
+      case v_relkind
+        when 'i' then 'indexes'
+        when 'I' then 'partitioned indexes'
+        when 'S' then 'sequences'
+        when 't' then 'TOAST tables'
+        when 'c' then 'composite types'
+        else format('objects of type "%s"', v_relkind)
+      end,
+      v_relkind;
+  end if;
+
+  -- Header
+  v_lines := array_append(v_lines, format('Table: %I.%I', v_schema, v_table));
+  v_lines := array_append(v_lines, format('Type: %s | relpages: %s | reltuples: %s',
+    case v_relkind
+      when 'r' then 'table'
+      when 'p' then 'partitioned table'
+      when 'v' then 'view'
+      when 'm' then 'materialized view'
+      when 'f' then 'foreign table'
+    end,
+    v_relpages,
+    case when v_reltuples < 0 then '-1' else v_reltuples::bigint::text end
+  ));
+
+  -- Vacuum/analyze stats (only for tables and materialized views, not views)
+  if v_relkind in ('r', 'p', 'm', 'f') then
+    select
+      format('Vacuum: %s (auto: %s) | Analyze: %s (auto: %s)',
+        coalesce(to_char(last_vacuum at time zone 'UTC', 'YYYY-MM-DD HH24:MI:SS UTC'), 'never'),
+        coalesce(to_char(last_autovacuum at time zone 'UTC', 'YYYY-MM-DD HH24:MI:SS UTC'), 'never'),
+        coalesce(to_char(last_analyze at time zone 'UTC', 'YYYY-MM-DD HH24:MI:SS UTC'), 'never'),
+        coalesce(to_char(last_autoanalyze at time zone 'UTC', 'YYYY-MM-DD HH24:MI:SS UTC'), 'never')
+      )
+    into v_line
+    from pg_stat_all_tables
+    where relid = v_oid;
+
+    if v_line is not null then
+      v_lines := array_append(v_lines, v_line);
+    end if;
+  end if;
+
+  v_lines := array_append(v_lines, '');
+
+  -- Columns
+  v_lines := array_append(v_lines, 'Columns:');
+  for v_rec in
+    select
+      a.attname,
+      format_type(a.atttypid, a.atttypmod) as data_type,
+      a.attnotnull,
+      (select pg_get_expr(d.adbin, d.adrelid, true)
+       from pg_attrdef d
+       where d.adrelid = a.attrelid and d.adnum = a.attnum and a.atthasdef) as default_val,
+      a.attidentity,
+      a.attgenerated
+    from pg_attribute a
+    where a.attrelid = v_oid
+      and a.attnum > 0
+      and not a.attisdropped
+    order by a.attnum
+  loop
+    v_line := format('  %s %s', v_rec.attname, v_rec.data_type);
+
+    if v_rec.attnotnull then
+      v_line := v_line || ' NOT NULL';
+    end if;
+
+    if v_rec.attidentity = 'a' then
+      v_line := v_line || ' GENERATED ALWAYS AS IDENTITY';
+    elsif v_rec.attidentity = 'd' then
+      v_line := v_line || ' GENERATED BY DEFAULT AS IDENTITY';
+    elsif v_rec.attgenerated = 's' then
+      v_line := v_line || format(' GENERATED ALWAYS AS (%s) STORED', v_rec.default_val);
+    elsif v_rec.default_val is not null then
+      v_line := v_line || format(' DEFAULT %s', v_rec.default_val);
+    end if;
+
+    v_lines := array_append(v_lines, v_line);
+  end loop;
+
+  -- View definition (for views and materialized views)
+  if v_relkind in ('v', 'm') then
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Definition:');
+    v_line := pg_get_viewdef(v_oid, true);
+    if v_line is not null then
+      -- Indent the view definition
+      v_line := '  ' || replace(v_line, e'\n', e'\n  ');
+      v_lines := array_append(v_lines, v_line);
+    end if;
+  end if;
+
+  -- Indexes (tables, partitioned tables, and materialized views can have indexes)
+  if v_relkind in ('r', 'p', 'm') then
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Indexes:');
+    for v_rec in
+      select
+        i.relname as index_name,
+        pg_get_indexdef(i.oid) as index_def,
+        ix.indisprimary,
+        ix.indisunique
+      from pg_index ix
+      join pg_class i on i.oid = ix.indexrelid
+      where ix.indrelid = v_oid
+      order by ix.indisprimary desc, ix.indisunique desc, i.relname
+    loop
+      v_line := '  ';
+      if v_rec.indisprimary then
+        v_line := v_line || 'PRIMARY KEY: ';
+      elsif v_rec.indisunique then
+        v_line := v_line || 'UNIQUE: ';
+      else
+        v_line := v_line || 'INDEX: ';
+      end if;
+      -- Extract just the column part from index definition
+      v_line := v_line || v_rec.index_name || ' ' ||
+        regexp_replace(v_rec.index_def, '^CREATE.*INDEX.*ON.*USING\s+\w+\s*', '');
+      v_lines := array_append(v_lines, v_line);
+    end loop;
+
+    if not exists (select 1 from pg_index where indrelid = v_oid) then
+      v_lines := array_append(v_lines, '  (none)');
+    end if;
+  end if;
+
+  -- Constraints (only tables can have constraints)
+  if v_relkind in ('r', 'p', 'f') then
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Constraints:');
+    v_constraint_count := 0;
+
+    for v_rec in
+      select
+        conname,
+        contype,
+        pg_get_constraintdef(oid, true) as condef
+      from pg_constraint
+      where conrelid = v_oid
+        and contype != 'p'  -- skip primary key (shown with indexes)
+      order by
+        case contype when 'f' then 1 when 'u' then 2 when 'c' then 3 else 4 end,
+        conname
+    loop
+      v_constraint_count := v_constraint_count + 1;
+      v_line := '  ';
+      case v_rec.contype
+        when 'f' then v_line := v_line || 'FK: ';
+        when 'u' then v_line := v_line || 'UNIQUE: ';
+        when 'c' then v_line := v_line || 'CHECK: ';
+        else v_line := v_line || v_rec.contype || ': ';
+      end case;
+      v_line := v_line || v_rec.conname || ' ' || v_rec.condef;
+      v_lines := array_append(v_lines, v_line);
+    end loop;
+
+    if v_constraint_count = 0 then
+      v_lines := array_append(v_lines, '  (none)');
+    end if;
+
+    -- Foreign keys referencing this table
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Referenced by:');
+    v_constraint_count := 0;
+
+    for v_rec in
+      select
+        conname,
+        conrelid::regclass::text as from_table,
+        pg_get_constraintdef(oid, true) as condef
+      from pg_constraint
+      where confrelid = v_oid
+        and contype = 'f'
+      order by conrelid::regclass::text, conname
+    loop
+      v_constraint_count := v_constraint_count + 1;
+      v_lines := array_append(v_lines, format('  %s.%s %s',
+        v_rec.from_table, v_rec.conname, v_rec.condef));
+    end loop;
+
+    if v_constraint_count = 0 then
+      v_lines := array_append(v_lines, '  (none)');
+    end if;
+  end if;
+
+  -- Partition info (if partitioned table or partition)
+  if v_relkind = 'p' then
+    -- This is a partitioned table - show partition key and partitions
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Partitioning:');
+
+    select format('  %s BY %s',
+      case partstrat
+        when 'r' then 'RANGE'
+        when 'l' then 'LIST'
+        when 'h' then 'HASH'
+        else partstrat
+      end,
+      pg_get_partkeydef(v_oid)
+    )
+    into v_line
+    from pg_partitioned_table
+    where partrelid = v_oid;
+
+    if v_line is not null then
+      v_lines := array_append(v_lines, v_line);
+    end if;
+
+    -- List partitions
+    v_constraint_count := 0;
+    for v_rec in
+      select
+        c.oid::regclass::text as partition_name,
+        pg_get_expr(c.relpartbound, c.oid) as partition_bound,
+        c.relpages,
+        c.reltuples
+      from pg_inherits i
+      join pg_class c on c.oid = i.inhrelid
+      where i.inhparent = v_oid
+      order by c.oid::regclass::text
+    loop
+      v_constraint_count := v_constraint_count + 1;
+      v_lines := array_append(v_lines, format('  %s: %s (relpages: %s, reltuples: %s)',
+        v_rec.partition_name, v_rec.partition_bound,
+        v_rec.relpages,
+        case when v_rec.reltuples < 0 then '-1' else v_rec.reltuples::bigint::text end
+      ));
+    end loop;
+
+    v_lines := array_append(v_lines, format('  Total partitions: %s', v_constraint_count));
+
+  elsif exists (select 1 from pg_inherits where inhrelid = v_oid) then
+    -- This is a partition - show parent and bound
+    v_lines := array_append(v_lines, '');
+    v_lines := array_append(v_lines, 'Partition of:');
+
+    select format('  %s FOR VALUES %s',
+      i.inhparent::regclass::text,
+      pg_get_expr(c.relpartbound, c.oid)
+    )
+    into v_line
+    from pg_inherits i
+    join pg_class c on c.oid = i.inhrelid
+    where i.inhrelid = v_oid;
+
+    if v_line is not null then
+      v_lines := array_append(v_lines, v_line);
+    end if;
+  end if;
+
+  result := array_to_string(v_lines, e'\n');
+end;
+$$;
+
+comment on function postgres_ai.table_describe(text) is
+  'Returns comprehensive table information in compact text format for LLM analysis';
+
+grant execute on function postgres_ai.table_describe(text) to {{ROLE_IDENT}};
+
+

package/lib/checkup.ts

@@ -117,6 +117,8 @@ export interface InvalidIndex {
   relation_name: string;
   index_size_bytes: number;
   index_size_pretty: string;
+  /** Full CREATE INDEX statement from pg_get_indexdef(), useful for DROP/CREATE migrations */
+  index_definition: string;
   supports_fk: boolean;
 }
 
@@ -581,6 +583,7 @@ export async function getInvalidIndexes(client: Client, pgMajorVersion: number =
       relation_name: String(transformed.relation_name || ""),
       index_size_bytes: indexSizeBytes,
       index_size_pretty: formatBytes(indexSizeBytes),
+      index_definition: String(transformed.index_definition || ""),
       supports_fk: toBool(transformed.supports_fk),
     };
   });

package/lib/init.ts

@@ -1,5 +1,5 @@
 import { randomBytes } from "crypto";
-import { URL } from "url";
+import { URL, fileURLToPath } from "url";
 import type { ConnectionOptions as TlsConnectionOptions } from "tls";
 import type { Client as PgClient } from "pg";
 import * as fs from "fs";
@@ -163,9 +163,15 @@ function sqlDir(): string {
   // Handle both development and production paths
   // Development: lib/init.ts -> ../sql
   // Production (bundled): dist/bin/postgres-ai.js -> ../sql (copied during build)
+  //
+  // IMPORTANT: Use import.meta.url instead of __dirname because bundlers (bun/esbuild)
+  // bake in __dirname at build time, while import.meta.url resolves at runtime.
+  const currentFile = fileURLToPath(import.meta.url);
+  const currentDir = path.dirname(currentFile);
+
   const candidates = [
-    path.resolve(__dirname, "..", "sql"),       // bundled: dist/bin -> dist/sql
-    path.resolve(__dirname, "..", "..", "sql"), // dev from lib: lib -> ../sql
+    path.resolve(currentDir, "..", "sql"),       // bundled: dist/bin -> dist/sql
+    path.resolve(currentDir, "..", "..", "sql"), // dev from lib: lib -> ../sql
   ];
 
   for (const candidate of candidates) {

package/lib/metrics-embedded.ts

@@ -1,6 +1,6 @@
 // AUTO-GENERATED FILE - DO NOT EDIT
 // Generated from config/pgwatch-prometheus/metrics.yml by scripts/embed-metrics.ts
-// Generated at: 2025-12-29T17:55:05.936Z
+// Generated at: 2025-12-29T19:46:00.537Z
 
 /**
  * Metric definition from metrics.yml
@@ -47,7 +47,7 @@ export const METRICS: Record<string, MetricDefinition> = {
   "pg_invalid_indexes": {
     description: "This metric identifies invalid indexes in the database. It provides insights into the number of invalid indexes and their details. This metric helps administrators identify and fix invalid indexes to improve database performance.",
     sqls: {
-      11: "with fk_indexes as ( /* pgwatch_generated */\n  select\n    schemaname as tag_schema_name,\n    (indexrelid::regclass)::text as tag_index_name,\n    (relid::regclass)::text as tag_table_name,\n    (confrelid::regclass)::text as tag_fk_table_ref,\n    array_to_string(indclass, ', ') as tag_opclasses\n  from\n    pg_stat_all_indexes\n  join pg_index using (indexrelid)\n  left join pg_constraint\n    on array_to_string(indkey, ',') = array_to_string(conkey, ',')\n      and schemaname = (connamespace::regnamespace)::text\n      and conrelid = relid\n      and contype = 'f'\n  where idx_scan = 0\n    and indisunique is false\n    and conkey is not null --conkey is not null then true else false end as is_fk_idx\n), data as (\n  select\n    pci.relname as tag_index_name,\n    pn.nspname as tag_schema_name,\n    pct.relname as tag_table_name,\n    quote_ident(pn.nspname) as tag_schema_name,\n    quote_ident(pci.relname) as tag_index_name,\n    quote_ident(pct.relname) as tag_table_name,\n    coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,\n    pg_relation_size(pidx.indexrelid) index_size_bytes,\n    ((\n      select count(1)\n      from fk_indexes fi\n      where\n        fi.tag_fk_table_ref = pct.relname\n        and fi.tag_opclasses like (array_to_string(pidx.indclass, ', ') || '%')\n    ) > 0)::int as supports_fk\n  from pg_index pidx\n  join pg_class as pci on pci.oid = pidx.indexrelid\n  join pg_class as pct on pct.oid = pidx.indrelid\n  left join pg_namespace pn on pn.oid = pct.relnamespace\n  where pidx.indisvalid = false\n), data_total as (\n    select\n      sum(index_size_bytes) as index_size_bytes_sum\n    from data\n), num_data as (\n  select\n    row_number() over () num,\n    data.*\n  from data\n)\nselect\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  num_data.*\nfrom num_data\nlimit 1000;\n",
+      11: "with fk_indexes as ( /* pgwatch_generated */\n  select\n    schemaname as tag_schema_name,\n    (indexrelid::regclass)::text as tag_index_name,\n    (relid::regclass)::text as tag_table_name,\n    (confrelid::regclass)::text as tag_fk_table_ref,\n    array_to_string(indclass, ', ') as tag_opclasses\n  from\n    pg_stat_all_indexes\n  join pg_index using (indexrelid)\n  left join pg_constraint\n    on array_to_string(indkey, ',') = array_to_string(conkey, ',')\n      and schemaname = (connamespace::regnamespace)::text\n      and conrelid = relid\n      and contype = 'f'\n  where idx_scan = 0\n    and indisunique is false\n    and conkey is not null --conkey is not null then true else false end as is_fk_idx\n), data as (\n  select\n    pci.relname as tag_index_name,\n    pn.nspname as tag_schema_name,\n    pct.relname as tag_table_name,\n    quote_ident(pn.nspname) as tag_schema_name,\n    quote_ident(pci.relname) as tag_index_name,\n    quote_ident(pct.relname) as tag_table_name,\n    coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,\n    pg_get_indexdef(pidx.indexrelid) as index_definition,\n    pg_relation_size(pidx.indexrelid) index_size_bytes,\n    ((\n      select count(1)\n      from fk_indexes fi\n      where\n        fi.tag_fk_table_ref = pct.relname\n        and fi.tag_opclasses like (array_to_string(pidx.indclass, ', ') || '%')\n    ) > 0)::int as supports_fk\n  from pg_index pidx\n  join pg_class as pci on pci.oid = pidx.indexrelid\n  join pg_class as pct on pct.oid = pidx.indrelid\n  left join pg_namespace pn on pn.oid = pct.relnamespace\n  where pidx.indisvalid = false\n), data_total as (\n    select\n      sum(index_size_bytes) as index_size_bytes_sum\n    from data\n), num_data as (\n  select\n    row_number() over () num,\n    data.*\n  from data\n)\nselect\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  num_data.*\nfrom num_data\nlimit 1000;\n",
     },
     gauges: ["*"],
     statement_timeout_seconds: 15,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.14.0-dev.55",
+  "version": "0.14.0-dev.56",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,
@@ -26,7 +26,7 @@
   },
   "scripts": {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
-    "build": "bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e \"const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\"",
+    "build": "bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e \"const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\" && cp -r ./sql ./dist/sql",
     "prepublishOnly": "npm run build",
     "start": "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",

package/test/checkup.integration.test.ts

@@ -253,6 +253,52 @@ describe.skipIf(!!skipReason)("checkup integration: express mode schema compatib
     expect(typeof nodeResult.data).toBe("object");
   });
 
+  test("H001 returns index_definition with CREATE INDEX statement", async () => {
+    // Create a table and an index, then mark the index as invalid
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS test_invalid_idx_table (id serial PRIMARY KEY, value text);
+      CREATE INDEX IF NOT EXISTS test_invalid_idx ON test_invalid_idx_table(value);
+    `);
+
+    // Mark the index as invalid (simulating a failed CONCURRENTLY build)
+    await client.query(`
+      UPDATE pg_index SET indisvalid = false
+      WHERE indexrelid = 'test_invalid_idx'::regclass;
+    `);
+
+    try {
+      const report = await checkup.generateH001(client, "test-node");
+      validateAgainstSchema(report, "H001");
+
+      const nodeResult = report.results["test-node"];
+      const dbName = Object.keys(nodeResult.data)[0];
+      expect(dbName).toBeTruthy();
+
+      const dbData = nodeResult.data[dbName] as any;
+      expect(dbData.invalid_indexes).toBeDefined();
+      expect(dbData.invalid_indexes.length).toBeGreaterThan(0);
+
+      // Find our test index
+      const testIndex = dbData.invalid_indexes.find(
+        (idx: any) => idx.index_name === "test_invalid_idx"
+      );
+      expect(testIndex).toBeDefined();
+
+      // Verify index_definition contains the actual CREATE INDEX statement
+      expect(testIndex.index_definition).toMatch(/^CREATE INDEX/);
+      expect(testIndex.index_definition).toContain("test_invalid_idx");
+      expect(testIndex.index_definition).toContain("test_invalid_idx_table");
+    } finally {
+      // Cleanup: restore the index and drop test objects
+      await client.query(`
+        UPDATE pg_index SET indisvalid = true
+        WHERE indexrelid = 'test_invalid_idx'::regclass;
+        DROP INDEX IF EXISTS test_invalid_idx;
+        DROP TABLE IF EXISTS test_invalid_idx_table;
+      `);
+    }
+  });
+
   test("H002 (unused indexes) has correct data structure", async () => {
     const report = await checkup.generateH002(client, "test-node");
     validateAgainstSchema(report, "H002");

package/test/checkup.test.ts

@@ -480,7 +480,7 @@ describe("H001 - Invalid indexes", () => {
   test("getInvalidIndexes returns invalid indexes", async () => {
     const mockClient = createMockClient({
       invalidIndexesRows: [
-        { schema_name: "public", table_name: "users", index_name: "users_email_idx", relation_name: "users", index_size_bytes: "1048576", supports_fk: false },
+        { schema_name: "public", table_name: "users", index_name: "users_email_idx", relation_name: "users", index_size_bytes: "1048576", index_definition: "CREATE INDEX users_email_idx ON public.users USING btree (email)", supports_fk: false },
       ],
     });
 
@@ -491,6 +491,7 @@ describe("H001 - Invalid indexes", () => {
     expect(indexes[0].index_name).toBe("users_email_idx");
     expect(indexes[0].index_size_bytes).toBe(1048576);
     expect(indexes[0].index_size_pretty).toBeTruthy();
+    expect(indexes[0].index_definition).toMatch(/^CREATE INDEX/);
     expect(indexes[0].relation_name).toBe("users");
     expect(indexes[0].supports_fk).toBe(false);
   });
@@ -502,7 +503,7 @@ describe("H001 - Invalid indexes", () => {
         { name: "server_version_num", setting: "160003" },
       ],
         invalidIndexesRows: [
-          { schema_name: "public", table_name: "orders", index_name: "orders_status_idx", relation_name: "orders", index_size_bytes: "2097152", supports_fk: false },
+          { schema_name: "public", table_name: "orders", index_name: "orders_status_idx", relation_name: "orders", index_size_bytes: "2097152", index_definition: "CREATE INDEX orders_status_idx ON public.orders USING btree (status)", supports_fk: false },
         ],
       }
     );

package/test/schema-validation.test.ts

@@ -30,7 +30,7 @@ const indexTestData = {
     emptyRows: { invalidIndexesRows: [] },
     dataRows: {
       invalidIndexesRows: [
-        { schema_name: "public", table_name: "users", index_name: "users_email_idx", relation_name: "users", index_size_bytes: "1048576", supports_fk: false },
+        { schema_name: "public", table_name: "users", index_name: "users_email_idx", relation_name: "users", index_size_bytes: "1048576", index_definition: "CREATE INDEX users_email_idx ON public.users USING btree (email)", supports_fk: false },
       ],
     },
   },