fix(database): make introspect -> verify roundtrip drift-free

Author: ditadi

packages/appkit/src/database/introspector/diff.ts

@@ -36,7 +36,7 @@ export function diffIntrospections(
       entries.push({
         severity: "warn",
         kind: "live-only",
-        message: `+ table ${key} (exists in db, missing in schema.ts)`,
+        message: `table ${key} (exists in db, missing in schema.ts)`,
       });
       continue;
     }
@@ -48,7 +48,7 @@ export function diffIntrospections(
       entries.push({
         severity: "warn",
         kind: "schema-only",
-        message: `- table ${key} (in schema.ts, missing in db)`,
+        message: `table ${key} (in schema.ts, missing in db)`,
       });
     }
   }
@@ -72,7 +72,7 @@ function diffColumns(
       entries.push({
         severity: "warn",
         kind: "live-only",
-        message: `+ column ${key}.${name} (in db, missing in schema.ts)`,
+        message: `column ${key}.${name} (in db, missing in schema.ts)`,
       });
       continue;
     }
@@ -81,7 +81,7 @@ function diffColumns(
       entries.push({
         severity: "warn",
         kind: "type-mismatch",
-        message: `~ column ${key}.${name} (${declaredCol.pgType} declared, ${liveCol.pgType} in db)`,
+        message: `column ${key}.${name} (${declaredCol.pgType} declared, ${liveCol.pgType} in db)`,
       });
     }
     diffColumnMetadata(key, name, liveCol, declaredCol, entries);
@@ -92,7 +92,7 @@ function diffColumns(
       entries.push({
         severity: "warn",
         kind: "schema-only",
-        message: `- column ${key}.${name} (in schema.ts, missing in db)`,
+        message: `column ${key}.${name} (in schema.ts, missing in db)`,
       });
     }
   }
