postgresai 0.14.0-dev.75 → 0.14.0-dev.77

package/dist/sql/02.extensions.sql

@@ -0,0 +1,8 @@
+-- Extensions required for postgres_ai monitoring
+
+-- Enable pg_stat_statements for query performance monitoring
+-- Note: Uses IF NOT EXISTS because extension may already be installed.
+-- We do NOT drop this extension in unprepare-db since it may have been pre-existing.
+create extension if not exists pg_stat_statements;
+
+

package/dist/sql/{02.permissions.sql → 03.permissions.sql}

@@ -8,6 +8,7 @@ grant pg_monitor to {{ROLE_IDENT}};
 grant select on pg_catalog.pg_index to {{ROLE_IDENT}};
 
 -- Create postgres_ai schema for our objects
+-- Using IF NOT EXISTS for idempotency - prepare-db can be run multiple times
 create schema if not exists postgres_ai;
 grant usage on schema postgres_ai to {{ROLE_IDENT}};
 

package/dist/sql/sql/02.extensions.sql

@@ -0,0 +1,8 @@
+-- Extensions required for postgres_ai monitoring
+
+-- Enable pg_stat_statements for query performance monitoring
+-- Note: Uses IF NOT EXISTS because extension may already be installed.
+-- We do NOT drop this extension in unprepare-db since it may have been pre-existing.
+create extension if not exists pg_stat_statements;
+
+

package/dist/sql/sql/{02.permissions.sql → 03.permissions.sql}

@@ -8,6 +8,7 @@ grant pg_monitor to {{ROLE_IDENT}};
 grant select on pg_catalog.pg_index to {{ROLE_IDENT}};
 
 -- Create postgres_ai schema for our objects
+-- Using IF NOT EXISTS for idempotency - prepare-db can be run multiple times
 create schema if not exists postgres_ai;
 grant usage on schema postgres_ai to {{ROLE_IDENT}};
 

package/dist/sql/sql/uninit/01.helpers.sql

@@ -0,0 +1,5 @@
+-- Drop helper functions created by prepare-db (template-filled by cli/lib/init.ts)
+-- Run before dropping the postgres_ai schema.
+
+drop function if exists postgres_ai.explain_generic(text, text, text);
+drop function if exists postgres_ai.table_describe(text);

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

@@ -0,0 +1,30 @@
+-- Revoke permissions and drop objects created by prepare-db (template-filled by cli/lib/init.ts)
+
+-- Drop the postgres_ai.pg_statistic view
+drop view if exists postgres_ai.pg_statistic;
+
+-- Drop the postgres_ai schema (CASCADE to handle any remaining objects)
+drop schema if exists postgres_ai cascade;
+
+-- Revoke permissions from the monitoring role
+-- Use a DO block to handle the case where the role doesn't exist
+do $$ begin
+  revoke pg_monitor from {{ROLE_IDENT}};
+exception when undefined_object then
+  null; -- Role doesn't exist, nothing to revoke
+end $$;
+
+do $$ begin
+  revoke select on pg_catalog.pg_index from {{ROLE_IDENT}};
+exception when undefined_object then
+  null; -- Role doesn't exist
+end $$;
+
+do $$ begin
+  revoke connect on database {{DB_IDENT}} from {{ROLE_IDENT}};
+exception when undefined_object then
+  null; -- Role doesn't exist
+end $$;
+
+-- Note: USAGE on public is typically granted by default; we don't revoke it
+-- to avoid breaking other applications that may rely on it.

package/dist/sql/sql/uninit/03.role.sql

