@bakery-framework/orm 2.0.0-alpha.4 → 2.0.0-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/orm",
-  "version": "2.0.0-alpha.4",
+  "version": "2.0.0-alpha.6",
   "description": "Bakery database layer: adapters, query builder, schema sync and backup.",
   "keywords": [
     "bakery",
@@ -54,6 +54,6 @@
     "bun": ">=1.3.14"
   },
   "dependencies": {
-    "@bakery-framework/core": "^2.0.0-alpha.4"
+    "@bakery-framework/core": "^2.0.0-alpha.6"
   }
 }

package/src/adapters/base.ts

@@ -849,20 +849,69 @@ export abstract class SQLAdapter {
     return new DatabaseStatement(this, sqlText)
   }
 
+  /**
+   * The `LIKE` escape character — `!`, and deliberately **not** a backslash.
+   *
+   * A backslash is the obvious choice and is unusable here. MySQL processes
+   * backslash escapes inside string literals where SQLite and Postgres do not,
+   * so the clause would need to differ per dialect; and worse, Postgres never
+   * receives what is written. `normalizePostgresSQL` treats `\'` as an escaped
+   * quote — MySQL's rule, applied to every dialect — so `ESCAPE '\'` leaves the
+   * string literal *open*, swallows the rest of the statement, and the driver
+   * reports `syntax error at or near "OFFSET"` from a clause several tokens
+   * later.
+   *
+   * That normalizer behaviour is a real defect and is not fixed here: a test
+   * pins it (`a backslash escape keeps the character it escapes`), and changing
+   * it would change every literal the framework emits. Choosing a character
+   * with no meaning to any of the three parsers sidesteps it entirely, and one
+   * spelling for all dialects beats a capability getter per dialect.
+   */
+  protected readonly likeEscape = '!'
+
+  get likeEscapeClause(): string {
+    return ` ESCAPE '${this.likeEscape}'`
+  }
+
+  /**
+   * Make a value match literally under `LIKE`.
+   *
+   * Without this a search for `50%` matches every row and one for `a_b` matches
+   * `axb` — `%` and `_` are the wildcards, and the filter passed user input
+   * through untouched. The escape character itself goes first, or escaping it
+   * afterwards would double the ones this method just added.
+   */
+  protected escapeLike(value: string): string {
+    const e = this.likeEscape
+    return value
+      .split(e)
+      .join(e + e)
+      .replace(/[%_]/g, m => `${e}${m}`)
+  }
+
+  /**
+   * `WHERE` and `ORDER BY` for a browsable table listing.
+   *
+   * A filter is either a **bare scalar**, which means `contains` and is what
+   * every caller sent before operators existed, or **`{op, value}`**. Keeping
+   * the scalar form meaningful is not politeness: `getData` is public and the
+   * dashboard still calls it that way.
+   *
+   * Columns are intersected with the real column set by the caller, so an
+   * unknown column disappears rather than reaching SQL. Values always bind.
+   */
   protected buildFilterSort(
     options: SQLAdapter.FilterSortOptions,
     validCols: Set<string>,
   ) {
     const whereParams: unknown[] = []
-    const whereClauses = Object.entries(options.filters || {})
-      .filter(
-        ([col, val]) =>
-          validCols.has(col) && val !== undefined && val !== null && val !== '',
-      )
-      .map(([col, val]) => {
-        whereParams.push(`%${val}%`)
-        return `${this.quote(col)} LIKE ?`
-      })
+    const whereClauses: string[] = []
+
+    for (const [col, raw] of Object.entries(options.filters || {})) {
+      if (!validCols.has(col)) continue
+      const clause = this.filterClause(col, raw, whereParams)
+      if (clause) whereClauses.push(clause)
+    }
 
     const whereSql = whereClauses.length
       ? ` WHERE ${whereClauses.join(' AND ')}`
@@ -880,6 +929,67 @@ export abstract class SQLAdapter {
     return { whereSql, orderSql, whereParams }
   }
 
+  /**
+   * One filter, as SQL. Returns `null` when the filter says nothing.
+   *
+   * `params` is appended to rather than returned, because an operator may bind
+   * one value, two, or none at all — `IS NULL` has nothing to bind, and
+   * pretending otherwise is how a placeholder count drifts from its arguments.
+   */
+  private filterClause(
+    col: string,
+    raw: unknown,
+    params: unknown[],
+  ): string | null {
+    const quoted = this.quote(col)
+
+    // The pre-operator form. An empty string means "no filter" here, which is
+    // what a cleared text box sends and what every caller has relied on.
+    if (raw === null || raw === undefined || typeof raw !== 'object') {
+      if (raw === undefined || raw === null || raw === '') return null
+      params.push(`%${this.escapeLike(String(raw))}%`)
+      return `${quoted} LIKE ?${this.likeEscapeClause}`
+    }
+
+    const { op, value } = raw as { op?: string; value?: unknown }
+
+    // No value to bind, and none expected — these two are the whole reason a
+    // filter cannot be modelled as a plain column/value pair.
+    if (op === 'null') return `${quoted} IS NULL`
+    if (op === 'notnull') return `${quoted} IS NOT NULL`
+
+    if (value === undefined || value === null) return null
+
+    const comparison: Record<string, string> = {
+      eq: '=',
+      ne: '<>',
+      gt: '>',
+      gte: '>=',
+      lt: '<',
+      lte: '<=',
+    }
+    if (op && comparison[op]) {
+      params.push(value)
+      return `${quoted} ${comparison[op]} ?`
+    }
+
+    const pattern: Record<string, (v: string) => string> = {
+      contains: v => `%${v}%`,
+      starts: v => `${v}%`,
+      ends: v => `%${v}`,
+    }
+    const shape = op ? pattern[op] : undefined
+    if (shape) {
+      params.push(shape(this.escapeLike(String(value))))
+      return `${quoted} LIKE ?${this.likeEscapeClause}`
+    }
+
+    // An operator this dialect does not know is dropped rather than guessed
+    // at. Guessing would mean answering a question nobody asked, and the
+    // caller validates the vocabulary before it gets here.
+    return null
+  }
+
   protected formatDefault(
     def: unknown,
     boolTrue: string,

package/src/adapters/pgsql.ts

@@ -267,13 +267,22 @@ export class PGAdapter extends SQLAdapter {
             " AND table_schema NOT IN ('pg_catalog', 'information_schema')" +
             ' ORDER BY ordinal_position',
         ).all(t.name),
+        // `::regclass` casts a **string**, so the table name binds as a
+        // parameter. It used to interpolate `qName` — a double-quoted
+        // *identifier* — which Postgres reads as a column reference, so this
+        // threw `column "<table>" does not exist` for every table and took the
+        // whole of `getSchema()` down with it on this dialect.
+        //
+        // The quiet case was worse than the loud one: a table with a column of
+        // the same name resolved, casting that column's *value* to a regclass
+        // and reporting some other table's primary key as this one's.
         this.query(
           'SELECT a.attname AS name' +
             ' FROM pg_index i' +
             ' JOIN pg_attribute a ON a.attrelid = i.indrelid' +
             ' AND a.attnum = ANY(i.indkey)' +
-            ` WHERE i.indisprimary AND i.indrelid = ${qName}::regclass`,
-        ).all(),
+            ' WHERE i.indisprimary AND i.indrelid = ?::regclass',
+        ).all(t.name),
         this.query(
           'SELECT indexname AS name, indexdef AS def' +
             ' FROM pg_indexes' +

package/src/adapters/sqlite.ts

@@ -304,7 +304,18 @@ export class SQLiteAdapter extends SQLAdapter {
           name: c.name,
           type: c.type,
           notnull: c.notnull === 1,
-          pk: c.pk === 1,
+          // `pk` is the column's **1-based position within the primary key**,
+          // not a boolean — `PRAGMA table_info` reports 0 for "not part of the
+          // key", 1 for the first key column, 2 for the second. So `=== 1`
+          // reported a composite `PRIMARY KEY (a, b)` as a single-column key on
+          // `a`, silently, and only on SQLite: MySQL reads `column_key = 'PRI'`
+          // and Postgres reads `pg_index.indisprimary`, both of which are set on
+          // every member.
+          //
+          // `parseConstraints` a few hundred lines down already had this right
+          // (`col.pk > 0`), which is why `getConstraints()` disagreed with
+          // `getSchema()` about the same table.
+          pk: c.pk > 0,
         })),
         indexes: idxs.map(i => ({ name: i.name, unique: i.unique === 1 })),
       })

