postgresai 0.16.0-rc.2 → 0.16.0-rc.4

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## Unreleased
+
+### Fixed
+
+- `checkup --markdown` previously performed server-side conversion and sent the
+  full report JSON to the PostgresAI API even when `--no-upload` was set. The
+  flags are now mutually exclusive, and `--no-upload` prevents report data from
+  being sent to the PostgresAI API. Use `--json` or `--output` for local-only
+  output.

package/bin/postgres-ai.ts

@@ -335,12 +335,18 @@ function prepareUploadConfig(
       console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
       return null; // Signal to exit
     }
-    // No credentials and upload not explicitly requested: fall back to
-    // local-only mode, but say so prominently — skipping the upload silently
-    // hides the fact that results never reach the Console.
-    console.error("Notice: no API key configured — results will NOT be uploaded to PostgresAI.");
-    console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
-    console.error("        To run locally without this notice, pass --no-upload.");
+    if (opts.markdown) {
+      console.error("Notice: no API key configured — regular report upload is disabled.");
+      console.error("        The full report JSON will still be sent to the PostgresAI API for markdown conversion.");
+      console.error("        To avoid sending report data, replace --markdown with --no-upload and --json or --output.");
+    } else {
+      // No credentials and upload not explicitly requested: fall back to
+      // local-only mode, but say so prominently — skipping the upload silently
+      // hides the fact that results never reach the Console.
+      console.error("Notice: no API key configured — results will NOT be uploaded to PostgresAI.");
+      console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
+      console.error("        To run locally without this notice, pass --no-upload.");
+    }
     return undefined; // Skip upload, run checks locally
   }
 
@@ -1996,7 +2002,7 @@ program
     "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)"
   )
   .option("--json", "output JSON to stdout")
-  .option("--markdown", "output markdown to stdout")
+  .option("--markdown", "output markdown via PostgresAI API (transmits the full report JSON)")
   .addHelpText(
     "after",
     [
@@ -2010,7 +2016,7 @@ program
       "  postgresai checkup postgresql://user:pass@host:5432/db --check-id H002",
       "  postgresai checkup postgresql://user:pass@host:5432/db --output ./reports",
       "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --json",
-      "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --markdown",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --markdown",
     ].join("\n")
   )
   .action(async (checkIdOrConn: string | undefined, connArg: string | undefined, opts: CheckupOptions, cmd: Command) => {
@@ -2060,9 +2066,14 @@ program
       process.exitCode = 1;
       return;
     }
-    // Note: --json, --markdown and --upload/--no-upload are independent flags.
-    // Use --no-upload to explicitly disable upload when using --json or --markdown.
     const uploadExplicitlyDisabled = opts.upload === false;
+    if (uploadExplicitlyDisabled && shouldConvertMarkdown) {
+      console.error("Error: --no-upload and --markdown are mutually exclusive");
+      console.error("Markdown conversion is performed by the PostgresAI API and transmits the full report JSON.");
+      console.error("Drop --no-upload to allow transmission, or use --json or --output for local-only output.");
+      process.exitCode = 1;
+      return;
+    }
     let shouldUpload = !uploadExplicitlyDisabled;
 
     // Preflight: validate/create output directory BEFORE connecting / running checks.
@@ -2308,7 +2319,9 @@ program
 
         console.log('\nFor details:');
         console.log('  --json          Output JSON');
-        console.log('  --markdown      Output markdown');
+        if (!uploadExplicitlyDisabled) {
+          console.log('  --markdown      Output markdown via PostgresAI API');
+        }
         console.log('  --output <dir>  Save to directory');
       }
     } catch (error) {
@@ -3931,13 +3944,9 @@ targets
 // Authentication and API key management
 const auth = program.command("auth").description("authentication and API key management");
 
-auth
-  .command("login", { isDefault: true })
-  .description("authenticate via browser (OAuth) or store API key directly")
-  .option("--set-key <key>", "store API key directly without OAuth flow")
-  .option("--port <port>", "local callback server port (default: random)", parseInt)
-  .option("--debug", "enable debug output")
-  .action(async (opts: { setKey?: string; port?: number; debug?: boolean }) => {
+type AuthLoginOptions = { setKey?: string; port?: number; debug?: boolean };
+
+async function runAuthLogin(opts: AuthLoginOptions) {
     // If --set-key is provided, store it directly without OAuth
     if (opts.setKey) {
       const trimmedKey = opts.setKey.trim();
@@ -4191,7 +4200,21 @@ auth
       console.error(`Authentication error: ${message}`);
       process.exit(1);
     }
-  });
+}
+
+function configureLoginCommand(command: Command): Command {
+  return command
+    .description("authenticate via browser (OAuth) or store API key directly")
+    .option("--set-key <key>", "store API key directly without OAuth flow")
+    .option("--port <port>", "local callback server port (default: random)", parseInt)
+    .option("--debug", "enable debug output");
+}
+
+configureLoginCommand(auth.command("login", { isDefault: true }))
+  .action(runAuthLogin);
+
+configureLoginCommand(program.command("login"))
+  .action(runAuthLogin);
 
 auth
   .command("show-key")

package/dist/bin/postgres-ai.js

@@ -13425,7 +13425,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-rc.2",
+  version: "0.16.0-rc.4",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16256,7 +16256,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.16.0-rc.2";
+var version = "0.16.0-rc.4";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -29452,10 +29452,6 @@ async function verifyInitSetup(params) {
         }
       }
     }