@@ -0,0 +1,27 @@
+-- Drop the monitoring role created by prepare-db (template-filled by cli/lib/init.ts)
+-- This must run after revoking all permissions from the role.
+
+-- Use a DO block to handle the case where the role doesn't exist
+do $$ begin
+  -- Reassign owned objects to current user before dropping
+  -- This handles any objects that might have been created by the role
+  begin
+    execute format('reassign owned by %I to current_user', {{ROLE_LITERAL}});
+  exception when undefined_object then
+    null; -- Role doesn't exist, nothing to reassign
+  end;
+
+  -- Drop owned objects (in case reassign didn't work for some objects)
+  begin
+    execute format('drop owned by %I', {{ROLE_LITERAL}});
+  exception when undefined_object then
+    null; -- Role doesn't exist
+  end;
+
+  -- Drop the role
+  begin
+    execute format('drop role %I', {{ROLE_LITERAL}});
+  exception when undefined_object then
+    null; -- Role doesn't exist, that's fine
+  end;
+end $$;

package/dist/sql/uninit/01.helpers.sql

@@ -0,0 +1,5 @@
+-- Drop helper functions created by prepare-db (template-filled by cli/lib/init.ts)
+-- Run before dropping the postgres_ai schema.
+
+drop function if exists postgres_ai.explain_generic(text, text, text);
+drop function if exists postgres_ai.table_describe(text);

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

@@ -0,0 +1,30 @@
+-- Revoke permissions and drop objects created by prepare-db (template-filled by cli/lib/init.ts)
+
+-- Drop the postgres_ai.pg_statistic view
+drop view if exists postgres_ai.pg_statistic;
+
+-- Drop the postgres_ai schema (CASCADE to handle any remaining objects)
+drop schema if exists postgres_ai cascade;
+
+-- Revoke permissions from the monitoring role
+-- Use a DO block to handle the case where the role doesn't exist
+do $$ begin
+  revoke pg_monitor from {{ROLE_IDENT}};
+exception when undefined_object then
+  null; -- Role doesn't exist, nothing to revoke
+end $$;
+
+do $$ begin
+  revoke select on pg_catalog.pg_index from {{ROLE_IDENT}};
+exception when undefined_object then
+  null; -- Role doesn't exist
+end $$;
+
+do $$ begin
+  revoke connect on database {{DB_IDENT}} from {{ROLE_IDENT}};
+exception when undefined_object then
+  null; -- Role doesn't exist
+end $$;
+
+-- Note: USAGE on public is typically granted by default; we don't revoke it
+-- to avoid breaking other applications that may rely on it.

package/dist/sql/uninit/03.role.sql

@@ -0,0 +1,27 @@
+-- Drop the monitoring role created by prepare-db (template-filled by cli/lib/init.ts)
+-- This must run after revoking all permissions from the role.
+
+-- Use a DO block to handle the case where the role doesn't exist
+do $$ begin
+  -- Reassign owned objects to current user before dropping
+  -- This handles any objects that might have been created by the role
+  begin
+    execute format('reassign owned by %I to current_user', {{ROLE_LITERAL}});
+  exception when undefined_object then
+    null; -- Role doesn't exist, nothing to reassign
+  end;
+
+  -- Drop owned objects (in case reassign didn't work for some objects)
+  begin
+    execute format('drop owned by %I', {{ROLE_LITERAL}});
+  exception when undefined_object then
+    null; -- Role doesn't exist
+  end;
+
+  -- Drop the role
+  begin
+    execute format('drop role %I', {{ROLE_LITERAL}});
+  exception when undefined_object then
+    null; -- Role doesn't exist, that's fine
+  end;
+end $$;

package/lib/checkup-dictionary.ts

@@ -0,0 +1,113 @@
+/**
+ * Checkup Dictionary Module
+ * =========================
+ * Provides access to the checkup report dictionary data embedded at build time.
+ *
+ * The dictionary is fetched from https://postgres.ai/api/general/checkup_dictionary
+ * during the build process and embedded into checkup-dictionary-embedded.ts.
+ *
+ * This ensures no API calls are made at runtime while keeping the data up-to-date.
+ */
+
+import { CHECKUP_DICTIONARY_DATA } from "./checkup-dictionary-embedded";
+
+/**
+ * A checkup dictionary entry describing a single check type.
+ */
+export interface CheckupDictionaryEntry {
+  /** Unique check code (e.g., "A001", "H002") */
+  code: string;
+  /** Human-readable title for the check */
+  title: string;
+  /** Brief description of what the check covers */
+  description: string;
+  /** Category grouping (e.g., "system", "indexes", "vacuum") */
+  category: string;
+  /** Optional sort order within category */
+  sort_order: number | null;
+  /** Whether this is a system-level report */
+  is_system_report: boolean;
+}
+
+/**
+ * Module-level cache for O(1) lookups by code.
+ * Initialized at module load time from embedded data.
+ */
+const dictionaryByCode: Map<string, CheckupDictionaryEntry> = new Map(
+  CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code, entry])
+);
+
+/**
+ * Get all checkup dictionary entries.
+ *
+ * @returns Array of all checkup dictionary entries
+ */
+export function getAllCheckupEntries(): CheckupDictionaryEntry[] {
+  return CHECKUP_DICTIONARY_DATA;
+}
+
+/**
+ * Get a checkup dictionary entry by its code.
+ *
+ * @param code - The check code (e.g., "A001", "H002")
+ * @returns The dictionary entry or null if not found
+ */
+export function getCheckupEntry(code: string): CheckupDictionaryEntry | null {
+  return dictionaryByCode.get(code.toUpperCase()) ?? null;
+}
+
+/**
+ * Get the title for a checkup code.
+ *
+ * @param code - The check code (e.g., "A001", "H002")
+ * @returns The title or the code itself if not found
+ */
+export function getCheckupTitle(code: string): string {
+  const entry = getCheckupEntry(code);
+  return entry?.title ?? code;
+}
+
+/**
+ * Check if a code exists in the dictionary.
+ *
+ * @param code - The check code to validate
+ * @returns True if the code exists in the dictionary
+ */
+export function isValidCheckupCode(code: string): boolean {
+  return dictionaryByCode.has(code.toUpperCase());
+}
+
+/**
+ * Get all check codes as an array.
+ *
+ * @returns Array of all check codes (e.g., ["A001", "A002", ...])
+ */
+export function getAllCheckupCodes(): string[] {
+  return CHECKUP_DICTIONARY_DATA.map((entry) => entry.code);
+}
+
+/**
+ * Get checkup entries filtered by category.
+ *
+ * @param category - The category to filter by (e.g., "indexes", "vacuum")
+ * @returns Array of entries in the specified category
+ */
+export function getCheckupEntriesByCategory(category: string): CheckupDictionaryEntry[] {
+  return CHECKUP_DICTIONARY_DATA.filter(
+    (entry) => entry.category.toLowerCase() === category.toLowerCase()
+  );
+}
+
+/**
+ * Build a code-to-title mapping object.
+ * Useful for backwards compatibility with CHECK_INFO style usage.
+ *
+ * @returns Object mapping check codes to titles (e.g., { "A001": "System information", ... })
+ */
+export function buildCheckInfoMap(): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const entry of CHECKUP_DICTIONARY_DATA) {
+    result[entry.code] = entry.title;
+  }
+  return result;
+}