package/src/sync/diff.ts

@@ -0,0 +1,339 @@
+import type { Logger } from '@bakery-framework/core/logger'
+import { Case } from '@bakery-framework/core/utils'
+import { findBestMatchAndPrompt } from './rename'
+import type * as SyncTypes from './types'
+import { normalizeViewBody } from './view-sql'
+
+type SyncPlan = SyncTypes.SyncPlan
+
+function diffColumnMismatch(
+  plan: SyncPlan,
+  dbName: string,
+  camelCol: string,
+  tsCol: any,
+  dbCol: any,
+  MESSAGES: any,
+) {
+  const tsNullable = tsCol.primary ? false : tsCol.nullable === true
+  const dbNullable = dbCol.primary ? false : dbCol.nullable === true
+  const tsDefault = tsCol.default === undefined ? null : tsCol.default
+  const dbDefault = dbCol.default === undefined ? null : dbCol.default
+  const isTypeMatch =
+    tsCol.type === dbCol.type ||
+    (tsCol.type === 'boolean' && dbCol.type === 'integer')
+  const norm = (v: any) =>
+    v === null
+      ? 'null'
+      : String(v)
+          .replace(/^\(+|\)+$/g, '')
+          .trim()
+
+  // Width joins the diff, so widening a Varchar migrates instead of silently
+  // doing nothing. It stayed out until all three adapters could be *measured*
+  // reporting it back exactly; see `SQLAdapter.sizedTextLength` for the MySQL
+  // TEXT trap that made this dangerous to add blind.
+  //
+  // Driven by the *schema* side only. When the schema declares a width, any
+  // other answer from the database differs — including no width at all, which
+  // is a real `TEXT` column that should become `VARCHAR(n)`. Requiring both
+  // sides to be sized meant sizing an existing TEXT column silently did
+  // nothing, and `db:sync` then reported a perfectly synced database whose
+  // columns did not match the schema it had just read.
+  //
+  // Converges because all three dialects report a `VARCHAR` width back exactly
+  // (measured, see `SQLAdapter.sizedTextLength`): after one rebuild the two
+  // agree. A column that reports *no* width really is unsized.
+  //
+  // When the schema declares no width, nothing differs — `Field.Text()` against
+  // an existing `VARCHAR` is not a request to shrink it.
+  const lengthDiffers =
+    typeof tsCol.length === 'number' && tsCol.length !== dbCol.length
+
+  // Enum members join the diff, so changing them migrates instead of silently
+  // doing nothing — but **only when the current state came from the ledger**.
+  //
+  // `_enum` is emitted as an inline `CHECK (col IN (...))` by all three
+  // dialects, and all three *will* report that constraint back — in three
+  // incompatible shapes. Measured:
+  //
+  //   sqlite  CHECK (status IN ('draft','live'))            in the table DDL
+  //   mysql   (`status` in (_utf8mb4'draft',_utf8mb4'live'))  charset prefixes
+  //   pgsql   CHECK (((status)::text = ANY ((ARRAY[...])))    re-rendered
+  //
+  // Postgres does not store the text it was given, it re-renders a parsed
+  // expression — the same trap that turned `EXTRACT` into `date_part` and
+  // rebuilt a table on every sync forever. Three parsers, each an opportunity
+  // for that bug, is the wrong trade when the ledger already holds the members
+  // exactly as declared.
+  //
+  // So under introspection this stays out of the diff. A schema-side-only
+  // comparison would find `_enum` on one side and nothing on the other, differ
+  // every time, and rebuild the table on every sync — which is precisely what
+  // the `length` note above says it waited to rule out before shipping.
+  const enumDiffers =
+    plan.ledgerSource === 'ledger' &&
+    !Bun.deepEquals(tsCol._enum ?? null, dbCol._enum ?? null)
+
+  if (
+    !isTypeMatch ||
+    tsNullable !== dbNullable ||
+    lengthDiffers ||
+    enumDiffers ||
+    norm(tsDefault) !== norm(dbDefault)
+  ) {
+    MESSAGES.COL_MISMATCH({ table: dbName, column: camelCol })
+    MESSAGES.COL_MISMATCH_TS({
+      tsType: tsCol.type,
+      tsNullable: String(tsNullable),
+      tsDefault: String(tsDefault),
+    })
+    MESSAGES.COL_MISMATCH_DB({
+      dbType: dbCol.type,
+      dbNullable: String(dbNullable),
+      dbDefault: String(dbDefault),
+    })
+    plan.tablesToRebuild.add(dbName)
+  }
+}
+
+function resolveColumnRenames(
+  plan: SyncPlan,
+  camelTable: string,
+  dbName: string,
+  constraints: any,
+  unmappedDbCols: Set<string>,
+  unmappedTsCols: Set<string>,
+  existingDbCamelCols: Set<string>,
+) {
+  for (const newCamel of [...unmappedTsCols]) {
+    const tsColObj = constraints[camelTable][newCamel]
+    if (!tsColObj?._oldColumn) continue
+    const oldCamel = Case.camel(tsColObj._oldColumn)
+    if (!existingDbCamelCols.has(oldCamel)) continue
+    plan.columnsToRename.push({
+      table: dbName,
+      oldColumn: Case.snake(tsColObj._oldColumn),
+      newColumn: Case.snake(newCamel),
+    })
+    unmappedDbCols.delete(Case.snake(tsColObj._oldColumn))
+    unmappedTsCols.delete(newCamel)
+    if (plan.dbConstraintsForDiff[camelTable]?.[oldCamel]) {
+      plan.dbConstraintsForDiff[camelTable][newCamel] =
+        plan.dbConstraintsForDiff[camelTable][oldCamel]
+      delete plan.dbConstraintsForDiff[camelTable][oldCamel]
+    }
+    existingDbCamelCols.delete(oldCamel)
+    existingDbCamelCols.add(newCamel)
+  }
+}
+
+function resolveUnmappedDbCols(
+  plan: SyncPlan,
+  camelTable: string,
+  dbName: string,
+  logger: Logger,
+  unmappedDbCols: Set<string>,
+  unmappedTsCols: Set<string>,
+  existingDbCamelCols: Set<string>,
+) {
+  for (const oldDbCol of [...unmappedDbCols]) {
+    const bestMatch = unmappedTsCols.size
+      ? findBestMatchAndPrompt(
+          oldDbCol,
+          unmappedTsCols,
+          'column',
+          dbName,
+          logger,
+        )
+      : null
+    if (bestMatch) {
+      plan.columnsToRename.push({
+        table: dbName,
+        oldColumn: oldDbCol,
+        newColumn: Case.snake(bestMatch),
+      })
+      unmappedDbCols.delete(oldDbCol)
+      unmappedTsCols.delete(bestMatch)
+      const oldCamel = Case.camel(oldDbCol)
+      if (plan.dbConstraintsForDiff[camelTable]?.[oldCamel]) {
+        plan.dbConstraintsForDiff[camelTable][bestMatch] =
+          plan.dbConstraintsForDiff[camelTable][oldCamel]
+        delete plan.dbConstraintsForDiff[camelTable][oldCamel]
+      }
+      existingDbCamelCols.delete(oldCamel)
+      existingDbCamelCols.add(bestMatch)
+    } else {
+      plan.columnsToDrop.push({ table: dbName, column: oldDbCol })
+    }
+  }
+}
+
+function diffTableColumns(
+  plan: SyncPlan,
+  camelTable: string,
+  dbName: string,
+  constraints: any,
+  logger: Logger,
+  MESSAGES: any,
+) {
+  const existingDbCamelCols = new Set(
+    Object.keys(plan.dbConstraintsForDiff[camelTable] || {}).filter(
+      k => k !== '_view',
+    ),
+  )
+  const unmappedDbCols = new Set(
+    [...existingDbCamelCols]
+      .filter(c => !constraints[camelTable][c])
+      .map(Case.snake),
+  )
+  const unmappedTsCols = new Set(
+    Object.keys(constraints[camelTable]).filter(
+      c =>
+        !existingDbCamelCols.has(c) &&
+        !['_view', '_oldTable', '_transform'].includes(c),
+    ),
+  )
+
+  resolveColumnRenames(
+    plan,
+    camelTable,
+    dbName,
+    constraints,
+    unmappedDbCols,
+    unmappedTsCols,
+    existingDbCamelCols,
+  )
+  resolveUnmappedDbCols(
+    plan,
+    camelTable,
+    dbName,
+    logger,
+    unmappedDbCols,
+    unmappedTsCols,
+    existingDbCamelCols,
+  )
+
+  plan.columnsToAdd.push(
+    ...[...unmappedTsCols].map(newCamel => ({
+      table: dbName,
+      column: Case.snake(newCamel),
+      def: constraints[camelTable][newCamel],
+    })),
+  )
+
+  for (const camelCol of existingDbCamelCols) {
+    if (unmappedDbCols.has(Case.snake(camelCol))) continue
+    const tsCol = constraints[camelTable][camelCol]
+    const dbCol = plan.dbConstraintsForDiff[camelTable]?.[camelCol]
+    if (tsCol && dbCol) {
+      diffColumnMismatch(plan, dbName, camelCol, tsCol, dbCol, MESSAGES)
+    }
+  }
+}
+
+function diffViewStrings(
+  plan: SyncPlan,
+  camelTable: string,
+  dbName: string,
+  constraints: any,
+  database?: string,
+): boolean {
+  // Both sides through the same canonicaliser, which is the only thing that
+  // makes a text comparison viable: you write `SELECT id FROM users` and MySQL
+  // returns it fully qualified, fully quoted and aliased column by column.
+  //
+  // Symmetry is the whole requirement. Normalising the *generated file* while
+  // comparing raw — or stripping the schema on one side only — recreates the
+  // view on every sync, which is the same churn the column diff has hit twice.
+  const tsViewStr = normalizeViewBody(
+    String(constraints[camelTable]._view || ''),
+    database,
+  )
+  const dbViewStr = normalizeViewBody(
+    String(plan.dbConstraintsForDiff[camelTable]?._view || ''),
+    database,
+  )
+  if (tsViewStr || dbViewStr) {
+    if (tsViewStr !== dbViewStr) plan.viewsToUpdate.push(dbName)
+    if (tsViewStr && !dbViewStr) plan.tablesToDrop.push(dbName)
+    return true
+  }
+  return false
+}
+
+/**
+ * The view lifecycle: create, recreate, drop.
+ *
+ * Views were invisible to the planner. `initDbTablesMap` skips `_view` entries,
+ * and every existing comparison iterates that map — so a declared view never
+ * reached `diffViewStrings`, and nothing about a view ever reached
+ * `hasChanges`. The consequences, all three measured:
+ *
+ * - a **new** view was never planned,
+ * - an **edited** `SELECT` was never detected, so a view could not be changed,
+ * - a view the schema no longer declares was never dropped.
+ *
+ * They were invisible rather than broken: `syncViewsAndTablesPhase` recreates
+ * every declared view whenever a sync happens to run, so a view kept up to date
+ * as a side effect of unrelated work. With nothing else to do, `db:sync`
+ * reported a perfectly synced database and left the view alone.
+ *
+ * Bodies are compared through `normalizeViewBody` on both sides. That converges
+ * on SQLite, which stores the text verbatim, and via the ledger everywhere —
+ * the ledger records what was *applied*, so it holds the authored SELECT.
+ * Diffing against live introspection on MySQL or Postgres will still see a
+ * difference, because both re-render the body (MySQL re-qualifies every column,
+ * Postgres adds parentheses), and no amount of text normalisation short of a
+ * parser fixes that. It costs a recreate, and a view holds no data.
+ */
+export function diffViews(
+  plan: SyncPlan,
+  constraints: SyncTypes.DBConstraints,
+  database?: string,
+) {
+  const dbSide = plan.dbConstraintsForDiff
+  const declared = new Set<string>()
+
+  for (const [name, cols] of Object.entries(constraints)) {
+    const body = (cols as SyncTypes.TableConstraints)?._view
+    if (!body) continue
+    const camel = Case.camel(name)
+    declared.add(camel)
+
+    const dbBody = (dbSide[camel] as SyncTypes.TableConstraints | undefined)
+      ?._view
+    const want = normalizeViewBody(String(body), database)
+    const have = dbBody ? normalizeViewBody(String(dbBody), database) : null
+    if (have !== want) plan.viewsToUpdate.push(Case.snake(name))
+  }
+
+  for (const [name, cols] of Object.entries(dbSide)) {
+    if (!(cols as SyncTypes.TableConstraints)?._view) continue
+    if (declared.has(Case.camel(name))) continue
+    // Same rule tables follow: what the schema does not declare, the database
+    // does not keep. Dropping is announced before it happens.
+    plan.tablesToDrop.push(Case.snake(name))
+  }
+}
+
+export function diffTableViewsAndColumns(
+  plan: SyncPlan,
+  dbTables: any,
+  constraints: any,
+  logger: Logger,
+  MESSAGES: any,
+  database?: string,
+) {
+  for (const camelTable of Object.keys(dbTables)) {
+    if (!constraints[camelTable]) continue
+    const dbName = dbTables[camelTable]!.dbName
+    if (
+      plan.tablesToRebuild.has(dbName) ||
+      plan.tablesToRebuild.has(Case.snake(camelTable))
+    )
+      continue
+    if (diffViewStrings(plan, camelTable, dbName, constraints, database))
+      continue
+    diffTableColumns(plan, camelTable, dbName, constraints, logger, MESSAGES)
+  }
+}

