@bakery-framework/orm 2.0.4 → 2.1.1

package/package.json

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

package/src/adapters/base.ts

@@ -4,6 +4,7 @@ import type { MapOf } from '@bakery-framework/core/types'
 import { Case, Try } from '@bakery-framework/core/utils'
 import { throws } from '@bakery-framework/core/utils/common'
 import type * as SyncTypes from '../sync/types'
+import { DatabaseMissingError, isMissingDatabase } from './missing-database'
 import { observe, observeIterate } from './observe'
 import type { Driver as RegisteredDriver } from './registry'
 
@@ -181,6 +182,12 @@ export function isOpenConnection(value: unknown): boolean {
   )
 }
 
+/** A database name as a URL path carries it, with the percent-encoding undone. */
+function decodedDatabaseName(raw: string | undefined): string | undefined {
+  if (!raw) return undefined
+  return Try.return(() => decodeURIComponent(raw), raw)
+}
+
 export function quoteIdentifier(name: string, quoteChar: string): string {
   // The `includes` guard is not redundant: `replaceAll` walks and rebuilds the
   // string even when there is nothing to replace, and an identifier containing
@@ -275,16 +282,40 @@ export function pagedIterate(
   }
 }
 
+/**
+ * `fn`, with whatever it throws passed through `explain` first.
+ */
+function explained<A extends unknown[], R>(
+  fn: (...args: A) => R | Promise<R>,
+  explain: (error: unknown) => unknown,
+): (...args: A) => Promise<R> {
+  return async (...args: A) => {
+    try {
+      return await fn(...args)
+    } catch (error) {
+      throw explain(error)
+    }
+  }
+}
+
 export function createExecutor(
-  all: SQLAdapter.Executor['all'],
-  run: SQLAdapter.Executor['run'],
+  rawAll: SQLAdapter.Executor['all'],
+  rawRun: SQLAdapter.Executor['run'],
   driver: SQLAdapter.Driver,
   options: {
     /** Replace the paging walker: for a driver that can genuinely stream. */
     iterate?: SQLAdapter.Executor['iterate']
     chunkSize?: number
+    /**
+     * Turn a driver error into one that says what to do, before any caller
+     * sees it. Applied to `all` and `run` themselves, so `get`, `values` and
+     * the paging `iterate` carry it too. See `SQLAdapter.explainError`.
+     */
+    explain?: (error: unknown) => unknown
   } = {},
 ): SQLAdapter.Executor {
+  const all = options.explain ? explained(rawAll, options.explain) : rawAll
+  const run = options.explain ? explained(rawRun, options.explain) : rawRun
   const iterate = options.iterate ?? pagedIterate(all, options.chunkSize)
   // `get` and `values` call the raw `all` rather than `exec.all`, which is a
   // behavioral detail worth stating: it is what keeps one executed statement
@@ -345,6 +376,71 @@ export abstract class SQLAdapter {
     }, undefined)
   }
 
