@everystack/cli 0.4.12 → 0.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

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

@@ -1,14 +1,24 @@
 /**
- * `everystack db:export --schema <name> --stage <n>` — the schema-scoped, fingerprint-stamped
- * artifact (canonical-sync gap B). pg_dump ONE schema → the stage's S3 artifact bucket, stamped
- * with the DECLARED schema fingerprint from the checkout, so db:swap can gate an incoming artifact
- * against the target's declared shape (declared-vs-declared: does the artifact and the stage agree
- * on the schema's shape). everystack owns the export so that fingerprint is one formula both sides.
+ * `everystack db:export --schema <name> [--stage <n> | --database-url <url>]` — the schema-scoped,
+ * fingerprint-stamped artifact (canonical-sync gap B). pg_dump ONE schema, stamped with the
+ * DECLARED schema fingerprint from the checkout, so db:swap can gate an incoming artifact against
+ * the target's declared shape (declared-vs-declared: does the artifact and the stage agree on the
+ * schema's shape). everystack owns the export so that fingerprint is one formula both sides.
  *
- * The dump runs in the ops Lambda (the DB is private); the CLI computes the fingerprint from the
- * models and invokes the action. Verification of the streaming path is a deploy smoke test.
+ * Two venues, mirroring db:swap:
+ * - `--stage` (default): the dump runs in the ops Lambda (the DB is private) → the stage's S3
+ *   artifact bucket, gzipped. Verification of the streaming path is a deploy smoke test.
+ * - `--database-url` (explicit flag only, never the env — the venue choice must be deliberate):
+ *   the CLI runs pg_dump itself against a reachable database and writes a plain `-Fc` `.dump`
+ *   plus the sibling `.meta.json` db:swap reads. This is the build-locally → publish → swap
+ *   on-ramp: a consumer pipeline shells this instead of hand-rolling pg_dump and duplicating
+ *   the fingerprint formula.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
 import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
 import { invokeAction } from '../aws.js';
@@ -17,11 +27,119 @@ import { resolveModelsPath } from '../models-path.js';
 import { loadModels } from './db-generate.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
 import { pgDumpPreflightError } from './db-backup.js';
+import { pgEnvFromUrl } from './db.js';
+import { utcStamp } from '../backup.js';
 import { step, success, fail, info } from '../output.js';
 
 const fmtBytes = (b?: number): string =>
   b == null ? '?' : b >= 1024 ** 3 ? `${(b / 1024 ** 3).toFixed(1)} GB` : b >= 1024 ** 2 ? `${(b / 1024 ** 2).toFixed(1)} MB` : `${(b / 1024).toFixed(0)} KB`;
 
+export type ExportVenue = { kind: 'local'; url: string } | { kind: 'stage'; stage: string | undefined };
+
+/**
+ * Which venue runs the dump. Local ONLY on an explicit `--database-url` — never the env, so a
+ * DATABASE_URL in the shell can't silently flip a stage export into a local one. Both flags at
+ * once is ambiguous and refused.
+ */
+export function resolveExportVenue(flags: Record<string, string>): ExportVenue {
+  const url = flags['database-url'];
+  if (url && flags.stage) {
+    throw new Error('db:export takes one venue: --database-url (dump a reachable database locally) OR --stage (dump the stage\'s private database in the ops Lambda) — not both.');
+  }
+  return url ? { kind: 'local', url } : { kind: 'stage', stage: flags.stage };
+}
+
+/**
+ * Where a local artifact lands. Mirrors the S3 scheme (`<stamp>-<shortId>`, meta as a sibling)
+ * with the schema in the file name since there is no bucket prefix; the id says `local` where
+ * the S3 id says the stage. Plain `.dump` (no gzip): db:swap's pg_restore reads the file as-is.
+ */
+export function localArtifactPaths(
+  schema: string,
+  now: Date,
+  shortId: string,
+  opts: { out?: string; outDir?: string } = {},
+): { dumpPath: string; metaPath: string; id: string } {
+  const stamp = utcStamp(now);
+  let dumpPath: string;
+  if (opts.out) {
+    if (!opts.out.endsWith('.dump')) {
+      throw new Error(`--out must end in .dump (got ${opts.out}) — db:swap resolves the sibling .meta.json from that suffix.`);
+    }
+    dumpPath = opts.out;
+  } else {
+    dumpPath = path.join(opts.outDir ?? '.', `${schema}-${stamp}-${shortId}.dump`);
+  }
+  return {
+    dumpPath,
+    metaPath: dumpPath.replace(/\.dump$/, '.meta.json'),
+    id: `${schema}/local/${stamp}-${shortId}`,
+  };
+}
+
+/** The meta record the swap gate reads — same shape as the S3 sidecar, `path` instead of `key`. */
+export function localArtifactMeta(opts: {
+  id: string;
+  schema: string;
+  createdAt: Date;
+  bytes: number;
+  path: string;
+  fingerprint: string;
+}): Record<string, unknown> {
+  return {
+    id: opts.id,
+    schema: opts.schema,
+    stage: 'local',
+    createdAt: opts.createdAt.toISOString(),
+    bytes: opts.bytes,
+    path: opts.path,
+    fingerprint: opts.fingerprint,
+  };
+}
+
+/** pg_dump args for the local venue — same dump shape as the ops venue, written straight to a file. */
+export function pgDumpLocalArgs(schema: string, dumpPath: string): string[] {
+  return ['-Fc', '--no-owner', '--no-privileges', '--no-comments', `--schema=${schema}`, '-f', dumpPath];
+}
+
+/**
+ * Run the local export: pg_dump one schema to a `-Fc` file, then write the meta sidecar. The
+ * connection rides PG* env (never argv). A failed dump removes the partial file — a truncated
+ * artifact never ships. Throws on failure; the command wraps it.
+ */
+export async function runLocalExport(opts: {
+  url: string;
+  schema: string;
+  fingerprint: string;
+  out?: string;
+  outDir?: string;
+}): Promise<{ id: string; dumpPath: string; metaPath: string; bytes: number }> {
+  const now = new Date();
+  const shortId = randomBytes(3).toString('hex');
+  const { dumpPath, metaPath, id } = localArtifactPaths(opts.schema, now, shortId, opts);
+
+  const env = { ...process.env, ...pgEnvFromUrl(opts.url) };
+  const child = spawn('pg_dump', pgDumpLocalArgs(opts.schema, dumpPath), { env, stdio: ['ignore', 'ignore', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      child.on('error', reject);
+      child.on('close', (code) =>
+        code === 0 ? resolve() : reject(new Error(`pg_dump exited ${code}: ${stderr.trim()}`)));
+    });
+  } catch (err) {
+    fs.rmSync(dumpPath, { force: true });
+    throw err;
+  }
+
+  const bytes = fs.statSync(dumpPath).size;
+  fs.writeFileSync(metaPath, JSON.stringify(localArtifactMeta({
+    id, schema: opts.schema, createdAt: now, bytes, path: dumpPath, fingerprint: opts.fingerprint,
+  }), null, 2));
+  return { id, dumpPath, metaPath, bytes };
+}
+
 export async function dbExportCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema;
   if (!schema) {
@@ -29,6 +147,14 @@ export async function dbExportCommand(flags: Record<string, string>): Promise<vo
     process.exit(1);
   }
 
