dbt-js 0.1.1

package/src/batches.js

@@ -0,0 +1,120 @@
+// Batch window computation for the microbatch incremental strategy.
+// Date math aligns to a configurable IANA timezone (default 'UTC') — windows
+// snap to that zone's wall-clock boundaries. No DB access, no SQL dialect concerns.
+
+const UNITS = ['hour', 'day', 'month', 'year'];
+
+// Wall-clock components of an instant as seen in `tz`: { year, month(1-12),
+// day, hour, minute, second }. Built on Intl so it tracks DST automatically.
+function partsInZone(date, tz) {
+  const dtf = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    hourCycle: 'h23',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+  const p = {};
+  for (const part of dtf.formatToParts(date)) {
+    if (part.type !== 'literal') p[part.type] = Number(part.value);
+  }
+  if (p.hour === 24) p.hour = 0; // some engines emit 24 for midnight under h23
+  return p;
+}
+
+// The UTC instant for a wall-clock time interpreted in `tz`, DST-correct via an
+// offset back-solve (one correction pass resolves spring-forward/fall-back).
+function zonedWallToUtc({ year, month, day, hour, minute, second }, tz) {
+  const offsetAt = (ms) => {
+    const p = partsInZone(new Date(ms), tz);
+    return Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second) - ms;
+  };
+  const naive = Date.UTC(year, month - 1, day, hour, minute, second);
+  let utc = naive - offsetAt(naive);
+  utc = naive - offsetAt(utc);
+  return new Date(utc);
+}
+
+// Parse a date string into a UTC instant. A string carrying an explicit zone
+// (Z or ±HH:MM) is an absolute instant; a naive 'YYYY-MM-DD[ HH:MM[:SS]]' is
+// interpreted as wall-clock in `tz`.
+export function parseInZone(s, tz = 'UTC') {
+  const iso = String(s).trim().replace(' ', 'T');
+  if (/(?:[zZ]|[+-]\d{2}:?\d{2})$/.test(iso)) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime())) throw new Error(`Invalid date '${s}' (use YYYY-MM-DD or ISO 8601)`);
+    return d;
+  }
+  const m = iso.match(/^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?)?$/);
+  if (!m) throw new Error(`Invalid date '${s}' (use YYYY-MM-DD or ISO 8601)`);
+  return zonedWallToUtc(
+    { year: +m[1], month: +m[2], day: +m[3], hour: +(m[4] || 0), minute: +(m[5] || 0), second: +(m[6] || 0) },
+    tz
+  );
+}
+
+// Back-compat alias — parsing in UTC.
+export const parseUtc = (s) => parseInZone(s, 'UTC');
+
+function truncTz(date, size, tz) {
+  const p = partsInZone(date, tz);
+  p.second = 0;
+  p.minute = 0;
+  if (size !== 'hour') p.hour = 0;
+  if (size === 'month' || size === 'year') p.day = 1;
+  if (size === 'year') p.month = 1;
+  return zonedWallToUtc(p, tz);
+}
+
+function addBatchesTz(date, size, n, tz) {
+  const p = partsInZone(date, tz);
+  if (size === 'hour') p.hour += n;
+  else if (size === 'day') p.day += n;
+  else if (size === 'month') p.month += n;
+  else p.year += n;
+  return zonedWallToUtc(p, tz); // Date.UTC normalizes overflow (day 32, month 13, ...)
+}
+
+function fmtTz(date, tz) {
+  const p = partsInZone(date, tz);
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${p.year}-${pad(p.month)}-${pad(p.day)} ${pad(p.hour)}:${pad(p.minute)}:${pad(p.second)}`;
+}
+
+// Returns [{ start, end }] of aligned [start, end) windows as 'YYYY-MM-DD HH:MM:SS'.
+//   first build / --full-refresh : trunc(begin) .. current batch end
+//   normal run                   : trunc(now) - lookback .. current batch end
+//   explicit backfill            : trunc(start) .. ceil(end)  (whole batches)
+// The window never starts before `begin`.
+export function computeBatches({ begin, batchSize, lookback = 1, start, end, firstBuild, timezone = 'UTC', now = new Date() }) {
+  if (!UNITS.includes(batchSize)) throw new Error(`Invalid batch_size '${batchSize}' (use ${UNITS.join('|')})`);
+  const beginAt = truncTz(parseInZone(begin, timezone), batchSize, timezone);
+
+  let endAt;
+  if (end) {
+    const e = parseInZone(end, timezone);
+    const t = truncTz(e, batchSize, timezone);
+    endAt = e.getTime() === t.getTime() ? t : addBatchesTz(t, batchSize, 1, timezone);
+  } else {
+    endAt = addBatchesTz(truncTz(now, batchSize, timezone), batchSize, 1, timezone);
+  }
+
+  let startAt;
+  if (start) startAt = truncTz(parseInZone(start, timezone), batchSize, timezone);
+  else if (firstBuild) startAt = beginAt;
+  else startAt = addBatchesTz(truncTz(now, batchSize, timezone), batchSize, -lookback, timezone);
+  if (startAt < beginAt) startAt = beginAt;
+
+  if (start && startAt >= endAt) {
+    throw new Error(`--event-time-start (${fmtTz(startAt, timezone)}) must be before the end of the window (${fmtTz(endAt, timezone)})`);
+  }
+
+  const batches = [];
+  for (let t = startAt; t < endAt; t = addBatchesTz(t, batchSize, 1, timezone)) {
+    batches.push({ start: fmtTz(t, timezone), end: fmtTz(addBatchesTz(t, batchSize, 1, timezone), timezone) });
+  }
+  return batches;
+}

package/src/cli.js

@@ -0,0 +1,175 @@
+// Thin CLI over src/api.js: parse flags, format events as log lines, map
+// result.ok to the exit code. All orchestration lives in the api.
+import { parseArgs } from 'node:util';
+import * as api from './api.js';
+
+const USAGE = `Usage: dbt-js <command> [options]
+
+Commands:
+  run      Build models in dependency order
+  test     Run data tests (not_null, unique, accepted_values)
+  seed     Load seeds/*.csv into the target schema
+  compile  Print compiled SQL without executing (is_incremental() = false)
+  ls       List nodes in execution order
+  debug    Check config and database connectivity
+
+Options:
+  --select SPEC          Comma-separated nodes; +name includes upstream, name+ downstream
+  --full-refresh         Rebuild incremental models from scratch (run only)
+  --vars JSON            Override project vars, e.g. --vars '{"start":"2026-06-01"}'
+  --event-time-start TS  Backfill microbatch models from this time (run only)
+  --event-time-end TS    End of the backfill window (requires --event-time-start)`;
+
+export async function main(argv = process.argv.slice(2)) {
+  let values, command;
+  try {
+    const parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        select: { type: 'string' },
+        'full-refresh': { type: 'boolean', default: false },
+        vars: { type: 'string' },
+        'event-time-start': { type: 'string' },
+        'event-time-end': { type: 'string' },
+        help: { type: 'boolean', default: false },
+      },
+    });
+    values = parsed.values;
+    command = parsed.positionals[0];
+  } catch (e) {
+    console.error(`Error: ${e.message}\n\n${USAGE}`);
+    process.exit(2);
+  }
+
+  if (!command || values.help) {
+    console.log(USAGE);
+    process.exit(command ? 0 : 2);
+  }
+
+  const commands = { run, test, seed, compile, ls, debug };
+  if (!commands[command]) {
+    console.error(`Error: unknown command '${command}'\n\n${USAGE}`);
+    process.exit(2);
+  }
+
+  try {
+    const ok = await commands[command](values);
+    process.exit(ok ? 0 : 1);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+const pad = (s, n) => String(s).padEnd(n);
+
+function baseOpts(values) {
+  const opts = { select: values.select };
+  if (values.vars) {
+    try {
+      opts.vars = JSON.parse(values.vars);
+    } catch {
+      throw new Error(`--vars must be valid JSON, got: ${values.vars}`);
+    }
+  }
+  return opts;
+}
+
+function printModelEvent(e) {
+  if (e.type === 'batch') {
+    const detail = e.ok ? (e.rowCount != null ? `${e.rowCount} rows` : 'ok') : e.message;
+    console.log(`      batch ${e.start} .. ${e.end}  ${e.ok ? 'OK' : 'FAIL'} (${detail})`);
+    return;
+  }
+  const tag = `[${e.index}/${e.total}]`;
+  if (e.status === 'skip') {
+    console.log(`${tag} ${pad('SKIP', 5)} ${pad(e.materialized, 12)} ${e.name} (upstream failed)`);
+  } else if (e.status === 'fail' && e.failedBatches?.length) {
+    const f = e.failedBatches;
+    console.log(
+      `${tag} ${pad('FAIL', 5)} ${pad(e.action, 12)} ${e.name} — ${e.error}; ` +
+      `retry with --select ${e.name} --event-time-start "${f[0].start}" --event-time-end "${f[f.length - 1].end}"`
+    );
+  } else if (e.status === 'fail') {
+    console.log(`${tag} ${pad('FAIL', 5)} ${pad(e.materialized, 12)} ${e.name} — ${e.error}`);
+  } else {
+    const rows = e.rowCount != null ? `, ${e.rowCount} rows` : '';
+    const batches = e.batchCount != null ? `, ${e.batchCount} batches` : '';
+    console.log(`${tag} ${pad('OK', 5)} ${pad(e.action, 12)} ${e.name} (${e.durationMs}ms${rows}${batches})`);
+  }
+}
+
+async function run(values) {
+  if (values['event-time-end'] && !values['event-time-start']) {
+    throw new Error('--event-time-end requires --event-time-start');
+  }
+  const result = await api.run({
+    ...baseOpts(values),
+    fullRefresh: values['full-refresh'],
+    eventTimeStart: values['event-time-start'],
+    eventTimeEnd: values['event-time-end'],
+    onEvent: printModelEvent,
+  });
+  const counts = { ok: 0, fail: 0, skip: 0 };
+  for (const m of result.models) counts[m.status]++;
+  console.log(`\nDone: ${counts.ok} ok, ${counts.fail} failed, ${counts.skip} skipped`);
+  return result.ok;
+}
+
+async function test(values) {
+  const result = await api.test({
+    ...baseOpts(values),
+    onEvent: (e) => {
+      if (e.pass) {
+        console.log(`PASS ${e.id}`);
+      } else {
+        console.log(`FAIL ${e.id} (${e.violations} violating rows)`);
+        for (const row of e.sample) console.log(`     ${JSON.stringify(row)}`);
+      }
+    },
+  });
+  if (!result.tests.length) {
+    console.log('No tests defined.');
+    return true;
+  }
+  const failures = result.tests.filter((t) => !t.pass).length;
+  console.log(`\nDone: ${result.tests.length - failures} passed, ${failures} failed`);
+  return result.ok;
+}
+
+async function seed(values) {
+  const result = await api.seed({
+    select: values.select,
+    onEvent: (e) =>
+      console.log(`[${e.index}/${e.total}] ${pad('OK', 5)} ${pad('seed', 12)} ${e.name} (${e.durationMs}ms, ${e.rowCount} rows)`),
+  });
+  return result.ok;
+}
+
+async function compile(values) {
+  for (const m of await api.compile(baseOpts(values))) {
+    console.log(`-- model: ${m.name} (${m.materialized})`);
+    m.preHookSql.forEach((sql, i) => console.log(`-- pre_hook[${i}]:\n${sql}`));
+    console.log(m.sql);
+    m.postHookSql.forEach((sql, i) => console.log(`-- post_hook[${i}]:\n${sql}`));
+    console.log('');
+  }
+  return true;
+}
+
+async function ls() {
+  for (const n of await api.ls()) {
+    const deps = n.deps.length ? `  <- ${n.deps.join(', ')}` : '';
+    console.log(`${pad(n.kind, 12)} ${n.name}${deps}`);
+  }
+  return true;
+}
+
+async function debug() {
+  const d = await api.debug();
+  console.log(`config:  OK (schema "${d.schema}", ${d.modelCount} models, ${d.seedCount} seeds)`);
+  console.log(`target:  ${d.target}`);
+  console.log(`connect: OK (${d.database}, ${d.version.split(' on ')[0]})`);
+  return true;
+}

package/src/config.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export function loadConfig(cwd = process.cwd()) {
+  const path = join(cwd, 'dbtjs.config.json');
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    throw new Error(`No dbtjs.config.json found in ${cwd}`);
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Invalid JSON in ${path}: ${e.message}`);
+  }
+  return validateConfig(cfg, cwd);
+}
+
+// Shared by the file path above and inline `config` objects passed to the api.
+// Mutates and returns cfg (defaults, env interpolation, duckdb path resolution).
+export function validateConfig(cfg, cwd = process.cwd()) {
+  if (!cfg.connection || typeof cfg.connection !== 'object') {
+    throw new Error('config must have a "connection" object');
+  }
+  cfg.connection.type ??= 'postgres';
+  if (!['postgres', 'duckdb', 'mysql', 'sqlite'].includes(cfg.connection.type)) {
+    throw new Error(
+      `connection.type must be "postgres", "duckdb", "mysql" or "sqlite", got "${cfg.connection.type}"`
+    );
+  }
+  if (['duckdb', 'sqlite'].includes(cfg.connection.type) && typeof cfg.connection.path !== 'string') {
+    throw new Error(
+      `${cfg.connection.type} connection requires a "path" string (file path or ":memory:")`
+    );
+  }
+  if (cfg.connection.type === 'mysql') {
+    if (typeof cfg.connection.database !== 'string') {
+      throw new Error('mysql connection requires a "database" string');
+    }
+    cfg.connection.port ??= 3306;
+  }
+  if (!cfg.schema || typeof cfg.schema !== 'string') {
+    throw new Error('config must have a "schema" string (target schema for models)');
+  }
+  for (const [key, value] of Object.entries(cfg.connection)) {
+    if (typeof value === 'string') cfg.connection[key] = interpolateEnv(value, key);
+  }
+  if (['duckdb', 'sqlite'].includes(cfg.connection.type) && cfg.connection.path !== ':memory:') {
+    // anchor to the project dir so embedding apps can run from any cwd
+    cfg.connection.path = resolve(cwd, cfg.connection.path);
+  }
+  cfg.vars ??= {};
+  cfg.sources ??= {};
+  cfg.seeds ??= {};
+  return cfg;
+}
+
+function interpolateEnv(value, key) {
+  return value.replace(/\$\{(\w+)\}/g, (_, name) => {
+    const v = process.env[name];
+    if (v === undefined) {
+      throw new Error(`connection.${key} references \${${name}} but that environment variable is not set`);
+    }
+    return v;
+  });
+}

package/src/dag.js

@@ -0,0 +1,67 @@
+import { extractRefs } from './render.js';
+
+// Returns { nodes: Map<name, node>, order: string[] } — dependencies before dependents.
+// Seeds are DAG nodes with no deps so ref('seed_name') resolves and orders correctly;
+// `run` does not load them (that's the seed command's job, like dbt).
+export function buildDag(models, seeds) {
+  const nodes = new Map();
+  for (const seed of seeds) nodes.set(seed.name, { ...seed, type: 'seed', deps: [] });
+  for (const model of models) {
+    nodes.set(model.name, { ...model, type: 'model', deps: [...new Set(extractRefs(model.rawSql))] });
+  }
+  return { nodes, order: topoSort(nodes) };
+}
+
+export function topoSort(nodes) {
+  const order = [];
+  const state = new Map(); // 0/undefined = unvisited, 1 = in stack, 2 = done
+  function visit(name, path) {
+    if (state.get(name) === 2) return;
+    if (state.get(name) === 1) {
+      throw new Error(`Cycle detected: ${[...path, name].join(' -> ')}`);
+    }
+    if (!nodes.has(name)) {
+      throw new Error(`'${path.at(-1)}' refs unknown model/seed '${name}'`);
+    }
+    state.set(name, 1);
+    for (const dep of nodes.get(name).deps) visit(dep, [...path, name]);
+    state.set(name, 2);
+    order.push(name);
+  }
+  for (const name of nodes.keys()) visit(name, []);
+  return order;
+}
+
+// spec: "a,b" | "+name" (name + upstream) | "name+" (name + downstream); null = everything.
+export function expandSelection(spec, nodes, order) {
+  if (!spec) return order;
+  const reversed = new Map([...nodes.keys()].map((k) => [k, []]));
+  for (const [name, node] of nodes) {
+    for (const dep of node.deps) reversed.get(dep)?.push(name);
+  }
+  const selected = new Set();
+  for (const token of spec.split(',').map((s) => s.trim()).filter(Boolean)) {
+    const upstream = token.startsWith('+');
+    const downstream = token.endsWith('+');
+    const name = token.replace(/^\+/, '').replace(/\+$/, '');
+    if (!nodes.has(name)) throw new Error(`--select: unknown model/seed '${name}'`);
+    selected.add(name);
+    if (upstream) for (const n of walk(name, (x) => nodes.get(x).deps)) selected.add(n);
+    if (downstream) for (const n of walk(name, (x) => reversed.get(x))) selected.add(n);
+  }
+  return order.filter((n) => selected.has(n));
+}
+
+function walk(start, next) {
+  const found = new Set();
+  const queue = [start];
+  while (queue.length) {
+    for (const n of next(queue.shift())) {
+      if (!found.has(n)) {
+        found.add(n);
+        queue.push(n);
+      }
+    }
+  }
+  return found;
+}

package/src/db.js

@@ -0,0 +1,182 @@
+// All database access lives here. connect() dispatches on connection.type and
+// returns a uniform client: { query(sql, params) -> { rows, rowCount }, end() }.
+// Drivers are imported lazily so each backend only loads its own.
+
+export async function connect(connection, { projectDir, readOnly = false, schema } = {}) {
+  const { type = 'postgres', ...rest } = connection;
+  return type === 'duckdb'
+    ? connectDuckdb(rest.path, projectDir, readOnly)
+    : type === 'mysql'
+      ? connectMysql(rest, readOnly)
+      : type === 'sqlite'
+        ? connectSqlite(rest, schema, readOnly)
+        : connectPg(rest, readOnly);
+}
+
+async function connectPg(connection, readOnly = false) {
+  const { default: pg } = await import('pg');
+  const client = new pg.Client(connection);
+  await client.connect();
+  // Session-level read-only also applies inside data-modifying CTEs,
+  // which a statement-keyword check can't catch.
+  if (readOnly) await client.query('SET default_transaction_read_only = on');
+  return {
+    dialect: 'postgres',
+    async query(sql, params) {
+      const res = await client.query(sql, params);
+      return { rows: res.rows, rowCount: res.rowCount ?? undefined };
+    },
+    end: () => client.end(),
+  };
+}
+
+async function connectMysql(connection, readOnly = false) {
+  const { default: mysql } = await import('mysql2/promise');
+  const conn = await mysql.createConnection({
+    dateStrings: true, // JSON-safe rows, matching the duckdb adapter
+    ...connection,
+    multipleStatements: false,
+  });
+  // render.js emits "schema"."name" with no dialect knowledge; ANSI_QUOTES
+  // makes double-quoted identifiers valid for the whole session.
+  await conn.query(`SET SESSION sql_mode = CONCAT_WS(',', NULLIF(@@sql_mode, ''), 'ANSI_QUOTES')`);
+  if (readOnly) await conn.query('SET SESSION transaction_read_only = 1');
+  return {
+    dialect: 'mysql',
+    async query(sql, params) {
+      const q = toQmarks(sql, params);
+      const [res] = await conn.query(q.sql, q.params); // rows[] or ResultSetHeader
+      return Array.isArray(res)
+        ? { rows: res, rowCount: res.length }
+        : { rows: [], rowCount: res.affectedRows ?? undefined }; // DML/DDL; CTAS reports inserted rows
+    },
+    end: () => conn.end(),
+  };
+}
+
+async function connectSqlite(connection, schema, readOnly = false) {
+  // Synchronous driver; long statements block the event loop (fine for CLI use,
+  // worth knowing when embedding).
+  const { default: Database } = await import('better-sqlite3');
+  const db = new Database(connection.path, readOnly ? { readonly: true } : {});
+  // cfg.schema 'main'/'temp' are SQLite's built-in schemas (single-file mode).
+  // Anything else lives in '<schema>.db' beside the main file, ATTACHed for the
+  // whole session so "schema"."name" from render.js resolves. ATTACH inherits
+  // the connection's readonly flag and can't create files read-only, so a
+  // missing file is skipped there (queries then fail with "no such table").
+  if (schema && schema !== 'main' && schema !== 'temp') {
+    const { join, dirname } = await import('node:path');
+    const { existsSync } = await import('node:fs');
+    const path =
+      connection.path === ':memory:' ? ':memory:' : join(dirname(connection.path), `${schema}.db`);
+    if (!readOnly || path === ':memory:' || existsSync(path)) {
+      db.prepare(`ATTACH DATABASE ? AS ${quoteIdent(schema)}`).run(path);
+    }
+  }
+  return {
+    dialect: 'sqlite',
+    async query(sql, params) {
+      const q = toQmarks(sql, params);
+      const stmt = db.prepare(q.sql); // rejects multi-statement strings, like mysql's multipleStatements:false
+      if (stmt.reader) {
+        const rows = stmt.all(...(q.params ?? []));
+        return { rows, rowCount: rows.length };
+      }
+      const info = stmt.run(...(q.params ?? []));
+      // sqlite3_changes is only updated by INSERT/UPDATE/DELETE; after DDL/CTAS
+      // it still holds the previous DML's count, so report undefined instead
+      const dml = /^\s*(insert|update|delete)\b/i.test(q.sql);
+      return { rows: [], rowCount: dml ? info.changes : undefined };
+    },
+    end: async () => db.close(),
+  };
+}
+
+// Internal queries (seeds, tests, relationKind) use Postgres-style $N
+// placeholders; model SQL never carries params, so user SQL is never rewritten.
+function toQmarks(sql, params) {
+  if (!params?.length) return { sql, params: undefined };
+  const ordered = [];
+  const out = sql.replace(/\$(\d+)/g, (_, n) => {
+    ordered.push(params[n - 1]);
+    return '?';
+  });
+  return { sql: out, params: ordered };
+}
+
+async function connectDuckdb(path, projectDir, readOnly = false) {
+  const { DuckDBInstance, ResultReturnType } = await import('@duckdb/node-api');
+  const instance = await DuckDBInstance.create(path, readOnly ? { access_mode: 'READ_ONLY' } : undefined);
+  const conn = await instance.connect();
+  if (projectDir) {
+    // resolve read_csv('data/...') etc. against the project dir, not the app's cwd
+    await conn.run(`SET file_search_path = '${projectDir.replace(/'/g, "''")}'`);
+  }
+  return {
+    dialect: 'duckdb',
+    async query(sql, params) {
+      const result = await conn.run(sql, params?.length ? params : undefined);
+      // Json variant returns BIGINT as string and dates as ISO strings —
+      // safe for JSON.stringify and Number() alike.
+      const rows = await result.getRowObjectsJson();
+      const rowCount =
+        result.returnType === ResultReturnType.CHANGED_ROWS ? result.rowsChanged
+        : result.returnType === ResultReturnType.QUERY_RESULT ? rows.length
+        : undefined; // DDL/CTAS: DuckDB doesn't report counts
+      return { rows, rowCount };
+    },
+    async end() {
+      conn.disconnectSync();
+      instance.closeSync(); // checkpoints WAL, releases the file lock
+    },
+  };
+}
+
+export const quoteIdent = (s) => `"${String(s).replace(/"/g, '""')}"`;
+export const rel = (schema, name) => `${quoteIdent(schema)}.${quoteIdent(name)}`;
+
+export async function ensureSchema(client, schema) {
+  // SQLite: CREATE SCHEMA doesn't exist; the schema was ATTACHed at connect
+  // time (which creates the file when writable), so it's already ensured.
+  if (client.dialect === 'sqlite') return;
+  await client.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`);
+}
+
+// 'r' = table, 'v' = view, null = absent. information_schema works on all
+// backends; the catalog predicate keeps DuckDB's temp catalog (schema "main")
+// from colliding when the target schema is also "main". MySQL has no catalog
+// (table_catalog is always 'def'; schema == database) so it skips the predicate.
+// The alias forces a lowercase key — MySQL returns information_schema columns
+// uppercase (TABLE_TYPE).
+export async function relationKind(client, schema, name) {
+  if (client.dialect === 'sqlite') {
+    // no information_schema; pragma_table_list covers main + attached schemas
+    const { rows } = await client.query(
+      'SELECT type FROM pragma_table_list WHERE schema = $1 AND name = $2',
+      [schema, name]
+    );
+    const t = rows[0]?.type; // lowercase 'table'/'view' (also 'shadow'/'virtual')
+    return t === 'table' ? 'r' : t === 'view' ? 'v' : null;
+  }
+  const catalogPredicate =
+    client.dialect === 'mysql' ? '' : 'table_catalog = current_database() AND ';
+  const { rows } = await client.query(
+    `SELECT table_type AS table_type FROM information_schema.tables
+     WHERE ${catalogPredicate}table_schema = $1 AND table_name = $2`,
+    [schema, name]
+  );
+  const t = rows[0]?.table_type;
+  return t === 'BASE TABLE' ? 'r' : t === 'VIEW' ? 'v' : null;
+}
+
+export async function withTransaction(client, fn) {
+  await client.query('BEGIN');
+  try {
+    const result = await fn();
+    await client.query('COMMIT');
+    return result;
+  } catch (e) {
+    await client.query('ROLLBACK');
+    throw e;
+  }
+}