@zerotal/orm 1.6.2 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -13,6 +13,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -30,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.2",
-    "@zerotal/validator": "1.6.2"
+    "@zerotal/core": "1.7.0",
+    "@zerotal/validator": "1.7.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/commands/MigrateCommand.ts

@@ -51,6 +51,20 @@ export class MigrateCommand extends Command {
 
     const runner = new MigrationRunner({ connection: _getConnection() });
 
+    // Said before anything runs, not after something breaks. On an engine with
+    // transactional DDL a failed migration leaves nothing behind; on MySQL every
+    // DDL statement implicitly commits, so a migration that fails half way leaves
+    // the half it did — and the operator needs to know which world they are in
+    // while they still have the option of taking a backup.
+    if (!runner.willRollBackOnFailure && entries.length > 0) {
+      this.warn(
+        "This database does not support transactional DDL, so a migration that fails " +
+          "part-way will leave the statements that already succeeded in place.",
+      );
+      this.dim("  Keep migrations small, and take a backup before running them in production.");
+      this.newLine();
+    }
+
     if (fresh) {
       await runner.reset(entries);
     }

package/src/db/DB.ts

@@ -65,6 +65,31 @@ export function _getDbConnection(): SQLInstance {
   return conn;
 }
 
+/**
+ * The connection statements at this call site must run on: the enclosing
+ * transaction if there is one, otherwise the ordinary connection.
+ *
+ * `_getDbConnection()` deliberately does not do this — it answers "what is the
+ * app's connection", which is what a migration command needs when it is *opening*
+ * a transaction. This answers "where does my SQL go", which is what anything
+ * running inside one needs.
+ *
+ * The distinction is not academic. `Schema` used the first, so DDL issued inside
+ * `DB.transaction()` — including every migration, which the runner wraps —
+ * executed on a pooled connection outside the transaction and committed on its
+ * own. The wrapper was decorative, and a migration that failed half way left the
+ * half it had done behind.
+ */
+export function _getScopedDbConnection(): SQLInstance {
+  const conn =
+    TransactionContext.getStore() ??
+    (RequestContext.tryGet()?._transaction as SQLInstance | undefined) ??
+    _fromContainer();
+  if (!conn)
+    throw new Error("[Zerotal ORM] No database connection. Is DatabaseProvider registered?");
+  return conn;
+}
+
 /** Alias used by migration command helpers. */
 export function _getConnection(): SQLInstance {
   return _getDbConnection();

package/src/db/dialects/MysqlDialect.ts

@@ -8,6 +8,10 @@ export class MysqlDialect implements SqlDialect {
   readonly name = "mysql" as const;
   readonly supportsAdvisoryLocks = true;
 
+  // Every DDL statement implicitly commits, so a migration that fails part-way
+  // through cannot be undone. Stated here rather than discovered in production.
+  readonly supportsTransactionalDdl = false;
+
   hasTableSql(table: string): DialectQuery {
     return {
       sql:

package/src/db/dialects/PostgresDialect.ts

@@ -8,6 +8,9 @@ export class PostgresDialect implements SqlDialect {
   readonly name = "postgres" as const;
   readonly supportsAdvisoryLocks = true;
 
+  // Full transactional DDL: CREATE/ALTER/DROP roll back like any other statement.
+  readonly supportsTransactionalDdl = true;
+
   hasTableSql(table: string): DialectQuery {
     return {
       sql: `SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_name = ?`,

package/src/db/dialects/SqliteDialect.ts

@@ -8,6 +8,10 @@ export class SqliteDialect implements SqlDialect {
   readonly name = "sqlite" as const;
   readonly supportsAdvisoryLocks = false;
 
+  // Transactional DDL, same as PostgreSQL — the schema lives in the same b-tree
+  // as the data and is written under the same transaction.
+  readonly supportsTransactionalDdl = true;
+
   hasTableSql(table: string): DialectQuery {
     return {
       sql: `SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`,

package/src/db/dialects/types.ts

@@ -59,6 +59,23 @@ export interface SqlDialect {
   /** Whether the engine supports application-level advisory locks. */
   readonly supportsAdvisoryLocks: boolean;
 
+  /**
+   * Whether DDL participates in transactions — so a failed migration can be
+   * rolled back and leave nothing behind.
+   *
+   * PostgreSQL and SQLite: yes. `CREATE TABLE` inside a transaction is undone by
+   * `ROLLBACK` like any other statement, which is what lets the migration runner
+   * promise all-or-nothing.
+   *
+   * MySQL and MariaDB: **no**. Every DDL statement causes an implicit commit, so
+   * `BEGIN; CREATE TABLE …; ROLLBACK;` leaves the table behind — the `ROLLBACK`
+   * has nothing left to undo. (MySQL 8.0's "atomic DDL" makes each *individual*
+   * statement crash-safe; it does not put them in your transaction.) A runner
+   * that wrapped MySQL DDL in a transaction anyway would report a rollback that
+   * did not happen, which is worse than not offering one.
+   */
+  readonly supportsTransactionalDdl: boolean;
+
   /** Statement acquiring an advisory lock (blocking), or null when unsupported. */
   advisoryLockSql(key: number): DialectQuery | null;
 

package/src/observability.ts

@@ -8,7 +8,7 @@
  * observer packages — installing or removing an observer requires no change here.
  * When an observer is not installed its binding is absent and its wiring is skipped.
  */
-import { FrameworkEvents } from "@zerotal/core";
+import { FrameworkEvents, RequestContext } from "@zerotal/core";
 import type { Application } from "@zerotal/core";
 import {
   QueryExecuted,
@@ -54,6 +54,19 @@ interface DevtoolsSink {
     q: { sql: string; bindings: unknown[]; startMs: number; durationMs: number; rowCount: number },
   ): void;
   bufferWarning(ctx: object, w: { sql: string; count: number }): void;
+  channel(descriptor: {
+    id: string;
+    label: string;
+    badge?: string;
+    title?: string;
+    meta?: string[];
+    warn?: string;
+    order?: number;
+    render?: "rows" | "tree" | "table" | "kv" | "grouped";
+    groupBy?: string;
+    flags?: string[];
+  }): void;
+  record(ctx: object, channel: string, entry: Record<string, unknown>): void;
 }
 
 /** The subset of the logger this bridge calls (bound as `log`). */
@@ -164,6 +177,67 @@ export function installOrmObservability(app: Application): () => void {
         trace.bufferWarning(e.ctx, { sql: e.fingerprint.replaceAll("\x00", "?"), count: e.count });
       }),
     );
+
+    // Two more tabs, declared as data. Both were already on the bus and neither
+    // had anywhere to go: a request that wrote four rows and a request that wrote
+    // none looked identical in the panel, and a transaction that rolled back
+    // showed only as queries that appeared to succeed.
+    //
+    // Rows rather than a table for models, because the interesting thing is *how
+    // many* per model, and the table view of a three-column feed is a worse
+    // version of the same three columns.
+    trace.channel({
+      id: "models",
+      label: "Models",
+      badge: "operation",
+      title: "model",
+      meta: ["table"],
+      order: 40,
+      render: "grouped",
+      groupBy: "model",
+    });
+    trace.channel({
+      id: "tx",
+      label: "Transactions",
+      badge: "outcome",
+      title: "txId",
+      meta: ["durationMs", "reason"],
+      warn: "rolledBack",
+      order: 45,
+    });
+
+    unsubs.push(
+      FrameworkEvents.on(ModelChanged, (e) => {
+        // `ModelChanged` carries no context — it rides the model hooks, which run
+        // wherever the write did — so the request is read from the ambient scope.
+        const ctx = RequestContext.tryGet();
+        if (ctx) {
+          trace.record(ctx, "models", {
+            model: e.model,
+            table: e.table,
+            operation: e.operation,
+          });
+        }
+      }),
+      FrameworkEvents.on(TransactionCommitted, (e) => {
+        if (!e.ctx) return;
+        trace.record(e.ctx, "tx", {
+          txId: e.txId,
+          outcome: "committed",
+          durationMs: e.durationMs,
+        });
+      }),
+      FrameworkEvents.on(TransactionRolledBack, (e) => {
+        if (!e.ctx) return;
+        trace.record(e.ctx, "tx", {
+          txId: e.txId,
+          outcome: "rolled back",
+          durationMs: e.durationMs,
+          rolledBack: true,
+          ...(e.reason ? { reason: e.reason } : {}),
+        });
+      }),
+    );
   }
 
   const log = app.container.tryMake("log" as never) as LogSink | undefined;

package/src/schema/MigrationRunner.ts

@@ -7,6 +7,7 @@ import { FrameworkEvents } from "@zerotal/core";
 import { MigrationRan } from "../events.ts";
 import { dialectFor } from "../db/QueryBuilder.ts";
 import { getDialect } from "../db/dialects/index.ts";
+import { TransactionContext } from "../db/TransactionContext.ts";
 
 // ── Public types ──────────────────────────────────────────────────────────────
 
@@ -42,10 +43,36 @@ interface MigrationRow {
  *
  * Applied migrations are recorded in a tracking table (default `"migrations"`) by
  * name and batch, so re-runs skip already-applied entries and rollbacks can undo a
- * whole batch. Each `up()` runs inside its own transaction; a failure rolls that
- * migration back and surfaces as a {@link MigrationError} without affecting
- * already-committed migrations. Every run/rollback emits a `MigrationRan`
- * framework event (success or failure) for observability.
+ * whole batch. Every run/rollback emits a `MigrationRan` framework event (success
+ * or failure) for observability.
+ *
+ * ## The all-or-nothing guarantee
+ *
+ * On an engine with transactional DDL — PostgreSQL and SQLite — each migration and
+ * its tracking-table row are written in **one transaction**. A migration that
+ * throws half way leaves nothing behind: not the tables it managed to create, and
+ * not a row claiming it ran. That is what makes `zt deploy:<env>` safe to retry,
+ * because the only two states a deploy can be interrupted in are "not applied" and
+ * "applied and recorded".
+ *
+ * Three things had to be true for that to hold, and none of them were:
+ *
+ * 1. **The migration's statements must run on the transaction.** `Schema` resolved
+ *    the *global* connection, so DDL inside the runner's `begin()` executed on a
+ *    pooled connection and committed independently. The wrapper was decorative.
+ * 2. **The tracking insert must be inside it.** Recording after the commit leaves
+ *    a window where the schema has moved and the record says otherwise — the
+ *    migration runs a second time on the next deploy, against a schema it has
+ *    already changed.
+ * 3. **The engine must actually support it.** MySQL implicitly commits on DDL, so
+ *    a transaction there is a promise that cannot be kept.
+ *
+ * ## MySQL
+ *
+ * No transactional DDL, so migrations run unwrapped and a failure leaves the
+ * statements that already succeeded in place. `willRollBackOnFailure` reports
+ * this, and `zt migrate` says so before it starts rather than after it breaks.
+ * Keeping each migration small is the only mitigation the engine allows.
  *
  * @example
  * ```ts
@@ -67,6 +94,49 @@ export class MigrationRunner {
     this._table = options.table ?? "migrations";
   }
 
+  /**
+   * Whether a failed migration will be rolled back on this connection's engine.
+   *
+   * `false` on MySQL/MariaDB, where DDL implicitly commits. Callers surface this
+   * before running anything — a developer who knows a failure will leave a
+   * half-applied schema writes smaller migrations and takes a backup first.
+   */
+  get willRollBackOnFailure(): boolean {
+    return getDialect(dialectFor(this._conn)).supportsTransactionalDdl;
+  }
+
+  /**
+   * Run `work` inside a transaction, or directly when the engine cannot roll DDL
+   * back.
+   *
+   * The transaction connection is published on {@link TransactionContext}, which
+   * is what `Schema` (and anything else the migration touches) resolves through.
+   * Without that the statements run on a pooled connection and commit on their
+   * own, which is precisely the bug this method exists to close — so the ALS is
+   * not an optimisation here, it is the entire mechanism.
+   */
+  private async _atomically(work: () => Promise<void>): Promise<void> {
+    if (!this.willRollBackOnFailure) {
+      await work();
+      return;
+    }
+    await this._conn.begin(async (tx: SQLInstance) => {
+      await TransactionContext.run(tx, work);
+    });
+  }
+
+  /**
+   * The connection this runner's own statements go to: the open transaction when
+   * there is one, otherwise the connection it was constructed with.
+   *
+   * The tracking-table writes need this as much as the migration does. An INSERT
+   * that went to the pool while the DDL went to the transaction would record a
+   * migration the transaction could still roll back.
+   */
+  private _active(): SQLInstance {
+    return TransactionContext.getStore() ?? this._conn;
+  }
+
   /**
    * Run all pending migrations from the provided list.
    *
@@ -85,10 +155,13 @@ export class MigrationRunner {
     for (const entry of pendingEntries) {
       const start = performance.now();
       try {
-        // Each migration runs in its own transaction so a failure rolls back
-        // that migration's DDL without affecting already-committed ones.
-        await this._conn.begin(async () => {
+        // The migration and its tracking row in one transaction. Recording after
+        // the commit would leave a window where the schema has moved and nothing
+        // says so — and the next deploy would run this migration again, against a
+        // schema it has already changed.
+        await this._atomically(async () => {
           await entry.migration.up();
+          await this._record(entry.name, batch);
         });
       } catch (err) {
         const cause = err instanceof Error ? err : new Error(String(err));
@@ -106,7 +179,6 @@ export class MigrationRunner {
       FrameworkEvents.emit(
         new MigrationRan(entry.name, "up", Math.round(performance.now() - start), true),
       );
-      await this._record(entry.name, batch);
       executed.push(entry.name);
     }
 
@@ -151,7 +223,12 @@ export class MigrationRunner {
     for (const entry of toRollback) {
       const start = performance.now();
       try {
-        await entry.migration.down();
+        // Same guarantee in reverse: a `down()` that fails half way leaves neither
+        // a partly-undone schema nor a deleted record claiming it was undone.
+        await this._atomically(async () => {
+          await entry.migration.down();
+          await this._deleteRecord(entry.name);
+        });
       } catch (err) {
         const cause = err instanceof Error ? err : new Error(String(err));
         FrameworkEvents.emit(
@@ -168,7 +245,6 @@ export class MigrationRunner {
       FrameworkEvents.emit(
         new MigrationRan(entry.name, "down", Math.round(performance.now() - start), true),
       );
-      await this._deleteRecord(entry.name);
       rolledBack.push(entry.name);
     }
 
@@ -300,7 +376,7 @@ export class MigrationRunner {
     const tpl = Object.assign(strings, {
       raw: strings,
     }) as TemplateStringsArray;
-    await this._conn(tpl);
+    await this._active()(tpl);
   }
 
   /** SELECT with no bound parameters. */
@@ -312,14 +388,14 @@ export class MigrationRunner {
   private async _selectParam<T>(sql: string, value: unknown): Promise<T[]> {
     const parts = sql.split("?");
     const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
-    return this._conn<T>(tpl, value);
+    return this._active()<T>(tpl, value);
   }
 
   /** DML with N bound parameters. */
   private async _exec(sql: string, ...values: unknown[]): Promise<void> {
     const parts = sql.split("?");
     const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
-    await this._conn(tpl, ...values);
+    await this._active()(tpl, ...values);
   }
 
   private async _exec0<T>(sql: string): Promise<T[]> {
@@ -327,7 +403,7 @@ export class MigrationRunner {
     const tpl = Object.assign(strings, {
       raw: strings,
     }) as TemplateStringsArray;
-    return this._conn<T>(tpl);
+    return this._active()<T>(tpl);
   }
 
   private async _loadDirectory(dir: string): Promise<MigrationEntry[]> {

package/src/schema/Schema.ts

@@ -1,4 +1,4 @@
-import { _getDbConnection } from "../db/DB.ts";
+import { _getScopedDbConnection } from "../db/DB.ts";
 import { _getDialect } from "../model/BaseModel.ts";
 import { getDialect } from "../db/dialects/index.ts";
 import { Blueprint } from "./Blueprint.ts";
@@ -11,7 +11,10 @@ import { Blueprint } from "./Blueprint.ts";
  * Bun SQL tagged-template function without interpolating anything.
  */
 async function ddl(sql: string): Promise<void> {
-  const conn = _getDbConnection();
+  // Scoped, not global: DDL issued inside a transaction has to run *on* that
+  // transaction or it commits independently of it — which is what made the
+  // migration runner's `begin()` wrapper decorative.
+  const conn = _getScopedDbConnection();
   const strings = [sql];
   const tpl = Object.assign(strings, { raw: strings }) as TemplateStringsArray;
   await conn(tpl);
@@ -22,7 +25,9 @@ async function ddl(sql: string): Promise<void> {
  * We need this for parameterised introspection queries (hasTable, hasColumn).
  */
 async function query<T = Record<string, unknown>>(sql: string, params: unknown[]): Promise<T[]> {
-  const conn = _getDbConnection();
+  // Same connection as `ddl()` above: `hasTable()` inside a transaction must see
+  // the tables that transaction has created, which a pooled connection cannot.
+  const conn = _getScopedDbConnection();
   const parts = sql.split("?");
   const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
   return conn<T>(tpl, ...params);