@@ -109,6 +109,13 @@ function tableKey(table: Pick<IntrospectedTable, "schema" | "name">): string {
  * Runtime writes and migrations depend on nullability, defaults, keys,
  * generated columns, and FK actions, so drift detection must compare the
  * metadata captured by introspection instead of stopping at `pgType`.
+ *
+ * Server-generated columns get special treatment: when both sides agree the
+ * column is server-generated, we skip `hasDefault` and `defaultExpression`
+ * comparisons because the live DB stores the literal `nextval(...)` /
+ * `GENERATED AS IDENTITY` expression while the schema models the same fact
+ * as `serverGenerated: true` metadata. Comparing them would produce noise on
+ * every introspect → verify roundtrip for serial / bigserial / identity PKs.
  */
 function diffColumnMetadata(
   table: string,
@@ -125,22 +132,28 @@ function diffColumnMetadata(
     declared.nullable,
     entries,
   );
-  compareField(
-    table,
-    column,
-    "hasDefault",
-    live.hasDefault,
-    declared.hasDefault,
-    entries,
-  );
-  compareField(
-    table,
-    column,
-    "defaultExpression",
-    live.defaultExpression,
-    declared.defaultExpression,
-    entries,
-  );
+
+  const bothServerGenerated =
+    Boolean(live.serverGenerated) && Boolean(declared.serverGenerated);
+  if (!bothServerGenerated) {
+    compareField(
+      table,
+      column,
+      "hasDefault",
+      live.hasDefault,
+      declared.hasDefault,
+      entries,
+    );
+    compareField(
+      table,
+      column,
+      "defaultExpression",
+      normalizeDefaultExpression(live.defaultExpression),
+      normalizeDefaultExpression(declared.defaultExpression),
+      entries,
+    );
+  }
+
   compareField(
     table,
     column,
@@ -149,22 +162,24 @@ function diffColumnMetadata(
     Boolean(declared.isPrimaryKey),
     entries,
   );
-  compareField(
-    table,
-    column,
-    "serverGenerated",
-    Boolean(live.serverGenerated),
-    Boolean(declared.serverGenerated),
-    entries,
-  );
+  if (live.isPrimaryKey || declared.isPrimaryKey) {
+    compareField(
+      table,
+      column,
+      "serverGenerated",
+      Boolean(live.serverGenerated),
+      Boolean(declared.serverGenerated),
+      entries,
+    );
+  }
 
   const liveRef = normalizeReference(live.references);
   const declaredRef = normalizeReference(declared.references);
   if (liveRef !== declaredRef) {
     entries.push({
       severity: "warn",
       kind: "type-mismatch",
-      message: `~ column ${table}.${column} foreign key (${declaredRef} declared, ${liveRef} in db)`,
+      message: `column ${table}.${column} foreign key (${declaredRef} declared, ${liveRef} in db)`,
     });
   }
 }
@@ -182,7 +197,7 @@ function compareField(
   entries.push({
     severity: "warn",
     kind: "type-mismatch",
-    message: `~ column ${table}.${column} ${field} (${formatValue(
+    message: `column ${table}.${column} ${field} (${formatValue(
       declared,
     )} declared, ${formatValue(live)} in db)`,
   });
@@ -206,3 +221,34 @@ function normalizeReference(
 function formatValue(value: unknown): string {
   return value === undefined ? "undefined" : JSON.stringify(value);
 }
+
+/**
+ * Strip the trivial `'literal'::type` cast Postgres emits around quoted
+ * string defaults so that `'member'::text` (live) compares equal to `member`
+ * (declared). Also unescapes `''` -> `'` inside the literal.
+ *
+ * Deliberately conservative:
+ *   - Matches a SINGLE quoted literal followed by a single `::type` cast.
+ *   - Does NOT touch expressions that contain `||`, function calls, or
+ *     additional casts — those are kept verbatim and compared as-is so we
+ *     don't claim equality between two non-trivially-different expressions
+ *     and silently miss real drift. Example: `'foo'::text || 'bar'::text`
+ *     and `'foobar'` stay distinct.
+ */
+function normalizeDefaultExpression(
+  value: string | undefined,
+): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  const castedString = SIMPLE_CAST_LITERAL.exec(trimmed);
+  if (castedString) return castedString[1].replaceAll("''", "'");
+  return trimmed;
+}
+
+/**
+ * Matches `'literal'::type` where the literal is a single quoted string with
+ * `''` escaping and the type is a simple identifier (no parens, no `||`,
+ * no further casts).
+ */
+const SIMPLE_CAST_LITERAL =
+  /^'((?:[^']|'')*)'::[a-zA-Z_][\w]*(?:\s*\(\s*\d+\s*\))?$/;

packages/appkit/src/database/introspector/drizzle-adapter.ts

@@ -49,12 +49,16 @@ function adaptColumn(
     hasDefault: column.hasDefault,
   };
 
-  if (column.default !== undefined)
-    adapted.defaultExpression = String(column.default);
+  if (column.default !== undefined) {
+    adapted.defaultExpression = stringifyDefault(column.default);
+  }
   if (column.primary) adapted.isPrimaryKey = true;
   if (
     meta?.serverGenerated ||
-    (column.hasDefault && column.columnType === "PgSerial")
+    (column.hasDefault &&
+      (column.columnType === "PgSerial" ||
+        column.columnType === "PgBigSerial53" ||
+        column.columnType === "PgBigSerial64"))
   ) {
     adapted.serverGenerated = true;
   }
@@ -75,14 +79,42 @@ function adaptColumn(
   return adapted;
 }
 
-/** Convert a Drizzle column type to a Postgres type. */
+function stringifyDefault(value: unknown): string {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    Array.isArray((value as { queryChunks?: unknown }).queryChunks)
+  ) {
+    const chunks = (value as { queryChunks: Array<{ value?: unknown }> })
+      .queryChunks;
+    return chunks
+      .map((chunk) => {
+        if (Array.isArray(chunk.value)) return chunk.value.join("");
+        return chunk.value === undefined ? String(chunk) : String(chunk.value);
+      })
+      .join("");
+  }
+
+  return String(value);
+}
+
+/**
+ * Convert a Drizzle column type to a Postgres `udt_name` value.
+ *
+ * Postgres returns `int4` for `serial` and `int8` for `bigserial` from
+ * `information_schema.columns.udt_name`, so we collapse the auto-incrementing
+ * and plain-integer Drizzle types to the same wire type. The `serverGenerated`
+ * flag tracks the sequence-vs-no-sequence distinction separately.
+ */
 function drizzleTypeToPgType(column: DrizzleColumn): string {
   switch (column.columnType) {
     case "PgSerial":
     case "PgInteger":
       return "int4";
     case "PgBigInt":
     case "PgBigInt53":
+    case "PgBigSerial53":
+    case "PgBigSerial64":
       return "int8";
     case "PgText":
       return "text";

packages/appkit/src/database/introspector/render.ts

@@ -6,7 +6,7 @@ import type {
 } from "./types";
 
 const HEADER = `// AUTO-GENERATED by \`appkit db introspect\`. Review before committing.
-import { defineSchema, bigint, boolean, fk, id, integer, jsonb, text, timestamp, uuid, varchar } from "@databricks/appkit";
+import { defineSchema, bigid, bigint, boolean, fk, id, integer, jsonb, text, timestamp, uuid, varchar } from "@databricks/appkit";
 
 export default defineSchema(({ table }) => {
 `;