tempest-db-js 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -45,6 +45,29 @@ var OPERATORS = [
   "between",
   "isNull"
 ];
+var Agg = class {
+  constructor(fn, column2) {
+    this.fn = fn;
+    this.column = column2;
+  }
+  fn;
+  column;
+};
+function count() {
+  return new Agg("count", "*");
+}
+function sum(column2) {
+  return new Agg("sum", column2);
+}
+function avg(column2) {
+  return new Agg("avg", column2);
+}
+function min(column2) {
+  return new Agg("min", column2);
+}
+function max(column2) {
+  return new Agg("max", column2);
+}
 var SelectBuilder = class _SelectBuilder {
   constructor(node, source) {
     this.node = node;
@@ -59,6 +82,37 @@ var SelectBuilder = class _SelectBuilder {
   where(input) {
     return this.with({ where: toCondNode(input) });
   }
+  /** Emit `SELECT DISTINCT` — drop duplicate rows. */
+  distinct() {
+    return this.with({ distinct: true });
+  }
+  /**
+   * Group by columns and compute aggregates. The result row is the grouped
+   * columns (typed from the model) plus one field per aggregate alias.
+   *
+   * @param groupBy The columns to group by (checked against the model). Pass `[]`
+   *   for a whole-table aggregate.
+   * @param spec A map of result alias → aggregate expression ({@link count},
+   *   {@link sum}, {@link avg}, {@link min}, {@link max}).
+   * @returns A builder whose row is `Pick<Full, K> & { [alias]: aggResult }`.
+   *
+   * @example
+   * ```ts
+   * select(Order).aggregate(["status"], { n: count(), total: sum("amount") });
+   * // rows: { status: string; n: number; total: number | null }[]
+   * ```
+   */
+  aggregate(groupBy, spec) {
+    const aggregates = Object.entries(spec).map(([alias, agg]) => ({
+      fn: agg.fn,
+      column: agg.column,
+      alias
+    }));
+    return new _SelectBuilder(
+      { ...this.node, aggregates, groupBy },
+      this.source
+    );
+  }
   /** Order by a column of `Full`. */
   orderBy(column2, direction = "asc") {
     return this.with({
@@ -80,6 +134,9 @@ function select(model, columns) {
       kind: "select",
       table: model.tablename,
       columns: columns ?? "*",
+      distinct: false,
+      aggregates: [],
+      groupBy: [],
       where: void 0,
       orderBy: [],
       limit: void 0,
@@ -105,6 +162,25 @@ var InsertBuilder = class _InsertBuilder {
     const list = Array.isArray(rows) ? rows : [rows];
     return this.with({ values: list });
   }
+  /**
+   * On a unique/PK conflict on `target`, do nothing (skip the row).
+   *
+   * @param target The conflicting column(s) — a unique or primary key.
+   */
+  onConflictDoNothing(target) {
+    return this.with({ onConflict: { target, update: "nothing" } });
+  }
+  /**
+   * On a unique/PK conflict on `target`, overwrite the given columns (upsert).
+   *
+   * @param target The conflicting column(s) — a unique or primary key.
+   * @param set The columns to update with new values.
+   */
+  onConflictDoUpdate(target, set) {
+    return this.with({
+      onConflict: { target, update: set }
+    });
+  }
   returning(columns) {
     return this.with({ returning: columns ?? "*" });
   }
@@ -212,7 +288,9 @@ var DIALECT_ALIASES = {
   sqlite3: "sqlite",
   postgresql: "postgresql",
   postgres: "postgresql",
-  pg: "postgresql"
+  pg: "postgresql",
+  mysql: "mysql",
+  mariadb: "mysql"
 };
 function splitScheme(scheme) {
   const plus = scheme.indexOf("+");
@@ -252,10 +330,10 @@ function parseSqlite(raw, driver, rest) {
     raw
   };
 }
-function parsePostgres(raw, driver, rest) {
+function parseNetworkUrl(raw, driver, rest, dialect) {
   let parsed;
   try {
-    parsed = new URL(`postgresql:${rest}`);
+    parsed = new URL(`${dialect}:${rest}`);
   } catch {
     throw new InvalidDatabaseUrl(raw, "could not parse host/credentials");
   }
@@ -263,7 +341,7 @@ function parsePostgres(raw, driver, rest) {
   const options = {};
   for (const [key, value] of parsed.searchParams) options[key] = value;
   return {
-    dialect: "postgresql",
+    dialect,
     driver,
     host: parsed.hostname || null,
     port: parsed.port ? Number(parsed.port) : null,
@@ -288,7 +366,8 @@ function parseDatabaseUrl(url) {
     throw new InvalidDatabaseUrl(url, `unknown dialect ${JSON.stringify(base)}`);
   }
   const rest = url.slice(schemeEnd + 1);
-  return dialect === "sqlite" ? parseSqlite(url, driver, rest) : parsePostgres(url, driver, rest);
+  if (dialect === "sqlite") return parseSqlite(url, driver, rest);
+  return parseNetworkUrl(url, driver, rest, dialect);
 }
 function detectDialect(url) {
   return parseDatabaseUrl(url).dialect;
@@ -408,12 +487,49 @@ function fromDict(model, data) {
 function parse(model, json) {
   return fromDict(model, JSON.parse(json));
 }
+function decoderForKind(kind) {
+  switch (kind) {
+    case "bigint":
+      return (v) => v == null ? null : typeof v === "bigint" ? v : BigInt(v);
+    case "date":
+    case "datetime":
+    case "timestamp":
+      return (v) => v == null ? null : v instanceof Date ? v : new Date(v);
+    case "blob":
+      return (v) => v == null ? null : v instanceof Uint8Array ? v : fromBase64(v);
+    case "json":
+      return (v) => v == null ? null : typeof v === "string" ? JSON.parse(v) : v;
+    case "numeric":
+      return (v) => v == null ? null : typeof v === "string" ? v : String(v);
+    case "boolean":
+      return (v) => v == null ? null : typeof v === "boolean" ? v : v === 1 || v === "true";
+    case "smallint":
+    case "integer":
+    case "real":
+    case "double":
+      return (v) => v == null ? null : typeof v === "number" ? v : Number(v);
+    default:
+      return null;
+  }
+}
+var decoderCache = /* @__PURE__ */ new WeakMap();
+function decodersFor(model) {
+  const cached = decoderCache.get(model);
+  if (cached) return cached;
+  const map = /* @__PURE__ */ new Map();
+  for (const [name, col] of Object.entries(columnsOf(model))) {
+    const decoder = decoderForKind(col.type.kind);
+    if (decoder) map.set(name, decoder);
+  }
+  decoderCache.set(model, map);
+  return map;
+}
 function coerceRow(model, raw) {
-  const columns = columnsOf(model);
+  const decoders = decodersFor(model);
   const out = {};
-  for (const [name, value] of Object.entries(raw)) {
-    const col = columns[name];
-    out[name] = col ? decodeValue(col, value) : value;
+  for (const name of Object.keys(raw)) {
+    const decode2 = decoders.get(name);
+    out[name] = decode2 ? decode2(raw[name]) : raw[name];
   }
   return out;
 }
@@ -438,10 +554,29 @@ var Params = class {
     return this.placeholder(this.values.length);
   }
 };
-var BaseDialect = class {
-  /** Quote an identifier (column/table) for the active dialect. */
+var BaseDialect = class _BaseDialect {
+  /**
+   * INSERT SQL templates keyed by structure (dialect|table|columns|rowCount|
+   * returning). Shared across dialect instances — the key namespaces by dialect
+   * name, and the placeholder text is dialect-specific but structure-determined.
+   */
+  static insertTemplates = /* @__PURE__ */ new Map();
+  /** Quoted-identifier cache (see {@link quoteId}). Shared across dialects. */
+  static quotedIds = /* @__PURE__ */ new Map();
+  /**
+   * Quote an identifier (column/table) for the active dialect.
+   *
+   * Memoized: identifiers form a small, stable set (column/table names), but this
+   * runs for every identifier on every compile. Caching the quoted form removes a
+   * regex-replace + string allocation from the hot path. The standard double-quote
+   * form is identical across both dialects, so one shared cache is correct.
+   */
   quoteId(name) {
-    return `"${name.replace(/"/g, '""')}"`;
+    const cached = _BaseDialect.quotedIds.get(name);
+    if (cached !== void 0) return cached;
+    const quoted = `"${name.replace(/"/g, '""')}"`;
+    _BaseDialect.quotedIds.set(name, quoted);
+    return quoted;
   }
   /** Compile any node to `{ sql, params }`. */
   compile(node) {
@@ -474,10 +609,23 @@ var BaseDialect = class {
   }
   // ---- statements -------------------------------------------------------
   compileSelect(node, params) {
-    const cols = node.columns === "*" ? "*" : node.columns.map((c) => this.quoteId(c)).join(", ");
-    let sql2 = `SELECT ${cols} FROM ${this.quoteId(node.table)}`;
+    let cols;
+    if (node.aggregates.length > 0) {
+      const groupSel = node.groupBy.map((c) => this.quoteId(c));
+      const aggSel = node.aggregates.map((a) => {
+        const inner = a.column === "*" ? "*" : this.quoteId(a.column);
+        return `${a.fn.toUpperCase()}(${inner}) AS ${this.quoteId(a.alias)}`;
+      });
+      cols = [...groupSel, ...aggSel].join(", ");
+    } else {
+      cols = node.columns === "*" ? "*" : node.columns.map((c) => this.quoteId(c)).join(", ");
+    }
+    let sql2 = `SELECT ${node.distinct ? "DISTINCT " : ""}${cols} FROM ${this.quoteId(node.table)}`;
     const where = this.compileCondition(node.where, params, (k) => this.quoteId(k));
     if (where) sql2 += ` WHERE ${where}`;
+    if (node.groupBy.length > 0) {
+      sql2 += ` GROUP BY ${node.groupBy.map((c) => this.quoteId(c)).join(", ")}`;
+    }
     if (node.orderBy.length > 0) {
       const terms = node.orderBy.map(
         (t) => `${this.quoteId(t.column)} ${t.direction === "desc" ? "DESC" : "ASC"}`
@@ -490,14 +638,58 @@ var BaseDialect = class {
   }
   compileInsert(node, params) {
     const columns = node.values.length > 0 ? Object.keys(node.values[0]) : [];
+    for (const row of node.values) {
+      for (const c of columns) params.bind(row[c] ?? null);
+    }
+    const conflictCols = node.onConflict && node.onConflict.update !== "nothing" ? Object.keys(node.onConflict.update) : [];
+    for (const c of conflictCols) {
+      params.bind((node.onConflict?.update)[c]);
+    }
+    return this.insertTemplate(node, columns, conflictCols);
+  }
+  /**
+   * The INSERT SQL template for a given structure, cached across calls.
+   *
+   * The text depends only on (dialect, table, columns, row count, returning,
+   * conflict shape) — never on the bound values — and placeholder positions are
+   * deterministic from the counts (a fresh statement always starts binding at 1).
+   * So a per-row insert loop compiles the string once and reuses it every row.
+   */
+  insertTemplate(node, columns, conflictCols) {
+    const returningKey = node.returning === null ? "" : node.returning === "*" ? "*" : node.returning.join(",");
+    const conflictKey = node.onConflict ? `${node.onConflict.target.join(",")}>${node.onConflict.update === "nothing" ? "nothing" : conflictCols.join(",")}` : "";
+    const key = `${this.name}|${node.table}|${columns.join(",")}|${node.values.length}|${returningKey}|${conflictKey}`;
+    const cached = _BaseDialect.insertTemplates.get(key);
+    if (cached !== void 0) return cached;
     const colSql = columns.map((c) => this.quoteId(c)).join(", ");
-    const rowsSql = node.values.map(
-      (row) => `(${columns.map((c) => params.bind(row[c] ?? null)).join(", ")})`
-    ).join(", ");
+    let position = 0;
+    const rowsSql = node.values.map(() => `(${columns.map(() => this.placeholder(++position)).join(", ")})`).join(", ");
     let sql2 = `INSERT INTO ${this.quoteId(node.table)} (${colSql}) VALUES ${rowsSql}`;
+    if (node.onConflict) {
+      sql2 += this.renderConflict(
+        node.onConflict,
+        conflictCols,
+        () => this.placeholder(++position)
+      );
+    }
     sql2 += this.compileReturning(node.returning);
+    _BaseDialect.insertTemplates.set(key, sql2);
     return sql2;
   }
+  /**
+   * Render the conflict-handling clause. Standard SQL (SQLite/PostgreSQL) uses
+   * `ON CONFLICT (...) DO NOTHING | DO UPDATE SET ...`; MySQL overrides this.
+   *
+   * @param onConflict The conflict clause from the node.
+   * @param conflictCols The columns to overwrite on `DO UPDATE` (empty for nothing).
+   * @param nextPlaceholder Yields the next positional placeholder (advances the count).
+   */
+  renderConflict(onConflict, conflictCols, nextPlaceholder) {
+    const target = onConflict.target.map((c) => this.quoteId(c)).join(", ");
+    if (onConflict.update === "nothing") return ` ON CONFLICT (${target}) DO NOTHING`;
+    const assignments = conflictCols.map((c) => `${this.quoteId(c)} = ${nextPlaceholder()}`).join(", ");
+    return ` ON CONFLICT (${target}) DO UPDATE SET ${assignments}`;
+  }
   compileUpdate(node, params) {
     const sets = Object.entries(node.set).map(([col, value]) => `${this.quoteId(col)} = ${params.bind(value)}`).join(", ");
     let sql2 = `UPDATE ${this.quoteId(node.table)} SET ${sets}`;
@@ -635,8 +827,46 @@ var PostgresDialect = class extends BaseDialect {
     return `${column2} ILIKE ${param}`;
   }
 };
+var mysqlQuotedIds = /* @__PURE__ */ new Map();
+var MysqlDialect = class extends BaseDialect {
+  name = "mysql";
+  placeholder() {
+    return "?";
+  }
+  ilike(column2, param) {
+    return `${column2} LIKE ${param}`;
+  }
+  quoteId(name) {
+    const cached = mysqlQuotedIds.get(name);
+    if (cached !== void 0) return cached;
+    const quoted = `\`${name.replace(/`/g, "``")}\``;
+    mysqlQuotedIds.set(name, quoted);
+    return quoted;
+  }
+  renderConflict(onConflict, conflictCols, nextPlaceholder) {
+    if (onConflict.update === "nothing") {
+      const col = this.quoteId(onConflict.target[0] ?? "id");
+      return ` ON DUPLICATE KEY UPDATE ${col} = ${col}`;
+    }
+    const assignments = conflictCols.map((c) => `${this.quoteId(c)} = ${nextPlaceholder()}`).join(", ");
+    return ` ON DUPLICATE KEY UPDATE ${assignments}`;
+  }
+  compileReturning(returning) {
+    if (returning === null) return "";
+    throw new Error(
+      "RETURNING is not supported on MySQL \u2014 insert, then SELECT by key (e.g. LAST_INSERT_ID())."
+    );
+  }
+};
 function getDialect(name) {
-  return name === "sqlite" ? new SqliteDialect() : new PostgresDialect();
+  switch (name) {
+    case "sqlite":
+      return new SqliteDialect();
+    case "postgresql":
+      return new PostgresDialect();
+    case "mysql":
+      return new MysqlDialect();
+  }
 }
 
 // src/join.ts
@@ -817,6 +1047,101 @@ var BaseRepository = class {
   }
 };
 
+// src/active-record.ts
+function primaryKeyOf2(model) {
+  for (const [name, col] of Object.entries(columnsOf(model))) {
+    if (col.flags.primaryKey) return name;
+  }
+  throw new Error(`${model.tablename} has no primary key`);
+}
+var ActiveRecord = class {
+  constructor(model, session, data) {
+    this.model = model;
+    this.session = session;
+    this.data = data;
+    this.pk = primaryKeyOf2(model);
+  }
+  model;
+  session;
+  data;
+  pk;
+  /** The primary-key value of the wrapped row. */
+  pkValue() {
+    return this.data[this.pk];
+  }
+  pkFilter() {
+    return { [this.pk]: this.pkValue() };
+  }
+  /**
+   * Persist the current `data` — insert if new, otherwise overwrite the existing
+   * row (upsert on the primary key). Refreshes `data` from the returned row.
+   *
+   * @returns This wrapper, for chaining.
+   */
+  async save() {
+    const cols = columnsOf(this.model);
+    const rowData = this.data;
+    const setPatch = {};
+    for (const c of Object.keys(rowData)) {
+      if (c !== this.pk && c in cols) setPatch[c] = rowData[c];
+    }
+    const saved = await this.session.execute(
+      insert(this.model).values(this.data).onConflictDoUpdate(
+        [this.pk],
+        setPatch
+      ).returning()
+    ).one();
+    this.data = saved;
+    return this;
+  }
+  /**
+   * Update the given columns for this row and merge them into `data`.
+   *
+   * @param patch The columns to change.
+   * @returns This wrapper, for chaining.
+   */
+  async update(patch) {
+    await this.session.execute(update(this.model).set(patch).where(this.pkFilter()));
+    this.data = { ...this.data, ...patch };
+    return this;
+  }
+  /**
+   * Delete this row.
+   *
+   * @returns The number of rows affected (0 or 1).
+   */
+  async delete() {
+    return this.session.execute(del(this.model).where(this.pkFilter())).rowsAffected();
+  }
+  /**
+   * Re-fetch this row by primary key and refresh `data`.
+   *
+   * @returns This wrapper, for chaining.
+   * @throws When the row no longer exists.
+   */
+  async reload() {
+    const fresh = await this.session.execute(select(this.model).where(this.pkFilter())).first();
+    if (fresh === null) {
+      throw new Error(
+        `${this.model.tablename} row ${JSON.stringify(this.pkValue())} not found on reload`
+      );
+    }
+    this.data = fresh;
+    return this;
+  }
+};
+function activeRecord(model, session) {
+  const pk = primaryKeyOf2(model);
+  return {
+    wrap: (row) => new ActiveRecord(model, session, row),
+    create: (data) => new ActiveRecord(model, session, data),
+    async get(id) {
+      const row = await session.execute(select(model).where({ [pk]: id })).first();
+      return row === null ? null : new ActiveRecord(model, session, row);
+    }
+  };
+}
+
 // src/relations.ts
 function hasMany(target, keys) {
   return {
@@ -879,6 +1204,14 @@ function encodeSqliteParam(value) {
 var NodeSqliteDriver = class _NodeSqliteDriver {
   // biome-ignore lint/suspicious/noExplicitAny: node:sqlite DatabaseSync has no shipped types here.
   db;
+  /**
+   * Prepared-statement cache keyed by SQL text. tempest-db-js always
+   * parameterizes, so a query shape maps to one stable SQL string — reusing the
+   * compiled statement avoids re-`prepare()` on every call (the dominant cost of
+   * per-row inserts and point lookups).
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: node:sqlite StatementSync has no shipped types here.
+  statements = /* @__PURE__ */ new Map();
   // biome-ignore lint/suspicious/noExplicitAny: accept an already-open DatabaseSync handle.
   constructor(database) {
     this.db = database;
@@ -888,8 +1221,17 @@ var NodeSqliteDriver = class _NodeSqliteDriver {
     const { DatabaseSync } = nodeRequire("node:sqlite");
     return new _NodeSqliteDriver(new DatabaseSync(path));
   }
-  execute(sql2, params) {
+  /** Return the cached prepared statement for `sql`, preparing it on first use. */
+  // biome-ignore lint/suspicious/noExplicitAny: statement type is unavailable here.
+  prepare(sql2) {
+    const cached = this.statements.get(sql2);
+    if (cached) return cached;
     const stmt = this.db.prepare(sql2);
+    this.statements.set(sql2, stmt);
+    return stmt;
+  }
+  execute(sql2, params) {
+    const stmt = this.prepare(sql2);
     const bound = params.map(encodeSqliteParam);
     if (returnsRows(sql2)) {
       return { rows: stmt.all(...bound), changes: 0 };
@@ -898,11 +1240,12 @@ var NodeSqliteDriver = class _NodeSqliteDriver {
     return { rows: [], changes: Number(info.changes ?? 0) };
   }
   *iterate(sql2, params) {
-    const stmt = this.db.prepare(sql2);
+    const stmt = this.prepare(sql2);
     const bound = params.map(encodeSqliteParam);
     yield* stmt.iterate(...bound);
   }
   close() {
+    this.statements.clear();
     this.db.close();
   }
 };
@@ -944,6 +1287,36 @@ var NoResultError = class extends Error {
     this.name = "NoResultError";
   }
 };
+function previewParam(value) {
+  if (value === null || value === void 0) return "null";
+  if (value instanceof Uint8Array) return `<${value.length} bytes>`;
+  const text = typeof value === "string" ? value : String(value);
+  return text.length > 64 ? `${text.slice(0, 61)}...` : text;
+}
+var QueryExecutionError = class extends Error {
+  constructor(cause, sql2, params) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    super(
+      `Query failed: ${reason}
+  SQL: ${sql2}
+  params: [${params.map(previewParam).join(", ")}]`
+    );
+    this.cause = cause;
+    this.sql = sql2;
+    this.params = params;
+    this.name = "QueryExecutionError";
+  }
+  cause;
+  sql;
+  params;
+};
+function emitLog(logger, sql2, params) {
+  if (!logger) return;
+  try {
+    logger({ sql: sql2, params });
+  } catch {
+  }
+}
 function firstScalar(row) {
   if (!row) return null;
   const keys = Object.keys(row);
@@ -1013,29 +1386,40 @@ var AsyncResult = class {
 };
 var savepointCounter = 0;
 var SyncSession = class {
-  constructor(driver, dialect) {
+  constructor(driver, dialect, logger) {
     this.driver = driver;
     this.dialect = dialect;
+    this.logger = logger;
   }
   driver;
   dialect;
+  logger;
+  /** Log, run, and error-wrap one raw statement. */
+  exec(sql2, params) {
+    emitLog(this.logger, sql2, params);
+    try {
+      return this.driver.execute(sql2, params);
+    } catch (error) {
+      throw new QueryExecutionError(error, sql2, params);
+    }
+  }
   /** Compile, run, and coerce a builder into a result. */
   execute(builder) {
     const node = builder.node;
     const { sql: sql2, params } = this.dialect.compile(node);
-    const result = this.driver.execute(sql2, params);
+    const result = this.exec(sql2, params);
     const rows = mapRows(builder, result.rows);
     return new SyncResult(rows, result.changes);
   }
   /** Run `fn` inside a transaction: commit on success, rollback on throw. */
   transaction(fn) {
-    this.driver.execute("BEGIN", []);
+    this.exec("BEGIN", []);
     try {
       const out = fn(this);
-      this.driver.execute("COMMIT", []);
+      this.exec("COMMIT", []);
       return out;
     } catch (error) {
-      this.driver.execute("ROLLBACK", []);
+      this.exec("ROLLBACK", []);
       throw error;
     }
   }
@@ -1043,13 +1427,13 @@ var SyncSession = class {
   beginNested(fn) {
     savepointCounter += 1;
     const name = `qsp_${savepointCounter}`;
-    this.driver.execute(`SAVEPOINT ${name}`, []);
+    this.exec(`SAVEPOINT ${name}`, []);
     try {
       const out = fn(this);
-      this.driver.execute(`RELEASE ${name}`, []);
+      this.exec(`RELEASE ${name}`, []);
       return out;
     } catch (error) {
-      this.driver.execute(`ROLLBACK TO ${name}`, []);
+      this.exec(`ROLLBACK TO ${name}`, []);
       throw error;
     }
   }
@@ -1060,31 +1444,51 @@ var SyncSession = class {
   *stream(builder) {
     const node = builder.node;
     const { sql: sql2, params } = this.dialect.compile(node);
+    emitLog(this.logger, sql2, params);
     if (this.driver.iterate) {
-      for (const raw of this.driver.iterate(sql2, params)) {
-        yield coerceOne(builder, raw);
+      try {
+        for (const raw of this.driver.iterate(sql2, params)) {
+          yield coerceOne(builder, raw);
+        }
+      } catch (error) {
+        throw new QueryExecutionError(error, sql2, params);
       }
       return;
     }
-    for (const raw of this.driver.execute(sql2, params).rows) {
+    for (const raw of this.exec(sql2, params).rows) {
       yield coerceOne(builder, raw);
     }
   }
   close() {
     this.driver.close();
   }
+  /** `using session = ...` closes the driver when the scope exits. */
+  [Symbol.dispose]() {
+    this.close();
+  }
 };
-var AsyncSession = class {
-  constructor(driver, dialect) {
+var AsyncSession = class _AsyncSession {
+  constructor(driver, dialect, logger) {
     this.driver = driver;
     this.dialect = dialect;
+    this.logger = logger;
   }
   driver;
   dialect;
+  logger;
+  /** Log, run, and error-wrap one raw statement. */
+  async exec(sql2, params) {
+    emitLog(this.logger, sql2, params);
+    try {
+      return await this.driver.execute(sql2, params);
+    } catch (error) {
+      throw new QueryExecutionError(error, sql2, params);
+    }
+  }
   execute(builder) {
     const node = builder.node;
     const { sql: sql2, params } = this.dialect.compile(node);
-    const inner = this.driver.execute(sql2, params).then((result) => {
+    const inner = this.exec(sql2, params).then((result) => {
       const rows = mapRows(builder, result.rows);
       return new SyncResult(rows, result.changes);
     });
@@ -1094,40 +1498,66 @@ var AsyncSession = class {
   async *stream(builder) {
     const node = builder.node;
     const { sql: sql2, params } = this.dialect.compile(node);
+    emitLog(this.logger, sql2, params);
     if (this.driver.iterate) {
-      for await (const raw of this.driver.iterate(sql2, params)) {
-        yield coerceOne(builder, raw);
+      try {
+        for await (const raw of this.driver.iterate(sql2, params)) {
+          yield coerceOne(builder, raw);
+        }
+      } catch (error) {
+        throw new QueryExecutionError(error, sql2, params);
       }
       return;
     }
-    const result = await this.driver.execute(sql2, params);
+    const result = await this.exec(sql2, params);
     for (const raw of result.rows) {
       yield coerceOne(builder, raw);
     }
   }
   async transaction(fn) {
-    await this.driver.execute("BEGIN", []);
+    if (this.driver.reserve) {
+      const reserved = await this.driver.reserve();
+      const scoped = new _AsyncSession(reserved, this.dialect, this.logger);
+      try {
+        await scoped.exec("BEGIN", []);
+        const out = await fn(scoped);
+        await scoped.exec("COMMIT", []);
+        return out;
+      } catch (error) {
+        await scoped.exec("ROLLBACK", []);
+        throw error;
+      } finally {
+        await reserved.release();
+      }
+    }
+    await this.exec("BEGIN", []);
     try {
       const out = await fn(this);
-      await this.driver.execute("COMMIT", []);
+      await this.exec("COMMIT", []);
       return out;
     } catch (error) {
-      await this.driver.execute("ROLLBACK", []);
+      await this.exec("ROLLBACK", []);
       throw error;
     }
   }
   async close() {
     await this.driver.close();
   }
+  /** `await using session = ...` closes the driver when the scope exits. */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
 };
 var SyncEngine = class {
-  constructor(driver) {
+  constructor(driver, logger) {
     this.driver = driver;
+    this.logger = logger;
   }
   driver;
+  logger;
   dialect = "sqlite";
   session() {
-    return new SyncSession(this.driver, getDialect("sqlite"));
+    return new SyncSession(this.driver, getDialect("sqlite"), this.logger);
   }
   transaction(fn) {
     return this.session().transaction(fn);
@@ -1135,16 +1565,22 @@ var SyncEngine = class {
   close() {
     this.driver.close();
   }
+  /** `using engine = createSyncEngine(...)` closes the pool when the scope exits. */
+  [Symbol.dispose]() {
+    this.close();
+  }
 };
 var AsyncEngine = class {
-  constructor(driver, dialect) {
+  constructor(driver, dialect, logger) {
     this.driver = driver;
     this.dialect = dialect;
+    this.logger = logger;
   }
   driver;
   dialect;
+  logger;
   session() {
-    return new AsyncSession(this.driver, getDialect(this.dialect));
+    return new AsyncSession(this.driver, getDialect(this.dialect), this.logger);
   }
   transaction(fn) {
     return this.session().transaction(fn);
@@ -1152,6 +1588,10 @@ var AsyncEngine = class {
   async close() {
     await this.driver.close();
   }
+  /** `await using engine = createEngine(...)` closes the pool when the scope exits. */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
 };
 function asAsync(driver) {
   const syncIterate = driver.iterate?.bind(driver);
@@ -1175,17 +1615,93 @@ function createSyncEngine(url, options) {
       `createSyncEngine supports only SQLite; ${parsed.dialect} is async-only \u2014 use createEngine.`
     );
   }
-  return new SyncEngine(openSqliteDriver(parsed.database ?? ":memory:"));
+  return new SyncEngine(
+    openSqliteDriver(parsed.database ?? ":memory:"),
+    options?.onQuery
+  );
 }
 function createEngine(url, options) {
   const parsed = parseDatabaseUrl(url);
   if (parsed.dialect === "sqlite") {
     return new AsyncEngine(
       asAsync(openSqliteDriver(parsed.database ?? ":memory:")),
-      "sqlite"
+      "sqlite",
+      options?.onQuery
+    );
+  }
+  if (parsed.dialect === "mysql") {
+    return new AsyncEngine(
+      createMysqlDriver(parsed.raw, options?.pool),
+      "mysql",
+      options?.onQuery
     );
   }
-  return new AsyncEngine(createPostgresDriver(parsed.raw, options?.pool), "postgresql");
+  return new AsyncEngine(
+    createPostgresDriver(parsed.raw, options?.pool),
+    "postgresql",
+    options?.onQuery
+  );
+}
+function encodeMysqlParam(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof Date) return value;
+  if (typeof value === "object") return JSON.stringify(value);
+  return value;
+}
+function toMysqlResult(rows) {
+  if (Array.isArray(rows)) {
+    return { rows, changes: 0 };
+  }
+  const header = rows;
+  return { rows: [], changes: header.affectedRows ?? 0 };
+}
+function createMysqlDriver(url, pool) {
+  let poolHandle;
+  const ensure = async () => {
+    if (poolHandle) return;
+    const moduleName = "mysql2/promise";
+    const mod = await import(
+      /* @vite-ignore */
+      moduleName
+    );
+    const opts = { uri: url };
+    if (pool?.size !== void 0) opts.connectionLimit = pool.size;
+    if (pool?.idleTimeoutMs !== void 0) opts.idleTimeout = pool.idleTimeoutMs;
+    if (pool?.connectTimeoutMs !== void 0) opts.connectTimeout = pool.connectTimeoutMs;
+    poolHandle = mod.createPool(opts);
+  };
+  const runOn = async (queryable, sql2, params) => {
+    const [rows] = await queryable.query(sql2, params.map(encodeMysqlParam));
+    return toMysqlResult(rows);
+  };
+  return {
+    async execute(sql2, params) {
+      await ensure();
+      return runOn(poolHandle, sql2, params);
+    },
+    async reserve() {
+      await ensure();
+      const conn = await poolHandle.getConnection();
+      return {
+        execute: (sql2, params) => runOn(conn, sql2, params),
+        async release() {
+          conn.release();
+        },
+        async close() {
+          conn.release();
+        }
+      };
+    },
+    async close() {
+      if (poolHandle) await poolHandle.end();
+    }
+  };
+}
+function toPostgresResult(rows) {
+  const arr = rows;
+  return { rows: Array.from(arr), changes: arr.count ?? arr.length };
 }
 function createPostgresDriver(url, pool) {
   let client;
@@ -1208,10 +1724,21 @@ function createPostgresDriver(url, pool) {
   return {
     async execute(sql2, params) {
       await ensure();
-      const rows = await client.unsafe(sql2, params);
+      return toPostgresResult(await client.unsafe(sql2, params));
+    },
+    async reserve() {
+      await ensure();
+      const conn = await client.reserve();
       return {
-        rows: Array.from(rows),
-        changes: rows.count ?? rows.length
+        async execute(sql2, params) {
+          return toPostgresResult(await conn.unsafe(sql2, params));
+        },
+        async release() {
+          conn.release();
+        },
+        async close() {
+          conn.release();
+        }
       };
     },
     async close() {
@@ -1347,7 +1874,10 @@ var column = {
 var Model = class {
   static tablename;
 };
+var columnsCache = /* @__PURE__ */ new WeakMap();
 function columnsOf(model) {
+  const cached = columnsCache.get(model);
+  if (cached) return cached;
   const instance = new model();
   const out = {};
   for (const [key, value] of Object.entries(instance)) {
@@ -1355,9 +1885,12 @@ function columnsOf(model) {
       out[key] = value;
     }
   }
+  columnsCache.set(model, out);
   return out;
 }
 
+exports.ActiveRecord = ActiveRecord;
+exports.Agg = Agg;
 exports.AsyncEngine = AsyncEngine;
 exports.AsyncResult = AsyncResult;
 exports.AsyncSession = AsyncSession;
@@ -1369,10 +1902,12 @@ exports.InsertBuilder = InsertBuilder;
 exports.InvalidDatabaseUrl = InvalidDatabaseUrl;
 exports.JoinBuilder = JoinBuilder;
 exports.Model = Model;
+exports.MysqlDialect = MysqlDialect;
 exports.NoResultError = NoResultError;
 exports.NodeSqliteDriver = NodeSqliteDriver;
 exports.OPERATORS = OPERATORS;
 exports.PostgresDialect = PostgresDialect;
+exports.QueryExecutionError = QueryExecutionError;
 exports.RecordNotFound = RecordNotFound;
 exports.SelectBuilder = SelectBuilder;
 exports.SqliteDialect = SqliteDialect;
@@ -1381,10 +1916,13 @@ exports.SyncResult = SyncResult;
 exports.SyncSession = SyncSession;
 exports.UpdateBuilder = UpdateBuilder;
 exports.ValidationError = ValidationError;
+exports.activeRecord = activeRecord;
 exports.and = and;
+exports.avg = avg;
 exports.belongsTo = belongsTo;
 exports.column = column;
 exports.columnsOf = columnsOf;
+exports.count = count;
 exports.createEngine = createEngine;
 exports.createSyncEngine = createSyncEngine;
 exports.del = del;
@@ -1396,6 +1934,8 @@ exports.insert = insert;
 exports.isCondition = isCondition;
 exports.join = join;
 exports.loadRelations = loadRelations;
+exports.max = max;
+exports.min = min;
 exports.not = not;
 exports.or = or;
 exports.parse = parse;
@@ -1403,6 +1943,7 @@ exports.parseDatabaseUrl = parseDatabaseUrl;
 exports.select = select;
 exports.sql = sql;
 exports.stringify = stringify;
+exports.sum = sum;
 exports.toCondNode = toCondNode;
 exports.toDict = toDict;
 exports.toJSON = toJSON;