cynx-lib 1.3.37 → 1.3.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cynx-lib",
-  "version": "1.3.37",
+  "version": "1.3.38",
   "type": "module",
   "main": "./index.js",
   "bin": {
@@ -10,6 +10,7 @@
     ".": "./index.js",
     "./ui": "./ui/index.js",
     "./utils": "./utils/index.js",
+    "./db": "./utils/utils/db.js",
     "./gen": "./gen.js"
   },
   "peerDependencies": {

package/utils/index.js

@@ -7,6 +7,7 @@ export * from './utils/storage.js';
 export * from './utils/duration.js';
 export * from './utils/session.js';
 export * from './utils/ui.js';
+export * from './utils/db.js';
 
 export { default as uidUtil } from './utils/uid.js';
 export { default as realtimeUtil } from './utils/realtime.js';
@@ -16,3 +17,4 @@ export { default as storageUtil } from './utils/storage.js';
 export { default as durationUtil } from './utils/duration.js';
 export { default as sessionUtil } from './utils/session.js';
 export { default as uiUtil } from './utils/ui.js';
+export { default as dbUtil } from './utils/db.js';

package/utils/utils/db.js

@@ -0,0 +1,946 @@
+/**
+ * cynx/utils — Universal Zero-Lock Database Schema Sync Engine (db.js)
+ *
+ * Automatically and non-destructively synchronizes PostgreSQL databases with a declarative schema.sql:
+ *  - Fresh database detection (applies full schema.sql in one fast pass)
+ *  - Zero-Lock catalog inspection (queries information_schema and pg_catalog with 0ms lock)
+ *  - Incremental sync: adds missing tables, columns, constraints, indexes without dropping existing data
+ *  - Executes custom data migration/seed `DO $$ ... $$` blocks
+ *  - Safe DDL execution with retry on lock timeouts and deadlocks
+ *  - Supports dry-run and custom loggers
+ *
+ * Works in Node.js (CommonJS & ESM), Serverless, and Container environments.
+ * Zero external dependencies.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// ─── SAFE DDL RUNNER ────────────────────────────────────────────────────────────
+
+/**
+ * Run an individual DDL statement safely with automatic retries on lock timeouts / deadlocks.
+ *
+ * @param {Function} queryFn (sql: string) => Promise<any>
+ * @param {string} sql DDL SQL command
+ * @param {string} [label='DDL'] Operation label for logging
+ * @param {object} [options]
+ * @param {number} [options.maxRetries=3] Maximum number of retry attempts
+ * @param {number} [options.retryDelayMs=300] Base backoff delay in ms
+ * @param {object} [options.logger=console] Logger instance
+ * @returns {Promise<boolean>} True if executed successfully, false otherwise
+ */
+export async function runSafeDdl(queryFn, sql, label = 'DDL', { maxRetries = 3, retryDelayMs = 300, logger = console } = {}) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      await queryFn(sql);
+      return true;
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      const isLockTimeout = msg.includes('lock timeout') || msg.includes('deadlock') || msg.includes('canceling statement due to lock timeout');
+
+      if (isLockTimeout && attempt < maxRetries) {
+        if (logger && logger.warn) {
+          logger.warn(`[DB Sync] Lock timeout on ${label} (attempt ${attempt}/${maxRetries}), retrying in ${retryDelayMs * attempt}ms...`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, retryDelayMs * attempt));
+        continue;
+      }
+
+      if (logger && logger.warn) {
+        logger.warn(`[DB Sync] Notice on ${label}: ${msg}`);
+      }
+      return false;
+    }
+  }
+  return false;
+}
+
+// ─── SCHEMA PARSER FUNCTIONS ───────────────────────────────────────────────────
+
+/**
+ * Parse CREATE TABLE statements and extract table names and column definitions.
+ *
+ * @param {string} schemaSql
+ * @returns {Array<{ name: string, columns: Array<{ name: string, def: string, raw: string }>, fullCreateSql: string }>}
+ */
+export function parseSchemaTables(schemaSql) {
+  if (!schemaSql || typeof schemaSql !== 'string') return [];
+  const tableRegex = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([a-zA-Z0-9_]+)\s*\(([\s\S]*?)\);/gi;
+  let match;
+  const tables = [];
+
+  while ((match = tableRegex.exec(schemaSql)) !== null) {
+    const tableName = match[1].toLowerCase();
+    const body = match[2];
+    const columns = [];
+
+    const lines = body.split('\n');
+    for (const rawLine of lines) {
+      const line = rawLine.trim().replace(/,$/, '');
+      if (!line || line.startsWith('--') || line.startsWith('/*')) continue;
+      if (/^(PRIMARY\s+KEY|FOREIGN\s+KEY|UNIQUE|CONSTRAINT|CHECK)\b/i.test(line)) continue;
+
+      const colMatch = line.match(/^([a-zA-Z0-9_]+)\s+([\s\S]+)$/i);
+      if (colMatch) {
+        const colName = colMatch[1].toLowerCase();
+        let colDef = colMatch[2].trim();
+        // Remove PRIMARY KEY from incremental ADD COLUMN definition (handled at table creation)
+        colDef = colDef.replace(/\bPRIMARY\s+KEY\b/gi, '').trim();
+        columns.push({ name: colName, def: colDef, raw: line });
+      }
+    }
+
+    tables.push({
+      name: tableName,
+      columns,
+      fullCreateSql: match[0],
+    });
+  }
+
+  return tables;
+}
+
+/**
+ * Parse explicit ALTER TABLE ADD COLUMN statements.
+ *
+ * @param {string} schemaSql
+ * @returns {Array<{ table: string, column: string, def: string, raw: string }>}
+ */
+export function parseSchemaAlterColumns(schemaSql) {
+  if (!schemaSql || typeof schemaSql !== 'string') return [];
+  const alterAddRegex = /ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?([a-zA-Z0-9_]+)\s+ADD\s+COLUMN\s+(?:IF\s+NOT\s+EXISTS\s+)?([a-zA-Z0-9_]+)\s+([^;]+);/gi;
+  let match;
+  const alterAdds = [];
+
+  while ((match = alterAddRegex.exec(schemaSql)) !== null) {
+    alterAdds.push({
+      table: match[1].toLowerCase(),
+      column: match[2].toLowerCase(),
+      def: match[3].trim(),
+      raw: match[0],
+    });
+  }
+
+  return alterAdds;
+}
+
+/**
+ * Parse ALTER TABLE DROP CONSTRAINT statements.
+ *
+ * @param {string} schemaSql
+ * @returns {Array<{ table: string, constraint: string, raw: string }>}
+ */
+export function parseSchemaDropConstraints(schemaSql) {
+  if (!schemaSql || typeof schemaSql !== 'string') return [];
+  const dropConstRegex = /ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?([a-zA-Z0-9_]+)\s+DROP\s+CONSTRAINT\s+(?:IF\s+EXISTS\s+)?([a-zA-Z0-9_]+);/gi;
+  let match;
+  const dropConstraints = [];
+
+  while ((match = dropConstRegex.exec(schemaSql)) !== null) {
+    dropConstraints.push({
+      table: match[1].toLowerCase(),
+      constraint: match[2].toLowerCase(),
+      raw: match[0],
+    });
+  }
+
+  return dropConstraints;
+}
+
+/**
+ * Parse DROP INDEX statements.
+ *
+ * @param {string} schemaSql
+ * @returns {Array<{ name: string, raw: string }>}
+ */
+export function parseSchemaDropIndexes(schemaSql) {
+  if (!schemaSql || typeof schemaSql !== 'string') return [];
+  const dropIndexRegex = /DROP\s+INDEX\s+(?:IF\s+EXISTS\s+)?([a-zA-Z0-9_]+);/gi;
+  let match;
+  const dropIndexes = [];
+
+  while ((match = dropIndexRegex.exec(schemaSql)) !== null) {
+    dropIndexes.push({
+      name: match[1].toLowerCase(),
+      raw: match[0],
+    });
+  }
+
+  return dropIndexes;
+}
+
+/**
+ * Parse CREATE [UNIQUE] INDEX statements.
+ *
+ * @param {string} schemaSql
+ * @returns {Array<{ unique: boolean, name: string, table: string, rest: string, raw: string }>}
+ */
+export function parseSchemaIndexes(schemaSql) {
+  if (!schemaSql || typeof schemaSql !== 'string') return [];
+  const indexRegex = /CREATE\s+(UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?([a-zA-Z0-9_]+)\s+ON\s+([a-zA-Z0-9_]+)\s*([\s\S]*?);/gi;
+  let match;
+  const indexes = [];
+
+  while ((match = indexRegex.exec(schemaSql)) !== null) {
+    indexes.push({
+      unique: Boolean(match[1]),
+      name: match[2].toLowerCase(),
+      table: match[3].toLowerCase(),
+      rest: match[4].trim(),
+      raw: match[0],
+    });
+  }
+
+  return indexes;
+}
+
+/**
+ * Parse procedural DO $$ ... $$ blocks (used for data migrations and seeding).
+ *
+ * @param {string} schemaSql
+ * @returns {string[]} Array of DO $$ ... $$ SQL strings
+ */
+export function parseSchemaDoBlocks(schemaSql) {
+  if (!schemaSql || typeof schemaSql !== 'string') return [];
+  const doRegex = /DO\s+\$\$\s*BEGIN([\s\S]*?)END\s+\$\$;/gi;
+  let match;
+  const doBlocks = [];
+
+  while ((match = doRegex.exec(schemaSql)) !== null) {
+    doBlocks.push(match[0]);
+  }
+
+  return doBlocks;
+}
+
+/**
+ * Parse entire schema SQL into structured components.
+ *
+ * @param {string} schemaSql
+ * @returns {{
+ *   tables: ReturnType<typeof parseSchemaTables>,
+ *   alterAdds: ReturnType<typeof parseSchemaAlterColumns>,
+ *   dropConstraints: ReturnType<typeof parseSchemaDropConstraints>,
+ *   dropIndexes: ReturnType<typeof parseSchemaDropIndexes>,
+ *   indexes: ReturnType<typeof parseSchemaIndexes>,
+ *   doBlocks: string[]
+ * }}
+ */
+export function parseSchema(schemaSql) {
+  return {
+    tables: parseSchemaTables(schemaSql),
+    alterAdds: parseSchemaAlterColumns(schemaSql),
+    dropConstraints: parseSchemaDropConstraints(schemaSql),
+    dropIndexes: parseSchemaDropIndexes(schemaSql),
+    indexes: parseSchemaIndexes(schemaSql),
+    doBlocks: parseSchemaDoBlocks(schemaSql),
+  };
+}
+
+// ─── MAIN DB SYNC FUNCTION ─────────────────────────────────────────────────────
+
+/**
+ * Universal Zero-Lock Database Schema Synchronizer.
+ *
+ * @param {object} options
+ * @param {object} [options.pool] Postgres Pool instance (e.g. from 'pg')
+ * @param {Function} [options.query] Custom query function `(sql, params) => Promise<{ rows: any[], rowCount: number }>`
+ * @param {string} [options.schemaSql] Raw SQL string containing the schema definitions
+ * @param {string} [options.schemaPath] Path to schema.sql file
+ * @param {string} [options.tableSchema='public'] PostgreSQL schema name (default: 'public')
+ * @param {string} [options.freshCheckTable] Optional table name to test for fresh DB (defaults to checking if table count is 0)
+ * @param {object|boolean} [options.logger=console] Logger instance or false to suppress logs
+ * @param {boolean} [options.dryRun=false] If true, previews changes without executing DDL
+ * @param {number} [options.maxRetries=3] Max retries on lock timeouts
+ * @param {number} [options.retryDelayMs=300] Base backoff delay on lock timeouts
+ * @param {boolean} [options.throwOnError=false] If true, rethrows caught errors
+ * @returns {Promise<{
+ *   success: boolean,
+ *   isFreshDb: boolean,
+ *   createdTables: string[],
+ *   addedColumns: string[],
+ *   createdIndexes: string[],
+ *   droppedConstraints: string[],
+ *   droppedIndexes: string[],
+ *   executedDoBlocks: number,
+ *   changesCount: number,
+ *   durationMs: number,
+ *   summary: string,
+ *   error?: Error
+ * }>}
+ */
+export async function sync_db(options = {}) {
+  const startTime = Date.now();
+  const {
+    pool,
+    query: customQuery,
+    schemaSql: directSql,
+    schemaPath,
+    tableSchema = 'public',
+    freshCheckTable,
+    logger: rawLogger = console,
+    dryRun = false,
+    maxRetries = 3,
+    retryDelayMs = 300,
+    throwOnError = false,
+  } = options;
+
+  const logger = rawLogger === false ? null : rawLogger || console;
+  const log = (msg) => { if (logger && logger.log) logger.log(`[DB Sync] ${msg}`); };
+  const warn = (msg) => { if (logger && logger.warn) logger.warn(`[DB Sync] ${msg}`); };
+  const error = (msg, err) => { if (logger && logger.error) logger.error(`[DB Sync] ${msg}`, err || ''); };
+
+  // Resolve query executor
+  let queryFn = customQuery;
+  if (!queryFn && pool) {
+    queryFn = (text, params) => pool.query(text, params);
+  }
+
+  if (typeof queryFn !== 'function') {
+    const err = new Error('[cynx/db] No database query function or pool provided to sync_db()');
+    error(err.message);
+    if (throwOnError) throw err;
+    return {
+      success: false,
+      isFreshDb: false,
+      createdTables: [],
+      addedColumns: [],
+      createdIndexes: [],
+      droppedConstraints: [],
+      droppedIndexes: [],
+      executedDoBlocks: 0,
+      changesCount: 0,
+      durationMs: 0,
+      summary: 'Failed: No query executor',
+      error: err,
+    };
+  }
+
+  // Resolve schema SQL
+  let schemaSql = directSql;
+  if (!schemaSql && schemaPath) {
+    const resolvedPath = path.resolve(schemaPath);
+    if (!fs.existsSync(resolvedPath)) {
+      const err = new Error(`[cynx/db] schema.sql not found at: ${resolvedPath}`);
+      warn(err.message);
+      if (throwOnError) throw err;
+      return {
+        success: false,
+        isFreshDb: false,
+        createdTables: [],
+        addedColumns: [],
+        createdIndexes: [],
+        droppedConstraints: [],
+        droppedIndexes: [],
+        executedDoBlocks: 0,
+        changesCount: 0,
+        durationMs: 0,
+        summary: 'Failed: schema.sql file not found',
+        error: err,
+      };
+    }
+    schemaSql = fs.readFileSync(resolvedPath, 'utf-8');
+  }
+
+  if (!schemaSql || typeof schemaSql !== 'string' || !schemaSql.trim()) {
+    const err = new Error('[cynx/db] No schema SQL provided to sync_db()');
+    warn(err.message);
+    if (throwOnError) throw err;
+    return {
+      success: false,
+      isFreshDb: false,
+      createdTables: [],
+      addedColumns: [],
+      createdIndexes: [],
+      droppedConstraints: [],
+      droppedIndexes: [],
+      executedDoBlocks: 0,
+      changesCount: 0,
+      durationMs: 0,
+      summary: 'Failed: Empty schema SQL',
+      error: err,
+    };
+  }
+
+  try {
+    // ── 1. Fresh Database Check ────────────────────────────────────────────────
+    let isFreshDb = false;
+
+    if (freshCheckTable) {
+      const tableCheck = await queryFn(
+        "SELECT 1 FROM information_schema.tables WHERE table_schema = $1 AND table_name = $2 LIMIT 1",
+        [tableSchema, String(freshCheckTable).toLowerCase()]
+      );
+      isFreshDb = tableCheck.rowCount === 0;
+    } else {
+      const countCheck = await queryFn(
+        "SELECT count(*)::int as count FROM information_schema.tables WHERE table_schema = $1 AND table_type = 'BASE TABLE'",
+        [tableSchema]
+      );
+      const tableCount = countCheck.rows && countCheck.rows[0] ? Number(countCheck.rows[0].count) : 0;
+      isFreshDb = tableCount === 0;
+    }
+
+    if (isFreshDb) {
+      log('Fresh database detected. Applying full schema.sql in one pass...');
+      if (!dryRun) {
+        await queryFn(schemaSql);
+      }
+      const durationMs = Date.now() - startTime;
+      log(`Fresh database schema initialized successfully (${durationMs}ms)`);
+      return {
+        success: true,
+        isFreshDb: true,
+        createdTables: ['* (full schema applied)'],
+        addedColumns: [],
+        createdIndexes: [],
+        droppedConstraints: [],
+        droppedIndexes: [],
+        executedDoBlocks: 0,
+        changesCount: 1,
+        durationMs,
+        summary: `Fresh database initialized in ${durationMs}ms`,
+      };
+    }
+
+    log('Analyzing schema.sql and comparing with database catalogs (Zero-Lock)...');
+
+    // ── 2. Query System Catalogs in parallel (AccessShareLock only - 0ms blocking) ──
+    const [tablesRes, colsRes, idxRes, conRes] = await Promise.all([
+      queryFn("SELECT table_name FROM information_schema.tables WHERE table_schema = $1 AND table_type = 'BASE TABLE'", [tableSchema]),
+      queryFn("SELECT table_name, column_name FROM information_schema.columns WHERE table_schema = $1", [tableSchema]),
+      queryFn("SELECT indexname FROM pg_indexes WHERE schemaname = $1", [tableSchema]),
+      queryFn("SELECT conname FROM pg_constraint"),
+    ]);
+
+    const existingTables = new Set((tablesRes.rows || []).map((r) => String(r.table_name).toLowerCase()));
+    const existingColumns = new Set((colsRes.rows || []).map((r) => `${String(r.table_name).toLowerCase()}.${String(r.column_name).toLowerCase()}`));
+    const existingIndexes = new Set((idxRes.rows || []).map((r) => String(r.indexname).toLowerCase()));
+    const existingConstraints = new Set((conRes.rows || []).map((r) => String(r.conname).toLowerCase()));
+
+    const createdTables = [];
+    const addedColumns = [];
+    const createdIndexes = [];
+    const droppedConstraints = [];
+    const droppedIndexes = [];
+    let executedDoBlocks = 0;
+
+    // ── 3. Parse Schema Rules from schema.sql ──────────────────────────────────
+    const parsed = parseSchema(schemaSql);
+    const safeDdlOpts = { maxRetries, retryDelayMs, logger };
+
+    // ── Step 0: Execute Custom DO Blocks (Data migrations / fixes / seed updates)
+    for (const doSql of parsed.doBlocks) {
+      if (!dryRun) {
+        await runSafeDdl(queryFn, doSql, 'schema do-block', safeDdlOpts);
+      }
+      executedDoBlocks++;
+    }
+
+    // ── Step A: Ensure Tables ─────────────────────────────────────────────────
+    for (const table of parsed.tables) {
+      if (!existingTables.has(table.name)) {
+        if (!dryRun) {
+          const ok = await runSafeDdl(queryFn, table.fullCreateSql, `create table ${table.name}`, safeDdlOpts);
+          if (ok) {
+            existingTables.add(table.name);
+            createdTables.push(table.name);
+            for (const col of table.columns) {
+              existingColumns.add(`${table.name}.${col.name}`);
+            }
+            log(`Created missing table: ${table.name}`);
+          }
+        } else {
+          createdTables.push(table.name);
+          log(`[DryRun] Would create table: ${table.name}`);
+        }
+      }
+    }
+
+    // ── Step B: Ensure Columns from CREATE TABLE definitions ───────────────────
+    for (const table of parsed.tables) {
+      if (existingTables.has(table.name)) {
+        for (const col of table.columns) {
+          const colKey = `${table.name}.${col.name}`;
+          if (!existingColumns.has(colKey)) {
+            const sql = `ALTER TABLE ${table.name} ADD COLUMN IF NOT EXISTS ${col.name} ${col.def};`;
+            if (!dryRun) {
+              const ok = await runSafeDdl(queryFn, sql, `add column ${colKey}`, safeDdlOpts);
+              if (ok) {
+                existingColumns.add(colKey);
+                addedColumns.push(colKey);
+                log(`Added missing column: ${colKey}`);
+              }
+            } else {
+              addedColumns.push(colKey);
+              log(`[DryRun] Would add column: ${colKey}`);
+            }
+          }
+        }
+      }
+    }
+
+    // ── Step C: Ensure Columns from explicit ALTER TABLE ADD COLUMN ────────────
+    for (const alter of parsed.alterAdds) {
+      const colKey = `${alter.table}.${alter.column}`;
+      if (existingTables.has(alter.table) && !existingColumns.has(colKey)) {
+        const sql = `ALTER TABLE ${alter.table} ADD COLUMN IF NOT EXISTS ${alter.column} ${alter.def};`;
+        if (!dryRun) {
+          const ok = await runSafeDdl(queryFn, sql, `alter add column ${colKey}`, safeDdlOpts);
+          if (ok) {
+            existingColumns.add(colKey);
+            addedColumns.push(colKey);
+            log(`Added missing column: ${colKey}`);
+          }
+        } else {
+          addedColumns.push(colKey);
+          log(`[DryRun] Would add column: ${colKey}`);
+        }
+      }
+    }
+
+    // ── Step D: Drop Obsolete Constraints & Indexes ───────────────────────────
+    for (const drop of parsed.dropConstraints) {
+      if (existingConstraints.has(drop.constraint)) {
+        if (!dryRun) {
+          const ok = await runSafeDdl(queryFn, drop.raw, `drop constraint ${drop.constraint}`, safeDdlOpts);
+          if (ok) {
+            existingConstraints.delete(drop.constraint);
+            droppedConstraints.push(`${drop.table}.${drop.constraint}`);
+            log(`Dropped obsolete constraint: ${drop.table}.${drop.constraint}`);
+          }
+        } else {
+          droppedConstraints.push(`${drop.table}.${drop.constraint}`);
+          log(`[DryRun] Would drop constraint: ${drop.table}.${drop.constraint}`);
+        }
+      }
+    }
+
+    for (const drop of parsed.dropIndexes) {
+      if (existingIndexes.has(drop.name)) {
+        if (!dryRun) {
+          const ok = await runSafeDdl(queryFn, drop.raw, `drop index ${drop.name}`, safeDdlOpts);
+          if (ok) {
+            existingIndexes.delete(drop.name);
+            droppedIndexes.push(drop.name);
+            log(`Dropped obsolete index: ${drop.name}`);
+          }
+        } else {
+          droppedIndexes.push(drop.name);
+          log(`[DryRun] Would drop index: ${drop.name}`);
+        }
+      }
+    }
+
+    // ── Step E: Ensure Indexes (Non-blocking) ──────────────────────────────────
+    for (const idx of parsed.indexes) {
+      if (existingTables.has(idx.table) && !existingIndexes.has(idx.name)) {
+        const uniqueClause = idx.unique ? 'UNIQUE ' : '';
+        const sql = `CREATE ${uniqueClause}INDEX IF NOT EXISTS ${idx.name} ON ${idx.table} ${idx.rest};`;
+        if (!dryRun) {
+          const ok = await runSafeDdl(queryFn, sql, `create index ${idx.name}`, safeDdlOpts);
+          if (ok) {
+            existingIndexes.add(idx.name);
+            createdIndexes.push(idx.name);
+            log(`Created index: ${idx.name}`);
+          }
+        } else {
+          createdIndexes.push(idx.name);
+          log(`[DryRun] Would create index: ${idx.name}`);
+        }
+      }
+    }
+
+    const durationMs = Date.now() - startTime;
+    const summaryParts = [];
+    if (createdTables.length > 0) summaryParts.push(`${createdTables.length} tables created`);
+    if (addedColumns.length > 0) summaryParts.push(`${addedColumns.length} columns added`);
+    if (createdIndexes.length > 0) summaryParts.push(`${createdIndexes.length} indexes created`);
+    if (droppedConstraints.length > 0) summaryParts.push(`${droppedConstraints.length} constraints dropped`);
+    if (droppedIndexes.length > 0) summaryParts.push(`${droppedIndexes.length} indexes dropped`);
+    if (executedDoBlocks > 0) summaryParts.push(`${executedDoBlocks} migration blocks run`);
+
+    const changesCount = createdTables.length + addedColumns.length + createdIndexes.length + droppedConstraints.length + droppedIndexes.length;
+    const summary = summaryParts.length > 0
+      ? `Database synced in ${durationMs}ms: ${summaryParts.join(', ')}`
+      : `Database schema is up to date (0 changes needed, ${durationMs}ms)`;
+
+    log(summary);
+
+    return {
+      success: true,
+      isFreshDb: false,
+      createdTables,
+      addedColumns,
+      createdIndexes,
+      droppedConstraints,
+      droppedIndexes,
+      executedDoBlocks,
+      changesCount,
+      durationMs,
+      summary,
+    };
+  } catch (err) {
+    error('Database sync failed:', err.message);
+    if (throwOnError) throw err;
+    return {
+      success: false,
+      isFreshDb: false,
+      createdTables: [],
+      addedColumns: [],
+      createdIndexes: [],
+      droppedConstraints: [],
+      droppedIndexes: [],
+      executedDoBlocks: 0,
+      changesCount: 0,
+      durationMs: Date.now() - startTime,
+      summary: `Failed: ${err.message}`,
+      error: err,
+    };
+  }
+}
+
+// ─── DROP & RESET UTILITIES ───────────────────────────────────────────────────
+
+/**
+ * Universal Database Table Dropper (Clean Reset).
+ * Dynamically discovers all tables in the given schema and drops them with CASCADE (no hardcoded list).
+ *
+ * @param {object} options
+ * @param {object} [options.pool] Postgres Pool instance
+ * @param {Function} [options.query] Custom query function
+ * @param {string} [options.tableSchema='public'] PostgreSQL schema name (default: 'public')
+ * @param {object|boolean} [options.logger=console] Logger instance or false
+ * @param {boolean} [options.dryRun=false] If true, lists tables without executing drop
+ * @returns {Promise<{ success: boolean, droppedTables: string[], durationMs: number, summary: string, error?: Error }>}
+ */
+export async function drop_db(options = {}) {
+  const startTime = Date.now();
+  const {
+    pool,
+    query: customQuery,
+    tableSchema = 'public',
+    logger: rawLogger = console,
+    dryRun = false,
+  } = options;
+
+  const logger = rawLogger === false ? null : rawLogger || console;
+  const log = (msg) => { if (logger && logger.log) logger.log(`[DB Drop] ${msg}`); };
+  const error = (msg, err) => { if (logger && logger.error) logger.error(`[DB Drop] ${msg}`, err || ''); };
+
+  let queryFn = customQuery;
+  if (!queryFn && pool) {
+    queryFn = (text, params) => pool.query(text, params);
+  }
+
+  if (typeof queryFn !== 'function') {
+    const err = new Error('[cynx/db] No database query function or pool provided to drop_db()');
+    error(err.message);
+    return {
+      success: false,
+      droppedTables: [],
+      durationMs: 0,
+      summary: 'Failed: No query executor',
+      error: err,
+    };
+  }
+
+  try {
+    const res = await queryFn(
+      "SELECT table_name FROM information_schema.tables WHERE table_schema = $1 AND table_type = 'BASE TABLE'",
+      [tableSchema]
+    );
+    const tables = (res.rows || []).map((r) => r.table_name);
+
+    if (tables.length === 0) {
+      log(`No tables found in schema '${tableSchema}'. Nothing to drop.`);
+      return {
+        success: true,
+        droppedTables: [],
+        durationMs: Date.now() - startTime,
+        summary: `0 tables dropped (schema '${tableSchema}' was already empty)`,
+      };
+    }
+
+    if (dryRun) {
+      log(`[DryRun] Would drop ${tables.length} tables: ${tables.join(', ')}`);
+      return {
+        success: true,
+        droppedTables: tables,
+        durationMs: Date.now() - startTime,
+        summary: `[DryRun] ${tables.length} tables listed for drop`,
+      };
+    }
+
+    log(`Dropping ${tables.length} tables from schema '${tableSchema}' with CASCADE...`);
+
+    const dropSql = `
+      DO $$ DECLARE
+        r RECORD;
+      BEGIN
+        FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = '${tableSchema.replace(/'/g, "''")}') LOOP
+          EXECUTE 'DROP TABLE IF EXISTS ' || quote_ident(r.tablename) || ' CASCADE';
+        END LOOP;
+      END $$;
+    `;
+
+    await queryFn(dropSql);
+    const durationMs = Date.now() - startTime;
+    const summary = `Successfully dropped ${tables.length} tables in ${durationMs}ms`;
+    log(summary);
+
+    return {
+      success: true,
+      droppedTables: tables,
+      durationMs,
+      summary,
+    };
+  } catch (err) {
+    error('Failed to drop tables:', err.message);
+    return {
+      success: false,
+      droppedTables: [],
+      durationMs: Date.now() - startTime,
+      summary: `Failed: ${err.message}`,
+      error: err,
+    };
+  }
+}
+
+/**
+ * Reset / Truncate a specific table, delete specific rows, or drop and recreate a table cleanly.
+ *
+ * Examples:
+ *   // 1. Truncate entire table & restart auto-increment sequence:
+ *   await reset_table('late_records', { pool });
+ *
+ *   // 2. Delete specific rows matching criteria:
+ *   await reset_table('users', { pool, where: { role: 'tester', is_active: false } });
+ *   await reset_table('logs', { pool, where: "created_at < NOW() - INTERVAL '30 days'" });
+ *
+ *   // 3. Drop table and recreate from schema.sql:
+ *   await reset_table('metrics', { pool, schemaPath: './schema.sql', recreate: true });
+ *
+ * @param {string|object} tableOrOptions Target table name or options object
+ * @param {object} [options]
+ * @param {object} [options.pool] Postgres Pool instance
+ * @param {Function} [options.query] Custom query function
+ * @param {string} [options.table] Target table name (if not passed as 1st argument)
+ * @param {string|object|Array} [options.where] WHERE condition to delete specific rows instead of full truncate
+ * @param {boolean} [options.cascade=true] Truncate with CASCADE
+ * @param {boolean} [options.restartIdentity=true] Truncate with RESTART IDENTITY (resets sequences)
+ * @param {boolean} [options.recreate=false] If true, drops table and recreates it from schema.sql
+ * @param {string} [options.schemaSql] Schema SQL for recreate
+ * @param {string} [options.schemaPath] Path to schema.sql for recreate
+ * @param {object|boolean} [options.logger=console] Logger instance or false
+ * @returns {Promise<{ success: boolean, table: string, mode: 'truncate'|'delete'|'recreate', rowCount?: number, durationMs: number, summary: string, error?: Error }>}
+ */
+export async function reset_table(tableOrOptions, options = {}) {
+  const startTime = Date.now();
+  const opts = typeof tableOrOptions === 'object' && tableOrOptions !== null ? { ...tableOrOptions, ...options } : { ...options, table: tableOrOptions };
+  const {
+    table,
+    pool,
+    query: customQuery,
+    where,
+    cascade = true,
+    restartIdentity = true,
+    recreate = false,
+    schemaSql,
+    schemaPath,
+    logger: rawLogger = console,
+  } = opts;
+
+  const logger = rawLogger === false ? null : rawLogger || console;
+  const log = (msg) => { if (logger && logger.log) logger.log(`[DB Reset Table] ${msg}`); };
+  const error = (msg, err) => { if (logger && logger.error) logger.error(`[DB Reset Table] ${msg}`, err || ''); };
+
+  if (!table || typeof table !== 'string') {
+    const err = new Error('[cynx/db] Table name is required for reset_table()');
+    error(err.message);
+    return {
+      success: false,
+      table: '',
+      mode: 'truncate',
+      durationMs: 0,
+      summary: 'Failed: Missing table name',
+      error: err,
+    };
+  }
+
+  const cleanTable = table.trim().toLowerCase();
+  let queryFn = customQuery;
+  if (!queryFn && pool) {
+    queryFn = (text, params) => pool.query(text, params);
+  }
+
+  if (typeof queryFn !== 'function') {
+    const err = new Error('[cynx/db] No database query function or pool provided to reset_table()');
+    error(err.message);
+    return {
+      success: false,
+      table: cleanTable,
+      mode: 'truncate',
+      durationMs: 0,
+      summary: 'Failed: No query executor',
+      error: err,
+    };
+  }
+
+  try {
+    // ── Mode 1: Delete Specific Rows (WHERE condition provided) ────────────────
+    if (where) {
+      let whereClause = '';
+      let params = [];
+
+      if (typeof where === 'string') {
+        whereClause = where.trim().replace(/^WHERE\s+/i, '');
+      } else if (Array.isArray(where) && where.length > 0) {
+        whereClause = where[0].replace(/^WHERE\s+/i, '');
+        params = Array.isArray(where[1]) ? where[1] : [];
+      } else if (typeof where === 'object') {
+        const conditions = [];
+        let pIndex = 1;
+        for (const [key, val] of Object.entries(where)) {
+          if (val === null) {
+            conditions.push(`${key} IS NULL`);
+          } else {
+            conditions.push(`${key} = $${pIndex++}`);
+            params.push(val);
+          }
+        }
+        whereClause = conditions.join(' AND ');
+      }
+
+      if (!whereClause) {
+        throw new Error('[cynx/db] Invalid WHERE condition provided for row reset');
+      }
+
+      const sql = `DELETE FROM ${cleanTable} WHERE ${whereClause};`;
+      const res = await queryFn(sql, params);
+      const rowCount = res && typeof res.rowCount === 'number' ? res.rowCount : 0;
+      const durationMs = Date.now() - startTime;
+      const summary = `Deleted ${rowCount} rows from table '${cleanTable}' (${durationMs}ms)`;
+      log(summary);
+
+      return {
+        success: true,
+        table: cleanTable,
+        mode: 'delete',
+        rowCount,
+        durationMs,
+        summary,
+      };
+    }
+
+    // ── Mode 2: Recreate Table from Schema (DROP + SYNC) ───────────────────────
+    if (recreate) {
+      log(`Dropping table '${cleanTable}' with CASCADE for full recreation...`);
+      await queryFn(`DROP TABLE IF EXISTS ${cleanTable} CASCADE;`);
+
+      log(`Recreating table '${cleanTable}' via sync_db...`);
+      const syncResult = await sync_db({
+        pool,
+        query: queryFn,
+        schemaSql,
+        schemaPath,
+        logger,
+      });
+
+      const durationMs = Date.now() - startTime;
+      const summary = `Recreated table '${cleanTable}' from schema (${durationMs}ms)`;
+      log(summary);
+
+      return {
+        success: syncResult.success,
+        table: cleanTable,
+        mode: 'recreate',
+        durationMs,
+        summary,
+      };
+    }
+
+    // ── Mode 3: Truncate Table (Default: Fast, cascades, resets identity) ───────
+    const restartClause = restartIdentity ? ' RESTART IDENTITY' : '';
+    const cascadeClause = cascade ? ' CASCADE' : '';
+    const sql = `TRUNCATE TABLE ${cleanTable}${restartClause}${cascadeClause};`;
+
+    await queryFn(sql);
+    const durationMs = Date.now() - startTime;
+    const summary = `Truncated table '${cleanTable}'${restartClause}${cascadeClause} in ${durationMs}ms`;
+    log(summary);
+
+    return {
+      success: true,
+      table: cleanTable,
+      mode: 'truncate',
+      durationMs,
+      summary,
+    };
+  } catch (err) {
+    error(`Failed to reset table '${cleanTable}':`, err.message);
+    return {
+      success: false,
+      table: cleanTable,
+      mode: where ? 'delete' : recreate ? 'recreate' : 'truncate',
+      durationMs: Date.now() - startTime,
+      summary: `Failed: ${err.message}`,
+      error: err,
+    };
+  }
+}
+
+/**
+ * Hard Reset Database (Drop All Tables + Fresh Schema Sync).
+ *
+ * @param {object} options
+ * @returns {Promise<{ success: boolean, dropResult: object, syncResult: object }>}
+ */
+export async function reset_db(options = {}) {
+  const dropResult = await drop_db(options);
+  const syncResult = await sync_db(options);
+  return {
+    success: dropResult.success && syncResult.success,
+    dropResult,
+    syncResult,
+  };
+}
+
+// ─── CONVENIENCE ALIASES & EXPORTS ─────────────────────────────────────────────
+
+export const init_db = sync_db;
+export const initDb = sync_db;
+export const dropDb = drop_db;
+export const dropAllTables = drop_db;
+export const resetDb = reset_db;
+export const resetTable = reset_table;
+export const truncate_table = reset_table;
+export const truncateTable = reset_table;
+export const syncDb = sync_db;
+export const syncDatabaseSchema = sync_db;
+
+export default {
+  sync_db,
+  syncDb,
+  syncDatabaseSchema,
+  init_db,
+  initDb,
+  drop_db,
+  dropDb,
+  dropAllTables,
+  reset_db,
+  resetDb,
+  reset_table,
+  resetTable,
+  truncate_table,
+  truncateTable,
+  runSafeDdl,
+  parseSchema,
+  parseSchemaTables,
+  parseSchemaAlterColumns,
+  parseSchemaDropConstraints,
+  parseSchemaDropIndexes,
+  parseSchemaIndexes,
+  parseSchemaDoBlocks,
+};