-    const explainFnRes = await params.client.query("select has_function_privilege($1, 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok", [role]);
-    if (!explainFnRes.rows?.[0]?.ok) {
-      missingRequired.push("EXECUTE on postgres_ai.explain_generic(text, text, text)");
-    }
     const tableDescribeFnRes = await params.client.query("select has_function_privilege($1, 'postgres_ai.table_describe(text)', 'EXECUTE') as ok", [role]);
     if (!tableDescribeFnRes.rows?.[0]?.ok) {
       missingRequired.push("EXECUTE on postgres_ai.table_describe(text)");
@@ -29522,10 +29518,28 @@ async function checkCurrentUserPermissions(client) {
 
       union all
 
+      select
+        'postgres_ai schema exists' as permission_name,
+        'optional' as status,
+        to_regnamespace('postgres_ai') is not null as granted
+
+      union all
+
+      select
+        'usage on postgres_ai schema' as permission_name,
+        'optional' as status,
+        case
+          when to_regnamespace('postgres_ai') is null then null
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as granted
+
+      union all
+
       select
         'postgres_ai.pg_statistic view exists' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
           else to_regclass('postgres_ai.pg_statistic') is not null
         end as granted
@@ -29536,6 +29550,7 @@ async function checkCurrentUserPermissions(client) {
         'select on postgres_ai.pg_statistic' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
           when to_regclass('postgres_ai.pg_statistic') is null then null
           else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'select')
@@ -29555,6 +29570,10 @@ async function checkCurrentUserPermissions(client) {
             when permission_name like 'select on pg_catalog.pg_index' then
               format('grant select on pg_catalog.pg_index to %I;', current_user)
           end
+        when permission_name = 'postgres_ai schema exists' and granted = false then
+          '-- run postgresai prepare-db or create the postgres_ai schema and pg_statistic view manually'
+        when permission_name = 'usage on postgres_ai schema' and granted = false then
+          format('grant usage on schema postgres_ai to %I;', current_user)
         when permission_name = 'postgres_ai.pg_statistic view exists' and granted = false then
           '-- create postgres_ai.pg_statistic view (see setup script)'
         when permission_name = 'select on postgres_ai.pg_statistic' and granted = false then
@@ -29581,6 +29600,10 @@ function formatPermissionCheckMessages(result) {
   const warnings = [];
   const errors3 = [];
   for (const row of result.missingOptional) {
+    if (row.permission_name === "postgres_ai schema exists") {
+      warnings.push("Warning: optional: postgres_ai schema not found — F004/F005 (bloat estimates) will be skipped; run prepare-db or create the view manually to enable them.");
+      continue;
+    }
     const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
     warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
   }
@@ -29974,15 +29997,6 @@ async function verifyInitSetupViaSupabase(params) {
       missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
     }
   }
-  const explainFnExistsRes = await params.client.query("SELECT oid FROM pg_proc WHERE proname = 'explain_generic' AND pronamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'postgres_ai')", true);
-  if (explainFnExistsRes.rowCount === 0) {
-    missingRequired.push("function postgres_ai.explain_generic exists");
-  } else {
-    const explainFnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok`, true);
-    if (!explainFnRes.rows?.[0]?.ok) {
-      missingRequired.push("EXECUTE on postgres_ai.explain_generic(text, text, text)");
-    }
-  }
   const tableDescribeFnExistsRes = await params.client.query("SELECT oid FROM pg_proc WHERE proname = 'table_describe' AND pronamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'postgres_ai')", true);
   if (tableDescribeFnExistsRes.rowCount === 0) {
     missingRequired.push("function postgres_ai.table_describe exists");
@@ -32778,12 +32792,70 @@ async function generateF003(client, nodeName) {
   };
   return report;
 }
+function bloatErrorStatus(err) {
+  const error2 = err instanceof Error ? err.message : String(err);
+  const code = typeof err === "object" && err !== null && "code" in err ? String(err.code || "") : "";
+  const normalized = error2.toLowerCase();
+  let reason = "query_error";
+  if (code === "3F000" || normalized.includes('schema "postgres_ai" does not exist')) {
+    reason = "missing_schema";
+  } else if (code === "42P01" || normalized.includes('relation "postgres_ai.pg_statistic" does not exist')) {
+    reason = "missing_view";
+  } else if (code === "42501" || normalized.includes("permission denied")) {
+    reason = "missing_grant";
+  }
+  return { ok: false, reason, error: error2 };
+}
+async function getBloatCheckStatus(client) {
+  try {
+    const result = await client.query(`
+      select
+        to_regnamespace('postgres_ai') is not null as schema_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as schema_usage,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as view_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          when to_regclass('postgres_ai.pg_statistic') is null then false
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'SELECT')
+        end as view_select
+    `);
+    const capability = result.rows[0] || {};
+    if (!capability.schema_exists) {
+      return { ok: false, reason: "missing_schema", error: 'schema "postgres_ai" does not exist' };
+    }
+    if (!capability.schema_usage) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for schema postgres_ai" };
+    }
+    if (!capability.view_exists) {
+      return { ok: false, reason: "missing_view", error: 'relation "postgres_ai.pg_statistic" does not exist' };
+    }
+    if (!capability.view_select) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for relation postgres_ai.pg_statistic" };
+    }
+    return { ok: true, reason: null, error: null };
+  } catch (err) {
+    return bloatErrorStatus(err);
+  }
+}
 async function generateF004(client, nodeName) {
   const report = createBaseReport("F004", "Autovacuum: heap bloat (estimated)", nodeName);
   const postgresVersion = await getPostgresVersion(client);
   const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
   let bloatedTables = [];
+  let status = await getBloatCheckStatus(client);
   try {
+    if (!status.ok)
+      throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+        code: status.reason === "missing_schema" ? "3F000" : status.reason === "missing_view" ? "42P01" : status.reason === "missing_grant" ? "42501" : undefined
+      });
     const sql = getMetricSql(METRIC_NAMES.F004, pgMajorVersion);
     const bloatResult = await client.query(sql);
     const vacuumStatsResult = await client.query(`
@@ -32827,7 +32899,8 @@ async function generateF004(client, nodeName) {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     console.error(`[F004] Error estimating table bloat: ${errorMsg}`);
     if (errorMsg.includes("postgres_ai.")) {
       console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
@@ -32837,6 +32910,7 @@ async function generateF004(client, nodeName) {
   const totalCount = bloatedTables.length;
   const totalBloatSizeBytes = bloatedTables.reduce((sum, t) => sum + t.bloat_size, 0);
   const dbEntry = {
+    status,
     bloated_tables: bloatedTables,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
@@ -32855,7 +32929,12 @@ async function generateF005(client, nodeName) {
   const postgresVersion = await getPostgresVersion(client);
   const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
   let bloatedIndexes = [];
+  let status = await getBloatCheckStatus(client);
   try {
+    if (!status.ok)
+      throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+        code: status.reason === "missing_schema" ? "3F000" : status.reason === "missing_view" ? "42P01" : status.reason === "missing_grant" ? "42501" : undefined
+      });
     const sql = getMetricSql(METRIC_NAMES.F005, pgMajorVersion);
     const bloatResult = await client.query(sql);
     const vacuumStatsResult = await client.query(`
@@ -32904,7 +32983,8 @@ async function generateF005(client, nodeName) {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     console.error(`[F005] Error estimating index bloat: ${errorMsg}`);
     if (errorMsg.includes("postgres_ai.")) {
       console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
@@ -32914,6 +32994,7 @@ async function generateF005(client, nodeName) {
   const totalCount = bloatedIndexes.length;
   const totalBloatSizeBytes = bloatedIndexes.reduce((sum, idx) => sum + idx.bloat_size, 0);
   const dbEntry = {
+    status,
     bloated_indexes: bloatedIndexes,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
@@ -33586,6 +33667,10 @@ function generateCheckSummary(checkId, report) {
       return summarizeF001(nodeData);
     case "F003":
       return summarizeF003(nodeData);
+    case "F004":
+      return summarizeBloat(nodeData, "table");
+    case "F005":
+      return summarizeBloat(nodeData, "index");
     case "G001":
       return summarizeG001(nodeData);
     case "G003":
@@ -33771,6 +33856,25 @@ function summarizeF003(nodeData) {
   }
   return { status: "warning", message: parts.join(", ") };
 }
+function summarizeBloat(nodeData, kind) {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData;
+    if (dbEntry?.status?.ok === false) {
+      const reason = String(dbEntry.status.reason || "query_error").replaceAll("_", " ");
+      return { status: "warning", message: `Bloat estimate degraded: ${reason}` };
+    }
+    totalCount += dbEntry?.total_count || 0;
+  }
+  if (totalCount === 0) {
+    return { status: "ok", message: `No bloated ${kind}${kind === "index" ? "es" : "s"} found` };
+  }
+  return {
+    status: "warning",
+    message: `Found ${totalCount} bloated ${kind}${totalCount === 1 ? "" : kind === "index" ? "es" : "s"}`
+  };
+}
 function summarizeG001(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
@@ -34127,9 +34231,15 @@ function prepareUploadConfig(opts, rootOpts, shouldUpload, uploadExplicitlyReque
       console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
       return null;
     }
-    console.error("Notice: no API key configured \u2014 results will NOT be uploaded to PostgresAI.");
-    console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
-    console.error("        To run locally without this notice, pass --no-upload.");
+    if (opts.markdown) {
+      console.error("Notice: no API key configured \u2014 regular report upload is disabled.");
+      console.error("        The full report JSON will still be sent to the PostgresAI API for markdown conversion.");
+      console.error("        To avoid sending report data, replace --markdown with --no-upload and --json or --output.");
+    } else {
+      console.error("Notice: no API key configured \u2014 results will NOT be uploaded to PostgresAI.");
+      console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
+      console.error("        To run locally without this notice, pass --no-upload.");
+    }
     return;
   }
   const cfg = readConfig();
@@ -35354,7 +35464,7 @@ program2.command("unprepare-db [conn]").description("remove monitoring setup: dr
     closeReadline();
   }
 });
-program2.command("checkup [checkIdOrConn] [conn]").description("generate health check reports directly from PostgreSQL (express mode)").option("--check-id <id>", `specific check to run (see list below), or ALL`).option("--node-name <name>", "node name for reports", "node-01").option("--output <path>", "output directory for JSON files").option("--upload", "upload JSON results to PostgresAI (requires API key)").option("--no-upload", "disable upload to PostgresAI").option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)").option("--json", "output JSON to stdout").option("--markdown", "output markdown to stdout").addHelpText("after", [
+program2.command("checkup [checkIdOrConn] [conn]").description("generate health check reports directly from PostgreSQL (express mode)").option("--check-id <id>", `specific check to run (see list below), or ALL`).option("--node-name <name>", "node name for reports", "node-01").option("--output <path>", "output directory for JSON files").option("--upload", "upload JSON results to PostgresAI (requires API key)").option("--no-upload", "disable upload to PostgresAI").option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)").option("--json", "output JSON to stdout").option("--markdown", "output markdown via PostgresAI API (transmits the full report JSON)").addHelpText("after", [
   "",
   "Available checks:",
   ...Object.entries(CHECK_INFO).map(([id, title]) => `  ${id}: ${title}`),
@@ -35365,7 +35475,7 @@ program2.command("checkup [checkIdOrConn] [conn]").description("generate health
   "  postgresai checkup postgresql://user:pass@host:5432/db --check-id H002",
   "  postgresai checkup postgresql://user:pass@host:5432/db --output ./reports",
   "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --json",
-  "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --markdown"
+  "  postgresai checkup postgresql://user:pass@host:5432/db --markdown"
 ].join(`
 `)).action(async (checkIdOrConn, connArg, opts, cmd) => {
   const checkIdPattern = /^[A-Z]\d{3}$/i;
@@ -35405,6 +35515,13 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
     return;
   }
   const uploadExplicitlyDisabled = opts.upload === false;
+  if (uploadExplicitlyDisabled && shouldConvertMarkdown) {
+    console.error("Error: --no-upload and --markdown are mutually exclusive");
+    console.error("Markdown conversion is performed by the PostgresAI API and transmits the full report JSON.");
+    console.error("Drop --no-upload to allow transmission, or use --json or --output for local-only output.");
+    process.exitCode = 1;
+    return;
+  }
   let shouldUpload = !uploadExplicitlyDisabled;
   const outputPath = prepareOutputDirectory(opts.output);
   if (outputPath === null) {
@@ -35587,7 +35704,9 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
       console.log(`
 For details:`);
       console.log("  --json          Output JSON");
-      console.log("  --markdown      Output markdown");
+      if (!uploadExplicitlyDisabled) {
+        console.log("  --markdown      Output markdown via PostgresAI API");
+      }
       console.log("  --output <dir>  Save to directory");
     }
   } catch (error2) {
@@ -36802,7 +36921,7 @@ targets.command("test <name>").description("test monitoring target database conn
   }
 });
 var auth = program2.command("auth").description("authentication and API key management");
-auth.command("login", { isDefault: true }).description("authenticate via browser (OAuth) or store API key directly").option("--set-key <key>", "store API key directly without OAuth flow").option("--port <port>", "local callback server port (default: random)", parseInt).option("--debug", "enable debug output").action(async (opts) => {
+async function runAuthLogin(opts) {
   if (opts.setKey) {
     const trimmedKey = opts.setKey.trim();
     if (!trimmedKey) {
@@ -37003,7 +37122,12 @@ Authentication failed: ${message}`);
     console.error(`Authentication error: ${message}`);
     process.exit(1);
   }
-});
+}
+function configureLoginCommand(command) {
+  return command.description("authenticate via browser (OAuth) or store API key directly").option("--set-key <key>", "store API key directly without OAuth flow").option("--port <port>", "local callback server port (default: random)", parseInt).option("--debug", "enable debug output");
+}
+configureLoginCommand(auth.command("login", { isDefault: true })).action(runAuthLogin);
+configureLoginCommand(program2.command("login")).action(runAuthLogin);
 auth.command("show-key").description("show API key (masked)").action(async () => {
   const cfg = readConfig();
   if (!cfg.apiKey) {

package/dist/sql/06.helpers.sql

@@ -2,126 +2,6 @@
 -- These functions use SECURITY DEFINER to allow the monitoring user to perform
 -- operations they don't have direct permissions for.
 
-/*
- * explain_generic
- *
- * Function to get generic explain plans with optional HypoPG index testing.
- * Requires: PostgreSQL 16+ (for generic_plan option), HypoPG extension (optional).
- *
- * Security notes:
- * - EXPLAIN without ANALYZE is read-only (plans but doesn't execute the query)
- * - PostgreSQL's EXPLAIN only accepts a single statement (primary protection)
- * - Input validation uses a simple heuristic to detect multiple statements
- *   (Note: may reject valid queries containing semicolons in string literals)
- *
- * 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;
-  v_clean_query text;
-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;
-
-  -- Input validation: reject empty queries
-  if query is null or trim(query) = '' then
-    raise exception 'query cannot be empty';
-  end if;
-
-  -- Input validation: detect multiple statements (defense-in-depth)
-  -- Note: This is a simple heuristic - EXPLAIN itself only accepts single statements
-  -- Limitation: Queries with semicolons inside string literals will be rejected
-  v_clean_query := trim(query);
-  if v_clean_query like '%;%' then
-    -- Strip trailing semicolon if present (common user convenience)
-    v_clean_query := regexp_replace(v_clean_query, ';\s*$', '');
-    -- If there's still a semicolon, reject (likely multiple statements or semicolon in string)
-    if v_clean_query like '%;%' then
-      raise exception 'query contains semicolon (multiple statements not allowed; note: semicolons in string literals are also not supported)';
-    end if;
-  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
-  -- Note: EXPLAIN is read-only (plans but doesn't execute), making this safe
-  begin
-    if lower(format) = 'json' then
-      execute 'explain (verbose, settings, generic_plan, format json) ' || v_clean_query
-        into result;
-    else
-      for v_line in execute 'explain (verbose, settings, generic_plan) ' || v_clean_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
  *
@@ -435,5 +315,3 @@ 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}};
-
-