bun-query-builder 0.2.35 → 0.2.36

package/dist/actions/schema-drift.d.ts

@@ -0,0 +1,74 @@
+import type { MigrationPlan, NormalizedColumnType } from '../migrations';
+import type { SupportedDialect } from '../types';
+/** The family a model's declared type belongs to. */
+export declare function familyOfDeclared(type: NormalizedColumnType): TypeFamily;
+/** The family a raw SQL type reported by a database belongs to. */
+export declare function familyOfSqlType(sqlType: string): TypeFamily;
+/**
+ * Whether a live column is an acceptable home for what the model declares.
+ *
+ * Same family always passes. Beyond that, only widenings are tolerated: a
+ * model asking for `varchar` is content in a `text` column, because nothing is
+ * lost. The reverse is exactly the bug this exists to find.
+ */
+export declare function satisfies(declared: TypeFamily, actual: TypeFamily): boolean;
+/**
+ * Audit the live database against a migration plan.
+ *
+ * Pass the plan built from the models (`buildMigrationPlan`). Tables the models
+ * do not declare are ignored: a database is allowed to hold more than one
+ * application's models, and framework-owned tables are not this plan's business.
+ */
+export declare function auditSchemaDrift(plan: MigrationPlan, options?: { dialect?: SupportedDialect }): Promise<SchemaDrift>;
+/**
+ * A human-readable report, or an empty string when there is nothing to say.
+ *
+ * Says what to do as well as what is wrong. A drift warning that only names the
+ * problem leaves the reader to guess whether it matters, and the honest answer
+ * here is that it always does: the schema cannot repair itself, because the
+ * migration runner has already decided there is nothing to run.
+ */
+export declare function formatSchemaDrift(drift: SchemaDrift): string;
+/**
+ * Compare a live database against what the models declare.
+ *
+ * This exists because the failure it catches is silent by construction. The
+ * migration runner only applies migration FILES: it asks "which of these have
+ * not run yet", not "does the database actually look like the models". So a
+ * database created from an older, wrong migration set reports **"nothing to
+ * migrate — your database is already up to date"** forever, while a column that
+ * should be `text` sits at `varchar(255)` and one that should hold 99.5 is an
+ * integer that stores 100.
+ *
+ * Every layer says it is fine. The write succeeds, the read comes back rounded
+ * or the insert is refused for length, and the only symptom reaches a customer.
+ * `CREATE TABLE IF NOT EXISTS` cannot repair it either, so a corrected migration
+ * set deploys as a no-op and the wrong schema survives every deploy after it.
+ *
+ * The comparison is by type FAMILY rather than by exact SQL string. Dialects
+ * spell the same type several ways — `character varying`, `varchar`, `int4`,
+ * `integer`, `real`, `float4` — and an audit that reported those as drift would
+ * be noise, which is the fastest way to teach people to ignore it.
+ */
+export declare interface ColumnDrift {
+  table: string
+  column: string
+  expected: string
+  actual: string
+  actualSqlType: string
+}
+export declare interface SchemaDrift {
+  missingTables: string[]
+  missingColumns: Array<{ table: string, column: string, expected: string }>
+  typeMismatches: ColumnDrift[]
+  clean: boolean
+}
+/**
+ * The coarse family a column type belongs to.
+ *
+ * Deliberately coarse. `bigint` and `integer` are both `integer` here: widening
+ * an id is not the class of mistake this looks for, and flagging it would bury
+ * the ones that are. What it does separate is the pairs that silently lose
+ * data — text from bounded varchar, and fractional from whole.
+ */
+export type TypeFamily = 'text' | 'varchar' | 'integer' | 'fractional' | 'boolean' | 'date' | 'json' | 'binary' | 'other';

package/dist/bin/cli.js

