agnes-cli 0.0.4 → 0.0.5

package/README.md

@@ -15,7 +15,8 @@ bun add agnes-cli agnes-library
 
 ## Configure
 
-Create `agnes.config.ts` in your project root (see `agnes.config.example.ts`):
+Run `bun agnes init` to scaffold `agnes.config.ts`, or create it yourself
+(see `agnes.config.example.ts`):
 
 ```ts
 import { defineConfig } from "agnes-cli";
@@ -25,11 +26,15 @@ export default defineConfig({
   driver: "postgres",
   url: process.env.DATABASE_URL!,
   schema,
-  out: "./schema.ts",          // where `pull` writes
+
+  schemas: ["public"],         // PostgreSQL schemas to introspect (default: public)
+  pullMode: "singlefile",      // "singlefile" | "multifile"
+  out: "./schema.ts",          // where `pull` writes (a directory in multifile mode)
   migrationsDir: "./migrations",
 
   // `generate` output — extension picks the language (.ts or .js)
   output: "src/services/db.ts",
+  urlEnv: "DATABASE_URL",      // `generate` reads the URL from here (keeps it out of the file)
   schemaPath: "./schema.ts",   // module the generated client imports `schema` from
   cache: { enabled: true, walPath: ".agnes/cache.wal" },
 });
@@ -38,6 +43,7 @@ export default defineConfig({
 ## Commands
 
 ```bash
+bun agnes init        # scaffold agnes.config.ts
 bun agnes push        # make the DB match schema.ts (create/alter/DROP)
 bun agnes pull        # regenerate schema.ts from the live DB
 bun agnes migrate     # write a versioned .sql from drift, then apply pending
@@ -68,6 +74,24 @@ Prompts before overwriting an existing file unless `--yes`.
 bun agnes pull --out src/schema.ts
 ```
 
+**Multi-schema (PostgreSQL).** List the schemas you want in `schemas` — tables
+outside `public` get qualified physical names (`table(def, "auth.users")`):
+
+```ts
+schemas: ["public", "auth", "billing"],
+```
+
+With `pullMode: "multifile"`, `pull` writes one file per DB schema plus an
+`index.ts` that merges them into a single `schema` export — `out` is then a
+directory:
+
+```
+schema/
+  public.ts
+  auth.ts
+  index.ts   ← import { schema } from "./schema"
+```
+
 ### `migrate` — versioned SQL files
 
 1. Diffs schema vs DB and, if there's drift, writes a timestamped file to
@@ -95,7 +119,7 @@ import { schema } from "../../schema";
 export const db = await AgnesClient.create(
   {
     driver: "sqlite",
-    url: "sqlite:./demo.db",
+    url: process.env["DATABASE_URL"]!,
     cache: { enabled: true, walPath: ".agnes/cache.wal" },
   },
   schema,
@@ -105,6 +129,9 @@ export const db = await AgnesClient.create(
 - `output` (config) or `--output` picks the path. `.ts` → TypeScript, `.js` → JavaScript.
 - The `import { schema }` path is made relative to the output file automatically.
 - The `cache` block is emitted only if you set `cache` in the config.
+- **Secrets stay out of the file:** set `urlEnv` (e.g. `"DATABASE_URL"`) and the
+  client reads `process.env[urlEnv]` at runtime instead of inlining the URL.
+  Without `urlEnv`, `generate` warns and inlines the literal `url`.
 
 ```bash
 bun agnes generate                       # uses config.output
@@ -116,7 +143,7 @@ bun agnes generate --output src/db.js    # override; JS output
 | Flag | Applies to | Meaning |
 |------|-----------|---------|
 | `-c, --config <path>` | all | Config file (default `agnes.config.ts`) |
-| `-o, --out <path>` | pull | Output schema file |
+| `-o, --out <path>` | init, pull | Config path (init) / output schema file or dir (pull) |
 | `--output <path>` | generate | Output client module (.ts/.js) |
 | `--dir <path>` | migrate | Migrations directory |
 | `-n, --name <name>` | migrate | Name for the generated migration |

package/agnes.config.example.ts

