@everystack/cli 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -74,7 +74,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.3.3"
+    "@everystack/model": "0.3.4"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",

package/src/cli/authz-compile.ts

@@ -48,7 +48,8 @@ function castForType(type: string): string {
     case 'uuid': return 'uuid';
     case 'bigint':
     case 'bigserial': return 'bigint';
-    case 'integer': return 'integer';
+    case 'integer':
+    case 'serial': return 'integer';
     default: return type;
   }
 }

package/src/cli/commands/db-pull.ts

@@ -1,7 +1,7 @@
 /**
  * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
  *
- *   db:pull [--stage <name> | --database-url <url>] [--schema public] [--out models/index.ts]
+ *   db:pull [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>]
  *
  * The reverse of db:generate: that writes migrations FROM Models; this writes Models FROM the
  * database. It introspects the deployed schema through the read-only ops Lambda `db:query`
@@ -11,15 +11,19 @@
  * starting point you review and refine (it flags, as inline comments, anything the field
  * builder can't yet express).
  *
- * The rendered source is the artifact: it goes to stdout (so `db:pull > models.ts` works) or
- * to `--out`. Every progress/diagnostic line goes to stderr, so the stdout pipe stays pure
- * source. The renderer (model-render.ts) is pure; this shell is the IO.
+ * The rendered source is the artifact. An `--out` that is a directory (anything not ending
+ * in `.ts` — `--out models` is the canonical form) is the DEFAULT shape: one file per model
+ * plus an `index.ts` assembling the `models` array, because a real schema pulled as a single
+ * module is unreviewable. An `--out` ending in `.ts` writes the single-module form; with no
+ * `--out` the single module goes to stdout (so `db:pull > models.ts` works). Every
+ * progress/diagnostic line goes to stderr, so the stdout pipe stays pure source. The
+ * renderers (model-render.ts) are pure; this shell is the IO.
  */
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { introspectSchema } from '../schema-introspect.js';
-import { renderModelSource } from '../model-render.js';
+import { renderModelSource, renderModelFiles, pullableTables } from '../model-render.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
@@ -80,16 +84,34 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
-  const pulled = current.tables.filter((t) => t.table.startsWith(`${schema}.`));
+  const pulled = pullableTables(current, schema);
   if (pulled.length === 0) {
     fail(`No tables found in schema "${schema}".`);
     process.exit(1);
   }
 