+  let venue: ExportVenue;
+  try {
+    venue = resolveExportVenue(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
   // The DECLARED fingerprint of just this schema — the stamp the swap gate compares against.
   const modelsPath = resolveModelsPath(flags.models);
   let fingerprint: string;
@@ -43,10 +169,22 @@ export async function dbExportCommand(flags: Record<string, string>): Promise<vo
     process.exit(1);
   }
 
+  if (venue.kind === 'local') {
+    step(`Running pg_dump --schema=${schema} against --database-url...`);
+    try {
+      const res = await runLocalExport({ url: venue.url, schema, fingerprint, out: flags.out });
+      success(`Artifact ${res.dumpPath} (${fmtBytes(res.bytes)}, fingerprint ${fingerprint.slice(0, 12)}, meta ${res.metaPath}). Deploy with: everystack db:swap --schema ${schema} --from ${res.dumpPath} --database-url <target>`);
+    } catch (err: any) {
+      fail(`Export failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   step('Resolving deployed config...');
   let config: CliConfig;
   try {
-    config = await resolveConfig(flags.stage);
+    config = await resolveConfig(venue.stage);
   } catch (err: any) {
     fail(err.message);
     process.exit(1);
@@ -68,7 +206,7 @@ export async function dbExportCommand(flags: Record<string, string>): Promise<vo
   step(`Running pg_dump --schema=${schema} → S3 (this may take a while for large schemas)...`);
   let result: any;
   try {
-    result = await invokeAction(config.region, opsFunction(config), 'db:export', { schema, stage: flags.stage, fingerprint });
+    result = await invokeAction(config.region, opsFunction(config), 'db:export', { schema, stage: venue.stage, fingerprint });
   } catch (err: any) {
     fail(`Export failed: ${err.message}`);
     process.exit(1);

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

@@ -29,7 +29,7 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { introspectSchema } from '../schema-introspect.js';
+import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, type ColumnRow, type ColumnSchema } from '../schema-introspect.js';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
 import { renderDerivedSource, renderDerivedFile, type DerivedRenderResult } from '../derived-render.js';
 import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
@@ -84,8 +84,11 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  const matviewsAsTables = flags['matviews-as-tables'] === 'true';
+
   let current;
   let derivedCatalog: DerivedCatalog | undefined;
+  let matviewColumns: Map<string, ColumnSchema[]> | undefined;
   try {
     let runner: QueryRunner;
     let end: (() => Promise<void>) | undefined;
@@ -103,6 +106,11 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     // The derived layer rides the same pull (B5) — views/matviews/functions/sequences
     // render as descriptors; adoption is pull → commit → --baseline → clean reconcile.
     derivedCatalog = await introspectDerived(runner);
+    // --matviews-as-tables: the flip needs real fields — one extra catalog read for the
+    // matview columns the derived layer (definition-only) doesn't carry.
+    if (matviewsAsTables) {
+      matviewColumns = matviewColumnsByIdentity((await runner(MATVIEW_COLUMNS_SQL)) as ColumnRow[]);
+    }
     await end?.();
   } catch (err: any) {
     fail(err.message);
@@ -131,12 +139,22 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   const derived: DerivedRenderResult = renderDerivedSource(derivedCatalog ?? { objects: [], edges: [], provenance: [] }, {
     knownTables,
     sequences: current.sequences,
+    ...(matviewsAsTables ? {
+      matviewsAsTables: {
+        columns: matviewColumns ?? new Map(),
+        enums: new Map((current.enums ?? []).map((e) => [e.name, e.values])),
+      },
+    } : {}),
   });
   for (const w of derived.warnings) caution(w);
   const derivedCount = derived.names.length + derived.sequenceNames.length;
   if (derivedCount > 0) {
     detail(`Derived layer: ${derived.names.length} descriptor(s) + ${derived.sequenceNames.length} sequence(s) rendered (adopt with db:reconcile --baseline after committing).`);
   }
+  if (derived.materializedTableNames.length) {
+    detail(`${derived.materializedTableNames.length} matview(s) rendered as defineMaterializedTable — these are MODELS: wire them into your module's models array (spread \`materializedTables\` from the derived file).`);
+    caution('Matviews carry no PK/NOT NULL — the rendered fields are nullable and unkeyed; tighten (.primaryKey()/.notNull()) as you review. Unique matview indexes render as index().unique() constraints.');
+  }
 
   // The standalone derived file. The models output (below) then omits the derived
   // layer — it lives here, and the module wires both: defineModule({ models, sequences, derived }).
@@ -149,8 +167,9 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       fail(`Could not write ${derivedOut}: ${err.message}`);
       process.exit(1);
     }
-    ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${derived.names.length} descriptor(s) + ${derived.sequenceNames.length} sequence(s), self-contained.`);
-    note(`Wire it on your module — defineModule({ models${derived.sequenceNames.length ? ', sequences' : ''}, derived }) — then adopt with db:reconcile --apply --baseline (--rebaseline over db/sql-era provenance).`);
+    const mtPart = derived.materializedTableNames.length ? ` + ${derived.materializedTableNames.length} materialized table(s)` : '';
+    ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${derived.names.length} descriptor(s) + ${derived.sequenceNames.length} sequence(s)${mtPart}, self-contained.`);
+    note(`Wire it on your module — defineModule({ models${derived.materializedTableNames.length ? ': [...models, ...materializedTables]' : ''}${derived.sequenceNames.length ? ', sequences' : ''}, derived }) — then adopt with db:reconcile --apply --baseline (--rebaseline over db/sql-era provenance).`);
     if (!flags.out) {
       // The brownfield case: the barrel is hand-maintained; leave the models alone.
       note('Models were NOT rendered (--derived-out extracts the derived layer only; add --out to render models too).');

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

@@ -86,8 +86,11 @@ async function restoreIntoIncoming(url: string, artifactPath: string, schema: st
   ]);
 }
 
