@bakery-framework/orm 2.1.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/orm",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Bakery database layer: adapters, query builder, schema sync and backup.",
   "keywords": [
     "bakery",
@@ -36,13 +36,15 @@
     "./sync/ledger": "./src/sync/ledger.ts",
     "./sync/history": "./src/sync/history.ts",
     "./sync/rollback": "./src/sync/rollback.ts",
+    "./migrate": "./src/migrate/index.ts",
     "./templates/*": "./templates/*",
     "./package.json": "./package.json",
     "./schema-registry": "./src/schema-registry.ts",
     "./schema-util": "./src/schema-util.ts",
     "./connection": "./src/connection.ts",
     "./pool": "./src/pool.ts",
-    "./backup": "./src/backup.ts"
+    "./backup": "./src/backup.ts",
+    "./sessions": "./src/sessions.ts"
   },
   "files": [
     "src",
@@ -54,6 +56,6 @@
     "bun": ">=1.4.0"
   },
   "dependencies": {
-    "@bakery-framework/core": "^2.1.2"
+    "@bakery-framework/core": "^2.2.0"
   }
 }

package/src/adapters/base.ts

@@ -3,6 +3,8 @@ import { Logger } from '@bakery-framework/core/logger'
 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 { isArrayValue } from '../array-value'
+import type { ScriptDialect } from '../migrate/script'
 import type * as SyncTypes from '../sync/types'
 import { DatabaseMissingError, isMissingDatabase } from './missing-database'
 import { observe, observeIterate } from './observe'
@@ -20,6 +22,27 @@ export namespace SQLAdapter {
     lastInsertRowid: number | bigint | null
     changes: number
   }
+  /**
+   * A column as the database's catalog describes it, for the check that
+   * migrations mode runs in place of a sync (`migrate/check.ts`).
+   */
+  export interface LiveColumn {
+    /** As the database spells it. */
+    table: string
+    column: string
+    /** In the dialect's own spelling, lower-cased: `character varying(64)`, `int`. */
+    type: string
+    nullable: boolean
+    primary: boolean
+    /** A view's column: catalogs report every one of them nullable. */
+    view: boolean
+    /** A native enum's labels, in order, where the dialect has native enums. */
+    enumValues?: string[]
+  }
+  /** The one call `executeScript` makes on a driver handle. */
+  export interface ScriptHandle {
+    unsafe(text: string): Promise<unknown>
+  }
   export interface BackupResult {
     file: string
     cleanupCount?: number
@@ -298,6 +321,22 @@ function explained<A extends unknown[], R>(
   }
 }
 
