postgresai 0.14.0-beta.12 → 0.14.0-beta.13

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,12 +523,30 @@ 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 });
+  }
+
+  let permissionsSql = applyTemplate(loadSqlTemplate("02.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: "02.permissions",
-    sql: applyTemplate(loadSqlTemplate("02.permissions.sql"), vars),
+    sql: permissionsSql,
   });
 
   // Helper functions (SECURITY DEFINER) for plan analysis and table info
@@ -612,6 +662,8 @@ export async function verifyInitSetup(params: {
   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 +673,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 +737,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");
+        }
       }
     }