package/lib/checkup.ts

@@ -51,6 +51,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as pkg from "../package.json";
 import { getMetricSql, transformMetricRow, METRIC_NAMES } from "./metrics-loader";
+import { getCheckupTitle, buildCheckInfoMap } from "./checkup-dictionary";
 
 // Time constants
 const SECONDS_PER_DAY = 86400;
@@ -1344,21 +1345,27 @@ export const REPORT_GENERATORS: Record<string, (client: Client, nodeName: string
 };
 
 /**
- * Check IDs and titles
+ * Check IDs and titles.
+ *
+ * This mapping is built from the embedded checkup dictionary, which is
+ * fetched from https://postgres.ai/api/general/checkup_dictionary at build time.
+ *
+ * For the full dictionary (all available checks), use the checkup-dictionary module.
+ * CHECK_INFO is filtered to only include checks that have express-mode generators.
  */
-export const CHECK_INFO: Record<string, string> = {
-  A002: "Postgres major version",
-  A003: "Postgres settings",
-  A004: "Cluster information",
-  A007: "Altered settings",
-  A013: "Postgres minor version",
-  D004: "pg_stat_statements and pg_stat_kcache settings",
-  F001: "Autovacuum: current settings",
-  G001: "Memory-related settings",
-  H001: "Invalid indexes",
-  H002: "Unused indexes",
-  H004: "Redundant indexes",
-};
+export const CHECK_INFO: Record<string, string> = (() => {
+  // Build the full dictionary map
+  const fullMap = buildCheckInfoMap();
+
+  // Filter to only include checks that have express-mode generators
+  const expressCheckIds = Object.keys(REPORT_GENERATORS);
+  const filtered: Record<string, string> = {};
+  for (const checkId of expressCheckIds) {
+    // Use dictionary title if available, otherwise use a fallback
+    filtered[checkId] = fullMap[checkId] || checkId;
+  }
+  return filtered;
+})();
 
 /**
  * Generate all available health check reports.

package/lib/init.ts

@@ -527,7 +527,13 @@ end $$;`;
     steps.push({ name: "01.role", sql: roleSql });
   }
 
-  let permissionsSql = applyTemplate(loadSqlTemplate("02.permissions.sql"), vars);
+  // Extensions should be created before permissions (so we can grant permissions on them)
+  steps.push({
+    name: "02.extensions",
+    sql: loadSqlTemplate("02.extensions.sql"),
+  });
+
+  let permissionsSql = applyTemplate(loadSqlTemplate("03.permissions.sql"), vars);
 
   // Some providers restrict ALTER USER - remove those statements.
   // TODO: Make this more flexible by allowing users to specify which statements to skip via config.
@@ -545,26 +551,26 @@ end $$;`;
   }
 
   steps.push({
-    name: "02.permissions",
+    name: "03.permissions",
     sql: permissionsSql,
   });
 
   // Helper functions (SECURITY DEFINER) for plan analysis and table info
   steps.push({
-    name: "05.helpers",
-    sql: applyTemplate(loadSqlTemplate("05.helpers.sql"), vars),
+    name: "06.helpers",
+    sql: applyTemplate(loadSqlTemplate("06.helpers.sql"), vars),
   });
 
   if (params.includeOptionalPermissions) {
     steps.push(
       {
-        name: "03.optional_rds",
-        sql: applyTemplate(loadSqlTemplate("03.optional_rds.sql"), vars),
+        name: "04.optional_rds",
+        sql: applyTemplate(loadSqlTemplate("04.optional_rds.sql"), vars),
         optional: true,
       },
       {
-        name: "04.optional_self_managed",
-        sql: applyTemplate(loadSqlTemplate("04.optional_self_managed.sql"), vars),
+        name: "05.optional_self_managed",
+        sql: applyTemplate(loadSqlTemplate("05.optional_self_managed.sql"), vars),
         optional: true,
       }
     );
@@ -657,6 +663,101 @@ export type VerifyInitResult = {
   missingOptional: string[];
 };
 
+export type UninitPlan = {
+  monitoringUser: string;
+  database: string;
+  steps: InitStep[];
+  /** If true, also drop the monitoring role. If false, only revoke permissions. */
+  dropRole: boolean;
+};
+
+export async function buildUninitPlan(params: {
+  database: string;
+  monitoringUser?: string;
+  /** If true, drop the role entirely. If false, only revoke permissions/drop objects. */
+  dropRole?: boolean;
+  /** Provider type. Affects which steps are included. Defaults to "self-managed". */
+  provider?: DbProvider;
+}): Promise<UninitPlan> {
+  const monitoringUser = params.monitoringUser || DEFAULT_MONITORING_USER;
+  const database = params.database;
+  const provider = params.provider ?? "self-managed";
+  const dropRole = params.dropRole ?? true;
+
+  const qRole = quoteIdent(monitoringUser);
+  const qDb = quoteIdent(database);
+  const qRoleLiteral = quoteLiteral(monitoringUser);
+
+  const steps: InitStep[] = [];
+
+  const vars: Record<string, string> = {
+    ROLE_IDENT: qRole,
+    DB_IDENT: qDb,
+    ROLE_LITERAL: qRoleLiteral,
+  };
+
+  // Step 1: Drop helper functions
+  steps.push({
+    name: "01.drop_helpers",
+    sql: applyTemplate(loadSqlTemplate("uninit/01.helpers.sql"), vars),
+  });
+
+  // Step 2: Drop view, revoke permissions, drop schema
+  steps.push({
+    name: "02.revoke_permissions",
+    sql: applyTemplate(loadSqlTemplate("uninit/02.permissions.sql"), vars),
+  });
+
+  // Step 3: Drop the role (only if requested and provider allows it)
+  if (dropRole && !SKIP_ROLE_CREATION_PROVIDERS.includes(provider)) {
+    steps.push({
+      name: "03.drop_role",
+      sql: applyTemplate(loadSqlTemplate("uninit/03.role.sql"), vars),
+    });
+  }
+
+  return { monitoringUser, database, steps, dropRole };
+}
+
+export async function applyUninitPlan(params: {
+  client: PgClient;
+  plan: UninitPlan;
+}): Promise<{ applied: string[]; errors: string[] }> {
+  const applied: string[] = [];
+  const errors: string[] = [];
+
+  // Helper to wrap a step execution in begin/commit
+  const executeStep = async (step: InitStep): Promise<void> => {
+    await params.client.query("begin;");
+    try {
+      await params.client.query(step.sql, step.params as any);
+      await params.client.query("commit;");
+    } catch (e) {
+      try {
+        await params.client.query("rollback;");
+      } catch {
+        // ignore
+      }
+      throw e;
+    }
+  };
+
+  // Apply steps in order - unlike init, uninit steps are not optional
+  // but we continue on errors to clean up as much as possible
+  for (const step of params.plan.steps) {
+    try {
+      await executeStep(step);
+      applied.push(step.name);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      errors.push(`${step.name}: ${msg}`);
+      // Continue to try other steps
+    }
+  }
+
+  return { applied, errors };
+}
+
 export async function verifyInitSetup(params: {
   client: PgClient;
   database: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.14.0-dev.75",
+  "version": "0.14.0-dev.77",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,
@@ -26,15 +26,17 @@
   },
   "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'))\" && cp -r ./sql ./dist/sql",
+    "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
+    "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
+    "build": "bun run embed-all && 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",
-    "dev": "bun run embed-metrics && bun --watch ./bin/postgres-ai.ts",
-    "test": "bun run embed-metrics && bun test",
-    "test:fast": "bun run embed-metrics && bun test --coverage=false",
-    "test:coverage": "bun run embed-metrics && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
-    "typecheck": "bun run embed-metrics && bunx tsc --noEmit"
+    "dev": "bun run embed-all && bun --watch ./bin/postgres-ai.ts",
+    "test": "bun run embed-all && bun test",
+    "test:fast": "bun run embed-all && bun test",
+    "test:coverage": "bun run embed-all && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
+    "typecheck": "bun run embed-all && bunx tsc --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",

package/scripts/embed-checkup-dictionary.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+/**
+ * Build script to fetch checkup dictionary from API and embed it.
+ *
+ * This script fetches from https://postgres.ai/api/general/checkup_dictionary
+ * and generates cli/lib/checkup-dictionary-embedded.ts with the data embedded.
+ *
+ * The generated file is NOT committed to git - it's regenerated at build time.
+ *
+ * Usage: bun run scripts/embed-checkup-dictionary.ts
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+// API endpoint - always available without auth
+const DICTIONARY_URL = "https://postgres.ai/api/general/checkup_dictionary";
+
+// Output path relative to cli/ directory
+const CLI_DIR = path.resolve(__dirname, "..");
+const OUTPUT_PATH = path.resolve(CLI_DIR, "lib/checkup-dictionary-embedded.ts");
+
+// Request timeout (10 seconds)
+const FETCH_TIMEOUT_MS = 10_000;
+
+interface CheckupDictionaryEntry {
+  code: string;
+  title: string;
+  description: string;
+  category: string;
+  sort_order: number | null;
+  is_system_report: boolean;
+}
+
+function generateTypeScript(data: CheckupDictionaryEntry[], sourceUrl: string): string {
+  const lines: string[] = [
+    "// AUTO-GENERATED FILE - DO NOT EDIT",
+    `// Generated from: ${sourceUrl}`,
+    `// Generated at: ${new Date().toISOString()}`,
+    "// To regenerate: bun run embed-checkup-dictionary",
+    "",
+    'import { CheckupDictionaryEntry } from "./checkup-dictionary";',
+    "",
+    "/**",
+    " * Embedded checkup dictionary data fetched from API at build time.",
+    " * Contains all available checkup report codes, titles, and metadata.",
+    " */",
+    `export const CHECKUP_DICTIONARY_DATA: CheckupDictionaryEntry[] = ${JSON.stringify(data, null, 2)};`,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    return response;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function main() {
+  console.log(`Fetching checkup dictionary from: ${DICTIONARY_URL}`);
+
+  try {
+    const response = await fetchWithTimeout(DICTIONARY_URL, FETCH_TIMEOUT_MS);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data: CheckupDictionaryEntry[] = await response.json();
+
+    if (!Array.isArray(data)) {
+      throw new Error("Expected array response from API");
+    }
+
+    // Validate entries have required fields
+    for (const entry of data) {
+      if (!entry.code || !entry.title) {
+        throw new Error(`Invalid entry missing code or title: ${JSON.stringify(entry)}`);
+      }
+    }
+
+    const tsCode = generateTypeScript(data, DICTIONARY_URL);
+    fs.writeFileSync(OUTPUT_PATH, tsCode, "utf8");
+
+    console.log(`Generated: ${OUTPUT_PATH}`);
+    console.log(`Dictionary contains ${data.length} entries`);
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.warn(`Warning: Failed to fetch checkup dictionary: ${errorMsg}`);
+    console.warn("Generating empty dictionary as fallback");
+
+    // Generate empty dictionary to allow build to proceed
+    const fallbackTs = generateTypeScript([], `N/A (fetch failed: ${errorMsg})`);
+    fs.writeFileSync(OUTPUT_PATH, fallbackTs, "utf8");
+    console.log(`Generated fallback dictionary at ${OUTPUT_PATH}`);
+  }
+}
+
+main();

package/sql/02.extensions.sql

@@ -0,0 +1,8 @@
+-- Extensions required for postgres_ai monitoring
+
+-- Enable pg_stat_statements for query performance monitoring
+-- Note: Uses IF NOT EXISTS because extension may already be installed.
+-- We do NOT drop this extension in unprepare-db since it may have been pre-existing.
+create extension if not exists pg_stat_statements;
+
+

package/sql/{02.permissions.sql → 03.permissions.sql}

@@ -8,6 +8,7 @@ grant pg_monitor to {{ROLE_IDENT}};
 grant select on pg_catalog.pg_index to {{ROLE_IDENT}};
 
 -- Create postgres_ai schema for our objects
+-- Using IF NOT EXISTS for idempotency - prepare-db can be run multiple times
 create schema if not exists postgres_ai;
 grant usage on schema postgres_ai to {{ROLE_IDENT}};
 

package/sql/uninit/01.helpers.sql

@@ -0,0 +1,5 @@
+-- Drop helper functions created by prepare-db (template-filled by cli/lib/init.ts)
+-- Run before dropping the postgres_ai schema.
+
+drop function if exists postgres_ai.explain_generic(text, text, text);
+drop function if exists postgres_ai.table_describe(text);