@@ -30092,10 +30092,139 @@ class Seeder {
 function defineSeeder(seederClass) {
   return seederClass;
 }
+// src/actions/schema-drift.ts
+function familyOfDeclared(type) {
+  switch (type) {
+    case "text":
+      return "text";
+    case "string":
+    case "enum":
+      return "varchar";
+    case "integer":
+    case "bigint":
+      return "integer";
+    case "float":
+    case "double":
+    case "decimal":
+      return "fractional";
+    case "boolean":
+      return "boolean";
+    case "date":
+    case "datetime":
+    case "timestamptz":
+      return "date";
+    case "json":
+      return "json";
+    default:
+      return "other";
+  }
+}
+function familyOfSqlType(sqlType) {
+  const type = String(sqlType ?? "").toLowerCase().trim();
+  if (/^(?:bool|boolean|bit)\b/.test(type) || type === "tinyint(1)")
+    return "boolean";
+  if (/^(?:json|jsonb)\b/.test(type))
+    return "json";
+  if (/^(?:bytea|blob|binary|varbinary)\b/.test(type))
+    return "binary";
+  if (/^(?:date|time|timestamp|datetime)\b/.test(type))
+    return "date";
+  if (/(?:^|\b)(?:varchar|character varying|nvarchar|char)\b/.test(type))
+    return "varchar";
+  if (/^(?:text|longtext|mediumtext|tinytext|clob|citext)\b/.test(type))
+    return "text";
+  if (/^(?:decimal|numeric|real|double|money)\b/.test(type) || /^float\d*\b/.test(type))
+    return "fractional";
+  if (/^(?:integer|bigint|smallint|tinyint|serial|bigserial|smallserial|mediumint)\b/.test(type) || /^int\d*\b/.test(type))
+    return "integer";
+  return "other";
+}
+function satisfies(declared, actual) {
+  if (declared === actual)
+    return true;
+  if (declared === "varchar" && actual === "text")
+    return true;
+  if (declared === "integer" && actual === "fractional")
+    return true;
+  if (declared === "other" || actual === "other")
+    return true;
+  return false;
+}
+async function auditSchemaDrift(plan, options = {}) {
+  const dialect = options.dialect ?? config5.dialect;
+  const declaredTables = plan.tables.map((table) => table.table);
+  const live = await introspectDatabase({ tables: declaredTables });
+  const byTable = new Map(live.map((model) => [model.table.toLowerCase(), model]));
+  const missingTables = [];
+  const missingColumns = [];
+  const typeMismatches = [];
+  for (const table of plan.tables) {
+    const liveTable = byTable.get(table.table.toLowerCase());
+    if (!liveTable) {
+      missingTables.push(table.table);
+      continue;
+    }
+    const liveColumns = new Map(liveTable.columns.map((column) => [column.name.toLowerCase(), column]));
+    for (const column of table.columns) {
+      const liveColumn = liveColumns.get(column.name.toLowerCase());
+      const declared = familyOfDeclared(column.type);
+      if (!liveColumn) {
+        missingColumns.push({ table: table.table, column: column.name, expected: declared });
+        continue;
+      }
+      const actual = familyOfSqlType(liveColumn.sqlType);
+      if (!satisfies(declared, actual)) {
+        typeMismatches.push({
+          table: table.table,
+          column: column.name,
+          expected: declared,
+          actual,
+          actualSqlType: liveColumn.sqlType
+        });
+      }
+    }
+  }
+  return {
+    missingTables,
+    missingColumns,
+    typeMismatches,
+    clean: missingTables.length === 0 && missingColumns.length === 0 && typeMismatches.length === 0
+  };
+}
+function formatSchemaDrift(drift) {
+  if (drift.clean)
+    return "";
+  const lines = [];
+  if (drift.missingTables.length > 0)
+    lines.push(`  Missing tables: ${drift.missingTables.join(", ")}`);
+  for (const column of drift.missingColumns.slice(0, 10))
+    lines.push(`  \u2022 ${column.table}.${column.column} is missing (models declare ${column.expected})`);
+  for (const mismatch of drift.typeMismatches.slice(0, 10))
+    lines.push(`  \u2022 ${mismatch.table}.${mismatch.column} is ${mismatch.actualSqlType}, models declare ${mismatch.expected}`);
+  const shown = Math.min(drift.missingColumns.length, 10) + Math.min(drift.typeMismatches.length, 10);
+  const total = drift.missingColumns.length + drift.typeMismatches.length;
+  if (total > shown)
+    lines.push(`  + ${total - shown} more`);
+  return [
+    "The live schema does not match the models.",
+    ...lines,
+    "",
+    "Migrations will NOT fix this on their own: the runner only applies files that have",
+    "not run yet, and a corrected `CREATE TABLE IF NOT EXISTS` is a no-op against a table",
+    "that already exists. Regenerate and apply the difference, or rebuild the schema."
+  ].join(`
+`);
+}
+var init_schema_drift = __esm(() => {
+  init_config();
+  init_introspect_db();
+});
+
 // src/index.ts
 var init_src2 = __esm(() => {
   init_model2();
   init_model2();
+  init_schema_drift();
   init_actions();
   init_browser();
   init_client();
@@ -32189,7 +32318,7 @@ function getPrefix() {
 }
 var prefix = getPrefix();
 // package.json
-var version2 = "0.2.35";
+var version2 = "0.2.36";
 
 // bin/cli.ts
 init_actions();

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export type {
   ModelCreateDataLoose,
   RelationCardinality,
 } from './type-inference';
+export type { ColumnDrift, SchemaDrift, TypeFamily } from './actions/schema-drift';
 export * from './actions/index';
 export * from './browser';
 export * from './client';
@@ -51,3 +52,4 @@ export { type ModelDefinition, defineModel } from './model';
 // Explicit re-exports for model registry functions
 export { getModel, getAllModels, getModelRegistry, hasModel, clearModelRegistry, registerModel } from './model';
 export { toDialectPlaceholders } from './sql-fragments';
+export { auditSchemaDrift, familyOfDeclared, familyOfSqlType, formatSchemaDrift, satisfies } from './actions/schema-drift';

package/dist/src/index.js

@@ -30091,10 +30091,139 @@ class Seeder {
 function defineSeeder(seederClass) {
   return seederClass;
 }
+// src/actions/schema-drift.ts
+function familyOfDeclared(type) {
+  switch (type) {
+    case "text":
+      return "text";
+    case "string":
+    case "enum":
+      return "varchar";
+    case "integer":
+    case "bigint":
+      return "integer";
+    case "float":
+    case "double":
+    case "decimal":
+      return "fractional";
+    case "boolean":
+      return "boolean";
+    case "date":
+    case "datetime":
+    case "timestamptz":
+      return "date";
+    case "json":
+      return "json";
+    default:
+      return "other";
+  }
+}
+function familyOfSqlType(sqlType) {
+  const type = String(sqlType ?? "").toLowerCase().trim();
+  if (/^(?:bool|boolean|bit)\b/.test(type) || type === "tinyint(1)")
+    return "boolean";
+  if (/^(?:json|jsonb)\b/.test(type))
+    return "json";
+  if (/^(?:bytea|blob|binary|varbinary)\b/.test(type))
+    return "binary";
+  if (/^(?:date|time|timestamp|datetime)\b/.test(type))
+    return "date";
+  if (/(?:^|\b)(?:varchar|character varying|nvarchar|char)\b/.test(type))
+    return "varchar";
+  if (/^(?:text|longtext|mediumtext|tinytext|clob|citext)\b/.test(type))
+    return "text";
+  if (/^(?:decimal|numeric|real|double|money)\b/.test(type) || /^float\d*\b/.test(type))
+    return "fractional";
+  if (/^(?:integer|bigint|smallint|tinyint|serial|bigserial|smallserial|mediumint)\b/.test(type) || /^int\d*\b/.test(type))
+    return "integer";
+  return "other";
+}
+function satisfies(declared, actual) {
+  if (declared === actual)
+    return true;
+  if (declared === "varchar" && actual === "text")
+    return true;
+  if (declared === "integer" && actual === "fractional")
+    return true;
+  if (declared === "other" || actual === "other")
+    return true;
+  return false;
+}
+async function auditSchemaDrift(plan, options = {}) {
+  const dialect = options.dialect ?? config5.dialect;
+  const declaredTables = plan.tables.map((table) => table.table);
+  const live = await introspectDatabase({ tables: declaredTables });
+  const byTable = new Map(live.map((model) => [model.table.toLowerCase(), model]));
+  const missingTables = [];
+  const missingColumns = [];
+  const typeMismatches = [];
+  for (const table of plan.tables) {
+    const liveTable = byTable.get(table.table.toLowerCase());
+    if (!liveTable) {
+      missingTables.push(table.table);
+      continue;
+    }
+    const liveColumns = new Map(liveTable.columns.map((column) => [column.name.toLowerCase(), column]));
+    for (const column of table.columns) {
+      const liveColumn = liveColumns.get(column.name.toLowerCase());
+      const declared = familyOfDeclared(column.type);
+      if (!liveColumn) {
+        missingColumns.push({ table: table.table, column: column.name, expected: declared });
+        continue;
+      }
+      const actual = familyOfSqlType(liveColumn.sqlType);
+      if (!satisfies(declared, actual)) {
+        typeMismatches.push({
+          table: table.table,
+          column: column.name,
+          expected: declared,
+          actual,
+          actualSqlType: liveColumn.sqlType
+        });
+      }
+    }
+  }
+  return {
+    missingTables,
+    missingColumns,
+    typeMismatches,
+    clean: missingTables.length === 0 && missingColumns.length === 0 && typeMismatches.length === 0
+  };
+}
+function formatSchemaDrift(drift) {
+  if (drift.clean)
+    return "";
+  const lines = [];
+  if (drift.missingTables.length > 0)
+    lines.push(`  Missing tables: ${drift.missingTables.join(", ")}`);
+  for (const column of drift.missingColumns.slice(0, 10))
+    lines.push(`  \u2022 ${column.table}.${column.column} is missing (models declare ${column.expected})`);
+  for (const mismatch of drift.typeMismatches.slice(0, 10))
+    lines.push(`  \u2022 ${mismatch.table}.${mismatch.column} is ${mismatch.actualSqlType}, models declare ${mismatch.expected}`);
+  const shown = Math.min(drift.missingColumns.length, 10) + Math.min(drift.typeMismatches.length, 10);
+  const total = drift.missingColumns.length + drift.typeMismatches.length;
+  if (total > shown)
+    lines.push(`  + ${total - shown} more`);
+  return [
+    "The live schema does not match the models.",
+    ...lines,
+    "",
+    "Migrations will NOT fix this on their own: the runner only applies files that have",
+    "not run yet, and a corrected `CREATE TABLE IF NOT EXISTS` is a no-op against a table",
+    "that already exists. Regenerate and apply the difference, or rebuild the schema."
+  ].join(`
+`);
+}
+var init_schema_drift = __esm(() => {
+  init_config();
+  init_introspect_db();
+});
+
 // src/index.ts
 var init_src2 = __esm(() => {
   init_model2();
   init_model2();
+  init_schema_drift();
   init_actions();
   init_browser();
   init_client();
@@ -30139,6 +30268,7 @@ export {
   setConfig,
   seedModel,
   saveMigrationSnapshot,
+  satisfies,
   runSeeders,
   runSeeder,
   runBenchmark,
@@ -30202,7 +30332,10 @@ export {
   relationDiagram as generateDiagram,
   generateAccessPatterns,
   freshDatabase,
+  formatSchemaDrift,
   file,
+  familyOfSqlType,
+  familyOfDeclared,
   extractTableDefinition,
   extractModelSchema,
   extractInsertId,
@@ -30257,6 +30390,7 @@ export {
   buildDatabaseSchema,
   browserQuery,
   browserAuth,
+  auditSchemaDrift,
   applySqliteBootstrapPragmas,
   VitessDriver,
   SingleTableRepository,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bun-query-builder",
   "type": "module",
-  "version": "0.2.35",
+  "version": "0.2.36",
   "description": "A simple yet performant query builder for TypeScript. Built with Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",