-/** Load the artifact's meta (fingerprint) from a sibling `.meta.json`, or fall back to a flag. */
-function readArtifactFingerprint(artifactPath: string, flag?: string): string | null {
+/**
+ * Load the artifact's meta (fingerprint) from a sibling `.meta.json`, or fall back to a flag.
+ * Exported so the db:export local venue can prove its meta round-trips into this gate.
+ */
+export function readArtifactFingerprint(artifactPath: string, flag?: string): string | null {
   if (flag) return flag;
   const metaPath = artifactPath.replace(/\.dump(\.gz)?$/, '.meta.json');
   try {

package/src/cli/derived-render.ts

@@ -14,9 +14,9 @@
  */
 
 import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
-import type { SequenceSchema } from './schema-introspect.js';
+import type { ColumnSchema, SequenceSchema, TableSchema } from './schema-introspect.js';
 import { parseIndexDefinition } from './schema-introspect.js';
-import { modelFileName } from './model-render.js';
+import { modelFileName, renderFieldLines } from './model-render.js';
 
 export interface DerivedRenderResult {
   /** The source block: `export const … = defineView(…)` etc., dependency-ordered. */
@@ -25,6 +25,9 @@ export interface DerivedRenderResult {
   names: string[];
   /** Rendered sequence variable names — feed `defineModule({ sequences })`. */
   sequenceNames: string[];
+  /** defineMaterializedTable variable names (--matviews-as-tables) — these are MODELS:
+   *  feed `defineModule({ models })`, never the derived array. */
+  materializedTableNames: string[];
   /** Model-package symbols the block uses (defineView, can, sql, arg, index, …). */
   imports: string[];
   /** Qualified tables the block references through knownTables — what a standalone
@@ -39,6 +42,17 @@ export interface DerivedRenderOptions {
   knownTables: Map<string, string>;
   /** Standalone sequences from the snapshot (serial-owned stay implicit). */
   sequences?: SequenceSchema[];
+  /**
+   * `db:pull --matviews-as-tables` (the gap-B consumer flip): render every matview as
+   * defineMaterializedTable with fields from its LIVE columns (matview identity → columns),
+   * instead of a defineMaterializedView descriptor. Matviews carry no PK/NOT NULL, so the
+   * fields land nullable and unkeyed — honest to the catalog; the consumer tightens on adoption.
+   */
+  matviewsAsTables?: {
+    columns: Map<string, ColumnSchema[]>;
+    /** Enum name → values, for enum-typed matview columns (same map the model render uses). */
+    enums?: Map<string, string[]>;
+  };
 }
 
 const PLAIN_IDENT = /^[a-z_][a-z0-9_$]*$/;
@@ -130,10 +144,28 @@ function renderIndexBuilder(indexdef: string): string | null {
   return s;
 }
 
+/**
+ * One matview index → the builder for a MODEL's `constraints: [...]` — same Brick E parse as
+ * {@link renderIndexBuilder}, but plain identifiers camelize to FIELD KEYS (the model
+ * constraints idiom; the compiler snake_cases them back), while expressions stay raw sql``.
+ */
+function renderTableIndexBuilder(indexdef: string): string | null {
+  const parsed = parseIndexDefinition(indexdef);
+  if (!parsed) return null;
+  const entry = (c: string): string => (PLAIN_IDENT.test(c) ? tsString(toCamelCase(c)) : `sql\`${tsTemplate(c)}\``);
+  let s = `index(${parsed.columns.map(entry).join(', ')})`;
+  if (parsed.using) s += `.using(${tsString(parsed.using)})`;
+  if (parsed.unique) s += '.unique()';
+  if (parsed.include?.length) s += `.include(${parsed.include.map((c) => tsString(toCamelCase(c))).join(', ')})`;
+  if (parsed.where) s += `.where(sql\`${tsTemplate(parsed.where)}\`)`;
+  return s;
+}
+
 export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRenderOptions): DerivedRenderResult {
   const warnings: string[] = [];
   const lines: string[] = [];
   const names: string[] = [];
+  const materializedTableNames: string[] = [];
   const used = new Set<string>();
   const need = (sym: string): void => { used.add(sym); };
 
@@ -227,6 +259,53 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
         lines.push(`// FIXME: ${o.identity} skipped — live grants (${grantText}) are not expressible as abilities (views are read surfaces).`, '');
         continue;
       }
+
+      // --matviews-as-tables (the gap-B consumer flip): the matview renders as a
+      // defineMaterializedTable MODEL — introspected fields, index constraints on field
+      // keys, the defining query as metadata. Same topo slot (its dependents still
+      // reference it by variable); the name lands in materializedTableNames, not names.
+      if (o.kind === 'materialized view' && opts.matviewsAsTables) {
+        const cols = opts.matviewsAsTables.columns.get(o.identity);
+        if (!cols || cols.length === 0) {
+          warnings.push(`${o.identity}: no live columns found for the table render — rendered as defineMaterializedView; re-pull or flip it by hand.`);
+        } else {
+          if (o.populated === false) {
+            warnings.push(`${o.identity}: the live matview is UNPOPULATED — rendered anyway (a materialized table's contents are pipeline-owned).`);
+          }
+          const shape: TableSchema = {
+            table: o.identity, columns: cols,
+            primaryKey: [], uniques: [], checks: [], foreignKeys: [], indexes: [],
+          };
+          const fieldLines = renderFieldLines(shape, new Set(), opts.matviewsAsTables.enums ?? new Map());
+          const builders = o.indexes.map((def) => {
+            const b = renderTableIndexBuilder(def);
+            if (b === null) warnings.push(`${o.identity}: index not renderable: ${def}`);
+            return b;
+          }).filter((b): b is string => b !== null);
+          if (builders.length) need('index');
+          if (abilities.length) need('can');
+          need('defineMaterializedTable');
+          need('field');
+          need('sql');
+          lines.push(
+            ...fixmes,
+            `export const ${varName} = defineMaterializedTable(${tsString(declaredName(o))}, {`,
+            `  ${abilities.length ? `abilities: [${abilities.join(', ')}],` : 'private: true,'}`,
+            '  fields: {',
+            ...fieldLines,
+            '  },',
+            ...(builders.length ? [`  constraints: [${builders.join(', ')}],`] : []),
+            ...(refs.length ? [`  dependsOn: [${refs.join(', ')}],`] : []),
+            ...(o.comment ? [`  comment: ${tsString(o.comment)},`] : []),
+            `  as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`,
+            '});',
+            '',
+          );
+          materializedTableNames.push(varName);
+          continue;
+        }
+      }
+
       const props: string[] = [];
       if (o.kind === 'view') props.push(`securityInvoker: ${o.securityInvoker === true},`);
       if (abilities.length === 0) props.push('private: true,');
@@ -327,6 +406,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     block: lines.join('\n').trimEnd(),
     names,
     sequenceNames,
+    materializedTableNames,
     imports: [...used].sort(),
     modelRefs: [...modelRefs].sort(),
     warnings,
@@ -359,6 +439,11 @@ export function renderDerivedFile(result: DerivedRenderResult, knownTables: Map<
   if (result.sequenceNames.length) {
     lines.push(`export const sequences = [\n${result.sequenceNames.map((n) => `  ${n},`).join('\n')}\n];`);
   }
+  // Materialized tables (--matviews-as-tables) are MODELS: the consumer spreads this array
+  // into their module's models — defineModule({ models: [...models, ...materializedTables] }).
+  if (result.materializedTableNames.length) {
+    lines.push(`export const materializedTables = [\n${result.materializedTableNames.map((n) => `  ${n},`).join('\n')}\n];`);
+  }
   if (result.names.length) {
     lines.push(`export const derived = [\n${result.names.map((n) => `  ${n},`).join('\n')}\n];`);
   }

package/src/cli/index.ts

@@ -361,10 +361,10 @@ 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:export         --schema <name> [--stage <name>] [--models <barrel>]  Schema-scoped pg_dump → S3 artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp)
+  everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
   everystack db:swap           --schema <name> --database-url <url> --from <artifact.dump> [--fingerprint <hash>]  Land a schema artifact atomically: fingerprint gate → restore into <schema>_incoming (COPY-safe rewrite) → one txn (drop+rename+recreate app→schema FKs, re-apply authz) → verify → drop retiring. Refresh-free; app.* untouched. DESTRUCTIVE (--stage/--direct ops venue rides stage-write-lanes)
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
-  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  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. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default
+  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  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. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default. --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review
                                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:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (direct connection only, atomic — DDL + provenance in one transaction) and records provenance + schema_log. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive.

package/src/cli/model-render.ts

@@ -345,6 +345,16 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
   return `    ${toCamelCase(col.name)}: ${expr},${comment}`;
 }
 
+/**
+ * The rendered field lines for a table shape — one `    key: field.…(),` line per column,
+ * 4-space indented, comma-terminated (ready to nest under `fields: {`). Exported for the
+ * derived renderer: a matview flipped to defineMaterializedTable (--matviews-as-tables)
+ * renders its introspected columns with the SAME field vocabulary a pulled table gets.
+ */
+export function renderFieldLines(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map()): string[] {
+  return table.columns.map((c) => renderField(table, c, known, enums, new Map()));
+}
+
 /**
  * The `constraints: [...]` block for a table's composite uniques, checks, indexes, and
  * multi-column foreign keys — the table-level surface a column-scoped `field()` can't carry.
@@ -434,9 +444,12 @@ function importHeader(body: string, extra: string[] = []): string {
 
 /** The barrel's module wrapper: models always; sequences/derived when the pull found any (B5). */
 function moduleFooter(modelNames: string[], derived?: DerivedRenderResult, multiline = false): string {
+  // A materialized table (--matviews-as-tables) is a MODEL — its block rides the derived
+  // render (topo-ordered with the objects around it) but its name belongs in `models`.
+  const allModels = [...modelNames, ...(derived?.materializedTableNames ?? [])];
   const models = multiline
-    ? `export const models = [\n${modelNames.map((n) => `  ${n},`).join('\n')}\n];`
-    : `export const models = [${modelNames.join(', ')}];`;
+    ? `export const models = [\n${allModels.map((n) => `  ${n},`).join('\n')}\n];`
+    : `export const models = [${allModels.join(', ')}];`;
   const parts = [models];
   const keys = ['models'];
   if (derived?.sequenceNames.length) {

package/src/cli/schema-introspect.ts

@@ -139,6 +139,31 @@ WHERE c.relkind = 'r'
 ORDER BY n.nspname, c.relname, a.attnum;
 `.trim();
 
+/**
+ * Every column of every MATERIALIZED VIEW — same shape as COLUMNS_SQL, relkind 'm'.
+ * Only `db:pull --matviews-as-tables` runs it: the flip to defineMaterializedTable
+ * needs real fields, and the matview's columns are catalog facts the derived layer
+ * (definition-only) doesn't carry. Matviews hold no NOT NULL/defaults/PK — the rows
+ * come back nullable and unkeyed, honestly.
+ */
+export const MATVIEW_COLUMNS_SQL = COLUMNS_SQL.replace(`WHERE c.relkind = 'r'`, `WHERE c.relkind = 'm'`);
+
+/**
+ * Fold MATVIEW_COLUMNS_SQL rows into matview identity (`stats.player_totals`) → its
+ * columns in ordinal order — the columns map the derived renderer's table mode takes.
+ */
+export function matviewColumnsByIdentity(rows: ColumnRow[]): Map<string, ColumnSchema[]> {
+  const out = new Map<string, { position: number; column: ColumnSchema }[]>();
+  for (const row of rows) {
+    const d = columnRowToDescriptor(row);
+    const list = out.get(d.table) ?? [];
+    list.push({ position: d.position, column: d.column });
+    out.set(d.table, list);
+  }
+  return new Map([...out.entries()].map(([identity, cols]) =>
+    [identity, cols.sort((a, b) => a.position - b.position).map((c) => c.column)]));
+}
+
 /**
  * Every table constraint — primary key, unique, check, foreign key — as its
  * canonical `pg_get_constraintdef` text. The mapper parses that text (stable