+/**
+ * The default `bind`: parameters as they are, refusing a `DB.array()` value,
+ * which only the Postgres adapter can encode. Bound as an object it would
+ * reach the driver as `[object Object]` or a driver error naming nothing.
+ */
+function refuseArrays(driver: SQLAdapter.Driver) {
+  return (params: unknown[]): unknown[] => {
+    if (params.some(isArrayValue)) {
+      throw new Error(
+        `DB.array() writes a Postgres array, and the ${driver} adapter has no array type. Store the values as JSON (Field.Json) instead.`,
+      )
+    }
+    return params
+  }
+}
+
 export function createExecutor(
   rawAll: SQLAdapter.Executor['all'],
   rawRun: SQLAdapter.Executor['run'],
@@ -312,10 +351,28 @@ export function createExecutor(
      * the paging `iterate` carry it too. See `SQLAdapter.explainError`.
      */
     explain?: (error: unknown) => unknown
+    /**
+     * Turn the query's parameters into what the driver binds. Postgres
+     * encodes a `DB.array()` value as an array literal here; the default
+     * refuses one, since only Postgres has arrays.
+     */
+    bind?: (params: unknown[]) => unknown[]
   } = {},
 ): SQLAdapter.Executor {
-  const all = options.explain ? explained(rawAll, options.explain) : rawAll
-  const run = options.explain ? explained(rawRun, options.explain) : rawRun
+  const bind = options.bind ?? refuseArrays(driver)
+  const bound = <F extends SQLAdapter.Executor['all'] | SQLAdapter.Executor['run']>(
+    fn: F,
+  ): F =>
+    (async (sqlText: string, params: unknown[] = []) =>
+      await fn(sqlText, bind(params))) as F
+  const explainedAll = options.explain
+    ? explained(rawAll, options.explain)
+    : rawAll
+  const explainedRun = options.explain
+    ? explained(rawRun, options.explain)
+    : rawRun
+  const all = bound(explainedAll)
+  const run = bound(explainedRun)
   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
@@ -459,7 +516,10 @@ export abstract class SQLAdapter {
    * `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 {
+  static withDatabase(
+    url: string | undefined,
+    name: string,
+  ): string | undefined {
     if (!url) return undefined
     return Try.return(() => {
       const target = new URL(url)
@@ -572,6 +632,76 @@ export abstract class SQLAdapter {
       ? await handle.savepoint(run)
       : await handle.transaction(run)
   }
+
+  /**
+   * Whether DDL runs inside a transaction here and is undone by a rollback.
+   * True on Postgres and SQLite; MySQL commits each DDL statement as it runs,
+   * so a migration that fails halfway there leaves its first half applied.
+   */
+  get transactionalDDL(): boolean {
+    return true
+  }
+
+  /**
+   * How this dialect's SQL text is lexed, for reading a migration file without
+   * running it (`migrate/script.ts`): standard quotes and comments, plus
+   * Postgres's dollar quotes or MySQL's backticks and `#` comments.
+   */
+  get scriptDialect(): ScriptDialect {
+    return 'sqlite'
+  }
+
+  /**
+   * Run a migration file's text as written: every statement in it, with no
+   * parameters and no rewriting.
+   *
+   * Not `query().run()`, which is built for one statement with placeholders:
+   * the Postgres executor rewrites `?` and backticks (it does not know about
+   * comments or `$$` bodies, and measured, it turned a backtick inside a quoted
+   * default into a double quote after a `-- don't` comment), and appends
+   * `RETURNING *` to anything starting with INSERT. With no parameters, Bun
+   * sends the text over the simple protocol, which takes several statements
+   * at once on all three dialects.
+   */
+  async executeScript(text: string): Promise<void> {
+    await (this.sql as SQLAdapter.ScriptHandle).unsafe(text)
+  }
+
+  /**
+   * Take the lock that keeps two migration runs from applying the same file,
+   * and return what releases it. A no-op here: SQLite serializes writers on
+   * its own. Held for the session, so the runner's connection pool has to be
+   * a single connection.
+   */
+  async takeMigrationLock(): Promise<() => Promise<void>> {
+    return async () => {}
+  }
+
+  /**
+   * Every column of every table and view in this connection's schema, read
+   * from the catalog alone, for the migrations-mode check. Catalog alone,
+   * because the check runs as the app's role, which may hold no privilege on
+   * some tables at all: on Postgres `information_schema` hid such a table
+   * entirely, and hid the primary key of a table the role could only read
+   * (measured), while `pg_catalog` showed both.
+   */
+  async liveColumns(): Promise<SQLAdapter.LiveColumn[]> {
+    throw new Error(
+      `The ${this.driver} adapter cannot read its catalog for the migrations check.`,
+    )
+  }
+
+  /**
+   * Why a live column's type does not match its declaration, or `null` when
+   * it does. Each adapter states its own dialect's rules: which spellings a
+   * `Field` accepts, and how a `Field.Sql` type compares.
+   */
+  columnTypeProblem(
+    _declared: SyncTypes.ColumnConstraint,
+    _live: SQLAdapter.LiveColumn,
+  ): string | null {
+    return null
+  }
   protected abstract parseConstraints(
     col: unknown,
     ...params: unknown[]
@@ -1097,8 +1227,11 @@ export abstract class SQLAdapter {
    * `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.
+   *
+   * Public for SQL written outside the adapter (the session store's search),
+   * which pairs it with {@link likeEscapeClause}: the two are one decision.
    */
-  protected escapeLike(value: string): string {
+  escapeLike(value: string): string {
     const e = this.likeEscape
     return value
       .split(e)

package/src/adapters/live-types.ts

@@ -0,0 +1,308 @@
+import type * as SyncTypes from '../sync/types'
+import type { SQLAdapter } from './base'
+
+/**
+ * Which live column types a declaration accepts, per dialect, for the check
+ * migrations mode runs instead of a sync (`migrate/check.ts`).
+ *
+ * The question each rule answers is "would a query typed by this declaration
+ * be right about what this column holds", which is looser than "is this the
+ * type classic sync would have created": a declared `Field.Int()` is right
+ * about a `smallint`, and a declared `Field.String()` about any `varchar`. A
+ * width or a precision the declaration states is held to exactly; one it
+ * leaves out is not asked about, the way an unsized `Field.String()` never
+ * asked for a column to shrink.
+ *
+ * Pure functions of the declaration and the catalog's description, so the
+ * rules are tested without a server.
+ */
+
+type Declared = SyncTypes.ColumnConstraint
+type Live = SQLAdapter.LiveColumn
+
+/** `declared X, the database has Y`. */
+function mismatch(expected: string, live: Live): string {
+  return `declared ${expected}, the database has ${live.type}`
+}
+
+/**
+ * A native enum whose labels differ from the declared members. Text with a
+ * CHECK is accepted unread: no catalog spells a CHECK's expression in a form
+ * worth parsing here.
+ */
+function enumProblem(declared: Declared, live: Live): string | null {
+  if (!declared._enum || !live.enumValues) return null
+  const want = [...declared._enum].sort().join(', ')
+  const have = [...live.enumValues].sort().join(', ')
+  return want === have
+    ? null
+    : `declared the values ${want}, the database's enum has ${have}`
+}
+
+/** The base name and modifier of a type: `numeric(5,2)` is `numeric` and `(5,2)`. */
+function splitModifier(type: string): { base: string; modifier: string } {
+  const open = type.indexOf('(')
+  if (open === -1) return { base: type, modifier: '' }
+  const close = type.indexOf(')', open)
+  const modifier = type.slice(open, close + 1).replace(/\s+/g, '')
+  // Postgres puts a timestamp's precision in the middle:
+  // `timestamp(3) with time zone`.
+  const base = `${type.slice(0, open)}${type.slice(close + 1)}`
+    .replace(/\s+/g, ' ')
+    .trim()
+  return { base, modifier }
+}
+
+/**
+ * Two spellings that mean the same type, where `declared` may leave a width,
+ * a precision or an array's element modifier unsaid.
+ */
+function sameType(declared: string, live: string): boolean {
+  if (declared === live) return true
+  const d = splitModifier(declared)
+  const l = splitModifier(live)
+  return d.base === l.base && (d.modifier === '' || d.modifier === l.modifier)
+}
+
+const PG_ALIASES: Record<string, string> = {
+  int: 'integer',
+  int4: 'integer',
+  serial: 'integer',
+  serial4: 'integer',
+  int2: 'smallint',
+  smallserial: 'smallint',
+  serial2: 'smallint',
+  int8: 'bigint',
+  bigserial: 'bigint',
+  serial8: 'bigint',
+  float4: 'real',
+  float8: 'double precision',
+  float: 'double precision',
+  bool: 'boolean',
+  varchar: 'character varying',
+  char: 'character',
+  bpchar: 'character',
+  decimal: 'numeric',
+  timestamptz: 'timestamp with time zone',
+  timestamp: 'timestamp without time zone',
+  timetz: 'time with time zone',
+  time: 'time without time zone',
+}
+
+/**
+ * A Postgres type as a declaration may spell it, in the spelling
+ * `format_type()` reports: `timestamptz` is `timestamp with time zone`,
+ * `varchar(64)` is `character varying(64)`, `int[]` is `integer[]`.
+ */
+export function normalizePgType(spelled: string): string {
+  let type = spelled.trim().toLowerCase().replace(/\s+/g, ' ')
+  let arrays = ''
+  while (type.endsWith('[]')) {
+    arrays += '[]'
+    type = type.slice(0, -2).trim()
+  }
+  const { base, modifier } = splitModifier(type)
+  const name = PG_ALIASES[base] ?? base
+  if (modifier && name.startsWith('timestamp ')) {
+    return `timestamp${modifier} ${name.slice('timestamp '.length)}${arrays}`
+  }
+  if (modifier && name.startsWith('time ')) {
+    return `time${modifier} ${name.slice('time '.length)}${arrays}`
+  }
+  return `${name}${modifier}${arrays}`
+}
+
+/** Postgres: `live.type` is `format_type()`, a domain already resolved to its base. */
+export function pgTypeProblem(declared: Declared, live: Live): string | null {
+  const type = live.type
+  const accepts = (ok: boolean, expected: string) =>
+    ok ? null : mismatch(expected, live)
+
+  switch (declared.type) {
+    case 'integer':
+      return accepts(
+        type === 'integer' || type === 'smallint',
+        'an integer (integer or smallint)',
+      )
+    case 'bigint':
+      return accepts(type === 'bigint', 'bigint')
+    case 'number':
+      return accepts(
+        type === 'double precision' || type === 'real',
+        'a float (double precision or real)',
+      )
+    case 'boolean':
+      return accepts(type === 'boolean', 'boolean')
+    case 'json':
+      return accepts(type === 'json' || type === 'jsonb', 'json or jsonb')
+    case 'buffer':
+      return accepts(type === 'bytea', 'bytea')
+    case 'sql': {
+      const want = normalizePgType(declared.sqlType ?? '')
+      return accepts(sameType(want, type), want)
+    }
+    case 'string': {
+      if (declared._enum) {
+        const textual = type === 'text' || type.startsWith('character varying')
+        if (!textual && !live.enumValues) {
+          return mismatch('an enum (text, varchar, or a native enum)', live)
+        }
+        return enumProblem(declared, live)
+      }
+      // Field.Uuid is a 36-character string; a native uuid holds the same.
+      if (declared.length === 36 && type === 'uuid') return null
+      if (declared.length) {
+        return accepts(
+          type === `character varying(${declared.length})` ||
+            type === `character(${declared.length})`,
+          `varchar(${declared.length})`,
+        )
+      }
+      return accepts(
+        type === 'text' ||
+          type === 'uuid' ||
+          type === 'citext' ||
+          type.startsWith('character varying') ||
+          type.startsWith('character('),
+        'text (text, varchar or char)',
+      )
+    }
+  }
+}
+
+const MYSQL_ALIASES: Record<string, string> = {
+  integer: 'int',
+  bool: 'tinyint(1)',
+  boolean: 'tinyint(1)',
+  numeric: 'decimal',
+  dec: 'decimal',
+  'double precision': 'double',
+  real: 'double',
+}
+
+/** A MySQL type the way `column_type` reports it: no display width on an integer. */
+export function normalizeMysqlType(spelled: string): string {
+  const type = spelled.trim().toLowerCase().replace(/\s+/g, ' ')
+  if (MYSQL_ALIASES[type]) return MYSQL_ALIASES[type]!
+  const { base, modifier } = splitModifier(type)
+  const name = MYSQL_ALIASES[base] ?? base
+  // `int(11)` is a display width, which MySQL 8 no longer reports: the type
+  // is `int`. `tinyint(1)` is the exception everyone relies on to mean bool.
+  if (/^(tinyint|smallint|mediumint|int|bigint)( unsigned)?$/.test(name)) {
+    return modifier === '(1)' && name === 'tinyint' ? 'tinyint(1)' : name
+  }
+  return `${name}${modifier}`
+}
+
+/** MySQL: `live.type` is `column_type`, lower-cased. */
+export function mysqlTypeProblem(
+  declared: Declared,
+  live: Live,
+): string | null {
+  const type = normalizeMysqlType(live.type)
+  const accepts = (ok: boolean, expected: string) =>
+    ok ? null : mismatch(expected, live)
+  const integer = /^(tinyint|smallint|mediumint|int)( unsigned)?$/
+
+  switch (declared.type) {
+    case 'integer':
+      return accepts(
+        integer.test(type),
+        'an integer (int, smallint, mediumint)',
+      )
+    case 'bigint':
+      return accepts(type.startsWith('bigint'), 'bigint')
+    case 'number':
+      return accepts(
+        type === 'double' || type === 'float',
+        'a float (double or float)',
+      )
+    case 'boolean':
+      return accepts(type === 'tinyint(1)', 'tinyint(1)')
+    case 'json':
+      return accepts(type === 'json', 'json')
+    case 'buffer':
+      return accepts(
+        type.endsWith('blob') || type.startsWith('varbinary'),
+        'a blob',
+      )
+    case 'sql': {
+      const want = normalizeMysqlType(declared.sqlType ?? '')
+      return accepts(sameType(want, type), want)
+    }
+    case 'string': {
+      if (declared._enum) {
+        if (type.startsWith('enum(')) {
+          const labels = [...type.matchAll(/'((?:[^']|'')*)'/g)].map(m =>
+            m[1]!.replace(/''/g, "'"),
+          )
+          return enumProblem(declared, { ...live, enumValues: labels })
+        }
+        return accepts(
+          type.endsWith('text') || type.startsWith('varchar'),
+          'an enum (enum, varchar or text)',
+        )
+      }
+      if (declared.length) {
+        return accepts(
+          type === `varchar(${declared.length})` ||
+            type === `char(${declared.length})`,
+          `varchar(${declared.length})`,
+        )
+      }
+      return accepts(
+        type.endsWith('text') ||
+          type.startsWith('varchar') ||
+          type.startsWith('char('),
+        'text (text, varchar or char)',
+      )
+    }
+  }
+}
+
+/**
+ * SQLite: `live.type` is the declared type text, which SQLite keeps but does
+ * not enforce. The rules are its type affinity rules, so a column declared
+ * `VARCHAR(10)` that holds text of any length still reads as text.
+ */
+export function sqliteTypeProblem(
+  declared: Declared,
+  live: Live,
+): string | null {
+  const type = live.type
+  const accepts = (ok: boolean, expected: string) =>
+    ok ? null : mismatch(expected, live)
+  const integer = type.includes('int')
+  const textual =
+    type.includes('char') || type.includes('clob') || type.includes('text')
+  const real =
+    type.includes('real') || type.includes('floa') || type.includes('doub')
+
+  switch (declared.type) {
+    case 'integer':
+    case 'bigint':
+      return accepts(integer, 'an integer')
+    case 'boolean':
+      return accepts(integer || type.includes('bool'), 'an integer or boolean')
+    case 'number':
+      return accepts(real || type.includes('numeric'), 'a real')
+    case 'json':
+      return accepts(type.includes('json') || textual, 'json or text')
+    case 'buffer':
+      return accepts(type === '' || type.includes('blob'), 'a blob')
+    case 'sql': {
+      const want = (declared.sqlType ?? '').trim().toLowerCase()
+      return accepts(sameType(want, type.replace(/\s+/g, ' ')), want)
+    }
+    case 'string': {
+      if (declared.length && /\(\d+\)/.test(type)) {
+        return accepts(
+          type === `varchar(${declared.length})` ||
+            type === `character varying(${declared.length})`,
+          `varchar(${declared.length})`,
+        )
+      }
+      return accepts(textual, 'text')
+    }
+  }
+}

package/src/adapters/mysql.ts

@@ -3,6 +3,22 @@ import { SQL } from 'bun'
 import { type PoolOptions, withPoolOptions } from '../pool'
 import type * as SyncTypes from '../sync/types'
 import { createExecutor, isOpenConnection, SQLAdapter } from './base'
+import { mysqlTypeProblem } from './live-types'
+import type { ScriptDialect } from '../migrate/script'
+
+/** The database's tables and views, a row per column, from `information_schema`. */
+const MYSQL_LIVE_COLUMNS = `
+  SELECT c.table_name AS table_name,
+         t.table_type AS table_type,
+         c.column_name AS column_name,
+         c.column_type AS type,
+         c.is_nullable = 'YES' AS nullable,
+         c.column_key = 'PRI' AS is_primary
+  FROM information_schema.columns c
+  JOIN information_schema.tables t
+    ON t.table_schema = c.table_schema AND t.table_name = c.table_name
+  WHERE c.table_schema = DATABASE()
+  ORDER BY c.table_name, c.ordinal_position`
 
 export class MySQLAdapter extends SQLAdapter {
   protected readonly sql: SQL
@@ -267,6 +283,65 @@ export class MySQLAdapter extends SQLAdapter {
     return false
   }
 
+  /** MySQL commits every DDL statement as it runs; a rollback cannot undo one. */
+  override get transactionalDDL(): boolean {
+    return false
+  }
+
+  override get scriptDialect(): ScriptDialect {
+    return 'mysql'
+  }
+
+  /**
+   * A named lock, held by the session. `GET_LOCK` waits up to its timeout and
+   * answers 1 when it has the lock and 0 when the wait ran out, so 0 has to be
+   * refused here rather than taken for success.
+   */
+  override async takeMigrationLock(): Promise<() => Promise<void>> {
+    const rows = (await this.sql.unsafe(
+      "SELECT GET_LOCK('bakery_migrations', 600) AS taken",
+    )) as { taken: unknown }[]
+    if (Number(rows[0]?.taken) !== 1) {
+      throw new Error(
+        'Another migration run has held the lock for 10 minutes. Wait for it to finish, then run db:migrate again.',
+      )
+    }
+    return async () => {
+      await this.sql.unsafe("SELECT RELEASE_LOCK('bakery_migrations')")
+    }
+  }
+
+  /**
+   * From `information_schema`, MySQL's only catalog. It lists what the user
+   * holds a privilege on, so a table the app's user cannot touch is reported
+   * missing, which for a query typed against it is the truth.
+   */
+  override async liveColumns(): Promise<SQLAdapter.LiveColumn[]> {
+    const rows = (await this.sql.unsafe(MYSQL_LIVE_COLUMNS)) as {
+      table_name: string
+      table_type: string
+      column_name: string
+      type: string
+      nullable: number | boolean
+      is_primary: number | boolean
+    }[]
+    return rows.map(row => ({
+      table: row.table_name,
+      column: row.column_name,
+      type: String(row.type).toLowerCase(),
+      nullable: Boolean(Number(row.nullable)),
+      primary: Boolean(Number(row.is_primary)),
+      view: row.table_type === 'VIEW',
+    }))
+  }
+
+  override columnTypeProblem(
+    declared: SyncTypes.ColumnConstraint,
+    live: SQLAdapter.LiveColumn,
+  ): string | null {
+    return mysqlTypeProblem(declared, live)
+  }
+
   protected withConnection(sql: unknown): SQLAdapter {
     return new MySQLAdapter(sql as SQL)
   }