@agent-native/core 0.85.6 → 0.86.0

package/dist/db/ensure-additive-columns.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Boot-time convergence for columns Drizzle's schema declares but a
+ * pre-existing table is missing.
+ *
+ * Lives in its own module (like `./widen-columns.js`) so stores/plugins can
+ * import it without every `vi.mock("../db/client.js")` test needing to stub
+ * it: the helper resolves `isPostgres()` / `getDbExec()` through `client.js`,
+ * so a test that mocks the client to SQLite makes the Postgres introspection
+ * path a no-op automatically.
+ *
+ * ## Why
+ *
+ * `CREATE TABLE IF NOT EXISTS` only runs the CREATE the first time a table is
+ * created — once it exists, adding a column to the Drizzle schema (e.g.
+ * `schema.ts`) does nothing to already-existing rows unless a hand-written
+ * `ALTER TABLE ... ADD COLUMN` migration ships alongside it. Fresh dev
+ * databases mask this because the CREATE always includes every declared
+ * column; only long-lived, pre-existing production tables are missing the
+ * new column. Forgetting the migration turns every query that references the
+ * column into a Postgres `42703 (undefined_column)` — e.g.
+ * `session_recordings.network_error_count`, which 500'd every
+ * `list-session-recordings` call.
+ *
+ * `ensureAdditiveColumns()` is belt-and-braces for that failure mode: after
+ * the authoritative hand-written migrations run, diff each Drizzle table's
+ * declared columns against the live table and additively patch any gap. It
+ * is NOT a replacement for migrations — it never touches indexes, data
+ * transforms, or existing columns, and a hand-written migration should still
+ * ship for every schema change. This is a safety net for the case where one
+ * doesn't.
+ *
+ * ## Safety rules (hard)
+ *
+ * - Additive only: never drops, renames, retypes, or otherwise touches a
+ *   column that already exists on the live table.
+ * - A `NOT NULL` column is only ever added when it has a renderable default
+ *   (so existing rows get a valid value in the same statement). If it has no
+ *   renderable default, it is added as nullable when the Drizzle declaration
+ *   allows null, else the column is SKIPPED entirely with a loud log line
+ *   naming the column and the reason.
+ * - Only simple literal defaults are rendered: numbers, strings, booleans,
+ *   and `sql` template defaults that stringify to one of a small allow-listed
+ *   set of safe constants (see `renderDefaultLiteral`). Any other `sql`
+ *   default is NOT rendered — the column is added without a `DEFAULT` (and
+ *   without `NOT NULL`, per the rule above) rather than risk interpolating
+ *   unsafe SQL.
+ * - All identifiers (table/column names) are validated against a strict
+ *   `[A-Za-z_][A-Za-z0-9_]*` pattern and double-quoted; no value from a row or
+ *   from user data is ever interpolated into the generated SQL.
+ * - If the table itself does not exist yet, this is a no-op — table creation
+ *   owns bringing every declared column into existence for a brand-new table.
+ * - Idempotent and best-effort: a failure on one column is logged and does
+ *   not abort the rest, and a total failure (e.g. `information_schema`
+ *   unreadable) must never crash boot — the caller decides whether/how to
+ *   surface `errors` in the returned summary.
+ */
+import { type DbExec } from "./client.js";
+export interface EnsureAdditiveColumnsLogger {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+export interface EnsureAdditiveColumnsOptions {
+    db: DbExec;
+    /** Drizzle table objects (from `pgTable`/`sqliteTable`, or the dialect-agnostic `table()` helper). */
+    tables: unknown[];
+    logger?: EnsureAdditiveColumnsLogger;
+}
+export interface EnsureAdditiveColumnsResult {
+    /** `"table.column"` entries that were successfully added. */
+    applied: string[];
+    /** Declared columns that were intentionally left unpatched, with why. */
+    skipped: Array<{
+        column: string;
+        reason: string;
+    }>;
+    /** `"table.column"` entries whose ALTER failed unexpectedly (logged, non-fatal). */
+    errors: Array<{
+        column: string;
+        error: string;
+    }>;
+}
+/**
+ * Diff each declared Drizzle table's columns against the live database and
+ * additively `ALTER TABLE ... ADD COLUMN` any that are missing. See the
+ * module docstring for the full safety-rule contract.
+ *
+ * Call this once at boot, immediately after the authoritative hand-written
+ * migrations have run. Never throws — every failure path is captured in the
+ * returned summary instead so a boot-time caller can log-and-continue.
+ */
+export declare function ensureAdditiveColumns(options: EnsureAdditiveColumnsOptions): Promise<EnsureAdditiveColumnsResult>;
+//# sourceMappingURL=ensure-additive-columns.d.ts.map

package/dist/db/ensure-additive-columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-additive-columns.d.ts","sourceRoot":"","sources":["../../src/db/ensure-additive-columns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAItD,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AA4BD,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,sGAAsG;IACtG,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,2BAA2B,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IAC1C,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yEAAyE;IACzE,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,oFAAoF;IACpF,MAAM,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAiLD;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAgHtC"}

package/dist/db/ensure-additive-columns.js

@@ -0,0 +1,355 @@
+/**
+ * Boot-time convergence for columns Drizzle's schema declares but a
+ * pre-existing table is missing.
+ *
+ * Lives in its own module (like `./widen-columns.js`) so stores/plugins can
+ * import it without every `vi.mock("../db/client.js")` test needing to stub
+ * it: the helper resolves `isPostgres()` / `getDbExec()` through `client.js`,
+ * so a test that mocks the client to SQLite makes the Postgres introspection
+ * path a no-op automatically.
+ *
+ * ## Why
+ *
+ * `CREATE TABLE IF NOT EXISTS` only runs the CREATE the first time a table is
+ * created — once it exists, adding a column to the Drizzle schema (e.g.
+ * `schema.ts`) does nothing to already-existing rows unless a hand-written
+ * `ALTER TABLE ... ADD COLUMN` migration ships alongside it. Fresh dev
+ * databases mask this because the CREATE always includes every declared
+ * column; only long-lived, pre-existing production tables are missing the
+ * new column. Forgetting the migration turns every query that references the
+ * column into a Postgres `42703 (undefined_column)` — e.g.
+ * `session_recordings.network_error_count`, which 500'd every
+ * `list-session-recordings` call.
+ *
+ * `ensureAdditiveColumns()` is belt-and-braces for that failure mode: after
+ * the authoritative hand-written migrations run, diff each Drizzle table's
+ * declared columns against the live table and additively patch any gap. It
+ * is NOT a replacement for migrations — it never touches indexes, data
+ * transforms, or existing columns, and a hand-written migration should still
+ * ship for every schema change. This is a safety net for the case where one
+ * doesn't.
+ *
+ * ## Safety rules (hard)
+ *
+ * - Additive only: never drops, renames, retypes, or otherwise touches a
+ *   column that already exists on the live table.
+ * - A `NOT NULL` column is only ever added when it has a renderable default
+ *   (so existing rows get a valid value in the same statement). If it has no
+ *   renderable default, it is added as nullable when the Drizzle declaration
+ *   allows null, else the column is SKIPPED entirely with a loud log line
+ *   naming the column and the reason.
+ * - Only simple literal defaults are rendered: numbers, strings, booleans,
+ *   and `sql` template defaults that stringify to one of a small allow-listed
+ *   set of safe constants (see `renderDefaultLiteral`). Any other `sql`
+ *   default is NOT rendered — the column is added without a `DEFAULT` (and
+ *   without `NOT NULL`, per the rule above) rather than risk interpolating
+ *   unsafe SQL.
+ * - All identifiers (table/column names) are validated against a strict
+ *   `[A-Za-z_][A-Za-z0-9_]*` pattern and double-quoted; no value from a row or
+ *   from user data is ever interpolated into the generated SQL.
+ * - If the table itself does not exist yet, this is a no-op — table creation
+ *   owns bringing every declared column into existence for a brand-new table.
+ * - Idempotent and best-effort: a failure on one column is logged and does
+ *   not abort the rest, and a total failure (e.g. `information_schema`
+ *   unreadable) must never crash boot — the caller decides whether/how to
+ *   surface `errors` in the returned summary.
+ */
+import { isPostgres } from "./client.js";
+const PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const defaultLogger = {
+    info: (message) => console.log(message),
+    warn: (message) => console.warn(message),
+    error: (message) => console.error(message),
+};
+function emptyResult() {
+    return { applied: [], skipped: [], errors: [] };
+}
+/**
+ * Resolve `getTableConfig` for the dialect currently in effect. Both
+ * `drizzle-orm/pg-core` and `drizzle-orm/sqlite-core` export a function with
+ * this name and a compatible-enough shape (`{ columns, name, schema? }`), but
+ * each only understands its own table class — calling the wrong one throws.
+ * `table()` from `./schema.js` builds a `pgTable` on Postgres and a
+ * `sqliteTable` everywhere else, so the same dialect switch used there
+ * decides which `getTableConfig` to load here.
+ */
+async function loadGetTableConfig() {
+    if (isPostgres()) {
+        const { getTableConfig } = await import("drizzle-orm/pg-core");
+        return getTableConfig;
+    }
+    const { getTableConfig } = await import("drizzle-orm/sqlite-core");
+    return getTableConfig;
+}
+/**
+ * Live columns already present on `table`, keyed by column name.
+ * Postgres: `information_schema.columns` scoped to the table's schema
+ * (default `public`). SQLite: `PRAGMA table_info(table)`.
+ *
+ * Returns `null` when the table itself does not exist (caller no-ops —
+ * table creation owns that path) or when introspection fails outright.
+ */
+async function introspectLiveColumns(db, table, schema) {
+    if (isPostgres()) {
+        try {
+            const tableSchema = schema || "public";
+            const { rows: existsRows } = await db.execute({
+                sql: `SELECT 1 FROM information_schema.tables
+              WHERE table_schema = ? AND table_name = ? LIMIT 1`,
+                args: [tableSchema, table],
+            });
+            if (existsRows.length === 0)
+                return null;
+            const { rows } = await db.execute({
+                sql: `SELECT column_name FROM information_schema.columns
+              WHERE table_schema = ? AND table_name = ?`,
+                args: [tableSchema, table],
+            });
+            return new Set(rows.map((r) => String(r.column_name)));
+        }
+        catch {
+            return null;
+        }
+    }
+    // SQLite: PRAGMA table_info returns zero rows for a non-existent table
+    // (no error), so we can't distinguish "missing table" from "no columns"
+    // that way — probe sqlite_master first.
+    try {
+        const { rows: existsRows } = await db.execute({
+            sql: `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1`,
+            args: [table],
+        });
+        if (existsRows.length === 0)
+            return null;
+        // PRAGMA doesn't support bound parameters; the table name is already
+        // validated against PLAIN_IDENTIFIER by the caller before we get here.
+        const { rows } = await db.execute(`PRAGMA table_info("${table}")`);
+        return new Set(rows.map((r) => String(r.name)));
+    }
+    catch {
+        return null;
+    }
+}
+/** Quote a validated identifier for use in generated SQL. */
+function quoteIdent(name) {
+    return `"${name}"`;
+}
+/**
+ * Render a column's declared default as a SQL literal, or `undefined` if it
+ * can't be rendered safely. Only numbers, strings, booleans, and a small
+ * allow-list of `sql` template defaults that stringify to a known-safe
+ * constant are supported — anything else is deliberately left unrendered so
+ * we never interpolate arbitrary SQL.
+ */
+function renderDefaultLiteral(column) {
+    if (!column.hasDefault)
+        return undefined;
+    const value = column.default;
+    if (value == null)
+        return undefined;
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(value);
+    }
+    if (typeof value === "boolean") {
+        return isPostgres() ? (value ? "true" : "false") : value ? "1" : "0";
+    }
+    if (typeof value === "string") {
+        // Escape single quotes for a plain string literal.
+        return `'${value.replace(/'/g, "''")}'`;
+    }
+    // Drizzle `sql` template defaults (e.g. `now()`, `(datetime('now'))`) carry
+    // a `queryChunks`/`toQuery`-style object rather than a plain scalar. Only
+    // render the handful of known-safe constants used by this codebase's
+    // `now()` helper (see ./schema.ts) — never stringify arbitrary SQL.
+    const raw = sqlDefaultText(value);
+    if (raw == null)
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    const SAFE_SQL_DEFAULTS = new Set([
+        "now()",
+        "(datetime('now'))",
+        "current_timestamp",
+        "current_date",
+        "current_time",
+    ]);
+    if (SAFE_SQL_DEFAULTS.has(normalized)) {
+        return raw.trim();
+    }
+    return undefined;
+}
+/**
+ * Best-effort extraction of the raw SQL text from a drizzle `SQL` default
+ * object (e.g. the value produced by `` sql`now()` ``). Drizzle's `SQL`
+ * class publicly exposes `readonly queryChunks: SQLChunk[]`, where a plain
+ * literal chunk is a `StringChunk` with a `.value: string[]`. Only accept the
+ * text when EVERY chunk is a plain string literal — if the default embeds any
+ * dynamic piece (a bound param, column reference, nested table, etc.) we
+ * refuse to stringify it, since that could contain unsafe or unbounded SQL.
+ */
+function sqlDefaultText(value) {
+    if (typeof value === "string")
+        return value;
+    const chunks = value?.queryChunks;
+    if (!Array.isArray(chunks))
+        return undefined;
+    const parts = [];
+    for (const chunk of chunks) {
+        const stringValues = chunk?.value;
+        if (!Array.isArray(stringValues) ||
+            !stringValues.every((v) => typeof v === "string")) {
+            return undefined;
+        }
+        parts.push(...stringValues);
+    }
+    const text = parts.join("");
+    return text || undefined;
+}
+/** True when an ALTER ... ADD COLUMN failure indicates the column already exists (race with a concurrent boot). */
+function isDuplicateColumnError(err) {
+    const msg = err?.message ?? "";
+    return (/duplicate column name/i.test(msg) ||
+        /column .* already exists/i.test(msg) ||
+        err?.code === "42701");
+}
+/** Annotate a schema-drift-shaped Postgres error (42703/42P01) so logs read plainly. */
+function describeSchemaDriftError(err) {
+    const code = err?.code;
+    const message = err?.message ?? String(err);
+    if (code === "42703") {
+        return `schema drift (42703 undefined_column): ${message}`;
+    }
+    if (code === "42P01") {
+        return `schema drift (42P01 undefined_table): ${message}`;
+    }
+    return message;
+}
+/**
+ * Diff each declared Drizzle table's columns against the live database and
+ * additively `ALTER TABLE ... ADD COLUMN` any that are missing. See the
+ * module docstring for the full safety-rule contract.
+ *
+ * Call this once at boot, immediately after the authoritative hand-written
+ * migrations have run. Never throws — every failure path is captured in the
+ * returned summary instead so a boot-time caller can log-and-continue.
+ */
+export async function ensureAdditiveColumns(options) {
+    const { db, tables, logger = defaultLogger } = options;
+    const result = emptyResult();
+    let getTableConfig;
+    try {
+        getTableConfig = await loadGetTableConfig();
+    }
+    catch (err) {
+        result.errors.push({
+            column: "*",
+            error: `failed to load drizzle-orm table config helper: ${err instanceof Error ? err.message : String(err)}`,
+        });
+        return result;
+    }
+    for (const tableObj of tables) {
+        let config;
+        try {
+            config = getTableConfig(tableObj);
+        }
+        catch (err) {
+            // Not a table this dialect's getTableConfig understands (e.g. a stray
+            // export that isn't a Drizzle table) — skip quietly rather than
+            // erroring the whole run over one bad entry.
+            logger.warn(`[ensure-additive-columns] skipping non-table export: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        const tableName = config.name;
+        if (!tableName || !PLAIN_IDENTIFIER.test(tableName))
+            continue;
+        let liveColumns;
+        try {
+            liveColumns = await introspectLiveColumns(db, tableName, config.schema);
+        }
+        catch (err) {
+            result.errors.push({
+                column: `${tableName}.*`,
+                error: describeSchemaDriftError(err),
+            });
+            continue;
+        }
+        // Table doesn't exist yet — the creation path (CREATE TABLE IF NOT
+        // EXISTS / a real migration) owns bringing every declared column into
+        // existence. Nothing to do here.
+        if (liveColumns == null)
+            continue;
+        for (const column of config.columns) {
+            const columnName = column.name;
+            if (!columnName || !PLAIN_IDENTIFIER.test(columnName))
+                continue;
+            if (liveColumns.has(columnName))
+                continue; // untouched — already present
+            const label = `${tableName}.${columnName}`;
+            const sqlType = safeSQLType(column, label, logger);
+            if (!sqlType) {
+                result.skipped.push({
+                    column: label,
+                    reason: "could not determine a safe SQL type for the column",
+                });
+                continue;
+            }
+            const defaultLiteral = renderDefaultLiteral(column);
+            let notNullClause = "";
+            if (column.notNull) {
+                if (defaultLiteral != null) {
+                    notNullClause = " NOT NULL";
+                }
+                else {
+                    // Can't safely backfill existing rows — adding NOT NULL without a
+                    // default would fail immediately on any existing row. Skip the
+                    // whole column rather than add a nullable column that silently
+                    // disagrees with the Drizzle declaration's NOT NULL contract in
+                    // a way that could surprise a future safe-default addition.
+                    result.skipped.push({
+                        column: label,
+                        reason: "declared NOT NULL with no renderable default — cannot backfill existing rows safely",
+                    });
+                    logger.warn(`[ensure-additive-columns] SKIPPING ${label}: declared NOT NULL with no renderable default (existing rows have no safe backfill value)`);
+                    continue;
+                }
+            }
+            const defaultClause = defaultLiteral != null ? ` DEFAULT ${defaultLiteral}` : "";
+            const ddl = `ALTER TABLE ${quoteIdent(tableName)} ADD COLUMN ${quoteIdent(columnName)} ${sqlType}${defaultClause}${notNullClause}`;
+            try {
+                await db.execute(ddl);
+                result.applied.push(label);
+                logger.info(`[ensure-additive-columns] added ${label}`);
+            }
+            catch (err) {
+                if (isDuplicateColumnError(err)) {
+                    // A concurrent boot already added it — treat as success.
+                    result.applied.push(label);
+                    continue;
+                }
+                const message = describeSchemaDriftError(err);
+                result.errors.push({ column: label, error: message });
+                logger.error(`[ensure-additive-columns] failed to add ${label}: ${message}`);
+                // Continue with the remaining columns/tables — one failure must not
+                // abort the rest.
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Resolve the SQL type to use for a new column. Prefers the column's own
+ * `getSQLType()` (the exact type Drizzle would have used in a fresh CREATE
+ * TABLE); falls back to skipping (returns `undefined`) if it throws or
+ * returns something empty.
+ */
+function safeSQLType(column, label, logger) {
+    try {
+        const sqlType = column.getSQLType();
+        if (typeof sqlType === "string" && sqlType.trim())
+            return sqlType.trim();
+    }
+    catch (err) {
+        logger.warn(`[ensure-additive-columns] getSQLType() threw for ${label}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return undefined;
+}
+//# sourceMappingURL=ensure-additive-columns.js.map

package/dist/db/ensure-additive-columns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-additive-columns.js","sourceRoot":"","sources":["../../src/db/ensure-additive-columns.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Boot-time convergence for columns Drizzle's schema declares but a\n * pre-existing table is missing.\n *\n * Lives in its own module (like `./widen-columns.js`) so stores/plugins can\n * import it without every `vi.mock(\"../db/client.js\")` test needing to stub\n * it: the helper resolves `isPostgres()` / `getDbExec()` through `client.js`,\n * so a test that mocks the client to SQLite makes the Postgres introspection\n * path a no-op automatically.\n *\n * ## Why\n *\n * `CREATE TABLE IF NOT EXISTS` only runs the CREATE the first time a table is\n * created — once it exists, adding a column to the Drizzle schema (e.g.\n * `schema.ts`) does nothing to already-existing rows unless a hand-written\n * `ALTER TABLE ... ADD COLUMN` migration ships alongside it. Fresh dev\n * databases mask this because the CREATE always includes every declared\n * column; only long-lived, pre-existing production tables are missing the\n * new column. Forgetting the migration turns every query that references the\n * column into a Postgres `42703 (undefined_column)` — e.g.\n * `session_recordings.network_error_count`, which 500'd every\n * `list-session-recordings` call.\n *\n * `ensureAdditiveColumns()` is belt-and-braces for that failure mode: after\n * the authoritative hand-written migrations run, diff each Drizzle table's\n * declared columns against the live table and additively patch any gap. It\n * is NOT a replacement for migrations — it never touches indexes, data\n * transforms, or existing columns, and a hand-written migration should still\n * ship for every schema change. This is a safety net for the case where one\n * doesn't.\n *\n * ## Safety rules (hard)\n *\n * - Additive only: never drops, renames, retypes, or otherwise touches a\n *   column that already exists on the live table.\n * - A `NOT NULL` column is only ever added when it has a renderable default\n *   (so existing rows get a valid value in the same statement). If it has no\n *   renderable default, it is added as nullable when the Drizzle declaration\n *   allows null, else the column is SKIPPED entirely with a loud log line\n *   naming the column and the reason.\n * - Only simple literal defaults are rendered: numbers, strings, booleans,\n *   and `sql` template defaults that stringify to one of a small allow-listed\n *   set of safe constants (see `renderDefaultLiteral`). Any other `sql`\n *   default is NOT rendered — the column is added without a `DEFAULT` (and\n *   without `NOT NULL`, per the rule above) rather than risk interpolating\n *   unsafe SQL.\n * - All identifiers (table/column names) are validated against a strict\n *   `[A-Za-z_][A-Za-z0-9_]*` pattern and double-quoted; no value from a row or\n *   from user data is ever interpolated into the generated SQL.\n * - If the table itself does not exist yet, this is a no-op — table creation\n *   owns bringing every declared column into existence for a brand-new table.\n * - Idempotent and best-effort: a failure on one column is logged and does\n *   not abort the rest, and a total failure (e.g. `information_schema`\n *   unreadable) must never crash boot — the caller decides whether/how to\n *   surface `errors` in the returned summary.\n */\n\nimport { isPostgres, type DbExec } from \"./client.js\";\n\nconst PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\nexport interface EnsureAdditiveColumnsLogger {\n  info: (message: string) => void;\n  warn: (message: string) => void;\n  error: (message: string) => void;\n}\n\nconst defaultLogger: EnsureAdditiveColumnsLogger = {\n  info: (message) => console.log(message),\n  warn: (message) => console.warn(message),\n  error: (message) => console.error(message),\n};\n\n/**\n * Minimal shape this module needs from a Drizzle column — matches both\n * `drizzle-orm/pg-core` and `drizzle-orm/sqlite-core` column instances (and\n * the dialect-agnostic wrappers in `./schema.js`, which delegate to one or\n * the other at runtime).\n */\ninterface DeclaredColumnLike {\n  name: string;\n  notNull: boolean;\n  hasDefault: boolean;\n  default: unknown;\n  getSQLType(): string;\n}\n\ninterface DeclaredTableLike {\n  columns: DeclaredColumnLike[];\n  name: string;\n  schema?: string;\n}\n\nexport interface EnsureAdditiveColumnsOptions {\n  db: DbExec;\n  /** Drizzle table objects (from `pgTable`/`sqliteTable`, or the dialect-agnostic `table()` helper). */\n  tables: unknown[];\n  logger?: EnsureAdditiveColumnsLogger;\n}\n\nexport interface EnsureAdditiveColumnsResult {\n  /** `\"table.column\"` entries that were successfully added. */\n  applied: string[];\n  /** Declared columns that were intentionally left unpatched, with why. */\n  skipped: Array<{ column: string; reason: string }>;\n  /** `\"table.column\"` entries whose ALTER failed unexpectedly (logged, non-fatal). */\n  errors: Array<{ column: string; error: string }>;\n}\n\nfunction emptyResult(): EnsureAdditiveColumnsResult {\n  return { applied: [], skipped: [], errors: [] };\n}\n\n/**\n * Resolve `getTableConfig` for the dialect currently in effect. Both\n * `drizzle-orm/pg-core` and `drizzle-orm/sqlite-core` export a function with\n * this name and a compatible-enough shape (`{ columns, name, schema? }`), but\n * each only understands its own table class — calling the wrong one throws.\n * `table()` from `./schema.js` builds a `pgTable` on Postgres and a\n * `sqliteTable` everywhere else, so the same dialect switch used there\n * decides which `getTableConfig` to load here.\n */\nasync function loadGetTableConfig(): Promise<\n  (table: unknown) => DeclaredTableLike\n> {\n  if (isPostgres()) {\n    const { getTableConfig } = await import(\"drizzle-orm/pg-core\");\n    return getTableConfig as unknown as (table: unknown) => DeclaredTableLike;\n  }\n  const { getTableConfig } = await import(\"drizzle-orm/sqlite-core\");\n  return getTableConfig as unknown as (table: unknown) => DeclaredTableLike;\n}\n\n/**\n * Live columns already present on `table`, keyed by column name.\n * Postgres: `information_schema.columns` scoped to the table's schema\n * (default `public`). SQLite: `PRAGMA table_info(table)`.\n *\n * Returns `null` when the table itself does not exist (caller no-ops —\n * table creation owns that path) or when introspection fails outright.\n */\nasync function introspectLiveColumns(\n  db: DbExec,\n  table: string,\n  schema: string | undefined,\n): Promise<Set<string> | null> {\n  if (isPostgres()) {\n    try {\n      const tableSchema = schema || \"public\";\n      const { rows: existsRows } = await db.execute({\n        sql: `SELECT 1 FROM information_schema.tables\n              WHERE table_schema = ? AND table_name = ? LIMIT 1`,\n        args: [tableSchema, table],\n      });\n      if (existsRows.length === 0) return null;\n      const { rows } = await db.execute({\n        sql: `SELECT column_name FROM information_schema.columns\n              WHERE table_schema = ? AND table_name = ?`,\n        args: [tableSchema, table],\n      });\n      return new Set(rows.map((r) => String(r.column_name)));\n    } catch {\n      return null;\n    }\n  }\n\n  // SQLite: PRAGMA table_info returns zero rows for a non-existent table\n  // (no error), so we can't distinguish \"missing table\" from \"no columns\"\n  // that way — probe sqlite_master first.\n  try {\n    const { rows: existsRows } = await db.execute({\n      sql: `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1`,\n      args: [table],\n    });\n    if (existsRows.length === 0) return null;\n    // PRAGMA doesn't support bound parameters; the table name is already\n    // validated against PLAIN_IDENTIFIER by the caller before we get here.\n    const { rows } = await db.execute(`PRAGMA table_info(\"${table}\")`);\n    return new Set(rows.map((r) => String(r.name)));\n  } catch {\n    return null;\n  }\n}\n\n/** Quote a validated identifier for use in generated SQL. */\nfunction quoteIdent(name: string): string {\n  return `\"${name}\"`;\n}\n\n/**\n * Render a column's declared default as a SQL literal, or `undefined` if it\n * can't be rendered safely. Only numbers, strings, booleans, and a small\n * allow-list of `sql` template defaults that stringify to a known-safe\n * constant are supported — anything else is deliberately left unrendered so\n * we never interpolate arbitrary SQL.\n */\nfunction renderDefaultLiteral(column: DeclaredColumnLike): string | undefined {\n  if (!column.hasDefault) return undefined;\n  const value = column.default;\n  if (value == null) return undefined;\n\n  if (typeof value === \"number\" && Number.isFinite(value)) {\n    return String(value);\n  }\n  if (typeof value === \"boolean\") {\n    return isPostgres() ? (value ? \"true\" : \"false\") : value ? \"1\" : \"0\";\n  }\n  if (typeof value === \"string\") {\n    // Escape single quotes for a plain string literal.\n    return `'${value.replace(/'/g, \"''\")}'`;\n  }\n\n  // Drizzle `sql` template defaults (e.g. `now()`, `(datetime('now'))`) carry\n  // a `queryChunks`/`toQuery`-style object rather than a plain scalar. Only\n  // render the handful of known-safe constants used by this codebase's\n  // `now()` helper (see ./schema.ts) — never stringify arbitrary SQL.\n  const raw = sqlDefaultText(value);\n  if (raw == null) return undefined;\n  const normalized = raw.trim().toLowerCase();\n  const SAFE_SQL_DEFAULTS = new Set([\n    \"now()\",\n    \"(datetime('now'))\",\n    \"current_timestamp\",\n    \"current_date\",\n    \"current_time\",\n  ]);\n  if (SAFE_SQL_DEFAULTS.has(normalized)) {\n    return raw.trim();\n  }\n  return undefined;\n}\n\n/**\n * Best-effort extraction of the raw SQL text from a drizzle `SQL` default\n * object (e.g. the value produced by `` sql`now()` ``). Drizzle's `SQL`\n * class publicly exposes `readonly queryChunks: SQLChunk[]`, where a plain\n * literal chunk is a `StringChunk` with a `.value: string[]`. Only accept the\n * text when EVERY chunk is a plain string literal — if the default embeds any\n * dynamic piece (a bound param, column reference, nested table, etc.) we\n * refuse to stringify it, since that could contain unsafe or unbounded SQL.\n */\nfunction sqlDefaultText(value: unknown): string | undefined {\n  if (typeof value === \"string\") return value;\n  const chunks = (value as { queryChunks?: unknown } | null)?.queryChunks;\n  if (!Array.isArray(chunks)) return undefined;\n  const parts: string[] = [];\n  for (const chunk of chunks) {\n    const stringValues = (chunk as { value?: unknown } | null)?.value;\n    if (\n      !Array.isArray(stringValues) ||\n      !stringValues.every((v) => typeof v === \"string\")\n    ) {\n      return undefined;\n    }\n    parts.push(...(stringValues as string[]));\n  }\n  const text = parts.join(\"\");\n  return text || undefined;\n}\n\n/** True when an ALTER ... ADD COLUMN failure indicates the column already exists (race with a concurrent boot). */\nfunction isDuplicateColumnError(err: unknown): boolean {\n  const msg = (err as { message?: string } | undefined)?.message ?? \"\";\n  return (\n    /duplicate column name/i.test(msg) ||\n    /column .* already exists/i.test(msg) ||\n    (err as { code?: string } | undefined)?.code === \"42701\"\n  );\n}\n\n/** Annotate a schema-drift-shaped Postgres error (42703/42P01) so logs read plainly. */\nfunction describeSchemaDriftError(err: unknown): string {\n  const code = (err as { code?: string } | undefined)?.code;\n  const message =\n    (err as { message?: string } | undefined)?.message ?? String(err);\n  if (code === \"42703\") {\n    return `schema drift (42703 undefined_column): ${message}`;\n  }\n  if (code === \"42P01\") {\n    return `schema drift (42P01 undefined_table): ${message}`;\n  }\n  return message;\n}\n\n/**\n * Diff each declared Drizzle table's columns against the live database and\n * additively `ALTER TABLE ... ADD COLUMN` any that are missing. See the\n * module docstring for the full safety-rule contract.\n *\n * Call this once at boot, immediately after the authoritative hand-written\n * migrations have run. Never throws — every failure path is captured in the\n * returned summary instead so a boot-time caller can log-and-continue.\n */\nexport async function ensureAdditiveColumns(\n  options: EnsureAdditiveColumnsOptions,\n): Promise<EnsureAdditiveColumnsResult> {\n  const { db, tables, logger = defaultLogger } = options;\n  const result = emptyResult();\n\n  let getTableConfig: (table: unknown) => DeclaredTableLike;\n  try {\n    getTableConfig = await loadGetTableConfig();\n  } catch (err) {\n    result.errors.push({\n      column: \"*\",\n      error: `failed to load drizzle-orm table config helper: ${err instanceof Error ? err.message : String(err)}`,\n    });\n    return result;\n  }\n\n  for (const tableObj of tables) {\n    let config: DeclaredTableLike;\n    try {\n      config = getTableConfig(tableObj);\n    } catch (err) {\n      // Not a table this dialect's getTableConfig understands (e.g. a stray\n      // export that isn't a Drizzle table) — skip quietly rather than\n      // erroring the whole run over one bad entry.\n      logger.warn(\n        `[ensure-additive-columns] skipping non-table export: ${err instanceof Error ? err.message : String(err)}`,\n      );\n      continue;\n    }\n\n    const tableName = config.name;\n    if (!tableName || !PLAIN_IDENTIFIER.test(tableName)) continue;\n\n    let liveColumns: Set<string> | null;\n    try {\n      liveColumns = await introspectLiveColumns(db, tableName, config.schema);\n    } catch (err) {\n      result.errors.push({\n        column: `${tableName}.*`,\n        error: describeSchemaDriftError(err),\n      });\n      continue;\n    }\n\n    // Table doesn't exist yet — the creation path (CREATE TABLE IF NOT\n    // EXISTS / a real migration) owns bringing every declared column into\n    // existence. Nothing to do here.\n    if (liveColumns == null) continue;\n\n    for (const column of config.columns) {\n      const columnName = column.name;\n      if (!columnName || !PLAIN_IDENTIFIER.test(columnName)) continue;\n      if (liveColumns.has(columnName)) continue; // untouched — already present\n\n      const label = `${tableName}.${columnName}`;\n      const sqlType = safeSQLType(column, label, logger);\n      if (!sqlType) {\n        result.skipped.push({\n          column: label,\n          reason: \"could not determine a safe SQL type for the column\",\n        });\n        continue;\n      }\n\n      const defaultLiteral = renderDefaultLiteral(column);\n      let notNullClause = \"\";\n      if (column.notNull) {\n        if (defaultLiteral != null) {\n          notNullClause = \" NOT NULL\";\n        } else {\n          // Can't safely backfill existing rows — adding NOT NULL without a\n          // default would fail immediately on any existing row. Skip the\n          // whole column rather than add a nullable column that silently\n          // disagrees with the Drizzle declaration's NOT NULL contract in\n          // a way that could surprise a future safe-default addition.\n          result.skipped.push({\n            column: label,\n            reason:\n              \"declared NOT NULL with no renderable default — cannot backfill existing rows safely\",\n          });\n          logger.warn(\n            `[ensure-additive-columns] SKIPPING ${label}: declared NOT NULL with no renderable default (existing rows have no safe backfill value)`,\n          );\n          continue;\n        }\n      }\n\n      const defaultClause =\n        defaultLiteral != null ? ` DEFAULT ${defaultLiteral}` : \"\";\n      const ddl = `ALTER TABLE ${quoteIdent(tableName)} ADD COLUMN ${quoteIdent(columnName)} ${sqlType}${defaultClause}${notNullClause}`;\n\n      try {\n        await db.execute(ddl);\n        result.applied.push(label);\n        logger.info(`[ensure-additive-columns] added ${label}`);\n      } catch (err) {\n        if (isDuplicateColumnError(err)) {\n          // A concurrent boot already added it — treat as success.\n          result.applied.push(label);\n          continue;\n        }\n        const message = describeSchemaDriftError(err);\n        result.errors.push({ column: label, error: message });\n        logger.error(\n          `[ensure-additive-columns] failed to add ${label}: ${message}`,\n        );\n        // Continue with the remaining columns/tables — one failure must not\n        // abort the rest.\n      }\n    }\n  }\n\n  return result;\n}\n\n/**\n * Resolve the SQL type to use for a new column. Prefers the column's own\n * `getSQLType()` (the exact type Drizzle would have used in a fresh CREATE\n * TABLE); falls back to skipping (returns `undefined`) if it throws or\n * returns something empty.\n */\nfunction safeSQLType(\n  column: DeclaredColumnLike,\n  label: string,\n  logger: EnsureAdditiveColumnsLogger,\n): string | undefined {\n  try {\n    const sqlType = column.getSQLType();\n    if (typeof sqlType === \"string\" && sqlType.trim()) return sqlType.trim();\n  } catch (err) {\n    logger.warn(\n      `[ensure-additive-columns] getSQLType() threw for ${label}: ${err instanceof Error ? err.message : String(err)}`,\n    );\n  }\n  return undefined;\n}\n"]}

package/dist/db/index.d.ts

@@ -24,4 +24,5 @@ export { createGetDb } from "./create-get-db.js";
 export { runMigrations } from "./migrations.js";
 export { getDbExec, createDbExec, getDialect, isPostgres, intType, closeDbExec, type DbExec, type DbExecConfig, type Dialect, } from "./client.js";
 export { table, text, integer, now } from "./schema.js";
+export { ensureAdditiveColumns, type EnsureAdditiveColumnsOptions, type EnsureAdditiveColumnsResult, type EnsureAdditiveColumnsLogger, } from "./ensure-additive-columns.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/db/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAGtC,MAAM,MAAM,QAAQ,GAChB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAE,GAC9B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE,QAAQ;;;;IAe9C;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,WAAW,EACX,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,OAAO,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAGtC,MAAM,MAAM,QAAQ,GAChB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAE,GAC9B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE,QAAQ;;;;IAe9C;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,WAAW,EACX,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,OAAO,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,GACjC,MAAM,8BAA8B,CAAC"}

package/dist/db/index.js

@@ -23,4 +23,5 @@ export { createGetDb } from "./create-get-db.js";
 export { runMigrations } from "./migrations.js";
 export { getDbExec, createDbExec, getDialect, isPostgres, intType, closeDbExec, } from "./client.js";
 export { table, text, integer, now } from "./schema.js";
+export { ensureAdditiveColumns, } from "./ensure-additive-columns.js";
 //# sourceMappingURL=index.js.map

package/dist/db/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAOrD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAgB;IAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACvE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACjD,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACtD,OAAO,SAAS,CACd,EAAE,CAAC,MAAM,CAAC,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CACpE,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACpC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uBAAwB,MAAc,CAAC,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC;AAID,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,WAAW,GAIZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC","sourcesContent":["import Database from \"better-sqlite3\";\nimport { drizzle } from \"drizzle-orm/better-sqlite3\";\n\nexport type DbConfig =\n  | { driver: \"sqlite\"; filename: string }\n  | { driver: \"d1\"; binding: any }\n  | { driver: \"postgres\"; connectionString: string };\n\n/**\n * Create a Drizzle ORM database instance.\n * Supports SQLite via better-sqlite3 and Postgres via postgres-js.\n * Postgres driver is loaded dynamically to avoid bundling in edge runtimes.\n */\nexport async function createDb(config: DbConfig) {\n  if (config.driver === \"postgres\") {\n    const { drizzle: drizzlePg } = await import(\"drizzle-orm/postgres-js\");\n    const { default: pg } = await import(\"postgres\");\n    const { pgPoolOptions } = await import(\"./client.js\");\n    return drizzlePg(\n      pg(config.connectionString, pgPoolOptions(config.connectionString)),\n    );\n  }\n  if (config.driver === \"sqlite\") {\n    const sqlite = new Database(config.filename);\n    sqlite.pragma(\"journal_mode = WAL\");\n    return drizzle(sqlite);\n  }\n  throw new Error(`Unsupported driver: ${(config as any).driver}`);\n}\n\nexport type DrizzleDb = Awaited<ReturnType<typeof createDb>>;\n\nexport { createGetDb } from \"./create-get-db.js\";\nexport { runMigrations } from \"./migrations.js\";\nexport {\n  getDbExec,\n  createDbExec,\n  getDialect,\n  isPostgres,\n  intType,\n  closeDbExec,\n  type DbExec,\n  type DbExecConfig,\n  type Dialect,\n} from \"./client.js\";\nexport { table, text, integer, now } from \"./schema.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAOrD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAgB;IAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACvE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACjD,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACtD,OAAO,SAAS,CACd,EAAE,CAAC,MAAM,CAAC,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CACpE,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACpC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uBAAwB,MAAc,CAAC,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC;AAID,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,WAAW,GAIZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,qBAAqB,GAItB,MAAM,8BAA8B,CAAC","sourcesContent":["import Database from \"better-sqlite3\";\nimport { drizzle } from \"drizzle-orm/better-sqlite3\";\n\nexport type DbConfig =\n  | { driver: \"sqlite\"; filename: string }\n  | { driver: \"d1\"; binding: any }\n  | { driver: \"postgres\"; connectionString: string };\n\n/**\n * Create a Drizzle ORM database instance.\n * Supports SQLite via better-sqlite3 and Postgres via postgres-js.\n * Postgres driver is loaded dynamically to avoid bundling in edge runtimes.\n */\nexport async function createDb(config: DbConfig) {\n  if (config.driver === \"postgres\") {\n    const { drizzle: drizzlePg } = await import(\"drizzle-orm/postgres-js\");\n    const { default: pg } = await import(\"postgres\");\n    const { pgPoolOptions } = await import(\"./client.js\");\n    return drizzlePg(\n      pg(config.connectionString, pgPoolOptions(config.connectionString)),\n    );\n  }\n  if (config.driver === \"sqlite\") {\n    const sqlite = new Database(config.filename);\n    sqlite.pragma(\"journal_mode = WAL\");\n    return drizzle(sqlite);\n  }\n  throw new Error(`Unsupported driver: ${(config as any).driver}`);\n}\n\nexport type DrizzleDb = Awaited<ReturnType<typeof createDb>>;\n\nexport { createGetDb } from \"./create-get-db.js\";\nexport { runMigrations } from \"./migrations.js\";\nexport {\n  getDbExec,\n  createDbExec,\n  getDialect,\n  isPostgres,\n  intType,\n  closeDbExec,\n  type DbExec,\n  type DbExecConfig,\n  type Dialect,\n} from \"./client.js\";\nexport { table, text, integer, now } from \"./schema.js\";\nexport {\n  ensureAdditiveColumns,\n  type EnsureAdditiveColumnsOptions,\n  type EnsureAdditiveColumnsResult,\n  type EnsureAdditiveColumnsLogger,\n} from \"./ensure-additive-columns.js\";\n"]}

package/dist/db/migrations.d.ts

@@ -43,6 +43,11 @@ export interface RunMigrationsOptions {
  *
  *   { version: 14, sql: { postgres: "ALTER TABLE …" } }  // no-op on sqlite
  *   { version: 15, sql: { sqlite: "…", postgres: "…" } } // both dialects
+ *
+ * `name` is an optional stable, unique slug that opts a migration into
+ * **name-based tracking** instead of the legacy version-number gate. See the
+ * "Name-based tracking" section on `runMigrations` for why this exists and
+ * exactly how the two gating strategies interact.
  */
 export type MigrationSql = string | {
     postgres?: string;
@@ -51,7 +56,72 @@ export type MigrationSql = string | {
 export interface MigrationEntry {
     version: number;
     sql: MigrationSql;
+    /**
+     * Stable, unique slug for this migration (e.g. `"analytics-alert-rules-table"`).
+     * When present, this migration is tracked by NAME instead of by version
+     * number — see the `runMigrations` doc comment for the full rationale and
+     * gating rules. Must be unique across the migration list; a duplicate name
+     * throws at startup (programmer error, not a runtime data problem).
+     */
+    name?: string;
 }
+/**
+ * Runs a list of migrations against the configured database, gated by a
+ * per-table bookkeeping row (`options.table`) so repeated boots only apply
+ * new migrations.
+ *
+ * ## Name-based tracking (why it exists)
+ *
+ * The legacy gate is purely numeric: `SELECT MAX(version)` from the
+ * bookkeeping table, then apply every entry whose `version` is greater. That
+ * scheme silently breaks down when **two independent branches each extend the
+ * same migration list with different DDL under the same version numbers** —
+ * exactly what happened to the analytics template's v75-v83 range. Branch A
+ * shipped alert-rule tables as v75-v78; branch B shipped unrelated DDL as its
+ * own v75-v83. Whichever branch deployed first recorded "v75..v83 applied"
+ * in the bookkeeping table. When the other branch merged and deployed, its
+ * migrations at those same version numbers were never applied — `MAX(version)`
+ * was already ≥ their version, so the gate treated them as done even though
+ * their actual DDL had never run. The result: `analytics_migrations` showed
+ * rows for 1..83 with no gaps, yet `analytics_alert_rules`,
+ * `analytics_alert_incidents`, and `session_recordings.network_error_count`
+ * did not exist in production. Version numbers are not a stable identity —
+ * they're just sequence position, and sequence position collides across
+ * branches.
+ *
+ * Name-based tracking fixes this by keying application on a stable, unique
+ * **string slug** instead of a position in a shared integer sequence:
+ *
+ * - Entries with a `name` are recorded in a companion table,
+ *   `${table}_named` (`name TEXT PRIMARY KEY`), and APPLY IFF their name is
+ *   absent from that table — completely independent of version numbers or
+ *   the legacy `MAX(version)` gate. Two branches can both ship a migration
+ *   named `"analytics-alert-rules-table"` at version 75, or one at version 75
+ *   and the other at version 90 after a rebase — either way it applies
+ *   exactly once per database, keyed on the name.
+ * - Entries WITHOUT a `name` keep the exact legacy behavior
+ *   (`version > MAX(recorded version)`), so nothing changes for existing
+ *   unnamed migrations.
+ * - Named migrations still execute in list order, interleaved with unnamed
+ *   ones exactly as written.
+ * - When a named migration's DDL runs, we record BOTH the named row (always)
+ *   and — if its `version` is greater than the current legacy max — the
+ *   legacy version row too, in the SAME atomic batch/transaction as the DDL.
+ *   This keeps the legacy `MAX(version)` gate monotonically advancing for
+ *   any unnamed migrations that come after it in the list, while ensuring a
+ *   named migration is never "double recorded" in a way that would let it
+ *   re-apply.
+ * - A duplicate `name` across the migration list throws at startup — that's
+ *   a programmer error (copy-paste or merge mistake), not a runtime data
+ *   problem, and failing loud beats silently tracking the wrong row.
+ *
+ * New migrations should always set a `name`. Legacy unnamed migrations don't
+ * need to be renamed retroactively — the two gating strategies coexist in the
+ * same list — but if a table is EVER at risk of being shared across parallel
+ * branches (any template's own migrations qualify, since branches routinely
+ * extend the same list concurrently), giving new entries a name is what makes
+ * them immune to the collision class described above.
+ */
 export declare function runMigrations(migrations: Array<MigrationEntry>, options: RunMigrationsOptions): NitroPluginDef;
 export {};
 //# sourceMappingURL=migrations.d.ts.map

package/dist/db/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"AAmDA,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AA4B9D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAK5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CASvD;AAmDD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;OAYG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,YAAY,CAAC;CACnB;AAQD,wBAAgB,aAAa,CAC3B,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,EACjC,OAAO,EAAE,oBAAoB,GAC5B,cAAc,CA2QhB"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"AA8DA,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AA4B9D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAK5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CASvD;AAmDD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;OAYG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,YAAY,CAAC;IAClB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,EACjC,OAAO,EAAE,oBAAoB,GAC5B,cAAc,CAmYhB"}