postgresai 0.14.0-beta.12 → 0.14.0-beta.14

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.ts

@@ -109,6 +109,12 @@ export interface ClusterMetric {
 
 /**
  * Invalid index entry (H001) - matches H001.schema.json invalidIndex
+ *
+ * Decision tree for remediation recommendations:
+ * 1. has_valid_duplicate=true → DROP (valid duplicate exists, safe to remove)
+ * 2. is_pk=true or is_unique=true → RECREATE (backs a constraint, must restore)
+ * 3. table_row_estimate < 10000 → RECREATE (small table, quick rebuild)
+ * 4. Otherwise → UNCERTAIN (needs manual analysis of query plans)
  */
 export interface InvalidIndex {
   schema_name: string;
@@ -117,9 +123,61 @@ 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 */
+  /** Full CREATE INDEX statement from pg_get_indexdef() - useful for DROP/RECREATE migrations */
   index_definition: string;
   supports_fk: boolean;
+  /** True if this index backs a PRIMARY KEY constraint */
+  is_pk: boolean;
+  /** True if this is a UNIQUE index (includes PK indexes) */
+  is_unique: boolean;
+  /** Name of the constraint this index backs, or null if none */
+  constraint_name: string | null;
+  /** Estimated row count of the table from pg_class.reltuples */
+  table_row_estimate: number;
+  /** True if there is a valid index on the same column(s) */
+  has_valid_duplicate: boolean;
+  /** Name of the valid duplicate index if one exists */
+  valid_duplicate_name: string | null;
+  /** Full CREATE INDEX statement of the valid duplicate index */
+  valid_duplicate_definition: string | null;
+}
+
+/** Recommendation for handling an invalid index */
+export type InvalidIndexRecommendation = "DROP" | "RECREATE" | "UNCERTAIN";
+
+/** Threshold for considering a table "small" (quick to rebuild) */
+const SMALL_TABLE_ROW_THRESHOLD = 10000;
+
+/**
+ * Compute remediation recommendation for an invalid index using decision tree.
+ *
+ * Decision tree logic:
+ * 1. If has_valid_duplicate is true → DROP (valid duplicate exists, safe to remove)
+ * 2. If is_pk or is_unique is true → RECREATE (backs a constraint, must restore)
+ * 3. If table_row_estimate < 10000 → RECREATE (small table, quick rebuild)
+ * 4. Otherwise → UNCERTAIN (needs manual analysis of query plans)
+ *
+ * @param index - Invalid index with observation data
+ * @returns Recommendation: "DROP", "RECREATE", or "UNCERTAIN"
+ */
+export function getInvalidIndexRecommendation(index: InvalidIndex): InvalidIndexRecommendation {
+  // 1. Valid duplicate exists - safe to drop
+  if (index.has_valid_duplicate) {
+    return "DROP";
+  }
+
+  // 2. Backs a constraint - must recreate
+  if (index.is_pk || index.is_unique) {
+    return "RECREATE";
+  }
+
+  // 3. Small table - quick to recreate
+  if (index.table_row_estimate < SMALL_TABLE_ROW_THRESHOLD) {
+    return "RECREATE";
+  }
+
+  // 4. Large table without clear path - needs manual analysis
+  return "UNCERTAIN";
 }
 
 /**
@@ -564,11 +622,11 @@ export async function getClusterInfo(client: Client, pgMajorVersion: number = 16
 
 /**
  * Get invalid indexes from the database (H001).
- * Invalid indexes are indexes that failed to build (e.g., due to CONCURRENTLY failure).
+ * Invalid indexes have indisvalid = false, typically from failed CREATE INDEX CONCURRENTLY.
  *
  * @param client - Connected PostgreSQL client
  * @param pgMajorVersion - PostgreSQL major version (default: 16)
- * @returns Array of invalid index entries with size and FK support info
+ * @returns Array of invalid index entries with observation data for decision tree analysis
  */
 export async function getInvalidIndexes(client: Client, pgMajorVersion: number = 16): Promise<InvalidIndex[]> {
   const sql = getMetricSql(METRIC_NAMES.H001, pgMajorVersion);
@@ -576,6 +634,7 @@ export async function getInvalidIndexes(client: Client, pgMajorVersion: number =
   return result.rows.map((row) => {
     const transformed = transformMetricRow(row);
     const indexSizeBytes = parseInt(String(transformed.index_size_bytes || 0), 10);
+
     return {
       schema_name: String(transformed.schema_name || ""),
       table_name: String(transformed.table_name || ""),
@@ -585,6 +644,13 @@ export async function getInvalidIndexes(client: Client, pgMajorVersion: number =
       index_size_pretty: formatBytes(indexSizeBytes),
       index_definition: String(transformed.index_definition || ""),
       supports_fk: toBool(transformed.supports_fk),
+      is_pk: toBool(transformed.is_pk),
+      is_unique: toBool(transformed.is_unique),
+      constraint_name: transformed.constraint_name ? String(transformed.constraint_name) : null,
+      table_row_estimate: parseInt(String(transformed.table_row_estimate || 0), 10),
+      has_valid_duplicate: toBool(transformed.has_valid_duplicate),
+      valid_duplicate_name: transformed.valid_index_name ? String(transformed.valid_index_name) : null,
+      valid_duplicate_definition: transformed.valid_index_definition ? String(transformed.valid_index_definition) : null,
     };
   });
 }

package/lib/init.ts

@@ -7,6 +7,32 @@ import * as path from "path";
 
 export const DEFAULT_MONITORING_USER = "postgres_ai_mon";
 
+/**
+ * Database provider type. Affects which prepare-db steps are executed.
+ * Known providers have specific behavior adjustments; unknown providers use default behavior.
+ * TODO: Consider auto-detecting provider from connection string or server version string.
+ * TODO: Consider making this more flexible via a config that specifies which steps/checks to skip.
+ */
+export type DbProvider = string;
+
+/** Known providers with special handling. Unknown providers are treated as self-managed. */
+export const KNOWN_PROVIDERS = ["self-managed", "supabase"] as const;
+
+/** Providers where we skip role creation (users managed externally). */
+const SKIP_ROLE_CREATION_PROVIDERS = ["supabase"];
+
+/** Providers where we skip ALTER USER statements (restricted by provider). */
+const SKIP_ALTER_USER_PROVIDERS = ["supabase"];
+
+/** Providers where we skip search_path verification (not set via ALTER USER). */
+const SKIP_SEARCH_PATH_CHECK_PROVIDERS = ["supabase"];
+
+/** Check if a provider is known and return a warning message if not. */
+export function validateProvider(provider: string | undefined): string | null {
+  if (!provider || KNOWN_PROVIDERS.includes(provider as any)) return null;
+  return `Unknown provider "${provider}". Known providers: ${KNOWN_PROVIDERS.join(", ")}. Treating as self-managed.`;
+}
+
 export type PgClientConfig = {
   connectionString?: string;
   host?: string;
@@ -458,10 +484,13 @@ export async function buildInitPlan(params: {
   monitoringUser?: string;
   monitoringPassword: string;
   includeOptionalPermissions: boolean;
+  /** Provider type. Affects which steps are included. Defaults to "self-managed". */
+  provider?: DbProvider;
 }): Promise<InitPlan> {
   // NOTE: kept async for API stability / potential future async template loading.
   const monitoringUser = params.monitoringUser || DEFAULT_MONITORING_USER;
   const database = params.database;
+  const provider = params.provider ?? "self-managed";
 
   const qRole = quoteIdent(monitoringUser);
   const qDb = quoteIdent(database);
@@ -475,12 +504,15 @@ export async function buildInitPlan(params: {
     DB_IDENT: qDb,
   };
 
-  // Role creation/update is done in one template file.
-  // Always use a single DO block to avoid race conditions between "role exists?" checks and CREATE USER.
-  // We:
-  // - create role if missing (and handle duplicate_object in case another session created it concurrently),
-  // - then ALTER ROLE to ensure the password is set to the desired value.
-  const roleStmt = `do $$ begin
+  // Some providers (e.g., Supabase) manage users externally - skip role creation.
+  // TODO: Make this more flexible by allowing users to specify which steps to skip via config.
+  if (!SKIP_ROLE_CREATION_PROVIDERS.includes(provider)) {
+    // Role creation/update is done in one template file.
+    // Always use a single DO block to avoid race conditions between "role exists?" checks and CREATE USER.
+    // We:
+    // - create role if missing (and handle duplicate_object in case another session created it concurrently),
+    // - then ALTER ROLE to ensure the password is set to the desired value.
+    const roleStmt = `do $$ begin
   if not exists (select 1 from pg_catalog.pg_roles where rolname = ${qRoleNameLit}) then
     begin
       create user ${qRole} with password ${qPw};
@@ -491,30 +523,54 @@ export async function buildInitPlan(params: {
   alter user ${qRole} with password ${qPw};
 end $$;`;
 
-  const roleSql = applyTemplate(loadSqlTemplate("01.role.sql"), { ...vars, ROLE_STMT: roleStmt });
-  steps.push({ name: "01.role", sql: roleSql });
+    const roleSql = applyTemplate(loadSqlTemplate("01.role.sql"), { ...vars, ROLE_STMT: roleStmt });
+    steps.push({ name: "01.role", sql: roleSql });
+  }
 
+  // Extensions should be created before permissions (so we can grant permissions on them)
   steps.push({
-    name: "02.permissions",
-    sql: applyTemplate(loadSqlTemplate("02.permissions.sql"), vars),
+    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.
+  if (SKIP_ALTER_USER_PROVIDERS.includes(provider)) {
+    permissionsSql = permissionsSql
+      .split("\n")
+      .filter((line) => {
+        const trimmed = line.trim();
+        // Keep comments and empty lines
+        if (trimmed.startsWith("--") || trimmed === "") return true;
+        // Filter out ALTER USER statements (case-insensitive, flexible whitespace)
+        return !/^\s*alter\s+user\s+/i.test(line);
+      })
+      .join("\n");
+  }
+
+  steps.push({
+    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,
       }
     );
@@ -607,11 +663,108 @@ 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;
   monitoringUser: string;
   includeOptionalPermissions: boolean;
+  /** Provider type. Affects which checks are performed. */
+  provider?: DbProvider;
 }): Promise<VerifyInitResult> {
   // Use a repeatable-read snapshot so all checks see a consistent view.
   await params.client.query("begin isolation level repeatable read;");
@@ -621,6 +774,7 @@ export async function verifyInitSetup(params: {
 
     const role = params.monitoringUser;
     const db = params.database;
+    const provider = params.provider ?? "self-managed";
 
     const roleRes = await params.client.query("select 1 from pg_catalog.pg_roles where rolname = $1", [role]);
     const roleExists = (roleRes.rowCount ?? 0) > 0;
@@ -684,16 +838,20 @@ export async function verifyInitSetup(params: {
       missingRequired.push("USAGE on schema public");
     }
 
-    const rolcfgRes = await params.client.query("select rolconfig from pg_catalog.pg_roles where rolname = $1", [role]);
-    const rolconfig = rolcfgRes.rows?.[0]?.rolconfig;
-    const spLine = Array.isArray(rolconfig) ? rolconfig.find((v: any) => String(v).startsWith("search_path=")) : undefined;
-    if (typeof spLine !== "string" || !spLine) {
-      missingRequired.push("role search_path is set");
-    } else {
-      // We accept any ordering as long as postgres_ai, public, and pg_catalog are included.
-      const sp = spLine.toLowerCase();
-      if (!sp.includes("postgres_ai") || !sp.includes("public") || !sp.includes("pg_catalog")) {
-        missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
+    // Some providers don't allow setting search_path via ALTER USER - skip this check.
+    // TODO: Make this more flexible by allowing users to specify which checks to skip via config.
+    if (!SKIP_SEARCH_PATH_CHECK_PROVIDERS.includes(provider)) {
+      const rolcfgRes = await params.client.query("select rolconfig from pg_catalog.pg_roles where rolname = $1", [role]);
+      const rolconfig = rolcfgRes.rows?.[0]?.rolconfig;
+      const spLine = Array.isArray(rolconfig) ? rolconfig.find((v: any) => String(v).startsWith("search_path=")) : undefined;
+      if (typeof spLine !== "string" || !spLine) {
+        missingRequired.push("role search_path is set");
+      } else {
+        // We accept any ordering as long as postgres_ai, public, and pg_catalog are included.
+        const sp = spLine.toLowerCase();
+        if (!sp.includes("postgres_ai") || !sp.includes("public") || !sp.includes("pg_catalog")) {
+          missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
+        }
       }
     }