@everystack/cli 0.3.8 → 0.3.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "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",
@@ -87,10 +87,14 @@
     "@aws-sdk/s3-request-presigner": "3.1053.0",
     "drizzle-orm": "0.41.0",
     "expo-updates": "55.0.21",
+    "postgres": "3.4.9",
     "react": "19.2.0",
     "react-native": "0.83.6"
   },
   "peerDependenciesMeta": {
+    "postgres": {
+      "optional": true
+    },
     "@everystack/server": {
       "optional": true
     },

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-generate.ts

@@ -27,6 +27,7 @@ import { compileModuleMigration } from '../migration-compile.js';
 import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, HELD_DROP_PREFIX, type Journal } from '../migration-generate.js';
 import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { FUNCTIONS_SQL, catalogFunctionToDescriptor } from '../security-catalog.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
@@ -152,17 +153,27 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     // updates it. The drift-guard test asserts this file matches the models.
     step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
     await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
-    step('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
-    const runner = lambdaRunner(config.region, opsFunction(config));
+    const dbSource: DbSource = resolveDbSource(flags);
+    let runner: QueryRunner;
+    let end: (() => Promise<void>) | undefined;
+    if (dbSource.kind === 'url') {
+      step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+      ({ runner, end } = await createUrlRunner(dbSource.url));
+    } else {
+      step('Resolving deployed config...');
+      const config = await resolveConfig(flags.stage);
+      info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+      runner = lambdaRunner(config.region, opsFunction(config));
+    }
     step('Introspecting live database (columns + constraints)...');
     current = await introspectSchema(runner);
     step('Introspecting authorization (rls + grants + policies)...');
     liveAuthz = await introspectContract(runner, mapFunctionRow, FUNCTIONS_SQL);
+    await end?.();
   } catch (err: any) {
     fail(err.message);
     info('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
+    info('Diffing against a local database instead? Pass --database-url or set DATABASE_URL.');
     process.exit(1);
   }
 

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

@@ -1,23 +1,31 @@
 /**
  * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
  *
- *   db:pull --stage <name> [--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`
- * action and renders the TypeScript a Model is written in — a starting point you review and
- * refine (it flags, as inline comments, anything the field builder can't yet express).
+ * action — or, for a database no Lambda can reach (the brownfield case where the target
+ * schema exists only locally), directly via `--database-url` / an inherited `DATABASE_URL`
+ * (see db-source.ts for precedence) — and renders the TypeScript a Model is written in — a
+ * 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';
 import { invokeAction } from '../aws.js';
 import { fail } from '../output.js';
@@ -41,29 +49,69 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
 export async function dbPullCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema || 'public';
 
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
   let current;
   try {
-    note('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    detail(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+    let runner: QueryRunner;
+    let end: (() => Promise<void>) | undefined;
+    if (dbSource.kind === 'url') {
+      note(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+      ({ runner, end } = await createUrlRunner(dbSource.url));
+    } else {
+      note('Resolving deployed config...');
+      const config = await resolveConfig(flags.stage);
+      detail(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+      runner = lambdaRunner(config.region, opsFunction(config));
+    }
     note(`Introspecting live database (schema: ${schema})...`);
-    current = await introspectSchema(lambdaRunner(config.region, opsFunction(config)));
+    current = await introspectSchema(runner);
+    await end?.();
   } catch (err: any) {
     fail(err.message);
-    detail('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
+    if (dbSource.kind === 'url') {
+      detail('Check the connection string and that the database is accepting connections.');
+    } else {
+      detail('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
+      detail('Introspecting a local database instead? Pass --database-url or set DATABASE_URL.');
+    }
     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');
@@ -73,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/db-source.ts

@@ -0,0 +1,77 @@
+/**
+ * db-source — where db:pull / db:generate find the database.
+ *
+ * Two paths to the same QueryRunner contract:
+ *
+ * - **Deployed** (the default): introspection SQL runs through the read-only ops Lambda
+ *   `db:query` action. Credentials never leave AWS; works for any deployed stage.
+ * - **Direct** (`--database-url` or an inherited `DATABASE_URL`): a postgres.js
+ *   connection from this process. This is the brownfield on-ramp's missing half — when
+ *   the target schema exists only on a local Postgres (migrations applied locally, no
+ *   interim deploy), there is no Lambda to ask.
+ *
+ * Precedence is explicit-over-ambient: `--database-url` beats an explicit `--stage`,
+ * which beats an inherited `DATABASE_URL`, which beats the default stage. An explicit
+ * `--stage` deliberately wins over the env var so a shell with DATABASE_URL exported
+ * still introspects the stage you named.
+ *
+ * The driver is loaded lazily: `postgres` ships with @everystack/server (every deployed
+ * consumer has it hoisted), so the deployed path never pays the import and a missing
+ * driver only surfaces — with instructions — when the direct path is actually used.
+ */
+
+import type { QueryRunner } from './authz-contract.js';
+
+export type DbSource =
+  | { kind: 'url'; url: string; from: 'flag' | 'env' }
+  | { kind: 'stage' };
+
+/** Decide which path serves this invocation. Pure; env injectable for tests. */
+export function resolveDbSource(
+  flags: Record<string, string>,
+  env: Record<string, string | undefined> = process.env,
+): DbSource {
+  const flagUrl = flags['database-url'];
+  if (flagUrl) {
+    // parseFlags encodes a value-less flag as 'true'
+    if (flagUrl === 'true') {
+      throw new Error(
+        '--database-url needs a connection string (or omit the flag and set DATABASE_URL in the environment).',
+      );
+    }
+    return { kind: 'url', url: flagUrl, from: 'flag' };
+  }
+  if (flags.stage) return { kind: 'stage' };
+  if (env.DATABASE_URL) return { kind: 'url', url: env.DATABASE_URL, from: 'env' };
+  return { kind: 'stage' };
+}
+
+export interface UrlRunner {
+  runner: QueryRunner;
+  /** Close the client so the process can exit cleanly. */
+  end: () => Promise<void>;
+}
+
+/**
+ * A QueryRunner over a direct postgres.js connection. One connection is enough —
+ * introspection is a handful of sequential catalog queries.
+ */
+export async function createUrlRunner(
+  url: string,
+  load: () => Promise<any> = () => import('postgres'),
+): Promise<UrlRunner> {
+  let mod: any;
+  try {
+    mod = await load();
+  } catch {
+    throw new Error(
+      'The direct-connection path needs the "postgres" driver. It ships with @everystack/server; in a project without it: pnpm add -D postgres',
+    );
+  }
+  const postgres = mod.default ?? mod;
+  const sql = postgres(url, { max: 1, onnotice: () => {} });
+  return {
+    runner: async (query: string) => Array.from(await sql.unsafe(query)),
+    end: () => sql.end({ timeout: 5 }),
+  };
+}

package/src/cli/index.ts

@@ -95,6 +95,13 @@ async function main() {
 
   const flags = parseFlags(args.slice(1));
 
+  // `everystack <command> --help` shows help instead of running the command
+  // (a db command falling through to the default stage is a footgun).
+  if ('help' in flags || 'h' in flags) {
+    printHelp();
+    process.exit(0);
+  }
+
   // Auto-detect deployed URL from SST outputs
   await loadSstOutputs(flags.stage);
 
@@ -280,8 +287,9 @@ Usage:
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   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>] [--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>] [--schema public] [--out <file>]  Introspect the live DB → render field() Models (the brownfield on-ramp; stdout unless --out)
+  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 <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)
   everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)

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',
@@ -102,6 +104,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);
@@ -132,20 +147,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 +193,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 +264,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 +284,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/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':