@everystack/cli 0.4.102 → 0.4.104

package/src/cli/index-lock.ts

@@ -0,0 +1,65 @@
+/**
+ * ⚠ LOCK — which of a plan's statements build an index on a table that already holds rows.
+ *
+ * db:apply runs a plain `CREATE INDEX` inside its one transaction. PostgreSQL takes a SHARE lock
+ * on the table for the whole build, whatever its size: reads go on, INSERT/UPDATE/DELETE wait until
+ * the build finishes and the transaction commits. On a large table that is a write outage, so the
+ * plan says so, with the catalog's row estimate (`pg_class.reltuples`) to let the reader judge.
+ *
+ * Informational only: no --confirm, no exit code, and the plan is still "Safe to apply". Applying
+ * is unchanged. The estimate rides beside the snapshot (`rowEstimates`), never inside a table, so
+ * no fingerprint reads it.
+ *
+ * A table the same plan creates is not live, so it gets no line; an estimate of 0 is an empty table,
+ * no line; -1 is a table with data that was never analyzed, "row count unknown"; a read without
+ * estimates (an older ops Lambda) still warns, without a count.
+ */
+
+import { statementBody } from './sql-statement';
+import type { SchemaSnapshot } from './schema-introspect';
+
+export interface LockWarning {
+  index: string;
+  /** Schema-qualified, as the snapshot names it. */
+  table: string;
+  /** The estimate; null when the table has data but was never analyzed; absent when not read. */
+  rows?: number | null;
+}
+
+const IDENT = '"(?:[^"]|"")+"|[A-Za-z_][\\w$]*';
+const CREATE_INDEX = new RegExp(
+  `^CREATE\\s+(?:UNIQUE\\s+)?INDEX\\s+(?!CONCURRENTLY\\b)(?:IF\\s+NOT\\s+EXISTS\\s+)?(${IDENT})\\s+ON\\s+(?:ONLY\\s+)?((?:${IDENT})(?:\\.(?:${IDENT}))?)`,
+  'i',
+);
+const unquote = (part: string): string => (part.startsWith('"') ? part.slice(1, -1).replace(/""/g, '"') : part);
+const qualified = (name: string): string => {
+  const parts = name.match(new RegExp(IDENT, 'g')) ?? [name];
+  const clean = parts.map(unquote);
+  return clean.length === 1 ? `public.${clean[0]}` : clean.join('.');
+};
+
+export function indexLockWarnings(statements: readonly string[], live: SchemaSnapshot): LockWarning[] {
+  const liveTables = new Set(live.tables.map((t) => t.table));
+  const out: LockWarning[] = [];
+  for (const statement of statements) {
+    const m = CREATE_INDEX.exec(statementBody(statement));
+    if (!m) continue;
+    const table = qualified(m[2]);
+    if (!liveTables.has(table)) continue;
+    const estimate = live.rowEstimates?.[table];
+    if (estimate === 0) continue;
+    out.push({ index: unquote(m[1]), table, ...(estimate === undefined ? {} : { rows: estimate < 0 ? null : estimate }) });
+  }
+  return out;
+}
+
+const display = (table: string): string => (table.startsWith('public.') ? table.slice('public.'.length) : table);
+
+export function lockLines(warnings: readonly LockWarning[]): string[] {
+  return warnings.map((w) => {
+    const count = w.rows === undefined ? ''
+      : w.rows === null ? ' (row count unknown)'
+        : ` (about ${w.rows.toLocaleString('en-US')} ${w.rows === 1 ? 'row' : 'rows'})`;
+    return `⚠ LOCK — CREATE INDEX ${w.index} on ${display(w.table)} blocks writes to that table until it is built${count}.`;
+  });
+}

package/src/cli/index.ts

@@ -312,7 +312,7 @@ Usage:
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
   everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)
   everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (read-only). Runs as the SELECT-only 'reader' role when the stage has one (db:provision --with-reader + QUERY_DATABASE_URL wired to dbPlugin's queryDatabaseUrl); WITHOUT one it runs on the OPERATOR connection, fenced only by a read-only transaction — see docs/cli.md
-  everystack db:doctor         [--purge-after <days>] [--models <barrel>] [--stage <name>] [--direct | --database-url <api> [--admin-database-url <ops>]]  Check the DB is least-privilege + RLS-subject (api vs operator connection). No flag = ops-Lambda venue (auto-falls to direct via the stage secrets if the handler has no dbPlugin). --direct = probe both connections from the stage's DATABASE_URL + ADMIN_DATABASE_URL secrets; --database-url = explicit local venue (a lone URL is probed as both)
+  everystack db:doctor         [--destroy-after <days>] [--models <barrel>] [--stage <name>] [--direct | --database-url <api> [--admin-database-url <ops>]]  Check the DB is least-privilege + RLS-subject (api vs operator connection). No flag = ops-Lambda venue (auto-falls to direct via the stage secrets if the handler has no dbPlugin). --direct = probe both connections from the stage's DATABASE_URL + ADMIN_DATABASE_URL secrets; --database-url = explicit local venue (a lone URL is probed as both)
   everystack db:provision      --stage <name> [--direct | --database-url <url>] [--rotation-pairs] [--with-reader]  Create the least-privilege role chain (idempotent). --rotation-pairs creates A/B pairs for live rotation. --with-reader adds the SELECT-only 'reader' login db:query runs as, grants it read on the declared schemas, and writes QUERY_DATABASE_URL (opt-in once, then kept converged on every re-provision)
   everystack db:provision      --rotate --stage <name> [--slot api|ops|both] [--grace 60]  Rotate credentials live (A/B role swap, no deploy, no downtime)
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)

package/src/cli/lifecycle-canon.ts

@@ -29,7 +29,8 @@ export function canonOfFunction(fn: FunctionDescriptor): FunctionCanon {
     language: fn.language, secdef: fn.security === 'definer',
     volatility: { immutable: 'i', stable: 's', volatile: 'v' }[fn.volatility],
     strict: false, leakproof: false,
-    config: Array.isArray(fn.searchPath) ? [`search_path=${fn.searchPath.join(', ')}`] : [],
+    config: [...(Array.isArray(fn.searchPath) ? [`search_path=${fn.searchPath.join(', ')}`] : []),
+      ...(fn.lockTimeout === undefined ? [] : [`lock_timeout=${fn.lockTimeout}`])],
     owner: fn.owner ?? '(ambient)', execute: [...execute].sort(),
     // renderFunction adds exactly one newline on each side of the authored body.
     body: `\n${fn.body}\n`,