+  /**
+   * The server half of the connection URL, `host:port`, for messages. Never
+   * the URL itself, which carries the password.
+   */
+  get serverName(): string | undefined {
+    if (!this.url) return undefined
+    return Try.return(() => new URL(this.url!).host || undefined, undefined)
+  }
+
+  /**
+   * The error a query raised, or a {@link DatabaseMissingError} when it means
+   * the server has no database by this connection's name. Passed to
+   * `createExecutor` by the two server adapters; SQLite creates its file on
+   * open and has no such error to explain.
+   */
+  protected explainError(error: unknown): unknown {
+    if (!isMissingDatabase(error)) return error
+    const database = decodedDatabaseName(this.databaseName)
+    const server = this.serverName
+    if (!database || !server) return error
+    return new DatabaseMissingError(database, server, { cause: error })
+  }
+
+  /**
+   * The same server and credentials, pointed at a database that always
+   * exists there: where `CREATE DATABASE` runs. `undefined` for a dialect
+   * with no server to ask.
+   */
+  protected maintenanceUrl(): string | undefined {
+    return undefined
+  }
+
+  /** A sibling adapter on another URL, for {@link createDatabase}. */
+  protected forUrl(_url: string): SQLAdapter {
+    throw new Error(`The ${this.driver} adapter cannot open a second database.`)
+  }
+
+  /**
+   * Create the database this connection names, through a second connection
+   * to the server's maintenance database, and return its name.
+   *
+   * Not called by anything that runs on its own: `db:sync` calls it only with
+   * `--create-database` or a yes at its prompt, because creating a database
+   * needs a privilege an app's runtime role should not hold, and because a
+   * typo in `DB_URL` must not quietly become a fresh, empty database.
+   */
+  async createDatabase(): Promise<string> {
+    const database = decodedDatabaseName(this.databaseName)
+    const target = this.maintenanceUrl()
+    if (!database || !target) {
+      throw new Error(
+        database
+          ? `The ${this.driver} adapter has no server to create a database on.`
+          : `DB_URL names no database for the ${this.driver} adapter to create.`,
+      )
+    }
+    const admin = this.forUrl(target)
+    try {
+      await admin.query(`CREATE DATABASE ${admin.quote(database)}`).run()
+    } finally {
+      await admin.close()
+    }
+    return database
+  }
+
   /**
    * Placeholder ceiling for a single statement. See
    * {@link DEFAULT_MAX_QUERY_PARAMS} for why it is one number and not three.
@@ -357,6 +453,21 @@ export abstract class SQLAdapter {
     return DEFAULT_MAX_QUERY_PARAMS
   }
 
+  /**
+   * `url` with its database swapped for `name`, and everything else (the
+   * credentials, the host, the query string and with it `sslmode`) kept.
+   * `undefined` when there is no URL to rewrite. A static for the reason
+   * {@link usableTotal} gives.
+   */
+  static withDatabase(url: string | undefined, name: string): string | undefined {
+    if (!url) return undefined
+    return Try.return(() => {
+      const target = new URL(url)
+      target.pathname = `/${encodeURIComponent(name)}`
+      return target.toString()
+    }, undefined)
+  }
+
   /**
    * Whether a caller-supplied total can be used in place of a `COUNT(*)`.
    *

package/src/adapters/missing-database.ts

@@ -0,0 +1,42 @@
+/**
+ * A server that has no database by the name the connection asked for.
+ *
+ * Recognized by the code the server itself sends, which is stable across
+ * driver versions in a way no message is. Measured 2026-10-01 against
+ * Postgres 16 and MySQL 8.4:
+ *
+ *     Postgres  SQLSTATE 3D000   Bun: errno "3D000"   postgres.js: code "3D000"
+ *     MySQL     error 1049       Bun: errno 1049      mysql2: errno 1049
+ *
+ * postgres.js and mysql2 are not bakery's drivers. They are listed because
+ * silid's copy of this ORM runs on them, and one predicate serves both.
+ */
+export function isMissingDatabase(error: unknown): boolean {
+  const e = error as { errno?: unknown; code?: unknown } | null | undefined
+  return e?.errno === '3D000' || e?.code === '3D000' || e?.errno === 1049
+}
+
+/**
+ * What a query raises when the database `DB_URL` names does not exist, in
+ * place of the driver's own error (kept as `cause`).
+ *
+ * The message names the database, the server (host and port, never the
+ * credentials in the URL) and the command that creates it, because the
+ * driver's version names only the database, and on a production log that
+ * reads as data loss rather than as a typo or a missing step.
+ */
+export class DatabaseMissingError extends Error {
+  override readonly name = 'DatabaseMissingError'
+
+  constructor(
+    readonly database: string,
+    readonly server: string,
+    options?: ErrorOptions,
+  ) {
+    super(
+      `Database "${database}" does not exist on ${server}. ` +
+        'Run `bun run db:sync --create-database` to create it, or point DB_URL at one that exists.',
+      options,
+    )
+  }
+}

package/src/adapters/mysql.ts

@@ -56,6 +56,7 @@ export class MySQLAdapter extends SQLAdapter {
       }
     },
     this.driver,
