odac 1.4.8 → 1.4.10

package/src/Database/Migration.js

@@ -148,7 +148,8 @@ class Migration {
       } else {
         const currentColumns = await this._introspectColumns(knex, tableName)
         const currentIndexes = await this._introspectIndexes(knex, tableName)
-        const diff = this._computeDiff(desired, currentColumns, currentIndexes)
+        const currentForeignKeys = await this._introspectForeignKeys(knex, tableName)
+        const diff = this._computeDiff(desired, currentColumns, currentIndexes, currentForeignKeys)
 
         if (diff.length > 0) {
           operations.push(...diff.map(d => ({...d, table: tableName})))
@@ -379,6 +380,91 @@ class Migration {
     return result
   }
 
+  // ---------------------------------------------------------------------------
+  // FOREIGN KEY INTROSPECTION
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Introspects existing foreign key constraints for a given table.
+   * Why: The diff engine needs current FK state to detect when a schema adds, changes,
+   * or removes a `references` / `onDelete` / `onUpdate` definition on an existing column.
+   * @param {object} knex - Knex instance
+   * @param {string} tableName - Table to introspect
+   * @returns {Promise<Object>} Map of columnName -> {table, column, onDelete, onUpdate}
+   */
+  async _introspectForeignKeys(knex, tableName) {
+    const client = knex.client.config.client
+    const fks = {}
+
+    if (client === 'pg') {
+      const result = await knex.raw(
+        `SELECT
+           kcu.column_name,
+           ccu.table_name  AS foreign_table,
+           ccu.column_name AS foreign_column,
+           rc.delete_rule,
+           rc.update_rule,
+           tc.constraint_name
+         FROM information_schema.table_constraints tc
+         JOIN information_schema.key_column_usage kcu
+           ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+         JOIN information_schema.constraint_column_usage ccu
+           ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+         JOIN information_schema.referential_constraints rc
+           ON tc.constraint_name = rc.constraint_name AND tc.table_schema = rc.constraint_schema
+         WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = ?`,
+        [tableName]
+      )
+      for (const row of result.rows) {
+        fks[row.column_name] = {
+          table: row.foreign_table,
+          column: row.foreign_column,
+          onDelete: (row.delete_rule || 'NO ACTION').toUpperCase(),
+          onUpdate: (row.update_rule || 'NO ACTION').toUpperCase(),
+          constraintName: row.constraint_name
+        }
+      }
+    } else if (client === 'mysql2' || client === 'mysql') {
+      const [rows] = await knex.raw(
+        `SELECT
+           kcu.COLUMN_NAME          AS column_name,
+           kcu.REFERENCED_TABLE_NAME AS foreign_table,
+           kcu.REFERENCED_COLUMN_NAME AS foreign_column,
+           rc.DELETE_RULE            AS delete_rule,
+           rc.UPDATE_RULE            AS update_rule,
+           kcu.CONSTRAINT_NAME       AS constraint_name
+         FROM information_schema.KEY_COLUMN_USAGE kcu
+         JOIN information_schema.REFERENTIAL_CONSTRAINTS rc
+           ON kcu.CONSTRAINT_NAME = rc.CONSTRAINT_NAME AND kcu.TABLE_SCHEMA = rc.CONSTRAINT_SCHEMA
+         WHERE kcu.TABLE_SCHEMA = DATABASE() AND kcu.TABLE_NAME = ? AND kcu.REFERENCED_TABLE_NAME IS NOT NULL`,
+        [tableName]
+      )
+      for (const row of rows) {
+        fks[row.column_name] = {
+          table: row.foreign_table,
+          column: row.foreign_column,
+          onDelete: (row.delete_rule || 'NO ACTION').toUpperCase(),
+          onUpdate: (row.update_rule || 'NO ACTION').toUpperCase(),
+          constraintName: row.constraint_name
+        }
+      }
+    } else if (client === 'sqlite3') {
+      const result = await knex.raw(`PRAGMA foreign_key_list('${tableName}')`)
+      const rows = Array.isArray(result) ? result : []
+      for (const row of rows) {
+        fks[row.from] = {
+          table: row.table,
+          column: row.to,
+          onDelete: (row.on_delete || 'NO ACTION').toUpperCase(),
+          onUpdate: (row.on_update || 'NO ACTION').toUpperCase(),
+          constraintName: null
+        }
+      }
+    }
+
+    return fks
+  }
+
   // ---------------------------------------------------------------------------
   // DIFF ENGINE — Compute desired vs current delta
   // ---------------------------------------------------------------------------
@@ -391,7 +477,7 @@ class Migration {
    * @param {Array} currentIndexes - Introspected index list
    * @returns {Array} Ordered list of diff operations
    */
-  _computeDiff(desired, currentColumns, currentIndexes) {
+  _computeDiff(desired, currentColumns, currentIndexes, currentForeignKeys = {}) {
     const ops = []
     const desiredColumns = desired.columns || {}
     const desiredIndexes = desired.indexes || []
@@ -438,7 +524,35 @@ class Migration {
       if (!currentColumns[colName]) continue // New column, handled above
 
       if (this._columnNeedsAlter(colDef, currentColumns[colName])) {
-        ops.push({type: 'alter_column', column: colName, definition: colDef})
+        ops.push({type: 'alter_column', column: colName, definition: colDef, currentNullable: currentColumns[colName].nullable})
+      }
+    }
+
+    // --- Foreign key synchronization ---
+    for (const [colName, colDef] of Object.entries(desiredColumns)) {
+      if (colDef.type === 'timestamps') continue
+      if (!currentColumns[colName]) continue // New column — _addColumn handles FK
+
+      const desiredRef = colDef.references || null
+      const currentFK = currentForeignKeys[colName] || null
+      const desiredOnDelete = (colDef.onDelete || 'NO ACTION').toUpperCase()
+      const desiredOnUpdate = (colDef.onUpdate || 'NO ACTION').toUpperCase()
+
+      if (desiredRef && !currentFK) {
+        // FK added to existing column
+        ops.push({type: 'add_foreign_key', column: colName, definition: colDef})
+      } else if (!desiredRef && currentFK) {
+        // FK removed from schema
+        ops.push({type: 'drop_foreign_key', column: colName, constraintName: currentFK.constraintName})
+      } else if (desiredRef && currentFK) {
+        // FK exists — check if target table/column or actions changed
+        const targetChanged = desiredRef.table !== currentFK.table || desiredRef.column !== currentFK.column
+        const actionChanged = desiredOnDelete !== currentFK.onDelete || desiredOnUpdate !== currentFK.onUpdate
+
+        if (targetChanged || actionChanged) {
+          ops.push({type: 'drop_foreign_key', column: colName, constraintName: currentFK.constraintName})
+          ops.push({type: 'add_foreign_key', column: colName, definition: colDef})
+        }
       }
     }
 
@@ -468,22 +582,71 @@ class Migration {
   /**
    * Checks if a column definition differs from the current DB metadata enough to warrant ALTER.
    * Conservative: only alters when there is a clear type or constraint mismatch.
+   * Why: Without type comparison, changing a column from e.g. 'string' to 'text' in the
+   * schema file would be silently ignored — the DB would never receive the ALTER.
    * @param {object} desired - Column definition from schema file
    * @param {object} current - Column metadata from introspection
    * @returns {boolean}
    */
   _columnNeedsAlter(desired, current) {
+    // Type mismatch — map the raw DB type back to an ODAC type and compare.
+    // nanoid is stored as 'string' (varchar) in the DB, so normalize before comparison.
+    // specificType uses the raw DB type directly (def.length holds the actual PG type),
+    // so compare against the raw introspected type instead of reverse-mapping.
+    if (desired.type === 'specificType') {
+      const rawDesired = (desired.length || '').toLowerCase().trim()
+      const rawCurrent = (current.type || '').toLowerCase().trim()
+      if (rawDesired !== rawCurrent) return true
+    } else {
+      const desiredType = desired.type === 'nanoid' ? 'string' : desired.type
+      const currentType = this._reverseMapType(current.type)
+      if (desiredType !== currentType) return true
+    }
+
     // Nullable mismatch
     if (desired.nullable === false && current.nullable === true) return true
     if (desired.nullable === true && current.nullable === false) return true
 
     // Length mismatch for string types — use Number() coercion since some
     // drivers (SQLite) return maxLength as a string, e.g. '100' vs 100.
-    if (desired.length && current.maxLength && Number(desired.length) !== Number(current.maxLength)) return true
+    if (desired.type !== 'specificType' && desired.length && current.maxLength && Number(desired.length) !== Number(current.maxLength))
+      return true
+
+    // Default value mismatch — normalize both sides before comparing because
+    // drivers return defaults as strings (e.g. "'active'" in PG, "active" in SQLite).
+    const desiredDefault = desired.default !== undefined ? this._normalizeDefaultValue(desired.default) : null
+    const currentDefault =
+      current.defaultValue !== undefined && current.defaultValue !== null ? this._normalizeDefaultValue(current.defaultValue) : null
+
+    if (desiredDefault !== currentDefault) return true
 
     return false
   }
 
+  /**
+   * Normalizes a column default value to a canonical string for cross-driver comparison.
+   * Why: Each DB driver serializes defaults differently — PG wraps strings in single quotes
+   * and appends type casts (e.g. `'active'::character varying`), SQLite returns raw values,
+   * MySQL returns unquoted strings. Stripping quotes and casts gives a stable comparison key.
+   * @param {*} value - Raw default value from schema definition or DB introspection
+   * @returns {string} Normalized string representation
+   */
+  _normalizeDefaultValue(value) {
+    if (value === null || value === undefined) return 'null'
+
+    let str = String(value)
+
+    // Strip PG type cast suffix: 'foo'::character varying → 'foo'
+    str = str.replace(/::[\w\s]+$/, '')
+
+    // Strip surrounding single quotes added by PG/MySQL: 'foo' → foo
+    if (str.startsWith("'") && str.endsWith("'")) {
+      str = str.slice(1, -1)
+    }
+
+    return str.trim().toLowerCase()
+  }
+
   /**
    * Generates a deterministic signature for an index to enable set comparison.
    * @param {object} idx - Index definition {columns, unique}
@@ -538,11 +701,19 @@ class Migration {
   async _applyDiff(knex, tableName, diff) {
     const columnOps = diff.filter(op => op.type === 'add_column' || op.type === 'drop_column' || op.type === 'alter_column')
     const indexOps = diff.filter(op => op.type === 'add_index' || op.type === 'drop_index')
+    const fkOps = diff.filter(op => op.type === 'add_foreign_key' || op.type === 'drop_foreign_key')
+
+    // Separate primary key alter ops — PostgreSQL's ALTER COLUMN via Knex emits
+    // DROP NOT NULL before SET NOT NULL, which PG rejects on PK columns (42P16).
+    // These must be handled with raw ALTER COLUMN ... TYPE ... USING instead.
+    const isPG = knex.client?.config?.client === 'pg' || knex.client?.config?.client === 'postgresql'
+    const pkAlterOps = isPG ? columnOps.filter(op => op.type === 'alter_column' && op.definition.primary) : []
+    const batchOps = isPG ? columnOps.filter(op => !(op.type === 'alter_column' && op.definition.primary)) : columnOps
 
-    // Phase 1: Column operations — atomic batch
-    if (columnOps.length > 0) {
+    // Phase 1a: Batch column operations (non-PK alters + adds + drops)
+    if (batchOps.length > 0) {
       await knex.schema.alterTable(tableName, table => {
-        for (const op of columnOps) {
+        for (const op of batchOps) {
           switch (op.type) {
             case 'add_column':
               this._addColumn(table, op.column, op.definition)
@@ -551,19 +722,94 @@ class Migration {
               table.dropColumn(op.column)
               break
             case 'alter_column':
-              this._alterColumn(table, op.column, op.definition)
+              this._alterColumn(table, op.column, op.definition, op.currentNullable)
               break
           }
         }
       })
     }
 
-    // Phase 2: Index operations — each applied individually for idempotent safety
+    // Phase 1b: Primary key column type changes on PostgreSQL — raw SQL.
+    // Why: Knex .alter() generates "DROP NOT NULL" + "SET NOT NULL" sequence,
+    // but PG forbids DROP NOT NULL on primary key columns. Raw ALTER COLUMN TYPE
+    // changes the type without touching the NOT NULL constraint.
+    for (const op of pkAlterOps) {
+      const sqlType = this._pgColumnType(op.definition)
+      await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? TYPE ${sqlType} USING ??::${sqlType}`, [tableName, op.column, op.column])
+
+      // Apply default value change if specified
+      if (op.definition.default !== undefined) {
+        if (op.definition.default === 'now()') {
+          await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? SET DEFAULT now()`, [tableName, op.column])
+        } else {
+          await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? SET DEFAULT ?`, [tableName, op.column, op.definition.default])
+        }
+      }
+    }
+
+    // Phase 2: Foreign key operations — drop before add to handle replacements
+    for (const op of fkOps) {
+      if (op.type === 'drop_foreign_key') {
+        await this._applyForeignKeyOp(knex, tableName, op)
+      }
+    }
+    for (const op of fkOps) {
+      if (op.type === 'add_foreign_key') {
+        await this._applyForeignKeyOp(knex, tableName, op)
+      }
+    }
+
+    // Phase 3: Index operations — each applied individually for idempotent safety
     for (const op of indexOps) {
       await this._applyIndexOp(knex, tableName, op)
     }
   }
 
+  /**
+   * Maps an ODAC column definition to a PostgreSQL type string for raw ALTER COLUMN TYPE.
+   * @param {object} def - Column definition from schema
+   * @returns {string} PostgreSQL type name
+   */
+  _pgColumnType(def) {
+    switch (def.type) {
+      case 'nanoid':
+      case 'string':
+        return `varchar(${def.length || (def.type === 'nanoid' ? 21 : 255)})`
+      case 'text':
+        return 'text'
+      case 'integer':
+        return 'integer'
+      case 'bigInteger':
+        return 'bigint'
+      case 'boolean':
+        return 'boolean'
+      case 'float':
+        return 'double precision'
+      case 'decimal':
+        return `numeric(${def.precision || 10},${def.scale || 2})`
+      case 'uuid':
+        return 'uuid'
+      case 'json':
+        return 'json'
+      case 'jsonb':
+        return 'jsonb'
+      case 'timestamp':
+        return 'timestamp'
+      case 'datetime':
+        return 'timestamp'
+      case 'date':
+        return 'date'
+      case 'time':
+        return 'time'
+      case 'binary':
+        return 'bytea'
+      case 'specificType':
+        return def.length || def.specificType || def.type
+      default:
+        return def.type
+    }
+  }
+
   /**
    * Why: PostgreSQL introspection can miss existing constraints across PG versions
    * (int2vector cast edge cases, search_path mismatches, expression indexes).
@@ -606,6 +852,63 @@ class Migration {
     }
   }
 
+  /**
+   * Applies a single foreign key add/drop operation with idempotent error handling.
+   * Why: Knex's col.alter() cannot manage FK constraints — they require table-level
+   * alterTable calls (add .foreign() / drop .dropForeign()) which are separate from column ops.
+   * @param {object} knex - Knex instance
+   * @param {string} tableName - Target table
+   * @param {object} op - FK operation {type, column, definition?, constraintName?}
+   */
+  async _applyForeignKeyOp(knex, tableName, op) {
+    try {
+      if (op.type === 'add_foreign_key') {
+        const ref = op.definition.references
+
+        // Clean orphan rows before adding constraint — existing data may reference
+        // rows that no longer exist in the parent table, which would cause PG error 23503.
+        // Nullable columns get SET NULL safely. Non-nullable columns are NOT deleted —
+        // instead the constraint is skipped with a warning to prevent silent data loss.
+        const orphanCondition = knex(tableName).whereNotIn(op.column, knex(ref.table).select(ref.column)).whereNotNull(op.column)
+
+        if (op.definition.nullable !== false) {
+          await orphanCondition.update({[op.column]: null})
+        } else {
+          const [{count: orphanCount}] = await orphanCondition.clone().count('* as count')
+
+          if (Number(orphanCount) > 0) {
+            console.error(
+              `\x1b[31m[ODAC Migration]\x1b[0m Skipping foreign key on "${tableName}.${op.column}" → ` +
+                `"${ref.table}.${ref.column}": ${orphanCount} orphan row(s) found. ` +
+                `Column is NOT NULL so rows cannot be nullified. ` +
+                `Clean the data manually and restart, or make the column nullable.`
+            )
+            return
+          }
+        }
+
+        await knex.schema.alterTable(tableName, table => {
+          const fk = table.foreign(op.column).references(ref.column).inTable(ref.table)
+          if (op.definition.onDelete) fk.onDelete(op.definition.onDelete)
+          if (op.definition.onUpdate) fk.onUpdate(op.definition.onUpdate)
+        })
+      } else if (op.type === 'drop_foreign_key') {
+        await knex.schema.alterTable(tableName, table => {
+          table.dropForeign(op.column)
+        })
+      }
+    } catch (e) {
+      const isDuplicate = e.message && (e.message.includes('already exists') || e.code === '42710')
+      const isNotFound = e.message && (e.message.includes('does not exist') || e.code === '42704')
+
+      if ((op.type === 'add_foreign_key' && isDuplicate) || (op.type === 'drop_foreign_key' && isNotFound)) {
+        return
+      }
+
+      throw e
+    }
+  }
+
   /**
    * Translates schema column definitions into Knex schema builder calls.
    * Supports all common column types with their modifiers.
@@ -686,6 +989,8 @@ class Migration {
         return table.uuid(colName)
       case 'enum':
         return table.enum(colName, def.values || [])
+      case 'specificType':
+        return table.specificType(colName, def.length || def.specificType || def.type)
       default:
         return table.specificType(colName, def.type)
     }
@@ -734,12 +1039,18 @@ class Migration {
    * @param {string} colName - Column name
    * @param {object} def - Column definition
    */
-  _alterColumn(table, colName, def) {
+  _alterColumn(table, colName, def, currentNullable) {
     const col = this._createColumnBuilder(table, colName, def)
     if (!col) return
 
+    // Knex .alter() defaults to nullable when no explicit nullable/notNullable is set,
+    // which generates "ALTER COLUMN ... DROP NOT NULL" — PostgreSQL rejects this on
+    // primary key columns (error 42P16). When the schema doesn't specify nullable,
+    // preserve the column's current DB state to avoid destructive no-op alterations.
     if (def.nullable === false) col.notNullable()
     else if (def.nullable === true) col.nullable()
+    else if (currentNullable === false) col.notNullable()
+    else if (currentNullable === true) col.nullable()
 
     if (def.default !== undefined) col.defaultTo(def.default)
 

package/src/Database/ReadCache.js

@@ -0,0 +1,174 @@
+'use strict'
+const nodeCrypto = require('node:crypto')
+
+/**
+ * Read-Through Cache for ODAC Database layer.
+ *
+ * Why: Frequently-read, rarely-changed data (blog posts, settings, categories)
+ * generates redundant DB queries across workers. This module caches SELECT results
+ * via the Ipc layer, providing O(1) reads after the first query.
+ *
+ * Architecture: Fully delegated to Odac.Ipc for state management (same as WriteBuffer).
+ * - Memory driver: Primary process holds cached data in Maps via cluster IPC.
+ * - Redis driver: All state lives in Redis — works across horizontal load balancers.
+ * - Both drivers: TTL-based expiration + automatic invalidation on write operations.
+ *
+ * Key namespaces in Ipc:
+ *   rc:{connection}:{table}:{queryHash}   — cached query result (Ipc.set/get with TTL)
+ *   rc:idx:{connection}:{table}           — set of active cache keys for bulk invalidation
+ *
+ * API (exposed via Database.js proxy):
+ *   Odac.DB.posts.cache(60).where({active: true}).select('id', 'title')  — TTL cache
+ *   Odac.DB.posts.cache().where({id: 5}).first()                         — default TTL
+ *   Odac.DB.posts.cache.clear()                                          — table invalidation
+ *   Odac.DB.posts.cache.clear({id: 5})                                   — targeted invalidation
+ *
+ * Automatic invalidation:
+ *   insert/update/delete on a table → all cached queries for that table are purged.
+ */
+
+const DEFAULT_CONFIG = {
+  ttl: 300,
+  maxKeys: 10000
+}
+
+class ReadCache {
+  constructor() {
+    this._config = {}
+  }
+
+  /**
+   * Why: Merges user config with sensible defaults. Called from Database.init().
+   * No timers or background processes — cache is purely reactive (read-through + TTL).
+   */
+  init() {
+    this._config = {...DEFAULT_CONFIG, ...Odac.Config.cache}
+  }
+
+  /**
+   * Why: Generates a deterministic cache key from the Knex query builder's compiled SQL + bindings.
+   * SHA-256 ensures fixed-length keys regardless of query complexity.
+   * Sorting bindings is unnecessary — Knex preserves parameter order deterministically.
+   *
+   * @param {string} connection - Connection key (e.g., 'default', 'analytics')
+   * @param {string} table - Table name
+   * @param {object} queryBuilder - Knex query builder instance
+   * @returns {string} Cache key in format rc:{connection}:{table}:{hash}
+   */
+  buildKey(connection, table, queryBuilder) {
+    const {sql, bindings} = queryBuilder.toSQL()
+    const hash = nodeCrypto
+      .createHash('sha256')
+      .update(`${sql}:${JSON.stringify(bindings)}`)
+      .digest('hex')
+    return `rc:${connection}:${table}:${hash}`
+  }
+
+  /**
+   * Why: Core read-through logic. Returns cached result on HIT, executes query on MISS.
+   * TTL ensures eventual consistency even without explicit invalidation.
+   *
+   * @param {string} connection - Connection key
+   * @param {string} table - Table name
+   * @param {object} queryBuilder - Knex query builder (used for key generation via .toSQL())
+   * @param {function} executeFn - Callback that executes the original DB query (avoids .then() recursion)
+   * @param {number} ttl - Time-to-live in seconds
+   * @returns {Promise<*>} Query result (from cache or DB)
+   */
+  async get(connection, table, queryBuilder, executeFn, ttl) {
+    const effectiveTtl = ttl || this._config.ttl
+    const cacheKey = this.buildKey(connection, table, queryBuilder)
+
+    // O(1) cache lookup via Ipc — sentinel envelope {__v} distinguishes "cached null" from MISS
+    const cached = await Odac.Ipc.get(cacheKey)
+    if (cached !== null && typeof cached === 'object' && '__v' in cached) return cached.__v
+
+    // MISS — execute the actual DB query via the original (unwrapped) .then()
+    const result = await executeFn()
+
+    // Guard against exceeding maxKeys to prevent unbounded memory growth
+    const indexKey = `rc:idx:${connection}:${table}`
+    const currentKeys = await Odac.Ipc.smembers(indexKey)
+
+    if (currentKeys.length < this._config.maxKeys) {
+      await Odac.Ipc.set(cacheKey, {__v: result}, effectiveTtl)
+      await Odac.Ipc.sadd(indexKey, cacheKey)
+
+      // Cross-table invalidation: register cache key in joined tables' indexes too.
+      // Why: A query like posts.join('users').cache().select() must be invalidated
+      // when EITHER posts OR users is written to. Without this, a users.insert()
+      // would leave stale joined data in the posts cache.
+      const joinedTables = this._extractJoinedTables(queryBuilder)
+      for (const joinedTable of joinedTables) {
+        await Odac.Ipc.sadd(`rc:idx:${connection}:${joinedTable}`, cacheKey)
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Why: Purges all cached queries for a specific table. Called automatically on
+   * insert/update/delete via Database.js proxy intercept.
+   * Table-level granularity is intentional — row-level invalidation would require
+   * parsing WHERE clauses of cached queries, which is O(n) and error-prone.
+   *
+   * @param {string} connection - Connection key
+   * @param {string} table - Table name
+   * @returns {Promise<void>}
+   */
+  async invalidate(connection, table) {
+    if (!global.Odac?.Ipc) return
+
+    const indexKey = `rc:idx:${connection}:${table}`
+    const keys = await Odac.Ipc.smembers(indexKey)
+
+    if (keys.length === 0) return
+
+    // Delete all cached entries in parallel
+    await Promise.all(keys.map(key => Odac.Ipc.del(key)))
+    await Odac.Ipc.del(indexKey)
+  }
+
+  /**
+   * Why: Extracts table names from JOIN clauses in a Knex query builder.
+   * Used to register cache keys in joined tables' indexes for cross-table invalidation.
+   * Parses Knex's internal _statements array — entries with a joinType property
+   * contain the joined table name. Handles aliased tables (e.g., 'users as u' → 'users').
+   *
+   * @param {object} queryBuilder - Knex query builder instance
+   * @returns {string[]} Array of joined table names (deduplicated)
+   */
+  _extractJoinedTables(queryBuilder) {
+    const statements = queryBuilder._statements
+    if (!statements || !Array.isArray(statements)) return []
+
+    const tables = new Set()
+    for (const stmt of statements) {
+      if (!stmt.joinType || !stmt.table) continue
+      // Handle aliased tables: 'users as u' → 'users'
+      const tableName = String(stmt.table)
+        .split(/\s+as\s+/i)[0]
+        .trim()
+      if (tableName) tables.add(tableName)
+    }
+    return [...tables]
+  }
+
+  /**
+   * Why: Targeted invalidation — clears cache entries whose query hash matches
+   * a specific WHERE condition. Falls back to full table invalidation since
+   * precise row-level matching against arbitrary cached SQL is not feasible.
+   * Exposed as Odac.DB.posts.cache.clear({id: 5}) for semantic clarity,
+   * but internally equivalent to table-level purge.
+   *
+   * @param {string} connection - Connection key
+   * @param {string} table - Table name
+   * @returns {Promise<void>}
+   */
+  async clear(connection, table) {
+    return this.invalidate(connection, table)
+  }
+}
+
+module.exports = new ReadCache()

package/src/Database/WriteBuffer.js

@@ -1,5 +1,6 @@
 'use strict'
 const cluster = require('node:cluster')
+const nanoid = require('./nanoid')
 
 /**
  * Write-Behind Cache with Write Coalescing for ODAC Database layer.
@@ -56,12 +57,15 @@ class WriteBuffer {
    * Why: Initializes the WriteBuffer. Called from Database.init() after Ipc is ready.
    * Primary: recovers LMDB checkpoint, starts flush/checkpoint timers.
    * All processes: stores connection references for flush DB writes.
+   * @param {object} connections - Knex connection map {connectionKey: knexInstance}
+   * @param {object} nanoidColumns - NanoID column metadata from DatabaseManager {connectionKey: {tableName: [{column, size}]}}
    */
-  async init(connections) {
+  async init(connections, nanoidColumns = {}) {
     if (this._initialized) return
     this._initialized = true
 
     this._connections = connections
+    this._nanoidColumns = nanoidColumns
     this._config = {...DEFAULT_CONFIG, ...Odac.Config.buffer}
 
     if (cluster.isPrimary) {
@@ -127,6 +131,16 @@ class WriteBuffer {
    * that are drained to the database in a single INSERT batch.
    */
   async insert(connection, table, row) {
+    // Auto-generate nanoid values for columns defined as type 'nanoid' in schema.
+    // Why: The Database.js proxy nanoid injection only covers direct QB calls.
+    // WriteBuffer bypasses that proxy — rows must be populated here before queuing.
+    const nanoidCols = this._nanoidColumns?.[connection]?.[table]
+    if (nanoidCols) {
+      for (const {column, size} of nanoidCols) {
+        if (!row[column]) row[column] = nanoid(size)
+      }
+    }
+
     const queueKey = `${connection}:${table}`
     const length = await Odac.Ipc.rpush(`wb:q:${queueKey}`, row)
     await Odac.Ipc.sadd('wb:idx:queues', queueKey)