@@ -37,12 +37,25 @@ export default defineConfig({
   driver: "postgres",
   url: process.env.DATABASE_URL ?? "postgres://user:pass@localhost/db",
   schema,
+
+  // PostgreSQL schemas to introspect (default: ["public"]). Tables outside the
+  // default schema get qualified physical names, e.g. table(def, "auth.users").
+  schemas: ["public"],
+
+  // How `agnes pull` writes the schema:
+  //   "singlefile" (default) → one file at `out` (below).
+  //   "multifile"            → one file per DB schema + an index re-exporting
+  //                            them merged; `out` is then treated as a directory.
+  pullMode: "singlefile",
   out: "./schema.ts",
   migrationsDir: "./migrations",
 
   // `agnes generate` writes the ready-to-import client here.
   // Extension picks the language: db.ts → TypeScript, db.js → JavaScript.
   output: "src/services/db.ts",
+  // Env var holding the URL. When set, `agnes generate` emits
+  // process.env[urlEnv] instead of inlining the URL — credentials stay in .env.
+  urlEnv: "DATABASE_URL",
   // Module the generated client imports `schema` from (default: `out`).
   schemaPath: "./agnes.config.ts",
   // Cache baked into the generated client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agnes-cli",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Schema migration CLI for agnes-rs — push, pull and migrate from schema.ts",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "agnes-library": "0.0.4"
+    "agnes-library": "0.0.5"
   },
   "devDependencies": {
     "@types/bun": "latest"

package/src/cli.ts

@@ -1,4 +1,5 @@
 import { loadConfig } from "./config";
+import { init } from "./commands/init";
 import { push } from "./commands/push";
 import { pull } from "./commands/pull";
 import { migrate } from "./commands/migrate";
@@ -59,6 +60,7 @@ ${c.bold("Usage:")}
   agnes <command> [options]
 
 ${c.bold("Commands:")}
+  init       Scaffold an agnes.config.ts in the current directory
   push       Sync the database to match schema.ts (create/alter/drop)
   pull       Introspect the database and (re)generate schema.ts
   migrate    Generate a versioned SQL migration from drift, then apply pending
@@ -85,6 +87,12 @@ export async function run(argv: string[]): Promise<void> {
   }
 
   try {
+    // `init` runs without an existing config.
+    if (command === "init") {
+      await init({ out: flags.out, yes: flags.yes });
+      return;
+    }
+
     const config = await loadConfig(flags.config);
     switch (command) {
       case "push":

package/src/commands/generate.ts

@@ -15,10 +15,17 @@ function toImportSpecifier(fromFile: string, toModule: string): string {
   return rel;
 }
 
+function renderUrl(config: AgnesConfig): string {
+  // Never inline credentials: when urlEnv is set, read the URL from the
+  // environment at runtime so the generated file stays secret-free.
+  if (config.urlEnv) return `process.env[${JSON.stringify(config.urlEnv)}]!`;
+  return JSON.stringify(config.url);
+}
+
 function renderConfigObject(config: AgnesConfig): string {
   const lines: string[] = [
     `    driver: ${JSON.stringify(config.driver)},`,
-    `    url: ${JSON.stringify(config.url)},`,
+    `    url: ${renderUrl(config)},`,
   ];
   if (config.maxConnections !== undefined)
     lines.push(`    maxConnections: ${config.maxConnections},`);
@@ -57,6 +64,15 @@ export async function generate(config: AgnesConfig, args: GenerateArgs): Promise
   const schemaFsPath = resolve(process.cwd(), config.schemaPath ?? config.out ?? "schema.ts");
   const schemaImport = toImportSpecifier(outPath, schemaFsPath);
 
+  if (!config.urlEnv) {
+    console.log(
+      c.yellow(
+        `⚠ config.urlEnv is not set — the connection URL will be INLINED into ${outRel}.`,
+      ),
+    );
+    console.log(c.dim(`  Set urlEnv (e.g. "DATABASE_URL") to read it from the environment instead.`));
+  }
+
   const source = renderClient(config, schemaImport);
 
   if (await Bun.file(outPath).exists() && !args.yes) {

package/src/commands/init.ts

@@ -0,0 +1,67 @@
+import { resolve } from "node:path";
+import { c, confirm } from "../prompt";
+
+export interface InitArgs {
+  /** Target config path (default: agnes.config.ts). */
+  out?: string;
+  yes?: boolean;
+}
+
+const TEMPLATE = `import { defineConfig } from "agnes-cli";
+import { schema } from "./schema";
+
+export default defineConfig({
+  // Target database dialect: "postgres" | "mysql" | "sqlite".
+  driver: "postgres",
+
+  // Connection URL. Keep credentials in your .env — see urlEnv below.
+  url: process.env.DATABASE_URL!,
+
+  // The schema object exported from your schema.ts.
+  schema,
+
+  // ── pull / push ──────────────────────────────────────────────────────────
+  // PostgreSQL schemas to introspect. "public" is the default; add more to
+  // pull/push tables that live outside it (they get qualified names, "auth.users").
+  schemas: ["public"],
+
+  // How \`agnes pull\` lays out the generated schema:
+  //   "singlefile" — every table in one file (config.out, default ./schema.ts)
+  //   "multifile"  — one file per DB schema + an index re-exporting them merged
+  //                  (config.out is then a directory, default ./schema)
+  pullMode: "singlefile",
+  out: "./schema.ts",
+
+  // Directory for versioned migration files.
+  migrationsDir: "./migrations",
+
+  // ── generate ──────────────────────────────────────────────────────────────
+  // Env var holding the URL. When set, \`agnes generate\` emits
+  // process.env[urlEnv] in the client so no credentials land in the output file.
+  urlEnv: "DATABASE_URL",
+
+  // Where \`agnes generate\` writes the pre-wired AgnesClient module (.ts or .js).
+  output: "./src/db.ts",
+
+  // Cache baked into the generated client.
+  cache: { enabled: false },
+});
+`;
+
+/** Scaffold an agnes.config.ts in the current directory. */
+export async function init(args: InitArgs): Promise<void> {
+  const outRel = args.out ?? "agnes.config.ts";
+  const outPath = resolve(process.cwd(), outRel);
+
+  if ((await Bun.file(outPath).exists()) && !args.yes) {
+    console.log(c.yellow(`⚠ ${outPath} already exists and will be overwritten.`));
+    if (!(await confirm("Overwrite it?"))) {
+      console.log(c.dim("Aborted. File left unchanged."));
+      return;
+    }
+  }
+
+  await Bun.write(outPath, TEMPLATE);
+  console.log(c.green(`✓ Created ${outPath}`));
+  console.log(c.dim(`  Edit driver/url, then run \`agnes pull\` to generate schema.ts.`));
+}

package/src/commands/migrate.ts

@@ -62,7 +62,7 @@ export async function migrate(config: AgnesConfig, args: MigrateArgs): Promise<v
 
   // 1. Detect drift and write a new migration file.
   const desired = normalizeIR(schemaToIR(config.schema), config.driver);
-  const current = normalizeIR(await introspect(db, config.driver), config.driver);
+  const current = normalizeIR(await introspect(db, config.driver, config.schemas), config.driver);
   const ops = diffSchemas(desired, current);
 
   if (ops.length > 0) {

package/src/commands/pull.ts

@@ -1,8 +1,8 @@
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import type { AgnesConfig } from "../config";
 import { openDb } from "../db";
 import { introspect } from "../introspect";
-import { printSchema } from "../print";
+import { printSchema, printSchemaFiles } from "../print";
 import { c, confirm } from "../prompt";
 
 export interface PullArgs {
@@ -15,19 +15,30 @@ export async function pull(config: AgnesConfig, args: PullArgs): Promise<void> {
   console.log(c.cyan(`agnes pull ← ${config.driver}`));
   const db = await openDb(config);
 
-  const current = await introspect(db, config.driver);
+  const schemas = config.schemas?.length ? config.schemas : ["public"];
+  if (config.driver === "postgres" && schemas.length > 1) {
+    console.log(c.dim(`  schemas: ${schemas.join(", ")}`));
+  }
+
+  const current = await introspect(db, config.driver, schemas);
   const tableCount = Object.keys(current).length;
-  const source = printSchema(current);
+  console.log(c.green(`\n✓ Introspected ${tableCount} table(s).`));
 
-  const outPath = resolve(process.cwd(), args.out ?? config.out ?? "schema.ts");
-  const exists = await Bun.file(outPath).exists();
+  const multifile = config.pullMode === "multifile";
+  if (multifile) {
+    await writeMultifile(config, args, current);
+  } else {
+    await writeSinglefile(config, args, current);
+  }
+}
 
-  console.log(c.green(`\n✓ Introspected ${tableCount} table(s).`));
+async function writeSinglefile(config: AgnesConfig, args: PullArgs, ir: import("../ir").DatabaseIR) {
+  const outPath = resolve(process.cwd(), args.out ?? config.out ?? "schema.ts");
+  const source = printSchema(ir);
 
-  if (exists && !args.yes) {
+  if ((await Bun.file(outPath).exists()) && !args.yes) {
     console.log(c.yellow(`\n⚠ ${outPath} already exists and will be overwritten.`));
-    const ok = await confirm("Overwrite it?");
-    if (!ok) {
+    if (!(await confirm("Overwrite it?"))) {
       console.log(c.dim("Aborted. File left unchanged."));
       return;
     }
@@ -36,3 +47,26 @@ export async function pull(config: AgnesConfig, args: PullArgs): Promise<void> {
   await Bun.write(outPath, source);
   console.log(c.green(`✓ Wrote ${outPath}`));
 }
+
+async function writeMultifile(config: AgnesConfig, args: PullArgs, ir: import("../ir").DatabaseIR) {
+  // In multifile mode `out` names a directory (default ./schema).
+  const dir = resolve(process.cwd(), args.out ?? config.out ?? "schema");
+  const { files, index } = printSchemaFiles(ir);
+  const targets = [
+    ...files.map((f) => ({ path: join(dir, `${f.name}.ts`), source: f.source })),
+    { path: join(dir, "index.ts"), source: index },
+  ];
+
+  const existing = (await Promise.all(targets.map((t) => Bun.file(t.path).exists()))).some(Boolean);
+  if (existing && !args.yes) {
+    console.log(c.yellow(`\n⚠ Files under ${dir} already exist and will be overwritten.`));
+    if (!(await confirm("Overwrite them?"))) {
+      console.log(c.dim("Aborted. Files left unchanged."));
+      return;
+    }
+  }
+
+  for (const t of targets) await Bun.write(t.path, t.source);
+  console.log(c.green(`✓ Wrote ${files.length} schema file(s) + index → ${dir}`));
+  console.log(c.dim(`  point config.schemaPath / config.out at ${join(dir, "index.ts")}`));
+}

package/src/commands/push.ts

@@ -18,7 +18,7 @@ export async function push(config: AgnesConfig, args: PushArgs): Promise<void> {
   const db = await openDb(config);
 
   const desired = normalizeIR(schemaToIR(config.schema), config.driver);
-  const current = normalizeIR(await introspect(db, config.driver), config.driver);
+  const current = normalizeIR(await introspect(db, config.driver, config.schemas), config.driver);
   const ops = diffSchemas(desired, current);
 
   await applyPlan(db, config.driver, ops, args);

package/src/config.ts

@@ -15,8 +15,20 @@ export interface AgnesConfig {
   url: string;
   /** The schema object exported from your schema.ts (`export const schema = {...}`). */
   schema: DslSchema;
-  /** Where `pull` writes the generated schema (default: ./schema.ts). */
+  /** Where `pull` writes the generated schema (default: ./schema.ts).
+   * In `multifile` mode this is treated as a directory (default: ./schema). */
   out?: string;
+  /**
+   * PostgreSQL schemas to introspect on `pull`/`push` (default: `["public"]`).
+   * Tables outside the default schema get qualified physical names ("auth.users").
+   */
+  schemas?: string[];
+  /**
+   * How `pull` lays out the generated schema:
+   *  - "singlefile" (default): every table in one file.
+   *  - "multifile": one file per DB schema + an index re-exporting them merged.
+   */
+  pullMode?: "singlefile" | "multifile";
   /** Directory for versioned migration files (default: ./migrations). */
   migrationsDir?: string;
   maxConnections?: number;
@@ -28,6 +40,12 @@ export interface AgnesConfig {
    * e.g. "src/services/db.ts" or "db.js".
    */
   output?: string;
+  /**
+   * Env var holding the connection URL. When set, `agnes generate` emits
+   * `process.env[urlEnv]` in the client instead of inlining the literal URL —
+   * so credentials stay in your .env and never land in the generated file.
+   */
+  urlEnv?: string;
   /**
    * Module that exports `schema`, imported by the generated client.
    * Default: `out` (the pull target) or "./schema". A filesystem path

package/src/dialect.ts

@@ -51,7 +51,9 @@ export function logicalType(raw: string): ColumnType {
 }
 
 export function ident(dialect: Dialect, name: string): string {
-  return dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
+  const q = (p: string) => (dialect === "mysql" ? `\`${p}\`` : `"${p}"`);
+  // Qualified table refs ("schema.table") quote each part separately.
+  return name.includes(".") ? name.split(".").map(q).join(".") : q(name);
 }
 
 /** Render a default value as a SQL literal. */

package/src/generate.ts

@@ -1,5 +1,5 @@
 import { defaultLiteral, ident, physicalType, type Dialect } from "./dialect";
-import type { ColumnIR, ForeignKeyIR, TableIR } from "./ir";
+import { qualifiedName, type ColumnIR, type ForeignKeyIR, type TableIR } from "./ir";
 import type { Operation } from "./diff";
 
 function columnDef(dialect: Dialect, col: ColumnIR): string {
@@ -24,7 +24,7 @@ function createTable(dialect: Dialect, t: TableIR): string {
   if (dialect === "sqlite") {
     for (const fk of t.foreignKeys) lines.push(`  ${fkClause(dialect, fk)}`);
   }
-  return `CREATE TABLE ${ident(dialect, t.name)} (\n${lines.join(",\n")}\n);`;
+  return `CREATE TABLE ${ident(dialect, qualifiedName(t.name, t.schema))} (\n${lines.join(",\n")}\n);`;
 }
 
 function createIndex(dialect: Dialect, table: string, name: string, cols: string[], unique: boolean): string {
@@ -43,13 +43,14 @@ export function renderOperation(dialect: Dialect, op: Operation): string[] {
 
   switch (op.kind) {
     case "createTable": {
+      const qn = qualifiedName(op.table.name, op.table.schema);
       const out = [createTable(dialect, op.table)];
       for (const idx of op.table.indexes)
-        out.push(createIndex(dialect, op.table.name, idx.name, idx.columns, idx.unique));
+        out.push(createIndex(dialect, qn, idx.name, idx.columns, idx.unique));
       // Non-SQLite: add FKs after create (SQLite already inlined them).
       if (dialect !== "sqlite")
         for (const fk of op.table.foreignKeys)
-          out.push(`ALTER TABLE ${t(op.table.name)} ADD ${fkClause(dialect, fk)};`);
+          out.push(`ALTER TABLE ${t(qn)} ADD ${fkClause(dialect, fk)};`);
       return out;
     }
 

package/src/introspect.ts

@@ -1,5 +1,5 @@
 import { logicalType, type Dialect } from "./dialect";
-import type { ColumnIR, DatabaseIR, ForeignKeyIR, IndexIR, TableIR } from "./ir";
+import { qualifiedName, type ColumnIR, type DatabaseIR, type ForeignKeyIR, type IndexIR, type TableIR } from "./ir";
 
 // Minimal DB surface the CLI needs — satisfied by AgnesClient.
 export interface QueryClient {
@@ -17,10 +17,14 @@ function isInternal(name: string): boolean {
   return name.startsWith("_agnes") || name.startsWith("sqlite_");
 }
 
-export async function introspect(db: QueryClient, dialect: Dialect): Promise<DatabaseIR> {
+export async function introspect(
+  db: QueryClient,
+  dialect: Dialect,
+  schemas?: string[],
+): Promise<DatabaseIR> {
   switch (dialect) {
     case "postgres":
-      return introspectPostgres(db);
+      return introspectPostgres(db, schemas && schemas.length ? schemas : ["public"]);
     case "mysql":
       return introspectMysql(db);
     case "sqlite":
@@ -30,81 +34,87 @@ export async function introspect(db: QueryClient, dialect: Dialect): Promise<Dat
 
 // ─── PostgreSQL ─────────────────────────────────────────────────────────────
 
-async function introspectPostgres(db: QueryClient): Promise<DatabaseIR> {
+async function introspectPostgres(db: QueryClient, schemas: string[]): Promise<DatabaseIR> {
   const ir: DatabaseIR = {};
-  const tables = await db.query<Row>(
-    `SELECT table_name FROM information_schema.tables
-     WHERE table_schema = 'public' AND table_type = 'BASE TABLE'`,
-  );
-
-  for (const tr of tables) {
-    const name = str(tr.table_name);
-    if (isInternal(name)) continue;
-
-    const cols = await db.query<Row>(
-      `SELECT column_name, data_type, is_nullable, column_default
-       FROM information_schema.columns
-       WHERE table_schema = 'public' AND table_name = $1
-       ORDER BY ordinal_position`,
-      [name],
-    );
-    const pks = await db.query<Row>(
-      `SELECT kcu.column_name FROM information_schema.table_constraints tc
-       JOIN information_schema.key_column_usage kcu
-         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
-       WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_name = $1 AND tc.table_schema = 'public'`,
-      [name],
-    );
-    const pkSet = new Set(pks.map((r) => str(r.column_name)));
-
-    const columns: ColumnIR[] = cols.map((c) => ({
-      name: str(c.column_name),
-      type: logicalType(str(c.data_type)),
-      nullable: str(c.is_nullable) === "YES",
-      primary: pkSet.has(str(c.column_name)),
-      default: c.column_default == null ? undefined : str(c.column_default),
-    }));
 
-    const idxRows = await db.query<Row>(
-      `SELECT i.relname AS index_name, a.attname AS column_name,
-              ix.indisunique AS is_unique, ix.indisprimary AS is_primary
-       FROM pg_class t
-       JOIN pg_index ix ON t.oid = ix.indrelid
-       JOIN pg_class i ON i.oid = ix.indexrelid
-       JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
-       WHERE t.relname = $1 AND t.relkind = 'r'`,
-      [name],
-    );
-    const indexes = groupIndexes(
-      idxRows
-        .filter((r) => !truthy(r.is_primary))
-        .map((r) => ({ index: str(r.index_name), column: str(r.column_name), unique: truthy(r.is_unique) })),
+  for (const schema of schemas) {
+    const tables = await db.query<Row>(
+      `SELECT table_name FROM information_schema.tables
+       WHERE table_schema = $1 AND table_type = 'BASE TABLE'`,
+      [schema],
     );
 
-    const fkRows = await db.query<Row>(
-      `SELECT tc.constraint_name, kcu.column_name,
-              ccu.table_name AS foreign_table, ccu.column_name AS foreign_column,
-              rc.update_rule, rc.delete_rule
-       FROM information_schema.table_constraints tc
-       JOIN information_schema.key_column_usage kcu
-         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
-       JOIN information_schema.constraint_column_usage ccu
-         ON ccu.constraint_name = tc.constraint_name AND ccu.table_schema = tc.table_schema
-       JOIN information_schema.referential_constraints rc
-         ON rc.constraint_name = tc.constraint_name AND rc.constraint_schema = tc.table_schema
-       WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = $1 AND tc.table_schema = 'public'`,
-      [name],
-    );
-    const foreignKeys: ForeignKeyIR[] = fkRows.map((r) => ({
-      name: str(r.constraint_name),
-      column: str(r.column_name),
-      refTable: str(r.foreign_table),
-      refColumn: str(r.foreign_column),
-      onUpdate: str(r.update_rule).toUpperCase(),
-      onDelete: str(r.delete_rule).toUpperCase(),
-    }));
-
-    ir[name] = { name, columns, indexes, foreignKeys };
+    for (const tr of tables) {
+      const name = str(tr.table_name);
+      if (isInternal(name)) continue;
+
+      const cols = await db.query<Row>(
+        `SELECT column_name, data_type, is_nullable, column_default
+         FROM information_schema.columns
+         WHERE table_schema = $1 AND table_name = $2
+         ORDER BY ordinal_position`,
+        [schema, name],
+      );
+      const pks = await db.query<Row>(
+        `SELECT kcu.column_name FROM information_schema.table_constraints tc
+         JOIN information_schema.key_column_usage kcu
+           ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+         WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_name = $2 AND tc.table_schema = $1`,
+        [schema, name],
+      );
+      const pkSet = new Set(pks.map((r) => str(r.column_name)));
+
+      const columns: ColumnIR[] = cols.map((c) => ({
+        name: str(c.column_name),
+        type: logicalType(str(c.data_type)),
+        nullable: str(c.is_nullable) === "YES",
+        primary: pkSet.has(str(c.column_name)),
+        default: c.column_default == null ? undefined : str(c.column_default),
+      }));
+
+      const idxRows = await db.query<Row>(
+        `SELECT i.relname AS index_name, a.attname AS column_name,
+                ix.indisunique AS is_unique, ix.indisprimary AS is_primary
+         FROM pg_class t
+         JOIN pg_namespace n ON n.oid = t.relnamespace
+         JOIN pg_index ix ON t.oid = ix.indrelid
+         JOIN pg_class i ON i.oid = ix.indexrelid
+         JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+         WHERE t.relname = $2 AND n.nspname = $1 AND t.relkind = 'r'`,
+        [schema, name],
+      );
+      const indexes = groupIndexes(
+        idxRows
+          .filter((r) => !truthy(r.is_primary))
+          .map((r) => ({ index: str(r.index_name), column: str(r.column_name), unique: truthy(r.is_unique) })),
+      );
+
+      const fkRows = await db.query<Row>(
+        `SELECT tc.constraint_name, kcu.column_name,
+                ccu.table_schema AS foreign_schema, ccu.table_name AS foreign_table,
+                ccu.column_name AS foreign_column, rc.update_rule, rc.delete_rule
+         FROM information_schema.table_constraints tc
+         JOIN information_schema.key_column_usage kcu
+           ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+         JOIN information_schema.constraint_column_usage ccu
+           ON ccu.constraint_name = tc.constraint_name AND ccu.table_schema = tc.table_schema
+         JOIN information_schema.referential_constraints rc
+           ON rc.constraint_name = tc.constraint_name AND rc.constraint_schema = tc.table_schema
+         WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = $2 AND tc.table_schema = $1`,
+        [schema, name],
+      );
+      const foreignKeys: ForeignKeyIR[] = fkRows.map((r) => ({
+        name: str(r.constraint_name),
+        column: str(r.column_name),
+        refTable: qualifiedName(str(r.foreign_table), str(r.foreign_schema)),
+        refColumn: str(r.foreign_column),
+        onUpdate: str(r.update_rule).toUpperCase(),
+        onDelete: str(r.delete_rule).toUpperCase(),
+      }));
+
+      const s = schema === "public" ? undefined : schema;
+      ir[qualifiedName(name, s)] = { name, schema: s, columns, indexes, foreignKeys };
+    }
   }
   return ir;
 }

package/src/ir.ts

@@ -30,15 +30,23 @@ export interface ForeignKeyIR {
 }
 
 export interface TableIR {
+  /** Physical table name (unqualified). */
   name: string;
+  /** Owning DB schema. `undefined`/"public" = default schema. */
+  schema?: string;
   columns: ColumnIR[];
   indexes: IndexIR[];
   foreignKeys: ForeignKeyIR[];
 }
 
-/** Keyed by physical table name. */
+/** Keyed by qualified name (see {@link qualifiedName}). */
 export type DatabaseIR = Record<string, TableIR>;
 
+/** IR key / physical reference: `table` in the default schema, else `schema.table`. */
+export function qualifiedName(name: string, schema?: string): string {
+  return !schema || schema === "public" ? name : `${schema}.${name}`;
+}
+
 // ─── Structural view of the schema DSL ──────────────────────────────────────
 // We treat the schema object duck-typed (via `_kind`) so the CLI never has to
 // share a compiled build with agnes-library — only the shape matters.
@@ -140,7 +148,17 @@ export function schemaToIR(schema: DslSchema): DatabaseIR {
       // `many` relations have no physical footprint — the FK lives on the target side.
     }
 
-    ir[entry.tableName] = { name: entry.tableName, columns, indexes, foreignKeys };
+    // A dotted physical name ("auth.users") carries an explicit schema.
+    const dot = entry.tableName.indexOf(".");
+    const tblSchema = dot === -1 ? undefined : entry.tableName.slice(0, dot);
+    const bare = dot === -1 ? entry.tableName : entry.tableName.slice(dot + 1);
+    ir[qualifiedName(bare, tblSchema)] = {
+      name: bare,
+      schema: tblSchema,
+      columns,
+      indexes,
+      foreignKeys,
+    };
   }
 
   return ir;

package/src/print.ts

@@ -1,4 +1,4 @@
-import type { ColumnType, DatabaseIR, TableIR } from "./ir";
+import { qualifiedName, type ColumnType, type DatabaseIR, type TableIR } from "./ir";
 
 const HELPER: Record<ColumnType, string> = {
   int: "int",
@@ -18,6 +18,9 @@ const ON_ACTION: Record<string, string> = {
   "SET DEFAULT": "OnAction.SetDefault",
 };
 
+const HEADER =
+  `import { table, int, bigint, text, bool, float, bytes, json, one, OnAction } from "agnes-library";\n`;
+
 function onAction(rule: string): string {
   return ON_ACTION[rule.toUpperCase()] ?? "OnAction.None";
 }
@@ -28,7 +31,13 @@ function literal(v: unknown): string {
   return JSON.stringify(String(v));
 }
 
+/** A qualified name → a valid JS identifier (for the `schema` object keys / relation keys). */
+function idKey(name: string): string {
+  return name.replace(/[^A-Za-z0-9_]/g, "_");
+}
+
 function tableSource(t: TableIR): string {
+  const physical = qualifiedName(t.name, t.schema);
   const fkByColumn = new Map(t.foreignKeys.map((fk) => [fk.column, fk]));
   const lines: string[] = [];
 
@@ -49,26 +58,71 @@ function tableSource(t: TableIR): string {
 
   for (const fk of fkByColumn.values()) {
     // Relation TS key: derive from referenced table (best effort).
-    const relKey = fk.refTable;
+    const relKey = idKey(fk.refTable);
     lines.push(
       `    ${relKey}: one(${JSON.stringify(fk.refTable)}, ${JSON.stringify(fk.column)}, ` +
         `${JSON.stringify(fk.refColumn)}, ${onAction(fk.onUpdate)}, ${onAction(fk.onDelete)}),`,
     );
   }
 
-  return `  ${t.name}: table({\n${lines.join("\n")}\n  }, ${JSON.stringify(t.name)}),`;
+  return `  ${idKey(physical)}: table({\n${lines.join("\n")}\n  }, ${JSON.stringify(physical)}),`;
 }
 
-/** Render a full DatabaseIR into schema.ts source code. */
-export function printSchema(ir: DatabaseIR): string {
-  const tables = Object.values(ir)
-    .sort((a, b) => a.name.localeCompare(b.name))
+function schemaBlock(tables: TableIR[]): string {
+  const body = tables
+    .slice()
+    .sort((a, b) => qualifiedName(a.name, a.schema).localeCompare(qualifiedName(b.name, b.schema)))
     .map(tableSource)
     .join("\n");
+  return `export const schema = {\n${body}\n};\n`;
+}
 
+/** Render a full DatabaseIR into a single schema.ts source string. */
+export function printSchema(ir: DatabaseIR): string {
   return (
     `// Generated by \`agnes pull\`. Edit and re-run \`agnes push\` to apply changes.\n` +
-    `import { table, int, bigint, text, bool, float, bytes, json, one, OnAction } from "agnes-library";\n\n` +
-    `export const schema = {\n${tables}\n};\n`
+    HEADER +
+    `\n` +
+    schemaBlock(Object.values(ir))
   );
 }
+
+export interface SchemaFile {
+  /** Bare file name without extension, e.g. "public", "auth". */
+  name: string;
+  source: string;
+}
+
+/**
+ * Render a DatabaseIR into one file per DB schema plus an `index` that
+ * re-exports every file's tables merged into a single `schema` object.
+ */
+export function printSchemaFiles(ir: DatabaseIR): { files: SchemaFile[]; index: string } {
+  const bySchema = new Map<string, TableIR[]>();
+  for (const t of Object.values(ir)) {
+    const key = t.schema ?? "public";
+    (bySchema.get(key) ?? bySchema.set(key, []).get(key)!).push(t);
+  }
+
+  const names = [...bySchema.keys()].sort();
+  const files: SchemaFile[] = names.map((name) => ({
+    name,
+    source:
+      `// Generated by \`agnes pull\`. Schema "${name}".\n` +
+      HEADER +
+      `\n` +
+      schemaBlock(bySchema.get(name)!),
+  }));
+
+  // Alias with a "Schema" suffix so reserved words (e.g. "public") stay valid bindings.
+  const alias = (n: string) => `${idKey(n)}Schema`;
+  const imports = names
+    .map((n) => `import { schema as ${alias(n)} } from ${JSON.stringify(`./${n}`)};`)
+    .join("\n");
+  const spread = names.map((n) => `  ...${alias(n)},`).join("\n");
+  const index =
+    `// Generated by \`agnes pull\`. Merges every per-schema file into one \`schema\`.\n` +
+    `${imports}\n\nexport const schema = {\n${spread}\n};\n`;
+
+  return { files, index };
+}