package/src/sync/engine.ts

@@ -3,16 +3,14 @@ import { Case } from '@bakery-framework/core/utils'
 import type { SQLAdapter } from '../adapters/base'
 import { SchemaBuilder } from './builder'
 import {
-  buildSyncPlan,
   calculateForeignKeyDiff,
-  calculateIndexDiff,
   collectForeignKeys,
   executeSyncPlan,
   hasOldWrappers,
-  logPlannedChanges,
-} from './helpers'
+} from './execute'
 import { writeLedger } from './ledger'
 import type { SchemaLayout } from './load'
+import { buildSyncPlan, calculateIndexDiff, logPlannedChanges } from './plan'
 import type * as SyncTypes from './types'
 
 // prettier-ignore
@@ -70,6 +68,15 @@ export const syncMsgs = {
   EXEC_SYNC_VIEW: 'D Syncing view: %y{view}%*...',
   EXEC_SYNC_CONS: 'D Syncing constraints for: %y{table}%*...',
   EXEC_ADD_INDEX: 'I Creating %y{type}%* index: %g{name}%*...',
+  // Declared late. `executeSyncPlan` has always called these two, and
+  // `messageLogger`'s proxy answers an undeclared key with a live emitter that
+  // prints `E Error message not found: EXEC_ADD_FK` — so every foreign key
+  // added or dropped on a dialect that can ALTER one logged an *error* where
+  // its ten sibling operations logged progress. Only reachable with
+  // `supportsAlterForeignKey`, which is why SQLite-only local runs never
+  // showed it.
+  EXEC_DROP_FK: 'I Dropping foreign key: %r{table}.{name}%*...',
+  EXEC_ADD_FK: 'I Adding foreign key: %g{table}%* -> %g{ref}%*...',
   CATCH_UP_SUCCESS: 'I %gDatabase successfully caught up%*!',
   PROD_FORCE_REQUIRED: 'E %rProduction requires %y--force-sync%* to proceed.%*',
   BACKUP_REQUIRED:
@@ -274,7 +281,7 @@ export class SyncEngine {
     {
       await using _session = new SyncSession(adapter)
       await adapter.transaction(tx =>
-        executeSyncPlan(
+        executeSyncPlan({
           tx,
           plan,
           constraints,
@@ -284,7 +291,7 @@ export class SyncEngine {
           tsFks,
           fksToAdd,
           fksToDrop,
-        ),
+        }),
       )
     }