@bakery-framework/orm 2.1.1 → 2.2.0

package/src/sessions.ts

@@ -0,0 +1,309 @@
+import type {
+  SessionListOptions,
+  SessionStore,
+  StoredSession,
+} from '@bakery-framework/core/session'
+import type { SQLAdapter } from './adapters/base'
+import { getActiveDb } from './connection'
+
+/**
+ * Sessions in the app's own database: `sessions.store` in
+ * `server.config.ts`.
+ *
+ * ```ts no-check: a config fragment
+ * import { databaseSessions } from '@bakery-framework/orm/sessions'
+ *
+ * export default {
+ *   sessions: { store: databaseSessions(), account: 'accountId' },
+ * }
+ * ```
+ *
+ * Nothing is cached between requests, so every `--threads` worker reads the
+ * same rows: a session ended in one worker is gone for the next request in
+ * all of them. The table is the app's to create, in a migration or a schema
+ * declaration (docs/guides/sessions.md has both); this never creates or
+ * alters a table, which a database role without DDL rights could not do and
+ * migrations mode would not want done behind its back.
+ *
+ * Every statement runs on the connection in use at the time, so inside
+ * `DB.transaction()` it is part of the transaction: deleting an account and
+ * `Session.endForAccount()` commit together or not at all.
+ */
+export interface DatabaseSessionsOptions {
+  /** The table the sessions live in. `bakery_sessions` unless named. */
+  table?: string
+}
+
+export function databaseSessions(
+  options: DatabaseSessionsOptions = {},
+): SessionStore {
+  return new DatabaseSessionStore(options.table ?? 'bakery_sessions')
+}
+
+/** The columns an insert writes, in the order `rowValues` gives them. */
+const COLUMNS = [
+  'id',
+  'host',
+  'account',
+  'data',
+  'persisted',
+  'created_at',
+  'accessed_at',
+  'expires_at',
+] as const
+
+type Row = {
+  id?: unknown
+  account: unknown
+  data: unknown
+  created_at: unknown
+  accessed_at: unknown
+  expires_at: unknown
+}
+
+/**
+ * A class rather than a closure over the options: it lives as long as the
+ * process, and holds the one string it needs.
+ */
+class DatabaseSessionStore implements SessionStore {
+  constructor(private readonly table: string) {}
+
+  async load(
+    host: string,
+    id: string,
+    now: number,
+  ): Promise<StoredSession | undefined> {
+    const db = getActiveDb()
+    const q = (name: string) => db.quote(name)
+    const row = (await db
+      .query(
+        `SELECT ${q('account')}, ${q('data')}, ${q('created_at')}, ${q('accessed_at')}, ${q('expires_at')} ` +
+          `FROM ${q(this.table)} WHERE ${q('id')} = ? AND ${q('host')} = ? AND ${q('expires_at')} > ?`,
+      )
+      .get(id, host, now)) as Row | null | undefined
+    return row ? decode(id, host, row) : undefined
+  }
+
+  async insert(session: StoredSession): Promise<void> {
+    const db = getActiveDb()
+    const columns = COLUMNS.map(name => db.quote(name)).join(', ')
+    await db
+      .query(
+        `INSERT INTO ${db.quote(this.table)} (${columns}) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(...rowValues(session))
+  }
+
+  async update(storedId: string, session: StoredSession): Promise<boolean> {
+    const db = getActiveDb()
+    const q = (name: string) => db.quote(name)
+    const result = await db
+      .query(
+        `UPDATE ${q(this.table)} SET ${q('id')} = ?, ${q('account')} = ?, ${q('data')} = ?, ` +
+          `${q('persisted')} = ?, ${q('accessed_at')} = ?, ${q('expires_at')} = ? ` +
+          `WHERE ${q('id')} = ? AND ${q('host')} = ?`,
+      )
+      .run(
+        session.id,
+        session.account,
+        encode(session),
+        session.persistKeys.length,
+        session.accessedAt,
+        session.expiresAt,
+        storedId,
+        session.host,
+      )
+    return (
+      Number(result.changes) > 0 ||
+      (await this.stored(db, session.host, session.id))
+    )
+  }
+
+  async touch(
+    host: string,
+    id: string,
+    accessedAt: number,
+    expiresAt: number,
+  ): Promise<boolean> {
+    const db = getActiveDb()
+    const q = (name: string) => db.quote(name)
+    const result = await db
+      .query(
+        `UPDATE ${q(this.table)} SET ${q('accessed_at')} = ?, ${q('expires_at')} = ? ` +
+          `WHERE ${q('id')} = ? AND ${q('host')} = ?`,
+      )
+      .run(accessedAt, expiresAt, id, host)
+    return Number(result.changes) > 0 || (await this.stored(db, host, id))
+  }
+
+  async remove(host: string, id: string): Promise<boolean> {
+    const db = getActiveDb()
+    const q = (name: string) => db.quote(name)
+    const result = await db
+      .query(
+        `DELETE FROM ${q(this.table)} WHERE ${q('id')} = ? AND ${q('host')} = ?`,
+      )
+      .run(id, host)
+    return Number(result.changes) > 0
+  }
+
+  async removeAccount(host: string, account: string): Promise<number> {
+    const db = getActiveDb()
+    const q = (name: string) => db.quote(name)
+    const result = await db
+      .query(
+        `DELETE FROM ${q(this.table)} WHERE ${q('account')} = ? AND ${q('host')} = ?`,
+      )
+      .run(account, host)
+    return Number(result.changes)
+  }
+
+  async count(now: number): Promise<number> {
+    const db = getActiveDb()
+    const q = (name: string) => db.quote(name)
+    const row = (await db
+      .query(
+        `SELECT COUNT(*) AS ${q('total')} FROM ${q(this.table)} WHERE ${q('expires_at')} > ?`,
+      )
+      .get(now)) as { total: unknown } | null
+    return Number(row?.total ?? 0)
+  }
+
+  async list(
+    host: string,
+    options: SessionListOptions,
+    now: number,
+  ): Promise<{ rows: StoredSession[]; totalRows: number }> {
+    const db = getActiveDb()
+    const q = (name: string) => db.quote(name)
+    const where = [`${q('host')} = ?`, `${q('expires_at')} > ?`]
+    const params: unknown[] = [host, now]
+
+    // Matched without regard to case, against the id and the stored JSON, as
+    // the built-in store's listing does; and literally, which that one does
+    // not: a search for `50%` there matches every session.
+    const needle = options.search?.trim().toLowerCase()
+    if (needle) {
+      const pattern = `%${db.escapeLike(needle)}%`
+      where.push(
+        `(LOWER(${q('id')}) LIKE ?${db.likeEscapeClause} OR LOWER(${q('data')}) LIKE ?${db.likeEscapeClause})`,
+      )
+      params.push(pattern, pattern)
+    }
+    const filter = where.join(' AND ')
+
+    const counted = (await db
+      .query(
+        `SELECT COUNT(*) AS ${q('total')} FROM ${q(this.table)} WHERE ${filter}`,
+      )
+      .get(...params)) as { total: unknown } | null
+    const totalRows = Number(counted?.total ?? 0)
+
+    // The same arithmetic as the built-in store's: a page past the end is the
+    // last page, and only DESC or ASC reaches the SQL.
+    const pageSize = Math.max(1, Math.trunc(options.pageSize))
+    const totalPages = Math.max(1, Math.ceil(totalRows / pageSize))
+    const page = Math.min(Math.max(1, Math.trunc(options.page)), totalPages)
+    const direction = options.sortOrder === 'ASC' ? 'ASC' : 'DESC'
+    const sortColumn =
+      options.sortBy === 'id'
+        ? 'id'
+        : options.sortBy === 'keys'
+          ? 'persisted'
+          : 'accessed_at'
+
+    const rows = (await db
+      .query(
+        `SELECT ${q('id')}, ${q('account')}, ${q('data')}, ${q('created_at')}, ${q('accessed_at')}, ${q('expires_at')} ` +
+          `FROM ${q(this.table)} WHERE ${filter} ` +
+          `ORDER BY ${q(sortColumn)} ${direction}, ${q('id')} ${direction} ` +
+          `LIMIT ${pageSize} OFFSET ${(page - 1) * pageSize}`,
+      )
+      .all(...params)) as Row[]
+
+    return {
+      rows: rows.map(row => decode(String(row.id), host, row)),
+      totalRows,
+    }
+  }
+
+  async prune(now: number): Promise<number> {
+    const db = getActiveDb()
+    const q = (name: string) => db.quote(name)
+    const result = await db
+      .query(`DELETE FROM ${q(this.table)} WHERE ${q('expires_at')} <= ?`)
+      .run(now)
+    return Number(result.changes)
+  }
+
+  /**
+   * Whether a session is stored, asked only after an UPDATE reported no rows.
+   *
+   * That count cannot answer it alone on MySQL, which reports the rows an
+   * UPDATE *changed*, not the rows it matched. Measured against MySQL 8.4 on
+   * Bun 1.4.2: an UPDATE writing the values a row already holds reports 0
+   * there and 1 on SQLite and Postgres. `Session.save` of an unchanged
+   * session, or a renewal in the millisecond of the last write, would
+   * otherwise read as a session ended elsewhere.
+   */
+  private async stored(
+    db: SQLAdapter,
+    host: string,
+    id: string,
+  ): Promise<boolean> {
+    const q = (name: string) => db.quote(name)
+    const row = await db
+      .query(
+        `SELECT 1 AS ${q('found')} FROM ${q(this.table)} WHERE ${q('id')} = ? AND ${q('host')} = ?`,
+      )
+      .get(id, host)
+    return Boolean(row)
+  }
+}
+
+/** What the `data` column holds: the session's data and which keys persist. */
+function encode(session: StoredSession): string {
+  return JSON.stringify({
+    data: session.data,
+    persistKeys: session.persistKeys,
+  })
+}
+
+function rowValues(session: StoredSession): unknown[] {
+  return [
+    session.id,
+    session.host,
+    session.account,
+    encode(session),
+    session.persistKeys.length,
+    session.createdAt,
+    session.accessedAt,
+    session.expiresAt,
+  ]
+}
+
+/**
+ * A row as a stored session. `BIGINT` comes back as a string from Postgres
+ * and MySQL, and a `data` column declared `json` or `jsonb` comes back
+ * already parsed, so both are taken as they come.
+ */
+function decode(id: string, host: string, row: Row): StoredSession {
+  const payload = (
+    typeof row.data === 'string' ? JSON.parse(row.data) : row.data
+  ) as { data?: unknown; persistKeys?: unknown } | null
+  const data = payload?.data
+  const persistKeys = payload?.persistKeys
+  return {
+    id,
+    host,
+    account: row.account === null ? null : String(row.account),
+    createdAt: Number(row.created_at),
+    accessedAt: Number(row.accessed_at),
+    expiresAt: Number(row.expires_at),
+    persistKeys: Array.isArray(persistKeys) ? persistKeys.map(String) : [],
+    data:
+      data && typeof data === 'object' && !Array.isArray(data)
+        ? (data as Record<string, unknown>)
+        : {},
+  }
+}

package/src/sync/index.ts

@@ -9,6 +9,7 @@ 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 { checkSchema, sqlColumnsIn } from '../migrate/check'
 import { loadSchema, schemaFromConfig } from './load'
 
 const logger = new Logger('db-sync')
@@ -28,6 +29,15 @@ const syncMsgs = {
   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}%*.',
+  CHECK_OK:
+    'I Migrations mode (%y{dir}%*): the %y{count}%* declared table(s) match the database. db:sync changes nothing here; %ybun run db:migrate%* applies the files.',
+  CHECK_NOTHING:
+    'I Migrations mode (%y{dir}%*): no tables are declared, so there is nothing to check. %ybun run db:migrate%* applies the files.',
+  CHECK_MISMATCH: 'W {problem}',
+  CHECK_DRIFT:
+    'E %r{count} mismatch(es) between the declared tables and the database%* (migrations mode, %y{dir}%*). Correct the declarations, or write a migration; db:sync changes nothing here.',
+  SQL_NEEDS_MIGRATIONS:
+    'E %rField.Sql needs migrations mode%*: {columns}. db:sync cannot create or compare a SQL type it does not know. Set %ymigrations%* in server.config.ts, or declare these columns with another Field.',
 } as const
 
 const MESSAGES = messageLogger(logger, syncMsgs)
@@ -219,13 +229,24 @@ Flags:
     MESSAGES.MIGRATE_RETIRED({ to: to.slice(cwd.length + 1) })
   }
 
-  static async run() {
+  /**
+   * Sync, or in migrations mode check. Resolves `false` when the database and
+   * the declarations disagree in a way that is reported rather than exited on
+   * (drift found by the check, or a `Field.Sql` column in classic mode): the
+   * command exits 1 on it, `bakery --sync` refuses to serve, and the dev
+   * server reports it and serves.
+   */
+  static async run(): Promise<boolean> {
     // Before initConfig/initDB/loadSchema: help must not depend on a working
     // connection, a loadable schema, or the absence of a `foreign()`.
-    if (SyncService.helpRequested()) return SyncService.printHelp()
+    if (SyncService.helpRequested()) {
+      SyncService.printHelp()
+      return true
+    }
 
     const { initConfig } = await import('@bakery-framework/core/core/config')
     const config = await initConfig()
+
     await initDB()
     // `schema` in server.config.ts when the app sets one; otherwise prefers an
     // orm/ folder and falls back to a single schema.ts.
@@ -244,6 +265,21 @@ Flags:
       return process.exit(1)
     }
 
+    // In migrations mode the SQL files are the schema, and a sync built from
+    // the declarations would drop what only the files can say: a partial
+    // index, a trigger, a CHECK beyond an enum. So the declarations are only
+    // checked against the database, from the catalog, and nothing is changed.
+    if (config.migrations) {
+      return await SyncService.check(config.migrations, constraints)
+    }
+
+    const sqlColumns = sqlColumnsIn(constraints)
+    if (sqlColumns.length) {
+      MESSAGES.SQL_NEEDS_MIGRATIONS({ columns: sqlColumns.join(', ') })
+      await closeDB()
+      return false
+    }
+
     if (loaded.unreferenceable?.length) {
       MESSAGES.FOREIGN_TARGET({ refs: loaded.unreferenceable.join(', ') })
       await closeDB()
@@ -299,10 +335,36 @@ Flags:
     }
 
     await closeDB()
+    return true
+  }
+
+  /** Migrations mode: compare the declarations with the database, report, change nothing. */
+  static async check(
+    dir: string,
+    constraints: Parameters<typeof checkSchema>[1],
+  ): Promise<boolean> {
+    try {
+      const tables = Object.keys(constraints).length
+      if (!tables) {
+        MESSAGES.CHECK_NOTHING({ dir })
+        return true
+      }
+      const mismatches = await checkSchema(connection, constraints)
+      for (const mismatch of mismatches) {
+        MESSAGES.CHECK_MISMATCH({ problem: mismatch.problem })
+      }
+      if (mismatches.length) {
+        MESSAGES.CHECK_DRIFT({ count: mismatches.length, dir })
+        return false
+      }
+      MESSAGES.CHECK_OK({ count: tables, dir })
+      return true
+    } finally {
+      await closeDB()
+    }
   }
 }
 
 if (import.meta.main) {
-  await SyncService.run()
-  process.exit(0)
+  process.exit((await SyncService.run()) ? 0 : 1)
 }

package/src/sync/ledger.ts

@@ -1,5 +1,6 @@
 import { Case } from '@bakery-framework/core/utils'
 import type { SQLAdapter } from '../adapters/base'
+import { MIGRATIONS_TABLE } from '../migrate/runner'
 import type * as SyncTypes from './types'
 
 /**
@@ -191,11 +192,16 @@ export async function writeLedger(
  * a table the schema did not declare. Which then made the shape check fail
  * forever and the ledger never get used at all.
  */
-const LEDGER_ALIASES = new Set([
-  LEDGER_TABLE,
-  Case.camel(LEDGER_TABLE),
-  Case.snake(LEDGER_TABLE),
-])
+const LEDGER_ALIASES = new Set(
+  // The migration runner's ledger too (`migrate/runner.ts`): a database that
+  // has been migrated and is then synced the classic way must not see it as a
+  // table the schema forgot to declare, and offer to drop it.
+  [LEDGER_TABLE, MIGRATIONS_TABLE].flatMap(name => [
+    name,
+    Case.camel(name),
+    Case.snake(name),
+  ]),
+)
 
 /** The ledger must never appear in a diff, or sync would try to manage itself. */
 export function stripLedger(

package/src/sync/rollback.ts

@@ -28,6 +28,8 @@ const rollbackMsgs = {
   SCHEMA_KEPT:
     'W %y--keep-schema: schema.ts still describes the newer schema.%* The next %ydb:sync%* (including the one a dev boot runs) will apply it again and undo this rollback. Revert the file yourself, or re-run without the flag.',
   DONE: 'I %gRollback complete%*.',
+  MIGRATIONS_MODE:
+    'E %rdb:rollback does not run in migrations mode%* (%y{dir}%*): it rolls back by altering and dropping toward a stored snapshot, and the migration files are the schema here. Write a migration that undoes the change.',
 } as const
 
 const MESSAGES = messageLogger(logger, rollbackMsgs)
@@ -101,6 +103,10 @@ changes, exactly as db:sync does.
     const { initConfig } = await import('@bakery-framework/core/core/config')
     const { closeDB, connection, initDB } = await import('../connection')
     const config = await initConfig()
+    if (config.migrations) {
+      MESSAGES.MIGRATIONS_MODE({ dir: config.migrations })
+      process.exit(1)
+    }
     await initDB()
 
     const entries = await readLedgerEntries(connection)

package/src/sync/types.ts

@@ -6,6 +6,8 @@ export type ColumnType =
   | 'buffer'
   | 'bigint'
   | 'json'
+  /** `Field.Sql`: the SQL type is `sqlType`, given verbatim. Migrations mode only. */
+  | 'sql'
 
 export interface ColumnConstraint {
   type: ColumnType
@@ -35,6 +37,8 @@ export interface ColumnConstraint {
    * enum's members does not migrate on its own.**
    */
   _enum?: string[]
+  /** The SQL type of a `Field.Sql` column, as its declaration spelled it. */
+  sqlType?: string
   primary?: boolean
   autoIncrement?: boolean
   nullable?: boolean