postgresai 0.14.0-beta.13 → 0.14.0-beta.15

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,114 @@
+/**
+ * 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.
+ * Keys are normalized to uppercase for case-insensitive lookups.
+ */
+const dictionaryByCode: Map<string, CheckupDictionaryEntry> = new Map(
+  CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code.toUpperCase(), 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"). Lookup is case-insensitive.
+ * @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;
@@ -1185,6 +1186,37 @@ async function generateD004(client: Client, nodeName: string): Promise<Report> {
   return report;
 }
 
+/**
+ * Generate D001 report - Logging settings
+ *
+ * Collects all PostgreSQL logging-related settings including:
+ * - Log destination and collector settings
+ * - Log file rotation and naming
+ * - Log verbosity and filtering
+ * - Statement and duration logging
+ */
+async function generateD001(client: Client, nodeName: string): Promise<Report> {
+  const report = createBaseReport("D001", "Logging settings", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10) || 16;
+  const allSettings = await getSettings(client, pgMajorVersion);
+
+  // Filter logging-related settings (log_* and logging_*)
+  const loggingSettings: Record<string, SettingInfo> = {};
+  for (const [name, setting] of Object.entries(allSettings)) {
+    if (name.startsWith("log_") || name.startsWith("logging_")) {
+      loggingSettings[name] = setting;
+    }
+  }
+
+  report.results[nodeName] = {
+    data: loggingSettings,
+    postgres_version: postgresVersion,
+  };
+
+  return report;
+}
+
 /**
  * Generate F001 report - Autovacuum: current settings
  */
@@ -1326,6 +1358,82 @@ async function generateG001(client: Client, nodeName: string): Promise<Report> {
   return report;
 }
 
+/**
+ * Generate G003 report - Timeouts, locks, deadlocks
+ *
+ * Collects timeout and lock-related settings, plus deadlock statistics.
+ */
+async function generateG003(client: Client, nodeName: string): Promise<Report> {
+  const report = createBaseReport("G003", "Timeouts, locks, deadlocks", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10) || 16;
+  const allSettings = await getSettings(client, pgMajorVersion);
+
+  // Timeout and lock-related setting names
+  const lockTimeoutSettingNames = [
+    "lock_timeout",
+    "statement_timeout",
+    "idle_in_transaction_session_timeout",
+    "idle_session_timeout",
+    "deadlock_timeout",
+    "max_locks_per_transaction",
+    "max_pred_locks_per_transaction",
+    "max_pred_locks_per_relation",
+    "max_pred_locks_per_page",
+    "log_lock_waits",
+    "transaction_timeout",
+  ];
+
+  const lockSettings: Record<string, SettingInfo> = {};
+  for (const name of lockTimeoutSettingNames) {
+    if (allSettings[name]) {
+      lockSettings[name] = allSettings[name];
+    }
+  }
+
+  // Get deadlock statistics from pg_stat_database
+  let deadlockStats: {
+    deadlocks: number;
+    conflicts: number;
+    stats_reset: string | null;
+  } | null = null;
+  let deadlockError: string | null = null;
+
+  try {
+    const statsResult = await client.query(`
+      select
+        coalesce(sum(deadlocks), 0)::bigint as deadlocks,
+        coalesce(sum(conflicts), 0)::bigint as conflicts,
+        min(stats_reset)::text as stats_reset
+      from pg_stat_database
+      where datname = current_database()
+    `);
+    if (statsResult.rows.length > 0) {
+      const row = statsResult.rows[0];
+      deadlockStats = {
+        deadlocks: parseInt(row.deadlocks, 10),
+        conflicts: parseInt(row.conflicts, 10),
+        stats_reset: row.stats_reset || null,
+      };
+    }
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.log(`[G003] Error querying deadlock stats: ${errorMsg}`);
+    deadlockError = errorMsg;
+  }
+
+  report.results[nodeName] = {
+    data: {
+      settings: lockSettings,
+      deadlock_stats: deadlockStats,
+      ...(deadlockError && { deadlock_stats_error: deadlockError }),
+    },
+    postgres_version: postgresVersion,
+  };
+
+  return report;
+}
+
 /**
  * Available report generators
  */
@@ -1335,30 +1443,38 @@ export const REPORT_GENERATORS: Record<string, (client: Client, nodeName: string
   A004: generateA004,
   A007: generateA007,
   A013: generateA013,
+  D001: generateD001,
   D004: generateD004,
   F001: generateF001,
   G001: generateG001,
+  G003: generateG003,
   H001: generateH001,
   H002: generateH002,
   H004: generateH004,
 };
 
 /**
- * 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-beta.13",
+  "version": "0.14.0-beta.15",
   "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 --coverage=false",
+    "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",