-  const source = renderModelSource(current, { schema });
-
-  if (flags.out) {
+  let source: string;
+  if (flags.out && !flags.out.endsWith('.ts')) {
+    // A directory: one file per model + index.ts — the default shape for a real app.
+    const dir = path.resolve(flags.out);
+    const files = renderModelFiles(current, { schema });
+    try {
+      await fs.mkdir(dir, { recursive: true });
+      const written = new Set(files.map((f) => f.file));
+      const existing = (await fs.readdir(dir)).filter((f) => f.endsWith('.ts') && !written.has(f));
+      for (const f of files) await fs.writeFile(path.join(dir, f.file), f.source, 'utf8');
+      if (existing.length) {
+        caution(`${existing.length} existing .ts file(s) in ${path.relative(process.cwd(), dir)} were not part of this pull and were left untouched: ${existing.join(', ')}`);
+      }
+    } catch (err: any) {
+      fail(`Could not write ${flags.out}: ${err.message}`);
+      process.exit(1);
+    }
+    ok(`Wrote ${files.length - 1} model file(s) + index.ts to ${path.relative(process.cwd(), dir)}.`);
+    source = files.map((f) => f.source).join('\n');
+  } else if (flags.out) {
     const outPath = path.resolve(flags.out);
+    source = renderModelSource(current, { schema });
     try {
       await fs.mkdir(path.dirname(outPath), { recursive: true });
       await fs.writeFile(outPath, source, 'utf8');
@@ -99,6 +121,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${pulled.length} model(s).`);
   } else {
+    source = renderModelSource(current, { schema });
     process.stdout.write(source);
     ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
   }

package/src/cli/index.ts

@@ -288,7 +288,7 @@ Usage:
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models models/index.ts] [--allow-drops]  Diff models vs the live DB → write the next migration (never touches the DB; DROPs held back unless --allow-drops)
-  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <file>]  Introspect the live DB → render field() Models (the brownfield on-ramp; stdout unless --out)
+  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
   everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)

package/src/cli/model-render.ts

@@ -67,6 +67,8 @@ const FIELD_FACTORY: Record<string, string> = {
   text: 'text',
   integer: 'integer',
   bigint: 'bigint',
+  real: 'real',
+  'double precision': 'doublePrecision',
   boolean: 'boolean',
   jsonb: 'jsonb',
   date: 'date',
@@ -82,6 +84,13 @@ const FIELD_FACTORY: Record<string, string> = {
  * scale-0 numeric renders as the cleaner `field.numeric(p)` (identical to `(p, 0)`).
  */
 export function fieldFactoryCall(type: string): string | null {
+  // An array is its base type + `.array()` — exactly how the compiler emits it
+  // (`format_type` spells arrays `text[]`). An array of an unmapped base stays null.
+  if (type.endsWith('[]')) {
+    const base = fieldFactoryCall(type.slice(0, -2));
+    return base ? `${base}.array()` : null;
+  }
+
   const direct = FIELD_FACTORY[type];
   if (direct) return `field.${direct}()`;
 
@@ -102,6 +111,19 @@ function bareName(table: string): string {
   return table.replace(/^[^.]+\./, '');
 }
 
+/** Migration infrastructure a pull must never render as a model, whatever schema it landed in. */
+const INFRASTRUCTURE_TABLES = new Set(['__drizzle_migrations']);
+
+/**
+ * The tables a pull renders: the requested schema, minus migration infrastructure.
+ * drizzle-kit keeps its journal in the `drizzle` schema, but a restored or legacy
+ * database can carry `public.__drizzle_migrations` — the journal is tooling state,
+ * never an app model. Exported so the command shell counts the same set it writes.
+ */
+export function pullableTables(snapshot: SchemaSnapshot, schema: string): TableSchema[] {
+  return snapshot.tables.filter((t) => t.table.startsWith(`${schema}.`) && !INFRASTRUCTURE_TABLES.has(bareName(t.table)));
+}
+
 /** A table name → its model variable: PascalCase, naively singularized. `image_variants` → `ImageVariant`. */
 export function modelVarName(table: string): string {
   const bare = bareName(table);
@@ -109,9 +131,17 @@ export function modelVarName(table: string): string {
   return singular.split('_').filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
 }
 
-/** `author_id` → `authorId` (a SQL column to its camelCase field key — the inverse of the compiler's snake_case). */
+/**
+ * `author_id` → `authorId` — a SQL column to its field key, LOSSLESSLY: the compiler's
+ * snake_case must reconstruct the exact column (`snake(key) === column`, always). Only a
+ * letter after `_` camelizes, because only a capital letter survives the trip back — an
+ * underscore before a digit is preserved (`yardline_100` stays `yardline_100`,
+ * `top_3_best` → `top_3Best`). Swallowing it (the old `_([a-z0-9])` rule) generated a
+ * phantom rename for every digit-boundary column and COLLIDED distinct columns
+ * (`a_1` and `a1`) onto one key.
+ */
 function toCamelCase(name: string): string {
-  return name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
 
 /** The `.default*()` modifier for a column default, or null when the expression isn't one we map. */
@@ -132,20 +162,37 @@ function tsLiteral(value: string): string {
   return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 
+/**
+ * The `field.serial()`/`field.bigserial()` factory for an integer/bigint column whose
+ * default is its own conventional sequence (`<table>_<column>_seq`, optionally
+ * schema-qualified — the deparser qualifies it when the schema is off the search_path).
+ * A nextval on any OTHER sequence is not a serial declaration and stays surfaced.
+ */
+function serialFactoryCall(table: TableSchema, col: ColumnSchema): string | null {
+  const factory = col.type === 'integer' ? 'serial' : col.type === 'bigint' ? 'bigserial' : null;
+  if (!factory || col.default == null) return null;
+  const m = col.default.match(/^nextval\('(?:[^'.]+\.)?([^'.]+)'::regclass\)$/);
+  if (!m || m[1] !== `${bareName(table.table)}_${col.name}_seq`) return null;
+  return `field.${factory}()`;
+}
+
 /** One field line: `    authorId: field.uuid().notNull().references(() => Profile),` (+ any surfacing comment). */
 function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>, enums: Map<string, string[]>, validates: Map<string, string>): string {
   // An enum column's type is the enum's name; render the explicit-name field.enum with its
   // values (the always-explicit form round-trips the name and the value order).
   const enumValues = enums.get(col.type);
-  const call = enumValues
-    ? `field.enum(${tsLiteral(col.type)}, [${enumValues.map(tsLiteral).join(', ')}])`
-    : fieldFactoryCall(col.type);
+  const serial = serialFactoryCall(table, col);
+  const call = serial
+    ?? (enumValues
+      ? `field.enum(${tsLiteral(col.type)}, [${enumValues.map(tsLiteral).join(', ')}])`
+      : fieldFactoryCall(col.type));
   let expr = call ?? 'field.text()';
   let comment = call ? '' : ` // FIXME: column type '${col.type}' has no field mapping`;
 
   const isPk = table.primaryKey.includes(col.name);
   if (isPk) expr += '.primaryKey()';
-  else if (col.notNull) expr += '.notNull()';
+  // A serial field is NOT NULL by construction, so the modifier would be redundant.
+  else if (col.notNull && !serial) expr += '.notNull()';
 
   if (table.uniques.some((u) => u.columns.length === 1 && u.columns[0] === col.name)) expr += '.unique()';
 
@@ -161,7 +208,7 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
     } else comment += ` // FK → ${fk.refTable} (not in the pulled set)`;
   }
 
-  if (col.default != null) {
+  if (col.default != null && !serial) {
     const d = renderDefault(col.default);
     if (d) expr += d;
     else comment += ` // TODO: unmapped default ${col.default}`;
@@ -232,6 +279,19 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n  fields: {\n${fields}\n  },${constraints}\n});`;
 }
 
+/** The `import` lines a rendered body needs — only what it actually uses, so the file reads clean. */
+function importHeader(body: string): string {
+  const symbols = ['defineModel', 'field'];
+  if (/\bunique\(/.test(body)) symbols.push('unique');
+  if (/\bcheck\(/.test(body)) symbols.push('check');
+  if (/\bindex\(/.test(body)) symbols.push('index');
+  if (/\bforeignKey\(/.test(body)) symbols.push('foreignKey');
+  if (/\bsql`/.test(body)) symbols.push('sql');
+  const imports = [`import { ${symbols.join(', ')} } from '@everystack/model';`];
+  if (/\.validate\(/.test(body)) imports.push(`import { z } from 'zod';`);
+  return imports.join('\n');
+}
+
 /**
  * Render a whole snapshot as a single Models module: the import, one block per table (scoped
  * to `opts.schema`), and the `models` array the rest of the framework consumes. The tables
@@ -239,24 +299,71 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
  */
 export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions = {}): string {
   const schema = opts.schema ?? 'public';
-  const tables = snapshot.tables.filter((t) => t.table.startsWith(`${schema}.`));
+  const tables = pullableTables(snapshot, schema);
   const known = new Set(tables.map((t) => bareName(t.table)));
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
   const blocks = tables.map((t) => renderModelBlock(t, known, enums));
   const body = blocks.join('\n\n');
 
-  // Import only what the rendered models actually use, so the file reads clean.
-  const symbols = ['defineModel', 'field'];
-  if (/\bunique\(/.test(body)) symbols.push('unique');
-  if (/\bcheck\(/.test(body)) symbols.push('check');
-  if (/\bindex\(/.test(body)) symbols.push('index');
-  if (/\bforeignKey\(/.test(body)) symbols.push('foreignKey');
-  if (/\bsql`/.test(body)) symbols.push('sql');
-  const imports = [`import { ${symbols.join(', ')} } from '@everystack/model';`];
-  if (/\.validate\(/.test(body)) imports.push(`import { z } from 'zod';`);
-  const header = imports.join('\n');
+  const header = importHeader(body);
   const footer = `export const models = [${tables.map((t) => modelVarName(t.table)).join(', ')}];`;
 
   return [header, ...blocks, footer].join('\n\n') + '\n';
 }
+
+/** `image_variants` → `image-variants.ts` — the repo's kebab-case file convention. */
+function modelFileName(table: string): string {
+  return `${bareName(table).replace(/_/g, '-')}.ts`;
+}
+
+/** The bare tables (other than itself) a table's rendered FKs reference within the pulled set. */
+function referencedTables(table: TableSchema, known: Set<string>): string[] {
+  const self = bareName(table.table);
+  const refs = new Set<string>();
+  for (const fk of table.foreignKeys) {
+    const target = bareName(fk.refTable);
+    if (target !== self && known.has(target)) refs.add(target);
+  }
+  return [...refs].sort();
+}
+
+export interface RenderedModelFile {
+  /** File name relative to the output directory (`posts.ts`, …, `index.ts` last). */
+  file: string;
+  source: string;
+}
+
+/**
+ * Render a snapshot as one file per model plus an `index.ts` — the shape a real app keeps
+ * its models in (a 200-table pull as a single module is unreviewable). Each model file
+ * imports its own `@everystack/model` symbols and its FK targets from their sibling files
+ * (extensionless specifiers — Metro and TS bundler resolution both take them; the
+ * `() => Model` thunks make circular FK imports safe). The index re-exports every model
+ * and assembles the `models` array the rest of the framework consumes.
+ */
+export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions = {}): RenderedModelFile[] {
+  const schema = opts.schema ?? 'public';
+  const tables = pullableTables(snapshot, schema);
+  const known = new Set(tables.map((t) => bareName(t.table)));
+  const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
+
+  const files: RenderedModelFile[] = tables.map((t) => {
+    const block = renderModelBlock(t, known, enums);
+    const crossImports = referencedTables(t, known).map(
+      (target) => `import { ${modelVarName(target)} } from './${bareName(target).replace(/_/g, '-')}';`,
+    );
+    const header = [importHeader(block), ...crossImports].join('\n');
+    return { file: modelFileName(t.table), source: `${header}\n\n${block}\n` };
+  });
+
+  const names = tables.map((t) => modelVarName(t.table));
+  const index = [
+    names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`).join('\n'),
+    `export {\n${names.map((n) => `  ${n},`).join('\n')}\n};`,
+    `export const models = [\n${names.map((n) => `  ${n},`).join('\n')}\n];`,
+  ].join('\n\n');
+  files.push({ file: 'index.ts', source: index + '\n' });
+
+  return files;
+}

package/src/cli/output.ts

@@ -4,8 +4,10 @@
  * No spinner library — step markers work in CI/CD and terminals alike.
  */
 
+// Progress is diagnostics, never data — stderr, so a codegen command (db:pull) keeps a
+// pure stdout for redirects even when shared plumbing (resolveConfig discovery) reports.
 export function step(msg: string): void {
-  console.log(`  > ${msg}`);
+  console.error(`  > ${msg}`);
 }
 
 export function success(msg: string): void {

package/src/cli/runbook/model-section.ts

@@ -0,0 +1,112 @@
+/**
+ * renderDataModelSection — the app's Models, rendered for the runbook.
+ *
+ * The one chapter no generic doc can carry: this app's tables, fields,
+ * relations, and declared abilities. Compiled from the same ModelDescriptors
+ * db:generate consumes, so it can never describe a schema the app doesn't
+ * have — and an ability change shows up as runbook drift (`runbook --check`).
+ */
+
+import type { Ability, FieldSpec, ModelDescriptor, Relation } from '@everystack/model';
+
+function typeLabel(spec: FieldSpec): string {
+  let base: string;
+  switch (spec.type) {
+    case 'varchar':
+      base = spec.length != null ? `varchar(${spec.length})` : 'varchar';
+      break;
+    case 'numeric':
+      base =
+        spec.precision != null
+          ? `numeric(${spec.precision}${spec.scale != null ? `, ${spec.scale}` : ''})`
+          : 'numeric';
+      break;
+    case 'enum':
+      base = spec.enumValues ? `enum(${spec.enumValues.join(' | ')})` : 'enum';
+      break;
+    default:
+      base = spec.type;
+  }
+  return spec.isArray ? `${base}[]` : base;
+}
+
+function referenceTarget(spec: FieldSpec): string | null {
+  if (!spec.references) return null;
+  try {
+    const target = spec.references() as { table?: string } | undefined;
+    return target?.table ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function fieldLine(name: string, spec: FieldSpec): string {
+  const parts = [typeLabel(spec)];
+  if (spec.isPrimaryKey) parts.push('pk');
+  if (spec.isNotNull && !spec.isPrimaryKey) parts.push('not null');
+  if (spec.isUnique) parts.push('unique');
+  const target = referenceTarget(spec);
+  if (target) {
+    parts.push(`→ ${target}${spec.onDelete && spec.onDelete !== 'no action' ? ` (${spec.onDelete})` : ''}`);
+  }
+  if (spec.defaultKind === 'now') parts.push('default: now()');
+  else if (spec.defaultKind === 'random') parts.push('default: random');
+  else if (spec.defaultKind === 'value') parts.push(`default: ${JSON.stringify(spec.default)}`);
+  if (spec.isPrivate) parts.push('private (never serialized)');
+  if (spec.isReadonly) parts.push('readonly (never writable via the API)');
+  return `- \`${name}\` — ${parts.join(', ')}`;
+}
+
+function abilityLine(a: Ability): string {
+  const verb = a.action === 'manage' ? 'manage (all actions)' : a.action;
+  const c = a.condition ?? {};
+  const scope: string[] = [];
+  if (c.role) scope.push(`role \`${c.role}\``);
+  if (c.owner) scope.push(`owner (\`${c.owner}\`)`);
+  if (c.via) scope.push(`owner via \`${c.via}\``);
+  if (c.where || c.sql) scope.push('custom predicate');
+  const columns = c.columns ? ` — columns: ${c.columns.map((col) => `\`${col}\``).join(', ')}` : '';
+  return `- ${verb}: ${scope.length ? scope.join(', ') : 'anyone'}${columns}`;
+}
+
+function relationLine(name: string, rel: Relation): string {
+  let target = 'unknown';
+  try {
+    target = rel.target().table;
+  } catch {
+    /* forward reference that can't resolve here — label stays unknown */
+  }
+  const shape = rel.kind === 'belongsTo' ? 'belongs to' : 'has many';
+  return `- \`${name}\` — ${shape} ${target} (via \`${rel.column}\`)`;
+}
+
+export function renderDataModelSection(models: ModelDescriptor[]): string {
+  const lines: string[] = [
+    '## Your data model',
+    '',
+    "Compiled from the app's Models — edit `models/` and regenerate; never edit this section.",
+  ];
+  for (const m of models) {
+    const heading = m.schema && m.schema !== 'public' ? `${m.schema}.${m.table}` : m.table;
+    lines.push('', `### ${heading}`, '');
+    const annotations: string[] = [];
+    if (m.private) annotations.push('not exposed via the generic API');
+    if (m.writtenBy !== 'app') annotations.push(`written by ${m.writtenBy}`);
+    if (annotations.length) lines.push(`_Operational table — ${annotations.join('; ')}._`, '');
+    for (const [name, builder] of Object.entries(m.fields)) {
+      lines.push(fieldLine(name, builder.spec));
+    }
+    const relations = Object.entries(m.relations ?? {});
+    if (relations.length) {
+      lines.push('', 'Relations:', '');
+      for (const [name, rel] of relations) lines.push(relationLine(name, rel));
+    }
+    lines.push('', 'Access:', '');
+    if (m.abilities.length === 0) {
+      lines.push('- no abilities declared — nobody can reach this table through the API');
+    } else {
+      for (const a of m.abilities) lines.push(abilityLine(a));
+    }
+  }
+  return lines.join('\n');
+}

package/src/cli/schema-compile.ts

@@ -68,7 +68,14 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
   return { uniques, checks, indexes };
 }
 
-/** Postgres type for a field, with the precision drizzle-kit would emit. */
+/**
+ * Postgres type for a field, with the precision drizzle-kit would emit — in
+ * `format_type`'s vocabulary, because this feeds the IR that diffs against
+ * introspection. A serial field's *column type* is integer/bigint (`serial` is
+ * DDL shorthand, not a type — `format_type` never reports it); the sequence
+ * default is carried separately (see compileTableSchema), and the DDL renderers
+ * spell the shorthand (see SERIAL_DDL).
+ */
 const PG_TYPE: Record<string, string> = {
   text: 'text',
   uuid: 'uuid',
@@ -76,7 +83,10 @@ const PG_TYPE: Record<string, string> = {
   boolean: 'boolean',
   jsonb: 'jsonb',
   bigint: 'bigint',
-  bigserial: 'bigserial',
+  serial: 'integer',
+  bigserial: 'bigint',
+  real: 'real',
+  doublePrecision: 'double precision',
   timestamptz: 'timestamp with time zone',
   // `format_type` canonicalizes a bare `timestamp` column to this spelling, and
   // introspection compares against it — so the compiler must emit the same, or an
@@ -221,15 +231,26 @@ function literal(value: unknown): string {
   return String(value);
 }
 
+/** The DDL shorthand for the sequence-backed types — CREATE/ADD COLUMN must use it (it creates the sequence). */
+const SERIAL_DDL: Partial<Record<FieldSpec['type'], string>> = { serial: 'serial', bigserial: 'bigserial' };
+
+/** The implicit sequence a serial column owns, as `pg_get_expr` deparses its default. */
+function serialDefault(table: string, sqlName: string): string {
+  return `nextval('${table}_${sqlName}_seq'::regclass)`;
+}
+
 /**
  * One column definition (no leading indent). Clause order matches drizzle's:
  * type, PRIMARY KEY (single-column only), DEFAULT, NOT NULL. `.references()`,
  * `.unique()`, and composite PKs are table-level, emitted by compileCreateTable.
+ * A serial field renders the `serial` shorthand and no DEFAULT — the shorthand
+ * creates the backing sequence a bare nextval default could not reference.
  */
 export function fieldColumnSql(sqlName: string, spec: FieldSpec, inlinePrimaryKey: boolean): string {
-  let s = `"${sqlName}" ${pgType(spec)}`;
+  const serial = SERIAL_DDL[spec.type];
+  let s = `"${sqlName}" ${serial ?? pgType(spec)}`;
   if (inlinePrimaryKey) s += ' PRIMARY KEY';
-  const def = defaultExpr(spec);
+  const def = serial ? null : defaultExpr(spec);
   if (def) s += ` DEFAULT ${def}`;
   if (spec.isNotNull) s += ' NOT NULL';
   return s;
@@ -394,12 +415,23 @@ export function compileTableSchema(model: ModelDescriptor, opts: { schema?: stri
   const schema = model.schema ?? opts.schema ?? 'public';
   const entries = Object.entries(model.fields);
 
-  const columns = entries.map(([name, field]) => ({
-    name: toSnakeCase(name),
-    type: pgType(field.spec),
-    notNull: field.spec.isNotNull,
-    default: defaultExpr(field.spec),
-  }));
+  // A serial column's IR is the pg-precise truth introspection reports: integer/bigint
+  // (PG_TYPE), NOT NULL, and the implicit sequence's nextval default — so an unchanged
+  // serial column diffs clean. The `serial` shorthand exists only in the DDL renderers.
+  const columns = entries.map(([name, field]) => {
+    const sqlName = toSnakeCase(name);
+    const isSerial = field.spec.type in SERIAL_DDL;
+    return {
+      name: sqlName,
+      type: pgType(field.spec),
+      notNull: field.spec.isNotNull || isSerial,
+      // The deparser qualifies the sequence only when its schema is off the search_path,
+      // so a public table's sequence stays bare and a package-schema one is qualified.
+      default: isSerial
+        ? serialDefault(schema === 'public' ? model.table : `${schema}.${model.table}`, sqlName)
+        : defaultExpr(field.spec),
+    };
+  });
 
   const tableConstraints = modelConstraintSpecs(model);
 

package/src/cli/schema-diff.ts

@@ -111,6 +111,12 @@ export function normalizeDefault(expr: string | null): string | null {
   } while (s !== prev);
 
   if (/^current_timestamp$/i.test(s)) return 'now()';
+
+  // The deparser qualifies a sequence name only when its schema is off the search_path,
+  // so the same serial default reads `nextval('x_seq')` on one database and
+  // `nextval('public.x_seq')` on another. public is always on the search_path — strip it.
+  s = s.replace(/^nextval\('public\.([^']+)'/, "nextval('$1'");
+
   return s;
 }
 
@@ -124,6 +130,9 @@ export type TypeChangeRisk = 'safe' | 'lossy' | 'risky';
 /** Integer/numeric widening rank — a value at a lower rank always fits a higher one. */
 const NUMERIC_RANK: Record<string, number> = { smallint: 1, integer: 2, bigint: 3, numeric: 4 };
 
+/** Float widening rank — float4 always fits float8. */
+const FLOAT_RANK: Record<string, number> = { real: 1, 'double precision': 2 };
+
 /** Split a `format_type` string into its base and any precision/length args: `numeric(12,2)` -> {base:'numeric', args:[12,2]}. */
 function parseType(t: string): { base: string; args: number[] } {
   const m = t.match(/^(.*?)\s*\(([^)]*)\)\s*$/);
@@ -157,6 +166,18 @@ export function classifyTypeChange(from: string, to: string): TypeChangeRisk {
     return tr > fr ? 'safe' : 'lossy'; // widen up the integer/numeric ranks is safe; down can overflow
   }
 
+  const ff = FLOAT_RANK[f.base];
+  const tf = FLOAT_RANK[t.base];
+  if (ff && tf) return tf >= ff ? 'safe' : 'lossy'; // float widening is exact; narrowing rounds
+  // A true integer type into a float is safe only when the mantissa provably holds every
+  // value (smallint fits both; integer fits float8's 53 bits but not float4's 24);
+  // otherwise it rounds — lossy, never failing. numeric is excluded (its range exceeds
+  // float8, so the cast can fail), and a float into anything narrower falls through to
+  // risky: an out-of-range cast (1e300::integer) fails per row.
+  if ((f.base === 'smallint' || f.base === 'integer' || f.base === 'bigint') && tf) {
+    return f.base === 'smallint' || (f.base === 'integer' && t.base === 'double precision') ? 'safe' : 'lossy';
+  }
+
   if (f.base === t.base) return argsWiden(f.args, t.args) ? 'safe' : 'lossy'; // same base, only precision/length moved
 
   const timestamps = new Set(['timestamp', 'timestamp with time zone', 'timestamp without time zone']);
@@ -408,16 +429,25 @@ function diffColumns(d: TableSchema, c: TableSchema, tableRenames: Record<string
   return out;
 }
 
+/** A table's uniques and foreign keys as ConstraintSpecs (the shape addConstraintSql renders). */
+function tableConstraintSpecs(t: TableSchema): ConstraintSpec[] {
+  return [
+    ...t.uniques.map((u): ConstraintSpec => ({ type: 'unique', name: u.name, columns: u.columns })),
+    ...t.foreignKeys.map((fk): ConstraintSpec => ({ type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate })),
+  ];
+}
+
 /**
- * Name-keyed constraints whose names are content-derived and stable — uniques (named by
- * their columns) and foreign keys. Checks are handled separately, matched by predicate, because
- * a `check(...)` carries no author-given name and the database's name is arbitrary.
+ * The identity a unique/FK is matched on — its content, never its name. A pulled database
+ * carries Postgres default names (`posts_author_id_fkey`, `posts_slug_key`) while the
+ * compiler names drizzle-style; a same-content constraint under either name is the same
+ * constraint (the rule checks already follow). Matching by name would read every brownfield
+ * FK as drift and emit an ADD that duplicates a constraint the table already has.
  */
-function namedConstraints(t: TableSchema): Map<string, ConstraintSpec> {
-  const m = new Map<string, ConstraintSpec>();
-  for (const u of t.uniques) m.set(u.name, { type: 'unique', name: u.name, columns: u.columns });
-  for (const fk of t.foreignKeys) m.set(fk.name, { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate });
-  return m;
+function constraintContentKey(c: ConstraintSpec): string {
+  if (c.type === 'unique') return `u|${c.columns.join(',')}`;
+  if (c.type === 'foreignKey') return `f|${c.columns.join(',')}|${c.refTable}|${c.refColumns.join(',')}|${c.onDelete ?? ''}|${c.onUpdate ?? ''}`;
+  return `c|${normalizeCheck(c.expr)}`; // checks take their own predicate-matched path (diffChecks)
 }
 
 /**
@@ -437,32 +467,25 @@ function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChang
   }
 }
 
-function constraintsEqual(a: ConstraintSpec, b: ConstraintSpec): boolean {
-  if (a.type !== b.type) return false;
-  if (a.type === 'unique' && b.type === 'unique') return a.columns.join(',') === b.columns.join(',');
-  if (a.type === 'check' && b.type === 'check') return normalizeCheck(a.expr) === normalizeCheck(b.expr);
-  if (a.type === 'foreignKey' && b.type === 'foreignKey') {
-    return a.columns.join(',') === b.columns.join(',')
-      && a.refTable === b.refTable
-      && a.refColumns.join(',') === b.refColumns.join(',')
-      && (a.onDelete ?? '') === (b.onDelete ?? '')
-      && (a.onUpdate ?? '') === (b.onUpdate ?? '');
-  }
-  return false;
-}
-
 function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[], alters: SchemaChange[]): void {
-  const desired = namedConstraints(d);
-  const current = namedConstraints(c);
-
-  // Drop removed or changed constraints first (a changed one is dropped here, re-added below).
-  for (const [name, cur] of current) {
-    const des = desired.get(name);
-    if (!des || !constraintsEqual(des, cur)) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name });
+  // Multiset-match uniques and FKs by content: a desired constraint that finds a
+  // same-content current one is unchanged (whatever either is named); an unmatched
+  // desired is an add; a leftover current is dropped by its real name. A *changed*
+  // constraint therefore falls out as drop + add, never a silent mutation.
+  const currentByKey = new Map<string, ConstraintSpec[]>();
+  for (const cur of tableConstraintSpecs(c)) {
+    const key = constraintContentKey(cur);
+    const bucket = currentByKey.get(key);
+    if (bucket) bucket.push(cur);
+    else currentByKey.set(key, [cur]);
+  }
+  for (const des of tableConstraintSpecs(d)) {
+    const bucket = currentByKey.get(constraintContentKey(des));
+    if (bucket?.length) bucket.pop();
+    else addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: des });
   }
-  for (const [name, des] of desired) {
-    const cur = current.get(name);
-    if (!cur || !constraintsEqual(des, cur)) addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: des });
+  for (const bucket of currentByKey.values()) {
+    for (const cur of bucket) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: cur.name });
   }
 
   diffChecks(d, c, dropConstraints, addConstraints);
@@ -486,10 +509,24 @@ const colList = (cols: string[]): string => cols.map(quote).join(', ');
 /** A single-quoted enum value literal, doubling any embedded quote. */
 const enumLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
 
+/**
+ * The `serial`/`bigserial` DDL shorthand for a column whose IR is integer/bigint with a
+ * nextval default (how compileTableSchema and introspection both represent a serial
+ * column), or null. CREATE/ADD COLUMN must use the shorthand — it creates the backing
+ * sequence, which a bare `DEFAULT nextval(...)` would reference before it exists.
+ */
+function serialSpelling(col: ColumnSchema): string | null {
+  if (col.default == null || !/^nextval\('[^']+'::regclass\)$/.test(col.default)) return null;
+  if (col.type === 'integer') return 'serial';
+  if (col.type === 'bigint') return 'bigserial';
+  return null;
+}
+
 /** A column definition body (no leading indent): `"name" type [DEFAULT expr] [NOT NULL]`. */
 function columnSql(col: ColumnSchema): string {
-  let s = `${quote(col.name)} ${col.type}`;
-  if (col.default != null) s += ` DEFAULT ${col.default}`;
+  const serial = serialSpelling(col);
+  let s = `${quote(col.name)} ${serial ?? col.type}`;
+  if (!serial && col.default != null) s += ` DEFAULT ${col.default}`;
   if (col.notNull) s += ' NOT NULL';
   return s;
 }

package/src/cli/schema-source.ts

@@ -69,8 +69,14 @@ function baseColumnSource(columnName: string, spec: FieldSpec): { call: string;
       return { call: `integer(${n})`, builder: 'integer' };
     case 'bigint':
       return { call: `bigint(${n}, { mode: 'number' })`, builder: 'bigint' };
+    case 'serial':
+      return { call: `serial(${n})`, builder: 'serial' };
     case 'bigserial':
       return { call: `bigserial(${n}, { mode: 'number' })`, builder: 'bigserial' };
+    case 'real':
+      return { call: `real(${n})`, builder: 'real' };
+    case 'doublePrecision':
+      return { call: `doublePrecision(${n})`, builder: 'doublePrecision' };
     case 'boolean':
       return { call: `boolean(${n})`, builder: 'boolean' };
     case 'timestamptz':