@bakery-framework/orm 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/orm",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Bakery database layer: adapters, query builder, schema sync and backup.",
   "keywords": [
     "bakery",

package/src/sync/builder.ts

@@ -106,7 +106,6 @@ export class SchemaBuilder {
     const nul = cons.nullable ?? false
 
     const hasDefault = def !== undefined && def !== null && def !== 'NULL'
-    const isExplicitNull = def === null || def === 'NULL' || (!isView && nul)
 
     if (hasDefault) {
       const isStr = typeof def === 'string'
@@ -119,7 +118,22 @@ export class SchemaBuilder {
           : String(def)
     }
 
-    if (isExplicitNull) return 'null'
+    // **A null default is only spellable on a nullable column**, and conflating
+    // the two turned every NOT NULL column without a default into a nullable
+    // one. `Field`'s convention — stated in `asFieldCall` below — is that a null
+    // default *means* nullable, so `Field.Int(null)` does not describe
+    // `author_id integer NOT NULL`; it redefines it.
+    //
+    // Introspection is not the problem and reports this correctly: a NOT NULL
+    // column with no default comes back as `{type, default: null}` with no
+    // `nullable` key, and a genuinely nullable one carries `nullable: true`.
+    // This function was reading only the default and ignoring the flag beside
+    // it, so `--choose=db` on a real database produced a schema whose very next
+    // sync proposed rebuilding the table it had just been generated from.
+    if (!isView && nul) return 'null'
+    // A view has no NOT NULL to speak of, so there the null-ish default is all
+    // there is to go on.
+    if (isView && (def === null || def === 'NULL')) return 'null'
     return undefined
   }
 
@@ -163,9 +177,72 @@ export class SchemaBuilder {
     if (n) parts.push('nullable: true')
     if (a) parts.push('autoIncrement: true')
     if (p) parts.push('primary: true')
+    if (cons._references) {
+      const r = cons._references
+      const opts = [`table: '${r.table}'`, `column: '${r.column}'`]
+      if (r.onDelete) opts.push(`onDelete: '${r.onDelete}'`)
+      if (r.onUpdate) opts.push(`onUpdate: '${r.onUpdate}'`)
+      parts.push(`_references: { ${opts.join(', ')} }`)
+    }
     return `${indent}${colName}: { ${parts.join(', ')} },\n`
   }
 
+  /**
+   * Copy introspected foreign keys onto the columns that carry them.
+   *
+   * `getConstraints()` describes columns and `getForeignKeys()` describes
+   * references, and the generator only ever read the first — so a database whose
+   * `posts.author_id` references `users.id ON DELETE CASCADE` regenerated as a
+   * plain integer. The constraint stayed in the database, the schema stopped
+   * mentioning it, and the next sync therefore planned to rebuild the table to
+   * *remove* a key nobody asked to remove.
+   *
+   * Single-column keys only. A composite key cannot be a property of one column
+   * — it is declared with `foreign()` alongside the indexes — and inventing a
+   * per-column half of one would be worse than omitting it, so it is counted and
+   * reported rather than silently dropped.
+   */
+  private static attachReferences(
+    constraints: Record<string, any>,
+    fks: SyncTypes.DBForeignKeys,
+  ): { attached: number; composite: number } {
+    let attached = 0
+    let composite = 0
+
+    for (const fk of Object.values(fks)) {
+      if (fk.cols.length !== 1 || fk.refCols.length !== 1) {
+        composite++
+        continue
+      }
+      // Introspection reports SQL identifiers; the constraints map is keyed the
+      // way the schema declares them.
+      const table = Object.keys(constraints).find(
+        t => Case.camel(t) === Case.camel(fk.table),
+      )
+      const cols = table ? constraints[table] : undefined
+      if (!cols) continue
+
+      const col = Object.keys(cols).find(
+        c => Case.camel(c) === Case.camel(fk.cols[0]),
+      )
+      if (!col) continue
+
+      cols[col]._references = {
+        table: fk.refTable,
+        column: fk.refCols[0],
+        ...(fk.onDelete && fk.onDelete !== 'NO ACTION'
+          ? { onDelete: fk.onDelete }
+          : {}),
+        ...(fk.onUpdate && fk.onUpdate !== 'NO ACTION'
+          ? { onUpdate: fk.onUpdate }
+          : {}),
+      }
+      attached++
+    }
+
+    return { attached, composite }
+  }
+
   /**
    * The `Field` call for a column, or `null` when none fits.
    *
@@ -186,6 +263,13 @@ export class SchemaBuilder {
     nullable: boolean,
   ): string | null {
     if (cons.primary || cons.autoIncrement) return null
+    // A referencing column has no `Field.*` spelling that also carries the
+    // reference — `Field.Foreign` needs the parent table's column *value* in
+    // scope, which the generated file cannot guarantee (introspection order is
+    // not declaration order, and the single-file layout has no table values at
+    // all). Fall through to the object literal, which spells `_references`
+    // exactly as the loader reads it.
+    if (cons._references) return null
     const hasLen = typeof cons.length === 'number'
     // `undefined` from getDefaultValue means "no default", which is a different
     // column from one defaulting to null.
@@ -354,6 +438,39 @@ ${body}`
     return `${result}  } as const;\n`
   }
 
+  /**
+   * `orm/indexes.ts`: one exported declaration per index in the database.
+   *
+   * The folder layout's counterpart to the `indexes` block `DBInfo` carries, and
+   * the reason a regenerated folder schema no longer arms the next sync to drop
+   * every index it just read.
+   */
+  private static buildIndexModule(dbIndexes: Record<string, any>): string {
+    let body = ''
+    for (const [idxName, idx] of Object.entries(dbIndexes)) {
+      const cols =
+        idx.cols.length === 1
+          ? `'${idx.cols[0]}'`
+          : `[${idx.cols.map((c: string) => `'${c}'`).join(', ')}]`
+      const fn = idx.type === 'unique' ? 'Field.Unique' : 'Field.Index'
+      body += `export const ${Case.camel(idxName)} = ${fn}('${idx.table}', ${cols})\n`
+    }
+
+    return `/**
+ * Generated from the database by \`db:sync\`.
+ *
+ * Seeded once and never overwritten — unlike \`tables.ts\`. An index this file
+ * does not declare is dropped by the next TS-wins sync, so add new ones here
+ * rather than only in the database.
+ *
+ * Composite foreign keys belong here too, declared with \`foreign()\`: a
+ * reference on a single column cannot express them.
+ */
+import { Field } from '@bakery-framework/orm'
+
+${body}`
+  }
+
   private static buildIndexesString(dbIndexes: Record<string, any>): string {
     let result = '{\n'
     for (const [idxName, idx] of Object.entries(dbIndexes)) {
@@ -517,6 +634,16 @@ declare module '@bakery-framework/orm/schema-registry' {
     const { stripLedger } = await import('./ledger')
     const constraints = stripLedger(await adapter.getConstraints())
 
+    // Before nullability is reconciled, so a referencing column is described
+    // completely by the time anything decides how to spell it.
+    const refs = SchemaBuilder.attachReferences(
+      constraints,
+      await adapter.getForeignKeys(),
+    )
+    if (refs.composite) {
+      messages.GEN_COMPOSITE_FK({ count: String(refs.composite) })
+    }
+
     SchemaBuilder.syncNullableConstraints(constraints, existingConstraints)
 
     // The write target and the shape written have to agree. `folder` means
@@ -564,6 +691,25 @@ declare module '@bakery-framework/orm/schema-registry' {
           messages.VIEWS_SEEDED?.({ file: viewsPath })
         }
       }
+
+      // And `indexes.ts`, on the same seed-once terms.
+      //
+      // Nothing wrote this file before, which made the folder layout lossy in a
+      // way the single-file layout is not: `DBInfo` carries an `indexes` block,
+      // so `--choose=db` there round-trips them, while the folder layout left
+      // every index undeclared. A TS-wins sync then drops what the schema does
+      // not mention — so regenerating a folder-layout schema from a database
+      // armed the *next* sync to delete every index in it.
+      const indexes = await adapter.getIndexes()
+      if (Object.keys(indexes).length) {
+        const indexesPath = `${schemaPath.replace(/[^/\\]+$/, '')}indexes.ts`
+        if (await Bun.file(indexesPath).exists()) {
+          messages.INDEXES_KEPT?.({ file: indexesPath })
+        } else {
+          await Bun.write(indexesPath, SchemaBuilder.buildIndexModule(indexes))
+          messages.INDEXES_SEEDED?.({ file: indexesPath })
+        }
+      }
     }
 
     messages.SYNC_SUCCESS()

package/src/sync/engine.ts

@@ -18,6 +18,18 @@ import type * as SyncTypes from './types'
 // prettier-ignore
 export const syncMsgs = {
   GEN_TYPES: 'I Generating types...',
+  // Counted rather than silently dropped: a composite key is not a property of
+  // one column, so the generator cannot spell it — but a reader who is not told
+  // will believe the generated schema is complete.
+  GEN_COMPOSITE_FK:
+    'W %y{count}%* composite foreign key(s) could not be generated as column references — declare them with %yforeign()%* beside the indexes.',
+  INDEXES_SEEDED: 'I Seeded %y{file}%* from the database.',
+  INDEXES_KEPT:
+    'I Left %y{file}%* alone: index declarations are hand-owned once seeded. Delete it and re-run to reseed.',
+  MIGRATE_DONE:
+    'I %gAdopted the existing database%*. No tables were changed; run %ydb:sync%* to confirm nothing is pending.',
+  MIGRATE_NO_LEDGER:
+    'W Schema written, but the ledger could not be recorded — the next sync will diff against live introspection instead.',
   SYNC_SUCCESS: 'I %gschema.ts successfully synced%* to Database!',
   INVALID_SCHEMA: 'W %yschema.ts is invalid or corrupt. Treating as new.%*',
   NO_DBINFO: 'W %yDBInfo namespace not found in schema.ts!%*',
@@ -122,6 +134,28 @@ class SyncSession implements AsyncDisposable {
 export class SyncEngine {
   protected constructor() {}
 
+  /**
+   * Record the adopted database as the schema Bakery last applied.
+   *
+   * Without this, the first sync after an adoption falls back to introspection —
+   * safe, but it withdraws the thing the ledger is for, and enum member changes
+   * only migrate when the diff runs against the ledger.
+   *
+   * Seeded from introspection rather than from the generated file, deliberately:
+   * the ledger's job is to record *what is in the database*, and reading it back
+   * from a file that was itself just derived from the database would add a
+   * lossy hop for no gain.
+   */
+  private static async seedLedger(adapter: SQLAdapter): Promise<void> {
+    const { writeLedger, stripLedger } = await import('./ledger')
+    const wrote = await writeLedger(
+      adapter,
+      stripLedger(await adapter.getConstraints()),
+      await adapter.getIndexes(),
+    )
+    if (!wrote) MESSAGES.MIGRATE_NO_LEDGER()
+  }
+
   private static async checkEmptyConstraints(
     adapter: SQLAdapter,
     constraints: SyncTypes.DBConstraints,
@@ -290,6 +324,22 @@ export class SyncEngine {
   ): Promise<void> {
     const genLocal = (c: any = {}) =>
       SchemaBuilder.generate(adapter, schemaPath, MESSAGES, c, layout)
+
+    // `--migrate` runs before every other branch, and changes no tables.
+    //
+    // It is not `--choose=db` with a nicer name. `--choose=db` sits *after* the
+    // "no changes" early return, so on a database that already matches it does
+    // nothing — which is the common case when adopting one, since the schema
+    // being written is derived from that same database. And it never writes the
+    // ledger, so the first real sync afterwards diffs against introspection
+    // instead: the one place enum changes are invisible.
+    if (process.argv.includes('--migrate')) {
+      await genLocal(constraints)
+      await SyncEngine.seedLedger(adapter)
+      MESSAGES.MIGRATE_DONE()
+      return
+    }
+
     const isEmpty = await SyncEngine.checkEmptyConstraints(
       adapter,
       constraints,

package/src/sync/index.ts

@@ -14,11 +14,54 @@ const syncMsgs = {
   FOREIGN_UNSUPPORTED:
     'E %rforeign() is declared but not implemented%*: {names}. No adapter emits FOREIGN KEY DDL, so it would be created as a plain index and then re-diffed on every sync. Use index() on the column and enforce the reference in your application.',
   SCHEMA_NOT_FOUND:
-    'E %rConfigured schema path not found%*: {path}. %yschema%* in server.config.ts must name a file or an orm/ folder that exists; remove it to auto-detect. Generating one from the database? Create the (empty) file first.',
+    'E %rConfigured schema path not found%*: {path}. %yschema%* in server.config.ts must name a file or an orm/ folder that exists; remove it to auto-detect. Generating one from the database? Create the (empty) file first, or run %ydb:sync --migrate%*.',
+  MIGRATE_SCAFFOLDED: 'I Created %y{dir}%* — the generator owns tables.ts.',
 } as const
 
 const MESSAGES = messageLogger(logger, syncMsgs)
 
+/**
+ * `orm/index.ts` — the one file in the folder layout nothing else writes.
+ *
+ * `tables.ts` belongs to the generator, and `views.ts` / `indexes.ts` are seeded
+ * by it. This is the re-export barrel plus the type registration, and without
+ * the `declare module` block the ORM runs untyped: every table and column falls
+ * back to `any`.
+ */
+function ormIndexModule(hasViews: boolean, hasIndexes: boolean): string {
+  // Conditional, and it has to be: the generator seeds `views.ts` and
+  // `indexes.ts` only when the database actually has views or indexes, so an
+  // unconditional `export * from './views'` is a module that does not resolve
+  // in every project that has neither.
+  const viewImport = hasViews ? "import * as views from './views'\n" : ''
+  const model = hasViews ? 'typeof tables & typeof views' : 'typeof tables'
+
+  return `import type {
+  InferOptionals,
+  InferSchema,
+  InferViews,
+} from '@bakery-framework/orm'
+import * as tables from './tables'
+${viewImport}
+export * from './tables'
+${hasViews ? "export * from './views'\n" : ''}${hasIndexes ? "export * from './indexes'\n" : ''}
+type Model = ${model}
+
+// Without this block the ORM still runs, untyped: every table and column falls
+// back to \`any\`. The framework never imports this file at runtime — schema
+// values are loaded by path — so this is purely the type registration.
+declare module '@bakery-framework/orm/schema-registry' {
+  interface SchemaRegistry {
+    schema: {
+      DBSchema: InferSchema<Model>
+      DBOptionals: InferOptionals<Model>
+      Views: InferViews<Model>
+    }
+  }
+}
+`
+}
+
 export class SyncService {
   protected constructor() {}
 
@@ -40,9 +83,13 @@ export class SyncService {
     // CLI usage text goes to stdout verbatim — it is program output, not a
     // log line, so it deliberately bypasses the structured logger.
     console.log(`
-Usage: bun run db:sync [--choose=db|ts] [--dry-run] [--force-sync] [--help]
+Usage: bun run db:sync [--migrate] [--choose=db|ts] [--dry-run] [--force-sync] [--help]
 
 Flags:
+  --migrate       Adopt an existing database: write the schema from what is
+                  already there, creating the orm/ folder if none exists, and
+                  record it so the next sync has nothing to do. Changes no
+                  tables. Use this once, on a database Bakery did not create.
   --choose=db     Generate schema.ts from the database (DB wins)
   --choose=ts     Apply schema.ts to the database (TS wins, default)
   --dry-run       Preview planned changes without applying them
@@ -52,6 +99,41 @@ Flags:
 `)
   }
 
+  /** `--migrate`: adopt what is already in the database. */
+  static migrateRequested(argv: string[] = process.argv.slice(2)): boolean {
+    return argv.includes('--migrate')
+  }
+
+  /**
+   * Write the three files the generator does *not* own, and return the one it
+   * does.
+   *
+   * Only `index.ts`, and that is the whole point of the restraint.
+   *
+   * The first version also wrote empty `views.ts` and `indexes.ts` stubs, which
+   * *broke adoption* in a way that only an end-to-end run showed: the generator
+   * seeds both, but only when the file does not already exist, so the stubs
+   * blocked it. The schema then declared no views and no indexes, and the very
+   * next `db:sync` planned to drop the view and all three indexes it had just
+   * adopted. An adoption path that arms a destructive sync is worse than none.
+   *
+   * `tables.ts` is not written here either: `SchemaBuilder` owns it outright.
+   */
+  static async writeOrmIndex(cwd: string): Promise<void> {
+    const dir = `${cwd}/orm`
+    const indexPath = `${dir}/index.ts`
+    if (await Bun.file(indexPath).exists()) return
+
+    await Bun.write(
+      indexPath,
+      ormIndexModule(
+        await Bun.file(`${dir}/views.ts`).exists(),
+        await Bun.file(`${dir}/indexes.ts`).exists(),
+      ),
+    )
+    MESSAGES.MIGRATE_SCAFFOLDED({ dir: 'orm/' })
+  }
+
   static async run() {
     // Before initConfig/initDB/loadSchema: help must not depend on a working
     // connection, a loadable schema, or the absence of a `foreign()`.
@@ -97,12 +179,24 @@ Flags:
       MESSAGES.NO_DBINFO()
     }
 
-    await connection.syncSchema(
-      constraints,
-      tsIndexes,
-      schemaPath,
-      loaded.layout,
-    )
+    // `--migrate` on a project with no schema at all creates the folder layout
+    // rather than a single `schema.ts`. Adoption is exactly the case where the
+    // folder earns its keep: the generator owns `tables.ts` and regenerating it
+    // cannot touch the views, indexes and registration beside it — which for an
+    // adopted database is the difference between re-running the command and
+    // hand-restoring what it overwrote.
+    const adopting = SyncService.migrateRequested() && loaded.layout === 'none'
+    const layout = adopting ? 'folder' : loaded.layout
+    const targetPath = adopting ? `${process.cwd()}/orm/tables.ts` : schemaPath
+
+    await connection.syncSchema(constraints, tsIndexes, targetPath, layout)
+
+    // After generation, not before: `index.ts` re-exports `views.ts` and
+    // `indexes.ts`, which the generator writes only when the database has views
+    // or indexes to write. Deciding what to import before knowing which files
+    // exist is how the first version produced a barrel pointing at nothing.
+    if (adopting) await SyncService.writeOrmIndex(process.cwd())
+
     await closeDB()
   }
 }