+    { explain: error => this.explainError(error) },
   )
 
   async hasCol(table: string, column: string): Promise<boolean> {
@@ -270,6 +271,15 @@ export class MySQLAdapter extends SQLAdapter {
     return new MySQLAdapter(sql as SQL)
   }
 
+  /** `mysql`: the system database every MySQL server has, and the one Bun's client falls back to when a URL names none (measured). The query string, and with it `sslmode`, is kept. */
+  protected override maintenanceUrl(): string | undefined {
+    return SQLAdapter.withDatabase(this.url, 'mysql')
+  }
+
+  protected override forUrl(url: string): SQLAdapter {
+    return new MySQLAdapter(url)
+  }
+
   async getSchema(
     options?: SQLAdapter.SchemaOptions,
   ): Promise<SQLAdapter.TableDetails[]> {

package/src/adapters/pgsql.ts

@@ -175,6 +175,7 @@ export class PGAdapter extends SQLAdapter {
       return { lastInsertRowid, changes }
     },
     this.driver,
+    { explain: error => this.explainError(error) },
   )
 
   async hasCol(table: string, column: string): Promise<boolean> {
@@ -252,6 +253,15 @@ export class PGAdapter extends SQLAdapter {
     return new PGAdapter(sql as SQL)
   }
 
+  /** `postgres`: the database every Postgres cluster is created with. The query string, and with it `sslmode`, is kept. */
+  protected override maintenanceUrl(): string | undefined {
+    return SQLAdapter.withDatabase(this.url, 'postgres')
+  }
+
+  protected override forUrl(url: string): SQLAdapter {
+    return new PGAdapter(url)
+  }
+
   async getSchema(
     options?: SQLAdapter.SchemaOptions,
   ): Promise<SQLAdapter.TableDetails[]> {

package/src/adapters/sqlite.ts

@@ -1,3 +1,4 @@
+import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import { Bakery } from '@bakery-framework/core/core/bakery'
 import { Logger, messageLogger } from '@bakery-framework/core/logger'
@@ -381,7 +382,13 @@ export class SQLiteAdapter extends SQLAdapter {
       base = path.basename(this.filename, ext)
     const backupDir = `${path.dirname(this.filename)}/backups`,
       backupName = `${base}.${Date.now()}${ext}`
-    await Bun.write(`${backupDir}/${backupName}`, Bun.file(this.filename))
+    await mkdir(backupDir, { recursive: true })
+    // `VACUUM INTO`, not a copy of the file. In WAL mode a commit sits in
+    // `-wal` until a checkpoint, and a copy of the main file alone came out
+    // with no table in it at all after a CREATE and 50 inserts (see
+    // `sqlite-backup.test.ts`). SQLite writes this from a read transaction,
+    // so it is consistent and holds everything committed.
+    await this.query('VACUUM INTO ?').run(`${backupDir}/${backupName}`)
     return {
       file: backupName,
       cleanupCount: await this.cleanupBackups(backupDir, base, ext, keepCount),

package/src/adapters.ts

@@ -1,4 +1,5 @@
 export * from './adapters/base'
+export * from './adapters/missing-database'
 export * from './adapters/registry'
 
 import { registerAdapter, resolveAdapter } from './adapters/registry'

package/src/orm/query.ts

@@ -1079,10 +1079,8 @@ export namespace DB {
       return left
     }
     const op = operator.toUpperCase()
-    if (op === 'IS NULL' || op === 'IS NOT NULL') {
-      return `${left} ${op}`
-    }
-    // One rule, three callers. See `nullComparison`.
+    // One rule, three callers, `IS NULL` and `IS NOT NULL` included. See
+    // `nullComparison`.
     const nullOp = nullComparison(op, rightArg, isRightColumn)
     if (nullOp) return `${left} ${nullOp}`
     if (op === 'BETWEEN' && Array.isArray(rightArg)) {

package/src/schema-util.ts

@@ -484,14 +484,21 @@ export function old(
  * function three callers share cannot drift a third time.
  *
  * A column reference on the right is a different comparison and is left alone.
+ *
+ * `IS NULL` and `IS NOT NULL` themselves (`DB.isNull()`, `DB.isNotNull()`)
+ * are the third drift, and the reason they are answered here first:
+ * `formatClause` handled them before calling this, the two `evalWhere` copies
+ * did not, and every `UPDATE` or `DELETE` through either helper emitted
+ * `IS NULL NULL`, which no dialect parses.
  */
 export function nullComparison(
   operator: string,
   right: unknown,
   isRightColumn?: boolean,
 ): string | null {
-  if (right !== null || isRightColumn) return null
   const op = operator.toUpperCase()
+  if (op === 'IS NULL' || op === 'IS NOT NULL') return op
+  if (right !== null || isRightColumn) return null
   if (op === '=') return 'IS NULL'
   if (op === '!=' || op === '<>') return 'IS NOT NULL'
   return null

package/src/sync/engine.ts

@@ -47,6 +47,7 @@ export const syncMsgs = {
   DANGER_ZONE: 'W %rDANGER ZONE: Destructive or major changes detected!%*',
   DROP_TABLES: 'W Tables to drop: %r{tables}%*',
   RENAME_TABLES: 'I Tables to rename: %y{tables}%*',
+  CREATE_TABLES: 'I Tables to create: %g{tables}%*',
   DROP_COLS: 'W Columns to drop: %r{cols}%*',
   RENAME_COLS: 'I Columns to rename: %y{cols}%*',
   ADD_COLS: 'I Columns to add: %g{cols}%*',

package/src/sync/index.ts

@@ -1,6 +1,13 @@
 import '@bakery-framework/core/core/init'
 
-import { Logger, messageLogger } from '@bakery-framework/core/logger'
+import {
+  isInteractive,
+  Logger,
+  messageLogger,
+} from '@bakery-framework/core/logger'
+import { Try } from '@bakery-framework/core/utils'
+import type { SQLAdapter } from '../adapters/base'
+import { DatabaseMissingError } from '../adapters/missing-database'
 import { closeDB, connection, initDB } from '../connection'
 import { loadSchema, schemaFromConfig } from './load'
 
@@ -18,6 +25,9 @@ const syncMsgs = {
   MIGRATE_SCAFFOLDED: 'I Created %y{dir}%*: the generator owns tables.ts.',
   MIGRATE_RETIRED:
     'I Converted to the orm/ folder. The previous %yschema.ts%* was moved to %y{to}%*, not deleted.',
+  DB_MISSING:
+    'E %rDatabase %y{name}%r does not exist on {server}%*. Run %ybun run db:sync --create-database%* to create it, or point DB_URL at one that exists.',
+  DB_CREATED: 'I Created database %g{name}%* on %y{server}%*.',
 } as const
 
 const MESSAGES = messageLogger(logger, syncMsgs)
@@ -85,7 +95,7 @@ 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 [--migrate] [--choose=db|ts] [--dry-run] [--force-sync] [--help]
+Usage: bun run db:sync [--migrate] [--choose=db|ts] [--dry-run] [--force-sync] [--create-database] [--help]
 
 Flags:
   --migrate       Adopt an existing database: write the schema from what is
@@ -96,11 +106,59 @@ Flags:
   --choose=ts     Apply schema.ts to the database (TS wins, default)
   --dry-run       Preview planned changes without applying them
   --force-sync    In production, allow destructive changes
+  --create-database
+                  Create the database DB_URL names when the server does
+                  not have it. Asked in a terminal, needed without one.
   --no-ledger     Diff against live introspection, ignoring the recorded schema
   --help, -h      Show this help message
 `)
   }
 
+  /** `--create-database`: make the database `DB_URL` names if it is missing. */
+  static createRequested(argv: string[] = process.argv.slice(2)): boolean {
+    return argv.includes('--create-database')
+  }
+
+  /**
+   * Make sure the database the connection names exists, creating it when
+   * that was asked for.
+   *
+   * `present` and `created` mean the sync can go on; `missing` means it
+   * cannot, and `DB_MISSING` has said why. Creating needs `--create-database`
+   * or a yes at the prompt, and the prompt is only asked with a terminal: an
+   * unattended run (CI, a deploy step, a container) never creates one on its
+   * own, since a typo in `DB_URL` would otherwise become a fresh, empty
+   * database with the real one untouched beside it.
+   *
+   * Any other connection failure is thrown as before. SQLite answers
+   * `present`, having created its file on open.
+   */
+  static async ensureDatabase(
+    adapter: SQLAdapter,
+    {
+      argv = process.argv.slice(2),
+      interactive = isInteractive(),
+    }: { argv?: string[]; interactive?: boolean } = {},
+  ): Promise<'present' | 'created' | 'missing'> {
+    const [error] = await Try.catch(adapter.query('SELECT 1').get())
+    if (!error) return 'present'
+    if (!(error instanceof DatabaseMissingError)) throw error
+
+    const asked =
+      SyncService.createRequested(argv) ||
+      (interactive &&
+        logger.confirm(
+          `Database "${error.database}" does not exist on ${error.server}. Create it?`,
+        ))
+    if (!asked) {
+      MESSAGES.DB_MISSING({ name: error.database, server: error.server })
+      return 'missing'
+    }
+    await adapter.createDatabase()
+    MESSAGES.DB_CREATED({ name: error.database, server: error.server })
+    return 'created'
+  }
+
   /** `--migrate`: adopt what is already in the database. */
   static migrateRequested(argv: string[] = process.argv.slice(2)): boolean {
     return argv.includes('--migrate')
@@ -192,6 +250,13 @@ Flags:
       return process.exit(1)
     }
 
+    // After the schema checks, so a config error never leaves a new, empty
+    // database behind, and before anything else asks the database a question.
+    if ((await SyncService.ensureDatabase(connection)) === 'missing') {
+      await closeDB()
+      return process.exit(1)
+    }
+
     // `foreign()` used to abort here, because no adapter emitted FOREIGN KEY
     // DDL and the declaration would have become a plain index: referential
     // integrity in appearance only. All three adapters now emit and read back

package/src/sync/load.ts

@@ -29,11 +29,18 @@
  * somewhere else.
  */
 
+import { Logger, messageLogger } from '@bakery-framework/core/logger'
 import { Case, fs } from '@bakery-framework/core/utils'
 import { Try } from '@bakery-framework/core/utils/common'
 import { collectConstraints } from '../define'
 import type * as SyncTypes from './types'
 
+// Convention 4: logging is data, declared in a table.
+const MESSAGES = messageLogger(new Logger('db-sync'), {
+  SCHEMA_IMPORT_FAILED:
+    'W %y{file}%* could not be loaded: %r{error}%*. Sync is treating the schema as absent.',
+} as const)
+
 /**
  * Which shape the generator must write back.
  *
@@ -147,6 +154,9 @@ async function readSchema(
   targetPath: string,
 ): Promise<LoadedSchema> {
   const [error, module] = await importFresh(entry)
+  // Still read as no schema, which `loadSchema` relies on for a broken folder
+  // entry, but no longer in silence: this is the only place the cause exists.
+  if (error) MESSAGES.SCHEMA_IMPORT_FAILED({ file: entry, error: error.message })
   if (error || !module) return emptyAt(targetPath)
 
   if (layout === 'folder') {

package/src/sync/plan.ts

@@ -118,6 +118,15 @@ export function logPlannedChanges(
         .map(t => `${t.oldName} -> ${t.newName}`)
         .join(', '),
     })
+  // Counted as a change in `evaluateChanges` from the start and never
+  // printed, so a dry run on a fresh database listed its indexes and none of
+  // its tables. The tables are created by the last phase of the run, which
+  // emits CREATE TABLE IF NOT EXISTS for every table; this set is the ones
+  // that phase will actually create.
+  if (plan.unmappedTsTables.size)
+    MESSAGES.CREATE_TABLES({
+      tables: Array.from(plan.unmappedTsTables, t => Case.snake(t)).join(', '),
+    })
   if (plan.columnsToDrop.length)
     MESSAGES.DROP_COLS({
       cols: plan.columnsToDrop.map(c => `${c.table}.${c.column}`).join(', '),