From 46d62ee746f5bc5225ac5828c17110423217380d Mon Sep 17 00:00:00 2001
From: Dan Lynch <pyramation@gmail.com>
Date: Fri, 31 Jul 2026 22:47:50 +0000
Subject: [PATCH 1/6] =?UTF-8?q?feat(pgpm):=20pgpm=20import=20=E2=80=94=20p?=
 =?UTF-8?q?gpm-itize=20a=20SQL=20dump=20through=20the=20dials=20pipeline?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pgpm/cli/__tests__/import-e2e.test.ts     | 209 ++++++++++++++++++++++
 pgpm/cli/src/commands.ts                  |   2 +
 pgpm/cli/src/commands/import.ts           | 192 ++++++++++++++++++++
 pgpm/cli/src/commands/transform.ts        |   2 +-
 pgpm/cli/src/utils/display.ts             |   1 +
 pgpm/export/__tests__/dump-source.test.ts | 115 ++++++++++++
 pgpm/export/src/dump-source.ts            |  78 ++++++++
 pgpm/export/src/index.ts                  |   2 +
 8 files changed, 600 insertions(+), 1 deletion(-)
 create mode 100644 pgpm/cli/__tests__/import-e2e.test.ts
 create mode 100644 pgpm/cli/src/commands/import.ts
 create mode 100644 pgpm/export/__tests__/dump-source.test.ts
 create mode 100644 pgpm/export/src/dump-source.ts

diff --git a/pgpm/cli/__tests__/import-e2e.test.ts b/pgpm/cli/__tests__/import-e2e.test.ts
new file mode 100644
index 000000000..1d148b084
--- /dev/null
+++ b/pgpm/cli/__tests__/import-e2e.test.ts
@@ -0,0 +1,209 @@
+/**
+ * e2e for `pgpm import` against live Postgres: a pg_dump-style example dump
+ * (psql \\restrict/\\unrestrict meta-commands, session SET noise, OWNER TO) is
+ * imported at object granularity, deployed, verified, and reverted clean.
+ *
+ * PREREQUISITES: a running PostgreSQL instance via standard PG* env vars.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { teardownPgPools } from 'pg-cache';
+
+import { CLIDeployTestFixture } from '../test-utils';
+
+jest.setTimeout(120000);
+
+afterAll(async () => {
+  await teardownPgPools();
+});
+
+const WS = 'import-ws';
+const MODULE_NAME = 'import-e2e';
+
+/** Example pg_dump --schema-only output shape (plain format). */
+const DUMP_SQL = `--
+-- PostgreSQL database dump
+--
+
+\\restrict 8fKz01Lm3q
+
+-- Dumped from database version 18.0
+-- Dumped by pg_dump version 18.0
+
+SET statement_timeout = 0;
+SET lock_timeout = 0;
+SET idle_in_transaction_session_timeout = 0;
+SET client_encoding = 'UTF8';
+SET standard_conforming_strings = on;
+SELECT pg_catalog.set_config('search_path', '', false);
+SET check_function_bodies = false;
+SET xmloption = content;
+SET client_min_messages = warning;
+SET row_security = off;
+
+--
+-- Name: imp_app; Type: SCHEMA; Schema: -; Owner: postgres
+--
+
+CREATE SCHEMA imp_app;
+
+ALTER SCHEMA imp_app OWNER TO postgres;
+
+--
+-- Name: users; Type: TABLE; Schema: imp_app; Owner: postgres
+--
+
+CREATE TABLE imp_app.users (
+    id integer NOT NULL,
+    email text NOT NULL
+);
+
+ALTER TABLE imp_app.users OWNER TO postgres;
+
+--
+-- Name: notes; Type: TABLE; Schema: imp_app; Owner: postgres
+--
+
+CREATE TABLE imp_app.notes (
+    id integer NOT NULL,
+    user_id integer NOT NULL,
+    body text
+);
+
+ALTER TABLE imp_app.notes OWNER TO postgres;
+
+--
+-- Name: users users_pkey; Type: CONSTRAINT; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_app.users
+    ADD CONSTRAINT users_pkey PRIMARY KEY (id);
+
+--
+-- Name: notes notes_pkey; Type: CONSTRAINT; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_app.notes
+    ADD CONSTRAINT notes_pkey PRIMARY KEY (id);
+
+--
+-- Name: notes notes_user_id_fkey; Type: FK CONSTRAINT; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_app.notes
+    ADD CONSTRAINT notes_user_id_fkey FOREIGN KEY (user_id) REFERENCES imp_app.users(id);
+
+--
+-- Name: notes_user_id_idx; Type: INDEX; Schema: imp_app; Owner: postgres
+--
+
+CREATE INDEX notes_user_id_idx ON imp_app.notes USING btree (user_id);
+
+\\unrestrict 8fKz01Lm3q
+
+--
+-- PostgreSQL database dump complete
+--
+`;
+
+describe('pgpm import e2e', () => {
+  let fixture: CLIDeployTestFixture;
+  let wsDir: string;
+
+  beforeAll(async () => {
+    fixture = new CLIDeployTestFixture();
+    wsDir = path.join(fixture.tempFixtureDir, WS);
+    fs.mkdirSync(wsDir, { recursive: true });
+    fs.writeFileSync(path.join(wsDir, 'pgpm.json'), '{\n    "packages": [\n        "*"\n    ]\n}');
+    fs.writeFileSync(path.join(wsDir, `${MODULE_NAME}.sql`), DUMP_SQL);
+  });
+
+  afterAll(async () => {
+    await fixture.cleanup();
+  });
+
+  it('--dry-run prints derived changes without writing', async () => {
+    await fixture.runTerminalCommands(
+      `
+      cd ${WS}
+      pgpm import ${MODULE_NAME}.sql --granularity object --dry-run
+      `,
+      {}
+    );
+    expect(fs.existsSync(path.join(wsDir, MODULE_NAME))).toBe(false);
+  });
+
+  it('imports the dump into a complete pgpm module', async () => {
+    await fixture.runTerminalCommands(
+      `
+      cd ${WS}
+      pgpm import ${MODULE_NAME}.sql --granularity object
+      `,
+      {}
+    );
+
+    const moduleDir = path.join(wsDir, MODULE_NAME);
+    expect(fs.existsSync(path.join(moduleDir, 'pgpm.plan'))).toBe(true);
+    expect(fs.existsSync(path.join(moduleDir, `${MODULE_NAME}.control`))).toBe(true);
+
+    const plan = fs.readFileSync(path.join(moduleDir, 'pgpm.plan'), 'utf-8');
+    expect(plan).toContain('schemas/imp_app/schema');
+    expect(plan).toContain('tables/users/table');
+    expect(plan).toContain('tables/notes/table');
+
+    // psql/session/ownership noise must not leak into deploy scripts
+    const deployDir = path.join(moduleDir, 'deploy');
+    const walk = (dir: string): string[] =>
+      fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry =>
+        entry.isDirectory() ? walk(path.join(dir, entry.name)) : [path.join(dir, entry.name)]
+      );
+    for (const file of walk(deployDir)) {
+      const sql = fs.readFileSync(file, 'utf-8');
+      expect(sql).not.toContain('\\restrict');
+      expect(sql).not.toContain('OWNER TO');
+      expect(sql).not.toContain('set_config');
+    }
+  });
+
+  it('deploys, verifies, and reverts the imported module cleanly', async () => {
+    const testDb = await fixture.setupTestDatabase();
+
+    await fixture.runTerminalCommands(
+      `
+      cd ${WS}/${MODULE_NAME}
+      pgpm deploy --database ${testDb.name} --package ${MODULE_NAME} --yes
+      `,
+      { database: testDb.name }
+    );
+
+    expect(await testDb.exists('schema', 'imp_app')).toBe(true);
+    expect(await testDb.exists('table', 'imp_app.users')).toBe(true);
+    expect(await testDb.exists('table', 'imp_app.notes')).toBe(true);
+
+    const fk = await testDb.query(
+      `SELECT conname FROM pg_constraint WHERE conname = 'notes_user_id_fkey'`
+    );
+    expect(fk.rows).toHaveLength(1);
+
+    const idx = await testDb.query(
+      `SELECT indexname FROM pg_indexes WHERE schemaname = 'imp_app' AND indexname = 'notes_user_id_idx'`
+    );
+    expect(idx.rows).toHaveLength(1);
+
+    await fixture.runTerminalCommands(
+      `
+      cd ${WS}/${MODULE_NAME}
+      pgpm verify --database ${testDb.name} --package ${MODULE_NAME} --yes
+      pgpm revert --database ${testDb.name} --package ${MODULE_NAME} --yes
+      `,
+      { database: testDb.name }
+    );
+
+    expect(await testDb.exists('schema', 'imp_app')).toBe(false);
+    const remaining = await testDb.query(
+      `SELECT COUNT(*)::int AS count FROM pgpm_migrate.changes WHERE package = $1`,
+      [MODULE_NAME]
+    );
+    expect(remaining.rows[0].count).toBe(0);
+  });
+});
diff --git a/pgpm/cli/src/commands.ts b/pgpm/cli/src/commands.ts
index b120752ca..dc12ba02d 100644
--- a/pgpm/cli/src/commands.ts
+++ b/pgpm/cli/src/commands.ts
@@ -14,6 +14,7 @@ import dump from './commands/dump';
 import env from './commands/env';
 import _export from './commands/export';
 import extension from './commands/extension';
+import importDump from './commands/import';
 import init from './commands/init';
 import install from './commands/install';
 import kill from './commands/kill';
@@ -113,6 +114,7 @@ export const createPgpmCommandMap = (skipPgTeardown: boolean = false): Record<st
     slice,
     'sync-versions': syncVersions,
     'test-packages': pgt(testPackages),
+    import: pgt(importDump),
     transform: pgt(transform),
     tune: pgt(tune),
     upgrade: pgt(upgrade),
diff --git a/pgpm/cli/src/commands/import.ts b/pgpm/cli/src/commands/import.ts
new file mode 100644
index 000000000..cce6a3e83
--- /dev/null
+++ b/pgpm/cli/src/commands/import.ts
@@ -0,0 +1,192 @@
+import { PgpmRow } from '@pgpmjs/core';
+import {
+  EXPORT_GRANULARITIES,
+  ExportGranularity,
+  isExportGranularity,
+  loadDumpSource,
+  parsePartitionConfig,
+  PartitionConfig,
+  PartitionedPackageRows,
+  partitionExportRows,
+  restructureExportRows
+} from '@pgpmjs/export';
+import { Logger } from '@pgpmjs/logger';
+import { PartitionCycleError } from '@pgpmjs/transform';
+import { CLIOptions, cliExitWithError, Inquirerer, ParsedArgs } from 'inquirerer';
+import * as path from 'path';
+
+import { checkOverwrite, writePackage } from './transform';
+
+const log = new Logger('import');
+
+const importUsageText = `
+Import Command:
+
+  pgpm import <dump.sql> --granularity <atomic|object|consolidated> [OPTIONS]
+
+  pgpm-itize a SQL dump (pg_dump plain format or any plain SQL file) through
+  the dials pipeline: psql meta-commands and session/ownership noise are
+  stripped, then the statements are re-projected at the requested granularity
+  with spec-derived change paths, graph-derived requires, and generated
+  revert/verify scripts — emitting a complete pgpm module.
+
+Options:
+  --help, -h              Show this help message
+  --granularity <level>   Target granularity: atomic | object | consolidated (required)
+  --name <module>         Module name (default: dump file name without extension)
+  --partition <file>      Partition config (JSON: rules/defaultPackage/splitRiders)
+                          splitting the import into multiple pgpm packages with
+                          derived cross-package requires.
+  --naming <style>        Change path naming style: directory | flat (default: directory)
+  --cwd <directory>       Base directory (default: current directory)
+  --out <dir>             Output directory the module dir is created in (default: --cwd)
+  --write                 Allow writing over an existing output directory
+  --dry-run               Print the resulting plan/paths without writing
+
+Examples:
+  pg_dump --schema-only mydb > mydb.sql
+  pgpm import mydb.sql --granularity object
+  pgpm import mydb.sql --granularity consolidated --name my-module --out ./packages
+  pgpm import mydb.sql --granularity object --partition partition.json
+`;
+
+const NAMING_STYLES = ['directory', 'flat'] as const;
+type NamingStyle = (typeof NAMING_STYLES)[number];
+
+interface ImportedDump {
+  name: string;
+  outBase: string;
+  packages: PartitionedPackageRows[];
+  warnings: string[];
+}
+
+const importDump = async (
+  dumpFile: string,
+  name: string | undefined,
+  granularity: ExportGranularity,
+  naming: NamingStyle,
+  partition: PartitionConfig | undefined,
+  outBase: string
+): Promise<ImportedDump> => {
+  const source = loadDumpSource(dumpFile, name);
+  const warnings = [...source.warnings];
+
+  const rows: PgpmRow[] = [
+    {
+      name: source.name,
+      deploy: source.name,
+      deps: [],
+      content: source.sql
+    }
+  ];
+
+  const restructured = await restructureExportRows(rows, granularity, { naming });
+  warnings.push(...restructured.warnings.map(w => `restructure (${granularity}): ${w}`));
+
+  let packages: PartitionedPackageRows[];
+  if (partition) {
+    const result = await partitionExportRows(restructured.rows, partition);
+    warnings.push(...result.warnings.map(w => `partition: ${w}`));
+    packages = result.packages;
+  } else {
+    packages = [{ name: source.name, requires: [], rows: restructured.rows }];
+  }
+
+  return { name: source.name, outBase, packages, warnings };
+};
+
+const printDryRun = (imported: ImportedDump): void => {
+  for (const pkg of imported.packages) {
+    console.log(`  package ${pkg.name} -> ${path.join(imported.outBase, pkg.name)}`);
+    for (const row of pkg.rows) {
+      const deps = row.deps?.length ? ` [${row.deps.join(' ')}]` : '';
+      console.log(`    ${row.deploy}${deps}`);
+    }
+  }
+};
+
+export default async (
+  argv: Partial<ParsedArgs>,
+  prompter: Inquirerer,
+  _options: CLIOptions
+) => {
+  if (argv.help || argv.h) {
+    console.log(importUsageText);
+    process.exit(0);
+  }
+
+  const dumpFile = argv._?.[0] as string | undefined;
+  if (!dumpFile) {
+    await cliExitWithError('Usage: pgpm import <dump.sql> --granularity <atomic|object|consolidated>');
+    return;
+  }
+
+  const granularityRaw = argv.granularity;
+  if (granularityRaw === undefined) {
+    await cliExitWithError(`--granularity is required. Expected one of: ${EXPORT_GRANULARITIES.join(', ')}.`);
+  }
+  if (!isExportGranularity(granularityRaw)) {
+    await cliExitWithError(`Invalid --granularity "${granularityRaw}". Expected one of: ${EXPORT_GRANULARITIES.join(', ')}.`);
+  }
+  const granularity = granularityRaw as ExportGranularity;
+
+  const namingRaw = (argv.naming as string) ?? 'directory';
+  if (!(NAMING_STYLES as readonly string[]).includes(namingRaw)) {
+    await cliExitWithError(`Invalid --naming "${namingRaw}". Expected one of: ${NAMING_STYLES.join(', ')}.`);
+  }
+  const naming = namingRaw as NamingStyle;
+
+  const cwd = (argv.cwd as string) || process.cwd();
+
+  let partition: PartitionConfig | undefined;
+  if (typeof argv.partition === 'string' && argv.partition) {
+    try {
+      partition = parsePartitionConfig(path.resolve(cwd, argv.partition));
+    } catch (err) {
+      await cliExitWithError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  const name = typeof argv.name === 'string' && argv.name ? argv.name : undefined;
+  const outBase = typeof argv.out === 'string' && argv.out ? path.resolve(cwd, argv.out) : path.resolve(cwd);
+  const write = Boolean(argv.write);
+  const dryRun = Boolean(argv['dry-run'] ?? argv.dryRun);
+
+  let imported: ImportedDump;
+  try {
+    imported = await importDump(path.resolve(cwd, dumpFile), name, granularity, naming, partition, outBase);
+  } catch (err) {
+    if (err instanceof PartitionCycleError) {
+      await cliExitWithError(`Partition failed: ${err.message}`);
+      return;
+    }
+    await cliExitWithError(err instanceof Error ? err.message : String(err));
+    return;
+  }
+
+  for (const warning of imported.warnings) {
+    console.warn(`import: ${warning}`);
+  }
+
+  if (dryRun) {
+    printDryRun(imported);
+    prompter.close();
+    return argv;
+  }
+
+  for (const pkg of imported.packages) {
+    const targetDir = path.join(imported.outBase, pkg.name);
+    const guard = checkOverwrite(targetDir, path.resolve(cwd, dumpFile), write);
+    if (guard) {
+      await cliExitWithError(guard);
+    }
+  }
+
+  for (const pkg of imported.packages) {
+    const dir = writePackage(imported.outBase, pkg, []);
+    log.success(`wrote ${pkg.rows.length} changes to ${dir}`);
+  }
+
+  prompter.close();
+  return argv;
+};
diff --git a/pgpm/cli/src/commands/transform.ts b/pgpm/cli/src/commands/transform.ts
index e72af6087..3fa43d485 100644
--- a/pgpm/cli/src/commands/transform.ts
+++ b/pgpm/cli/src/commands/transform.ts
@@ -138,7 +138,7 @@ const writeControlFile = (dir: string, name: string, requires: string[]): void =
   fs.writeFileSync(path.join(dir, `${name}.control`), lines.join('\n') + '\n');
 };
 
-const writePackage = (
+export const writePackage = (
   outBase: string,
   pkg: PartitionedPackageRows,
   sourceRequires: string[]
diff --git a/pgpm/cli/src/utils/display.ts b/pgpm/cli/src/utils/display.ts
index 12db03b5d..ea3473178 100644
--- a/pgpm/cli/src/utils/display.ts
+++ b/pgpm/cli/src/utils/display.ts
@@ -17,6 +17,7 @@ export const usageText = `
     materialize        Transpile an apply proxy into a plain, committed module
     sync-versions      Sync .control/Makefile/sql metadata to package.json versions
     export             Export database migrations from existing databases
+    import             pgpm-itize a SQL dump (pg_dump) into a pgpm module
     update             Update pgpm to the latest version
     cache              Manage cached templates (clean)
     upgrade            Upgrade installed pgpm modules to latest versions (alias: up)
diff --git a/pgpm/export/__tests__/dump-source.test.ts b/pgpm/export/__tests__/dump-source.test.ts
new file mode 100644
index 000000000..2749a7bd6
--- /dev/null
+++ b/pgpm/export/__tests__/dump-source.test.ts
@@ -0,0 +1,115 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { loadDumpSource, sanitizeDumpSql } from '../src/dump-source';
+
+const PG_DUMP_SAMPLE = `--
+-- PostgreSQL database dump
+--
+
+\\restrict hK3jf82Klm
+
+-- Dumped from database version 18.0
+
+SET statement_timeout = 0;
+SET lock_timeout = 0;
+SET client_encoding = 'UTF8';
+SET standard_conforming_strings = on;
+SELECT pg_catalog.set_config('search_path', '', false);
+SET check_function_bodies = false;
+SET row_security = off;
+
+CREATE SCHEMA app;
+
+ALTER SCHEMA app OWNER TO postgres;
+
+CREATE TABLE app.users (
+    id integer NOT NULL,
+    email text NOT NULL
+);
+
+ALTER TABLE app.users OWNER TO postgres;
+
+ALTER TABLE ONLY app.users
+    ADD CONSTRAINT users_pkey PRIMARY KEY (id);
+
+\\unrestrict hK3jf82Klm
+
+--
+-- PostgreSQL database dump complete
+--
+`;
+
+describe('sanitizeDumpSql', () => {
+  it('strips psql meta-commands, SET/set_config noise, and OWNER TO', () => {
+    const { sql, warnings } = sanitizeDumpSql(PG_DUMP_SAMPLE);
+
+    expect(sql).not.toContain('\\restrict');
+    expect(sql).not.toContain('\\unrestrict');
+    expect(sql).not.toContain('SET statement_timeout');
+    expect(sql).not.toContain('set_config');
+    expect(sql).not.toContain('OWNER TO');
+
+    expect(sql).toContain('CREATE SCHEMA app;');
+    expect(sql).toContain('CREATE TABLE app.users');
+    expect(sql).toContain('ADD CONSTRAINT users_pkey PRIMARY KEY (id);');
+
+    expect(warnings).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('psql meta-command'),
+        expect.stringContaining('session SET statement'),
+        expect.stringContaining('set_config'),
+        expect.stringContaining('OWNER TO')
+      ])
+    );
+  });
+
+  it('keeps SET-like tokens inside multi-line statements', () => {
+    const body = [
+      'CREATE FUNCTION app.touch() RETURNS trigger AS $$',
+      'BEGIN',
+      '  UPDATE app.users SET email = NEW.email WHERE id = NEW.id;',
+      '  RETURN NEW;',
+      'END $$ LANGUAGE plpgsql;'
+    ].join('\n');
+    const { sql } = sanitizeDumpSql(body);
+    expect(sql).toBe(body);
+  });
+
+  it('passes plain SQL through unchanged with no warnings', () => {
+    const { sql, warnings } = sanitizeDumpSql('CREATE SCHEMA app;\n');
+    expect(sql).toBe('CREATE SCHEMA app;');
+    expect(warnings).toEqual([]);
+  });
+});
+
+describe('loadDumpSource', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'pgpm-dump-source-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('derives the module name from the file name', () => {
+    const file = join(dir, 'my-app.sql');
+    writeFileSync(file, PG_DUMP_SAMPLE);
+    const source = loadDumpSource(file);
+    expect(source.name).toBe('my-app');
+    expect(source.sql).toContain('CREATE TABLE app.users');
+  });
+
+  it('honors an explicit name override', () => {
+    const file = join(dir, 'raw.sql');
+    writeFileSync(file, 'CREATE SCHEMA app;');
+    expect(loadDumpSource(file, 'renamed').name).toBe('renamed');
+  });
+
+  it('throws on a missing file', () => {
+    expect(() => loadDumpSource(join(dir, 'nope.sql'))).toThrow(/not found/);
+  });
+});
diff --git a/pgpm/export/src/dump-source.ts b/pgpm/export/src/dump-source.ts
new file mode 100644
index 000000000..8a7e68122
--- /dev/null
+++ b/pgpm/export/src/dump-source.ts
@@ -0,0 +1,78 @@
+/**
+ * Dump ingestion for `pgpm import`: turn a SQL dump (pg_dump plain format or
+ * any plain SQL file) into parseable SQL text for the dials pipeline.
+ *
+ * pg_dump output is peppered with psql meta-commands and session settings the
+ * SQL parser cannot (and should not) consume — those are stripped here;
+ * everything else flows through unchanged.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface DumpSource {
+  /** Module name derived from the file name (or overridden by the caller). */
+  name: string;
+  /** Absolute path of the dump file. */
+  filePath: string;
+  /** Sanitized SQL, safe to hand to the parser. */
+  sql: string;
+  /** One entry per stripped construct class, for CLI visibility. */
+  warnings: string[];
+}
+
+/** psql meta-commands: \restrict, \unrestrict, \connect, \echo, ... */
+const PSQL_META = /^\s*\\/;
+/** Session settings pg_dump emits at the top of every dump. */
+const SET_STATEMENT = /^\s*SET\s+[\w.]+\s*(=|TO)\s*[^;]*;\s*$/i;
+const SET_CONFIG = /^\s*SELECT\s+pg_catalog\.set_config\s*\(.*\)\s*;\s*$/i;
+/** Ownership is environment-specific; dumps replay it, modules must not. */
+const OWNER_TO = /^\s*ALTER\s+.*\s+OWNER\s+TO\s+[^;]+;\s*$/i;
+
+interface StripRule {
+  pattern: RegExp;
+  label: string;
+}
+
+const STRIP_RULES: StripRule[] = [
+  { pattern: PSQL_META, label: 'psql meta-command (\\...)' },
+  { pattern: SET_STATEMENT, label: 'session SET statement' },
+  { pattern: SET_CONFIG, label: 'pg_catalog.set_config() call' },
+  { pattern: OWNER_TO, label: 'ALTER ... OWNER TO statement' }
+];
+
+/**
+ * Strip psql meta-commands and session/ownership noise from dump SQL,
+ * line-wise (pg_dump emits each of these on its own line). Returns the
+ * sanitized SQL and a summary of what was removed.
+ */
+export const sanitizeDumpSql = (sql: string): { sql: string; warnings: string[] } => {
+  const counts = new Map<string, number>();
+  const lines = sql.split('\n').filter(line => {
+    const rule = STRIP_RULES.find(r => r.pattern.test(line));
+    if (rule) {
+      counts.set(rule.label, (counts.get(rule.label) ?? 0) + 1);
+      return false;
+    }
+    return true;
+  });
+  const warnings = [...counts.entries()].map(
+    ([label, count]) => `stripped ${count} ${label}${count === 1 ? '' : 's'}`
+  );
+  return { sql: lines.join('\n').trim(), warnings };
+};
+
+/** Load and sanitize a SQL dump file. */
+export const loadDumpSource = (dumpFile: string, name?: string): DumpSource => {
+  const filePath = path.resolve(dumpFile);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Dump file not found: ${filePath}`);
+  }
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const { sql, warnings } = sanitizeDumpSql(raw);
+  return {
+    name: name ?? path.basename(filePath).replace(/\.(sql|dump)$/i, ''),
+    filePath,
+    sql,
+    warnings
+  };
+};
diff --git a/pgpm/export/src/index.ts b/pgpm/export/src/index.ts
index 45775ca03..e39df9387 100644
--- a/pgpm/export/src/index.ts
+++ b/pgpm/export/src/index.ts
@@ -5,6 +5,8 @@ export * from './export-graphql';
 export * from './export-graphql-meta';
 export { EXPORT_GRANULARITIES, isExportGranularity, restructureExportRows } from './restructure';
 export type { ExportGranularity, RestructureExportRowsOptions, RestructureExportRowsResult } from './restructure';
+export { loadDumpSource, sanitizeDumpSql } from './dump-source';
+export type { DumpSource } from './dump-source';
 export { loadModuleSource, stripTransactionWrapper } from './module-source';
 export type { ModuleSource, ModuleSourceChange } from './module-source';
 export { parsePartitionConfig, partitionExportRows } from './partition';

From 3052f5f867eda6658fe538a35756cd00dc58d9bf Mon Sep 17 00:00:00 2001
From: Dan Lynch <pyramation@gmail.com>
Date: Fri, 31 Jul 2026 22:53:05 +0000
Subject: [PATCH 2/6] =?UTF-8?q?feat(pgpm):=20add=20pgpm=20import=20?=
 =?UTF-8?q?=E2=80=94=20pgpm-itize=20an=20arbitrary=20SQL=20dump=20(Part=20?=
 =?UTF-8?q?A=20of=20#1340)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pgpm/cli/src/commands.ts           |   3 +
 pgpm/cli/src/commands/import.ts    | 153 ++++++++++++
 pgpm/cli/src/commands/transform.ts |  63 +----
 pgpm/cli/src/utils/display.ts      |   1 +
 pgpm/cli/src/utils/emit-package.ts |  74 ++++++
 pgpm/export/src/dump-source.ts     | 214 +++++++++++++++++
 pgpm/export/src/import.ts          | 358 +++++++++++++++++++++++++++++
 pgpm/export/src/index.ts           |   4 +
 8 files changed, 812 insertions(+), 58 deletions(-)
 create mode 100644 pgpm/cli/src/commands/import.ts
 create mode 100644 pgpm/cli/src/utils/emit-package.ts
 create mode 100644 pgpm/export/src/dump-source.ts
 create mode 100644 pgpm/export/src/import.ts

diff --git a/pgpm/cli/src/commands.ts b/pgpm/cli/src/commands.ts
index b120752ca..843fac233 100644
--- a/pgpm/cli/src/commands.ts
+++ b/pgpm/cli/src/commands.ts
@@ -14,6 +14,7 @@ import dump from './commands/dump';
 import env from './commands/env';
 import _export from './commands/export';
 import extension from './commands/extension';
+import _import from './commands/import';
 import init from './commands/init';
 import install from './commands/install';
 import kill from './commands/kill';
@@ -57,6 +58,7 @@ const ENGINE_EXEMPT_COMMANDS = new Set([
   'doctor',
   'env',
   'extension',
+  'import',
   'init',
   'install',
   'package',
@@ -102,6 +104,7 @@ export const createPgpmCommandMap = (skipPgTeardown: boolean = false): Record<st
     plan: pgt(plan),
     regen,
     export: pgt(_export),
+    import: pgt(_import),
     package: pgt(_package),
     tag: pgt(tag),
     kill: pgt(kill),
diff --git a/pgpm/cli/src/commands/import.ts b/pgpm/cli/src/commands/import.ts
new file mode 100644
index 000000000..5d99a8bca
--- /dev/null
+++ b/pgpm/cli/src/commands/import.ts
@@ -0,0 +1,153 @@
+import {
+  EXPORT_GRANULARITIES,
+  ExportGranularity,
+  importDumpRows,
+  isExportGranularity,
+  loadDumpSource
+} from '@pgpmjs/export';
+import { Logger } from '@pgpmjs/logger';
+import { CLIOptions, cliExitWithError, Inquirerer, ParsedArgs } from 'inquirerer';
+import * as path from 'path';
+
+import { checkOverwrite, writePackage } from '../utils/emit-package';
+
+const log = new Logger('import');
+
+const importUsageText = `
+Import Command:
+
+  pgpm import <dump.sql | dir-of-sql-files> --pkg <module-name> [OPTIONS]
+
+  pgpm-itize an arbitrary SQL dump (e.g. pg_dump --schema-only output): parse
+  it, classify every statement, and emit a complete deployable pgpm module —
+  module dir, pgpm.plan, and deploy/revert/verify trees with spec-derived
+  change paths, graph-derived requires, and generated revert/verify scripts.
+
+  Directory inputs concatenate their .sql files in sorted (lexicographic)
+  filename order.
+
+  Dump handling:
+  - pg_dump preamble noise (SET ..., SELECT set_config(...), psql backslash
+    commands) is skipped; COMMENT ON and GRANT statements are kept, attached
+    to their host object's change.
+  - CREATE EXTENSION statements become .control requires (pgpm owns
+    extension creation at deploy time).
+  - COPY ... FROM stdin blocks and INSERTs are skipped with a warning unless
+    --with-data is passed, which emits them as seed fixture changes (COPY
+    data is converted to INSERTs).
+  - Statements that classify to no object land in a misc/statements change
+    with a warning — never dropped silently.
+
+Options:
+  --help, -h              Show this help message
+  --pkg <name>            Module name for the generated package (required)
+  --granularity <level>   Granularity dial: atomic | object | consolidated
+                          (default: object)
+  --naming <style>        Change path naming style: directory | flat (default: directory)
+  --out <dir>             Output base directory (default: current directory);
+                          the module is written to <out>/<pkg>
+  --with-data             Import COPY/INSERT data as seed fixture changes
+  --write                 Allow overwriting an existing module directory
+  --cwd <directory>       Working directory (default: current directory)
+  --dry-run               Print the resulting plan/paths without writing
+
+Examples:
+  pgpm import dump.sql --pkg my-app
+  pgpm import dump.sql --pkg my-app --granularity consolidated --naming flat
+  pgpm import ./sql-files --pkg my-app --out ./packages --with-data
+`;
+
+const NAMING_STYLES = ['directory', 'flat'] as const;
+type NamingStyle = (typeof NAMING_STYLES)[number];
+
+export default async (
+  argv: Partial<ParsedArgs>,
+  prompter: Inquirerer,
+  _options: CLIOptions
+) => {
+  if (argv.help || argv.h) {
+    console.log(importUsageText);
+    process.exit(0);
+  }
+
+  const cwd = (argv.cwd as string) || process.cwd();
+
+  const input = (argv._ as string[] | undefined)?.filter(Boolean)[0];
+  if (!input) {
+    await cliExitWithError('Missing input: pgpm import <dump.sql | dir-of-sql-files> --pkg <name>');
+  }
+
+  const pkgName = argv.pkg as string | undefined;
+  if (!pkgName || typeof pkgName !== 'string') {
+    await cliExitWithError('--pkg <module-name> is required.');
+  }
+
+  const granularityRaw = argv.granularity ?? 'object';
+  if (!isExportGranularity(granularityRaw)) {
+    await cliExitWithError(`Invalid --granularity "${granularityRaw}". Expected one of: ${EXPORT_GRANULARITIES.join(', ')}.`);
+  }
+  const granularity = granularityRaw as ExportGranularity;
+
+  const namingRaw = (argv.naming as string) ?? 'directory';
+  if (!(NAMING_STYLES as readonly string[]).includes(namingRaw)) {
+    await cliExitWithError(`Invalid --naming "${namingRaw}". Expected one of: ${NAMING_STYLES.join(', ')}.`);
+  }
+  const naming = namingRaw as NamingStyle;
+
+  const outBase = typeof argv.out === 'string' && argv.out ? path.resolve(cwd, argv.out) : path.resolve(cwd);
+  const withData = Boolean(argv['with-data'] ?? argv.withData);
+  const write = Boolean(argv.write);
+  const dryRun = Boolean(argv['dry-run'] ?? argv.dryRun);
+
+  let source;
+  try {
+    source = loadDumpSource(path.resolve(cwd, input!));
+  } catch (err) {
+    await cliExitWithError(err instanceof Error ? err.message : String(err));
+    return;
+  }
+
+  if (source.files.length > 1) {
+    log.info(`concatenated ${source.files.length} .sql files in sorted order`);
+  }
+
+  const result = await importDumpRows(source, { granularity, naming, withData });
+
+  for (const warning of result.warnings) {
+    console.warn(`import: ${warning}`);
+  }
+
+  if (dryRun) {
+    console.log(`package ${pkgName} -> ${path.join(outBase, pkgName!)}`);
+    if (result.controlRequires.length) {
+      console.log(`  requires: ${result.controlRequires.join(', ')}`);
+    }
+    for (const row of result.rows) {
+      const deps = row.deps?.length ? ` [${row.deps.join(' ')}]` : '';
+      console.log(`  ${row.deploy}${deps}`);
+    }
+  } else {
+    const targetDir = path.join(outBase, pkgName!);
+    const guard = checkOverwrite(targetDir, source.files[0], write);
+    if (guard) {
+      await cliExitWithError(guard);
+    }
+
+    const dir = writePackage(outBase, {
+      name: pkgName!,
+      requires: result.controlRequires,
+      rows: result.rows
+    });
+    log.success(`wrote ${result.rows.length} changes to ${dir}`);
+  }
+
+  const { summary } = result;
+  log.success(
+    `import: ${summary.statements} statement(s) -> ${summary.changes} change(s), ` +
+    `${summary.skippedPreamble} preamble skipped, ${summary.skippedData} data skipped, ` +
+    `${summary.misc} in misc, ${result.warnings.length} warning(s)`
+  );
+
+  prompter.close();
+  return argv;
+};
diff --git a/pgpm/cli/src/commands/transform.ts b/pgpm/cli/src/commands/transform.ts
index e72af6087..e22cf0c30 100644
--- a/pgpm/cli/src/commands/transform.ts
+++ b/pgpm/cli/src/commands/transform.ts
@@ -1,4 +1,4 @@
-import { PgpmMigrate, PgpmPackage, PgpmRow, SqlWriteOptions, writePgpmFiles, writePgpmPlan } from '@pgpmjs/core';
+import { PgpmMigrate, PgpmPackage, PgpmRow } from '@pgpmjs/core';
 import {
   diffCatalogSnapshots,
   EXPORT_GRANULARITIES,
@@ -21,6 +21,10 @@ import { getPgPool } from 'pg-cache';
 import type { PgConfig } from 'pg-env';
 import { getPgEnvOptions } from 'pg-env';
 
+import { checkOverwrite, writePackage } from '../utils/emit-package';
+
+export { checkOverwrite } from '../utils/emit-package';
+
 const log = new Logger('transform');
 
 const transformUsageText = `
@@ -78,26 +82,6 @@ export const resolveOutBase = (modulePath: string, out?: string): string => {
   return path.dirname(modulePath);
 };
 
-/**
- * Guard against clobbering: writing into the source module requires --write,
- * as does overwriting any existing package directory.
- */
-export const checkOverwrite = (
-  targetDir: string,
-  modulePath: string,
-  write: boolean
-): string | null => {
-  const resolvedTarget = path.resolve(targetDir);
-  const resolvedSource = path.resolve(modulePath);
-  if (resolvedTarget === resolvedSource && !write) {
-    return `Refusing to overwrite the source module at ${resolvedSource} (pass --write to allow).`;
-  }
-  if (resolvedTarget !== resolvedSource && fs.existsSync(resolvedTarget) && !write) {
-    return `Output directory ${resolvedTarget} already exists (pass --write to overwrite).`;
-  }
-  return null;
-};
-
 /** Order partition packages so prerequisites come before dependents. */
 export const orderPackages = (packages: PartitionedPackageRows[]): PartitionedPackageRows[] => {
   const byName = new Map(packages.map(pkg => [pkg.name, pkg]));
@@ -124,43 +108,6 @@ const readControlRequires = (modulePath: string, name: string): string[] => {
   return match[1].split(',').map(s => s.trim()).filter(Boolean);
 };
 
-const writeControlFile = (dir: string, name: string, requires: string[]): void => {
-  const lines = [
-    `# ${name} extension`,
-    `comment = '${name} extension'`,
-    `default_version = '0.0.1'`,
-    `relocatable = false`,
-    `superuser = false`
-  ];
-  if (requires.length) {
-    lines.push(`requires = '${requires.join(',')}'`);
-  }
-  fs.writeFileSync(path.join(dir, `${name}.control`), lines.join('\n') + '\n');
-};
-
-const writePackage = (
-  outBase: string,
-  pkg: PartitionedPackageRows,
-  sourceRequires: string[]
-): string => {
-  const dir = path.join(outBase, pkg.name);
-  fs.rmSync(path.join(dir, 'deploy'), { recursive: true, force: true });
-  fs.rmSync(path.join(dir, 'revert'), { recursive: true, force: true });
-  fs.rmSync(path.join(dir, 'verify'), { recursive: true, force: true });
-  fs.mkdirSync(dir, { recursive: true });
-
-  writeControlFile(dir, pkg.name, [...sourceRequires, ...pkg.requires]);
-
-  const opts: SqlWriteOptions = {
-    outdir: outBase,
-    name: pkg.name,
-    replacer: (str: string) => str.split('constructive-extension-name').join(pkg.name)
-  };
-  writePgpmPlan(pkg.rows, opts);
-  writePgpmFiles(pkg.rows, opts);
-  return dir;
-};
-
 const createScratchDb = async (config: PgConfig, dbName: string): Promise<void> => {
   const adminPool = getPgPool({ ...config, database: 'postgres' });
   await adminPool.query(`DROP DATABASE IF EXISTS "${dbName}"`);
diff --git a/pgpm/cli/src/utils/display.ts b/pgpm/cli/src/utils/display.ts
index 12db03b5d..25d974d18 100644
--- a/pgpm/cli/src/utils/display.ts
+++ b/pgpm/cli/src/utils/display.ts
@@ -13,6 +13,7 @@ export const usageText = `
     plan               Generate module deployment plans
     regen              Generate revert/verify scripts from deploy scripts
     transform          Re-dial a module through the dials pipeline (granularity/naming/partition)
+    import             pgpm-itize an arbitrary SQL dump into a deployable module
     package            Package module for distribution
     materialize        Transpile an apply proxy into a plain, committed module
     sync-versions      Sync .control/Makefile/sql metadata to package.json versions
diff --git a/pgpm/cli/src/utils/emit-package.ts b/pgpm/cli/src/utils/emit-package.ts
new file mode 100644
index 000000000..4891ffdee
--- /dev/null
+++ b/pgpm/cli/src/utils/emit-package.ts
@@ -0,0 +1,74 @@
+/**
+ * Shared module emission for the dials commands (`pgpm transform`,
+ * `pgpm import`): write a package directory with a `.control` file,
+ * `pgpm.plan`, and deploy/revert/verify trees from PgpmRows.
+ */
+import { PgpmRow, SqlWriteOptions, writePgpmFiles, writePgpmPlan } from '@pgpmjs/core';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface EmitPackage {
+  /** Package (module) name. */
+  name: string;
+  /** Module names this package requires (control-file names). */
+  requires: string[];
+  /** Changes in plan order. */
+  rows: PgpmRow[];
+}
+
+export const writeControlFile = (dir: string, name: string, requires: string[]): void => {
+  const lines = [
+    `# ${name} extension`,
+    `comment = '${name} extension'`,
+    `default_version = '0.0.1'`,
+    `relocatable = false`,
+    `superuser = false`
+  ];
+  if (requires.length) {
+    lines.push(`requires = '${requires.join(',')}'`);
+  }
+  fs.writeFileSync(path.join(dir, `${name}.control`), lines.join('\n') + '\n');
+};
+
+export const writePackage = (
+  outBase: string,
+  pkg: EmitPackage,
+  extraRequires: string[] = []
+): string => {
+  const dir = path.join(outBase, pkg.name);
+  fs.rmSync(path.join(dir, 'deploy'), { recursive: true, force: true });
+  fs.rmSync(path.join(dir, 'revert'), { recursive: true, force: true });
+  fs.rmSync(path.join(dir, 'verify'), { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+
+  writeControlFile(dir, pkg.name, [...extraRequires, ...pkg.requires]);
+
+  const opts: SqlWriteOptions = {
+    outdir: outBase,
+    name: pkg.name,
+    replacer: (str: string) => str.split('constructive-extension-name').join(pkg.name)
+  };
+  writePgpmPlan(pkg.rows, opts);
+  writePgpmFiles(pkg.rows, opts);
+  return dir;
+};
+
+/**
+ * Guard against clobbering: writing into the source directory requires
+ * `--write`, as does overwriting any existing package directory.
+ */
+export const checkOverwrite = (
+  targetDir: string,
+  sourcePath: string,
+  write: boolean
+): string | null => {
+  const resolvedTarget = path.resolve(targetDir);
+  const resolvedSource = path.resolve(sourcePath);
+  if (resolvedTarget === resolvedSource && !write) {
+    return `Refusing to overwrite the source module at ${resolvedSource} (pass --write to allow).`;
+  }
+  if (resolvedTarget !== resolvedSource && fs.existsSync(resolvedTarget) && !write) {
+    return `Output directory ${resolvedTarget} already exists (pass --write to overwrite).`;
+  }
+  return null;
+};
diff --git a/pgpm/export/src/dump-source.ts b/pgpm/export/src/dump-source.ts
new file mode 100644
index 000000000..6125fe5a7
--- /dev/null
+++ b/pgpm/export/src/dump-source.ts
@@ -0,0 +1,214 @@
+/**
+ * Dump ingestion for `pgpm import`: turn a `pg_dump` output file (or a
+ * directory of .sql files, concatenated in sorted order) into parseable SQL
+ * plus extracted data blocks. This is the file/dump front door of the "ingest
+ * anything -> classified unit set" seam (`loadModuleSource` is the module
+ * front door).
+ *
+ * Text-level preprocessing handles the two things libpg_query cannot parse:
+ * - psql backslash meta-commands (`\connect`, `\restrict`, ...) — stripped
+ *   and reported;
+ * - `COPY ... FROM stdin;` data blocks — captured as a unit including the
+ *   terminating `\.` so they can be re-emitted as seed fixtures.
+ *
+ * The scanner tracks dollar-quoted strings so function bodies containing
+ * backslash-prefixed lines are left untouched.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+/** A `COPY ... FROM stdin;` block captured verbatim from the dump. */
+export interface CopyBlock {
+  /** The COPY statement line (without the data). */
+  statement: string;
+  /** Raw data lines between the statement and the terminating `\.`. */
+  dataLines: string[];
+}
+
+/** A dump loaded and preprocessed into parseable SQL + data blocks. */
+export interface DumpSource {
+  /** Files the SQL was read from, in concatenation order. */
+  files: string[];
+  /** Parseable SQL: the dump minus meta-commands and COPY data blocks. */
+  sql: string;
+  /** COPY data blocks, in dump order. */
+  copyBlocks: CopyBlock[];
+  /** psql backslash meta-commands that were stripped, verbatim. */
+  metaCommands: string[];
+  /** Non-fatal notes. */
+  warnings: string[];
+}
+
+const COPY_FROM_STDIN = /^COPY\s.+\bFROM\s+stdin\s*;\s*$/i;
+const DOLLAR_TAG = /\$[A-Za-z_][A-Za-z_0-9]*\$|\$\$/g;
+
+/** Advance the dollar-quote state across one line; returns the open tag or null. */
+const trackDollarQuotes = (line: string, openTag: string | null): string | null => {
+  let tag = openTag;
+  DOLLAR_TAG.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = DOLLAR_TAG.exec(line)) !== null) {
+    if (tag === null) {
+      tag = match[0];
+    } else if (match[0] === tag) {
+      tag = null;
+    }
+  }
+  return tag;
+};
+
+/**
+ * Preprocess raw dump text: strip psql meta-commands, extract
+ * `COPY ... FROM stdin;` data blocks (through their terminating `\.`), and
+ * return the remaining SQL, which is parseable as a whole.
+ */
+export const preprocessDumpText = (text: string): Omit<DumpSource, 'files'> => {
+  const sqlLines: string[] = [];
+  const copyBlocks: CopyBlock[] = [];
+  const metaCommands: string[] = [];
+  const warnings: string[] = [];
+
+  let openTag: string | null = null;
+  let copy: CopyBlock | null = null;
+
+  for (const line of text.split('\n')) {
+    if (copy) {
+      if (line === '\\.') {
+        copyBlocks.push(copy);
+        copy = null;
+      } else {
+        copy.dataLines.push(line);
+      }
+      continue;
+    }
+
+    if (openTag === null) {
+      const trimmed = line.trimStart();
+      if (trimmed.startsWith('\\')) {
+        metaCommands.push(trimmed);
+        continue;
+      }
+      if (COPY_FROM_STDIN.test(trimmed)) {
+        copy = { statement: trimmed, dataLines: [] };
+        continue;
+      }
+    }
+
+    openTag = trackDollarQuotes(line, openTag);
+    sqlLines.push(line);
+  }
+
+  if (copy) {
+    warnings.push(`COPY block "${copy.statement}" is missing its terminating \\. — its data was kept but may be truncated`);
+    copyBlocks.push(copy);
+  }
+
+  return { sql: sqlLines.join('\n'), copyBlocks, metaCommands, warnings };
+};
+
+/**
+ * Load a dump from a .sql file or a directory of .sql files. Directory
+ * inputs are concatenated in sorted (lexicographic) filename order — name
+ * files accordingly (e.g. `001-schema.sql`, `002-data.sql`).
+ */
+export const loadDumpSource = (inputPath: string): DumpSource => {
+  const resolved = path.resolve(inputPath);
+  const stat = fs.statSync(resolved);
+
+  let files: string[];
+  if (stat.isDirectory()) {
+    files = fs
+      .readdirSync(resolved)
+      .filter(f => f.endsWith('.sql'))
+      .sort((a, b) => a.localeCompare(b))
+      .map(f => path.join(resolved, f));
+    if (files.length === 0) {
+      throw new Error(`No .sql files found in directory: ${resolved}`);
+    }
+  } else {
+    files = [resolved];
+  }
+
+  const text = files.map(f => fs.readFileSync(f, 'utf-8')).join('\n');
+  return { files, ...preprocessDumpText(text) };
+};
+
+const COPY_TARGET = /^COPY\s+(.+?)(?:\s*\(([^)]*)\))?\s+FROM\s+stdin\s*;\s*$/i;
+
+/** The parsed target of a COPY statement. */
+export interface CopyTarget {
+  schema: string | null;
+  name: string;
+  /** Raw column list between the parens, or null when omitted. */
+  columns: string | null;
+}
+
+/** Parse the table (and column list) a COPY block targets. */
+export const copyTargetOf = (block: CopyBlock): CopyTarget => {
+  const match = COPY_TARGET.exec(block.statement.trim());
+  if (!match) {
+    throw new Error(`Unrecognized COPY statement: ${block.statement}`);
+  }
+  const target = match[1].trim();
+  const columns = match[2]?.trim() || null;
+  const unquote = (s: string): string =>
+    s.startsWith('"') && s.endsWith('"') ? s.slice(1, -1).replace(/""/g, '"') : s;
+  const parts = target.split('.').map(unquote);
+  return parts.length > 1
+    ? { schema: parts[0], name: parts.slice(1).join('.'), columns }
+    : { schema: null, name: target, columns };
+};
+
+/** Decode one field of COPY text-format data (`\N` handled by the caller). */
+const decodeCopyField = (field: string): string => {
+  let out = '';
+  for (let i = 0; i < field.length; i++) {
+    const ch = field[i];
+    if (ch !== '\\') {
+      out += ch;
+      continue;
+    }
+    const next = field[++i];
+    switch (next) {
+      case 'b': out += '\b'; break;
+      case 'f': out += '\f'; break;
+      case 'n': out += '\n'; break;
+      case 'r': out += '\r'; break;
+      case 't': out += '\t'; break;
+      case 'v': out += '\v'; break;
+      case undefined: out += '\\'; break;
+      default: out += next;
+    }
+  }
+  return out;
+};
+
+const quoteLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+
+/**
+ * Convert a COPY block to an equivalent multi-row INSERT statement, so the
+ * data can be deployed through the pg driver (which cannot stream
+ * `COPY ... FROM stdin` inline data).
+ */
+export const copyBlockToInsert = (block: CopyBlock): string => {
+  const match = COPY_TARGET.exec(block.statement.trim());
+  if (!match) {
+    throw new Error(`Unrecognized COPY statement: ${block.statement}`);
+  }
+  const target = match[1].trim();
+  const columns = match[2]?.trim();
+
+  const rows = block.dataLines
+    .filter(line => line.length > 0)
+    .map(line => {
+      const values = line
+        .split('\t')
+        .map(field => (field === '\\N' ? 'NULL' : quoteLiteral(decodeCopyField(field))));
+      return `(${values.join(', ')})`;
+    });
+
+  if (rows.length === 0) return '';
+
+  const columnList = columns ? ` (${columns})` : '';
+  return `INSERT INTO ${target}${columnList} VALUES\n  ${rows.join(',\n  ')};`;
+};
diff --git a/pgpm/export/src/import.ts b/pgpm/export/src/import.ts
new file mode 100644
index 000000000..e7e5c522e
--- /dev/null
+++ b/pgpm/export/src/import.ts
@@ -0,0 +1,358 @@
+/**
+ * `pgpm import` driver: pgpm-itize an arbitrary SQL dump.
+ *
+ * A preprocessed dump (`DumpSource`) is classified statement-by-statement,
+ * dump noise is filtered, riders (grants/comments/ownership) are re-attached
+ * to their host objects, and the result is routed through the shared dials
+ * pipeline (`restructureExportRows`): spec-derived change paths
+ * (`identityOf` + `pathFor`, collisions via `alterationPathFor`),
+ * graph-derived `requires`, generated revert/verify.
+ *
+ * Dump-specific handling:
+ * - `SET ...` / `SELECT set_config(...)` preamble statements are skipped;
+ * - `CREATE EXTENSION` statements become `.control` requires (pgpm owns
+ *   extension creation at deploy time);
+ * - `COPY ... FROM stdin` blocks and `INSERT`s are skipped by default with a
+ *   warning; `withData` emits them as seed fixture changes (COPY data is
+ *   converted to INSERTs so it deploys through the pg driver);
+ * - statements that classify to no object and attach to no host (roles,
+ *   default privileges, ...) land in a `misc/statements` change, first in
+ *   the plan, with a warning — never dropped silently.
+ */
+import { PgpmRow } from '@pgpmjs/core';
+import { ObjectIdentity, pathFor, PathStyle } from '@pgpmjs/naming-spec';
+import { classifyStatements, loadModule, regenerateScripts, StatementFacts } from '@pgpmjs/transform';
+
+import { copyBlockToInsert, copyTargetOf, DumpSource } from './dump-source';
+import { ExportGranularity, restructureExportRows } from './restructure';
+
+export const MISC_CHANGE_PATH = 'misc/statements';
+
+export interface ImportDumpRowsOptions {
+  /** Granularity dial (default: `object`). */
+  granularity?: ExportGranularity;
+  /** Naming spec path style (default: `directory`). */
+  naming?: PathStyle;
+  /** Emit data statements (COPY blocks, INSERTs) as seed fixture changes. */
+  withData?: boolean;
+}
+
+export interface ImportDumpSummary {
+  /** Total statements seen (parsed statements + COPY data blocks). */
+  statements: number;
+  /** Changes emitted. */
+  changes: number;
+  /** Preamble statements skipped (SET / set_config / psql meta-commands). */
+  skippedPreamble: number;
+  /** Data statements skipped (only when `withData` is off). */
+  skippedData: number;
+  /** Statements placed in the misc/ change. */
+  misc: number;
+}
+
+export interface ImportDumpRowsResult {
+  /** Changes in deploy order, ready for plan/file emission. */
+  rows: PgpmRow[];
+  /** Extension names from `CREATE EXTENSION`, for the module's `.control`. */
+  controlRequires: string[];
+  warnings: string[];
+  summary: ImportDumpSummary;
+}
+
+type NameParts = string[];
+
+const stringVal = (node: any): string | null =>
+  typeof node?.String?.sval === 'string' ? node.String.sval : null;
+
+const namesOf = (nodes: any[] | undefined): NameParts =>
+  (nodes ?? []).map(stringVal).filter((s): s is string => s !== null);
+
+const hostKey = (schema: string | null, name: string): string => `${schema ?? ''}.${name}`;
+
+const keyOfParts = (parts: NameParts): string | null => {
+  if (parts.length === 0) return null;
+  if (parts.length === 1) return hostKey(null, parts[0]);
+  return hostKey(parts[0], parts[1]);
+};
+
+/** Comment object types whose name parts end with a sub-object segment. */
+const COMMENT_SUBOBJECT_TYPES = new Set([
+  'OBJECT_COLUMN',
+  'OBJECT_TRIGGER',
+  'OBJECT_POLICY',
+  'OBJECT_RULE',
+  'OBJECT_TABCONSTRAINT'
+]);
+
+/** Resolve the host object a COMMENT statement targets. */
+const commentHostOf = (stmt: Record<string, any>): string | null => {
+  const comment = stmt.CommentStmt;
+  if (!comment) return null;
+  const { objtype, object } = comment;
+  if (!object) return null;
+
+  if (object.String) return hostKey(null, object.String.sval);
+  if (object.TypeName) return keyOfParts(namesOf(object.TypeName.names));
+  if (object.ObjectWithArgs) return keyOfParts(namesOf(object.ObjectWithArgs.objname));
+  if (object.List) {
+    let parts = namesOf(object.List.items);
+    if (COMMENT_SUBOBJECT_TYPES.has(objtype)) parts = parts.slice(0, -1);
+    return keyOfParts(parts);
+  }
+  return null;
+};
+
+/** Resolve the host object a GRANT/REVOKE statement targets. */
+const grantHostOf = (stmt: Record<string, any>): string | null => {
+  const grant = stmt.GrantStmt;
+  if (!grant?.objects?.length) return null;
+  const first = grant.objects[0];
+  if (first.String) return hostKey(null, first.String.sval);
+  if (first.RangeVar) {
+    return hostKey(first.RangeVar.schemaname ?? null, first.RangeVar.relname);
+  }
+  if (first.ObjectWithArgs) return keyOfParts(namesOf(first.ObjectWithArgs.objname));
+  return null;
+};
+
+/** The host object a rider statement (no creates) attaches to, if resolvable. */
+const riderHostOf = (facts: StatementFacts): string | null => {
+  if (facts.references.length > 0) {
+    const ref = facts.references[0];
+    return hostKey(ref.schema, ref.name);
+  }
+  if (!facts.stmt) return null;
+  if (facts.nodeTag === 'CommentStmt') return commentHostOf(facts.stmt);
+  if (facts.nodeTag === 'GrantStmt') return grantHostOf(facts.stmt);
+  return null;
+};
+
+const SET_CONFIG = /^SELECT\s+(pg_catalog\.)?set_config\s*\(/i;
+
+const isPreamble = (facts: StatementFacts, text: string): boolean =>
+  facts.nodeTag === 'VariableSetStmt' ||
+  (facts.nodeTag === 'SelectStmt' && SET_CONFIG.test(text));
+
+const statementText = (sql: string, facts: StatementFacts): string => {
+  const text = sql.slice(facts.span.start, facts.span.start + facts.span.len).trim();
+  return text.endsWith(';') ? text : `${text};`;
+};
+
+interface DataUnit {
+  key: string;
+  identity: ObjectIdentity;
+  sql: string;
+}
+
+const seedVerify = (schema: string | null, name: string): string => {
+  const target = schema ? `${schema}.${name}` : name;
+  return [
+    'DO $$ BEGIN',
+    `  IF NOT EXISTS (SELECT 1 FROM ${target}) THEN`,
+    `    RAISE EXCEPTION 'no seed rows in ${target}';`,
+    '  END IF;',
+    'END $$;'
+  ].join('\n');
+};
+
+const seedRevert = (schema: string | null, name: string): string => {
+  const target = schema ? `${schema}.${name}` : name;
+  return `DELETE FROM ${target};`;
+};
+
+/**
+ * Classify a preprocessed dump and restructure it into pgpm change rows at
+ * the requested granularity. Requires nothing beyond the `DumpSource` —
+ * `loadModule()` is awaited internally.
+ */
+export const importDumpRows = async (
+  source: DumpSource,
+  options: ImportDumpRowsOptions = {}
+): Promise<ImportDumpRowsResult> => {
+  await loadModule();
+
+  const granularity = options.granularity ?? 'object';
+  const style = options.naming ?? 'directory';
+  const withData = options.withData ?? false;
+
+  const warnings: string[] = [...source.warnings];
+  const controlRequires: string[] = [];
+  const miscTexts: string[] = [];
+  const dataUnits: DataUnit[] = [];
+
+  let skippedPreamble = source.metaCommands.length;
+  let skippedData = 0;
+
+  const facts = classifyStatements(source.sql);
+
+  // Main statements (those creating/targeting an object) in dump order, with
+  // per-statement rider buckets so riders re-attach right after their host.
+  const mainTexts: string[] = [];
+  const riderBuckets: string[][] = [];
+  const lastIndexOfKey = new Map<string, number>();
+
+  interface PendingRider {
+    text: string;
+    host: string;
+    nodeTag: string;
+  }
+  const pendingRiders: PendingRider[] = [];
+
+  for (const f of facts) {
+    const text = statementText(source.sql, f);
+
+    if (isPreamble(f, text)) {
+      skippedPreamble++;
+      continue;
+    }
+
+    if (f.kind === 'extension' && f.extension?.action === 'create') {
+      if (!controlRequires.includes(f.extension.name)) {
+        controlRequires.push(f.extension.name);
+      }
+      continue;
+    }
+
+    if (f.kind === 'seed_dml') {
+      const target = f.creates[0];
+      if (!withData) {
+        skippedData++;
+        continue;
+      }
+      dataUnits.push({
+        key: hostKey(target?.schema ?? null, target?.name ?? 'unknown'),
+        identity: {
+          kind: 'seed_dml',
+          schema: target?.schema ?? null,
+          name: 'seed',
+          table: target?.name ?? 'unknown'
+        },
+        sql: text
+      });
+      continue;
+    }
+
+    if (f.creates.length > 0) {
+      const index = mainTexts.length;
+      mainTexts.push(text);
+      riderBuckets.push([]);
+      for (const created of f.creates) {
+        lastIndexOfKey.set(hostKey(created.schema, created.name), index);
+      }
+      continue;
+    }
+
+    const host = riderHostOf(f);
+    if (host !== null) {
+      pendingRiders.push({ text, host, nodeTag: f.nodeTag });
+      continue;
+    }
+
+    miscTexts.push(text);
+    warnings.push(`unclassifiable statement (${f.nodeTag}) placed in ${MISC_CHANGE_PATH}: ${text.split('\n')[0]}`);
+  }
+
+  for (const rider of pendingRiders) {
+    const index = lastIndexOfKey.get(rider.host);
+    if (index !== undefined) {
+      riderBuckets[index].push(rider.text);
+    } else {
+      miscTexts.push(rider.text);
+      warnings.push(`${rider.nodeTag} targets an object not created in this dump — placed in ${MISC_CHANGE_PATH}: ${rider.text.split('\n')[0]}`);
+    }
+  }
+
+  // COPY data blocks (extracted pre-parse) become seed data too.
+  for (const block of source.copyBlocks) {
+    if (!withData) {
+      skippedData++;
+      continue;
+    }
+    const insert = copyBlockToInsert(block);
+    if (!insert) continue;
+    const target = copyTargetOf(block);
+    dataUnits.push({
+      key: hostKey(target.schema, target.name),
+      identity: { kind: 'seed_dml', schema: target.schema, name: 'seed', table: target.name },
+      sql: insert
+    });
+  }
+
+  if (!withData && skippedData > 0) {
+    warnings.push(`${skippedData} data statement(s) skipped (pass --with-data to import them as seed fixtures)`);
+  }
+
+  // Reassemble the program with riders adjacent to their hosts, and
+  // restructure through the shared dials pipeline.
+  const program = mainTexts
+    .flatMap((text, i) => [text, ...riderBuckets[i]])
+    .join('\n\n');
+
+  const restructured = await restructureExportRows(
+    program.trim()
+      ? [{ name: 'import/dump', deploy: 'import/dump', deps: [], content: program }]
+      : [],
+    granularity,
+    { naming: style }
+  );
+  warnings.push(...restructured.warnings);
+
+  const rows: PgpmRow[] = [];
+
+  if (miscTexts.length > 0) {
+    const miscSql = miscTexts.join('\n\n');
+    const scripts = regenerateScripts(miscSql);
+    warnings.push(...scripts.revert.warnings.map(w => `${MISC_CHANGE_PATH}: ${w}`));
+    warnings.push(...scripts.verify.warnings.map(w => `${MISC_CHANGE_PATH}: ${w}`));
+    rows.push({
+      name: MISC_CHANGE_PATH,
+      deploy: MISC_CHANGE_PATH,
+      deps: [],
+      content: miscSql,
+      revert: scripts.revert.sql,
+      verify: scripts.verify.sql
+    });
+  }
+
+  rows.push(...restructured.rows);
+
+  // Seed fixture changes, one per table, after the schema changes.
+  const seedsByTable = new Map<string, DataUnit[]>();
+  for (const unit of dataUnits) {
+    const existing = seedsByTable.get(unit.key);
+    if (existing) existing.push(unit);
+    else seedsByTable.set(unit.key, [unit]);
+  }
+  const taken = new Set(rows.map(row => row.deploy));
+  for (const units of seedsByTable.values()) {
+    const { identity } = units[0];
+    let deploy = pathFor(identity, { style });
+    while (taken.has(deploy)) deploy = `${deploy}_`;
+    taken.add(deploy);
+    const tablePath = pathFor(
+      { kind: 'table', schema: identity.schema, name: identity.table! },
+      { style }
+    );
+    rows.push({
+      name: deploy,
+      deploy,
+      deps: rows.some(row => row.deploy === tablePath) ? [tablePath] : [],
+      content: units.map(unit => unit.sql).join('\n\n'),
+      revert: seedRevert(identity.schema, identity.table!),
+      verify: seedVerify(identity.schema, identity.table!)
+    });
+  }
+
+  return {
+    rows,
+    controlRequires,
+    warnings,
+    summary: {
+      statements: facts.length + source.copyBlocks.length + source.metaCommands.length,
+      changes: rows.length,
+      skippedPreamble,
+      skippedData: withData ? 0 : skippedData,
+      misc: miscTexts.length
+    }
+  };
+};
diff --git a/pgpm/export/src/index.ts b/pgpm/export/src/index.ts
index 45775ca03..d1e2a77c1 100644
--- a/pgpm/export/src/index.ts
+++ b/pgpm/export/src/index.ts
@@ -7,6 +7,10 @@ export { EXPORT_GRANULARITIES, isExportGranularity, restructureExportRows } from
 export type { ExportGranularity, RestructureExportRowsOptions, RestructureExportRowsResult } from './restructure';
 export { loadModuleSource, stripTransactionWrapper } from './module-source';
 export type { ModuleSource, ModuleSourceChange } from './module-source';
+export { copyBlockToInsert, copyTargetOf, loadDumpSource, preprocessDumpText } from './dump-source';
+export type { CopyBlock, CopyTarget, DumpSource } from './dump-source';
+export { importDumpRows, MISC_CHANGE_PATH } from './import';
+export type { ImportDumpRowsOptions, ImportDumpRowsResult, ImportDumpSummary } from './import';
 export { parsePartitionConfig, partitionExportRows } from './partition';
 export type { PartitionConfig, PartitionedPackageRows, PartitionExportRowsResult } from './partition';
 export { diffCatalogSnapshots, snapshotCatalog } from './catalog-check';

From eb9f4f5e6e833d9d286fd69c79d45a3ffb50df88 Mon Sep 17 00:00:00 2001
From: Dan Lynch <pyramation@gmail.com>
Date: Fri, 31 Jul 2026 23:10:39 +0000
Subject: [PATCH 3/6] test(pgpm): unit + e2e coverage for pgpm import; fix
 ordering of serial sequences, OWNED BY, late ALTERs, and seed FKs

---
 pgpm/cli/__tests__/fixtures/import/dump.sql | 363 ++++++++++++++++++++
 pgpm/cli/__tests__/import-e2e.test.ts       | 153 +++++++++
 pgpm/export/__tests__/dump-source.test.ts   | 127 +++++++
 pgpm/export/__tests__/import-rows.test.ts   | 163 +++++++++
 pgpm/export/src/import.ts                   | 231 ++++++++++++-
 5 files changed, 1034 insertions(+), 3 deletions(-)
 create mode 100644 pgpm/cli/__tests__/fixtures/import/dump.sql
 create mode 100644 pgpm/cli/__tests__/import-e2e.test.ts
 create mode 100644 pgpm/export/__tests__/dump-source.test.ts
 create mode 100644 pgpm/export/__tests__/import-rows.test.ts

diff --git a/pgpm/cli/__tests__/fixtures/import/dump.sql b/pgpm/cli/__tests__/fixtures/import/dump.sql
new file mode 100644
index 000000000..62054e85f
--- /dev/null
+++ b/pgpm/cli/__tests__/fixtures/import/dump.sql
@@ -0,0 +1,363 @@
+--
+-- PostgreSQL database dump
+--
+
+\restrict Rhcdwy2WGDhj9Q1hKGNyv7beFEsbwg6bGgxjVYIVY9511ICWws8BXfu2kIXtqFa
+
+-- Dumped from database version 18.4
+-- Dumped by pg_dump version 18.4
+
+SET statement_timeout = 0;
+SET lock_timeout = 0;
+SET idle_in_transaction_session_timeout = 0;
+SET transaction_timeout = 0;
+SET client_encoding = 'UTF8';
+SET standard_conforming_strings = on;
+SELECT pg_catalog.set_config('search_path', '', false);
+SET check_function_bodies = false;
+SET xmloption = content;
+SET client_min_messages = warning;
+SET row_security = off;
+
+--
+-- Name: imp_app; Type: SCHEMA; Schema: -; Owner: postgres
+--
+
+CREATE SCHEMA imp_app;
+
+
+ALTER SCHEMA imp_app OWNER TO postgres;
+
+--
+-- Name: SCHEMA imp_app; Type: COMMENT; Schema: -; Owner: postgres
+--
+
+COMMENT ON SCHEMA imp_app IS 'Application schema';
+
+
+--
+-- Name: imp_audit; Type: SCHEMA; Schema: -; Owner: postgres
+--
+
+CREATE SCHEMA imp_audit;
+
+
+ALTER SCHEMA imp_audit OWNER TO postgres;
+
+--
+-- Name: pgcrypto; Type: EXTENSION; Schema: -; Owner: -
+--
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA public;
+
+
+--
+-- Name: EXTENSION pgcrypto; Type: COMMENT; Schema: -; Owner: 
+--
+
+COMMENT ON EXTENSION pgcrypto IS 'cryptographic functions';
+
+
+--
+-- Name: touch(); Type: FUNCTION; Schema: imp_app; Owner: postgres
+--
+
+CREATE FUNCTION imp_app.touch() RETURNS trigger
+    LANGUAGE plpgsql
+    AS $$
+BEGIN
+  NEW.created_at := now();
+  RETURN NEW;
+END;
+$$;
+
+
+ALTER FUNCTION imp_app.touch() OWNER TO postgres;
+
+--
+-- Name: FUNCTION touch(); Type: COMMENT; Schema: imp_app; Owner: postgres
+--
+
+COMMENT ON FUNCTION imp_app.touch() IS 'touch trigger fn';
+
+
+--
+-- Name: order_seq; Type: SEQUENCE; Schema: imp_app; Owner: postgres
+--
+
+CREATE SEQUENCE imp_app.order_seq
+    START WITH 100
+    INCREMENT BY 1
+    NO MINVALUE
+    NO MAXVALUE
+    CACHE 1;
+
+
+ALTER SEQUENCE imp_app.order_seq OWNER TO postgres;
+
+SET default_tablespace = '';
+
+SET default_table_access_method = heap;
+
+--
+-- Name: orders; Type: TABLE; Schema: imp_app; Owner: postgres
+--
+
+CREATE TABLE imp_app.orders (
+    id integer DEFAULT nextval('imp_app.order_seq'::regclass) NOT NULL,
+    user_id integer NOT NULL,
+    note text
+);
+
+
+ALTER TABLE imp_app.orders OWNER TO postgres;
+
+--
+-- Name: users; Type: TABLE; Schema: imp_app; Owner: postgres
+--
+
+CREATE TABLE imp_app.users (
+    id integer NOT NULL,
+    email text NOT NULL,
+    created_at timestamp with time zone DEFAULT now()
+);
+
+
+ALTER TABLE imp_app.users OWNER TO postgres;
+
+--
+-- Name: TABLE users; Type: COMMENT; Schema: imp_app; Owner: postgres
+--
+
+COMMENT ON TABLE imp_app.users IS 'App users';
+
+
+--
+-- Name: COLUMN users.email; Type: COMMENT; Schema: imp_app; Owner: postgres
+--
+
+COMMENT ON COLUMN imp_app.users.email IS 'Login email';
+
+
+--
+-- Name: users_id_seq; Type: SEQUENCE; Schema: imp_app; Owner: postgres
+--
+
+CREATE SEQUENCE imp_app.users_id_seq
+    AS integer
+    START WITH 1
+    INCREMENT BY 1
+    NO MINVALUE
+    NO MAXVALUE
+    CACHE 1;
+
+
+ALTER SEQUENCE imp_app.users_id_seq OWNER TO postgres;
+
+--
+-- Name: users_id_seq; Type: SEQUENCE OWNED BY; Schema: imp_app; Owner: postgres
+--
+
+ALTER SEQUENCE imp_app.users_id_seq OWNED BY imp_app.users.id;
+
+
+--
+-- Name: events; Type: TABLE; Schema: imp_audit; Owner: postgres
+--
+
+CREATE TABLE imp_audit.events (
+    id integer NOT NULL,
+    user_id integer,
+    detail text
+);
+
+
+ALTER TABLE imp_audit.events OWNER TO postgres;
+
+--
+-- Name: events_id_seq; Type: SEQUENCE; Schema: imp_audit; Owner: postgres
+--
+
+CREATE SEQUENCE imp_audit.events_id_seq
+    AS integer
+    START WITH 1
+    INCREMENT BY 1
+    NO MINVALUE
+    NO MAXVALUE
+    CACHE 1;
+
+
+ALTER SEQUENCE imp_audit.events_id_seq OWNER TO postgres;
+
+--
+-- Name: events_id_seq; Type: SEQUENCE OWNED BY; Schema: imp_audit; Owner: postgres
+--
+
+ALTER SEQUENCE imp_audit.events_id_seq OWNED BY imp_audit.events.id;
+
+
+--
+-- Name: users id; Type: DEFAULT; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_app.users ALTER COLUMN id SET DEFAULT nextval('imp_app.users_id_seq'::regclass);
+
+
+--
+-- Name: events id; Type: DEFAULT; Schema: imp_audit; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_audit.events ALTER COLUMN id SET DEFAULT nextval('imp_audit.events_id_seq'::regclass);
+
+
+--
+-- Data for Name: orders; Type: TABLE DATA; Schema: imp_app; Owner: postgres
+--
+
+COPY imp_app.orders (id, user_id, note) FROM stdin;
+100	1	first\torder
+101	2	\N
+\.
+
+
+--
+-- Data for Name: users; Type: TABLE DATA; Schema: imp_app; Owner: postgres
+--
+
+COPY imp_app.users (id, email, created_at) FROM stdin;
+1	a@example.com	2026-07-31 22:53:49.879981+00
+2	b@example.com	2026-07-31 22:53:49.879981+00
+\.
+
+
+--
+-- Data for Name: events; Type: TABLE DATA; Schema: imp_audit; Owner: postgres
+--
+
+COPY imp_audit.events (id, user_id, detail) FROM stdin;
+\.
+
+
+--
+-- Name: order_seq; Type: SEQUENCE SET; Schema: imp_app; Owner: postgres
+--
+
+SELECT pg_catalog.setval('imp_app.order_seq', 101, true);
+
+
+--
+-- Name: users_id_seq; Type: SEQUENCE SET; Schema: imp_app; Owner: postgres
+--
+
+SELECT pg_catalog.setval('imp_app.users_id_seq', 2, true);
+
+
+--
+-- Name: events_id_seq; Type: SEQUENCE SET; Schema: imp_audit; Owner: postgres
+--
+
+SELECT pg_catalog.setval('imp_audit.events_id_seq', 1, false);
+
+
+--
+-- Name: orders orders_pkey; Type: CONSTRAINT; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_app.orders
+    ADD CONSTRAINT orders_pkey PRIMARY KEY (id);
+
+
+--
+-- Name: users users_email_key; Type: CONSTRAINT; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_app.users
+    ADD CONSTRAINT users_email_key UNIQUE (email);
+
+
+--
+-- Name: users users_pkey; Type: CONSTRAINT; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_app.users
+    ADD CONSTRAINT users_pkey PRIMARY KEY (id);
+
+
+--
+-- Name: events events_pkey; Type: CONSTRAINT; Schema: imp_audit; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_audit.events
+    ADD CONSTRAINT events_pkey PRIMARY KEY (id);
+
+
+--
+-- Name: orders_user_idx; Type: INDEX; Schema: imp_app; Owner: postgres
+--
+
+CREATE INDEX orders_user_idx ON imp_app.orders USING btree (user_id);
+
+
+--
+-- Name: users users_touch; Type: TRIGGER; Schema: imp_app; Owner: postgres
+--
+
+CREATE TRIGGER users_touch BEFORE UPDATE ON imp_app.users FOR EACH ROW EXECUTE FUNCTION imp_app.touch();
+
+
+--
+-- Name: orders orders_user_fk; Type: FK CONSTRAINT; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_app.orders
+    ADD CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES imp_app.users(id);
+
+
+--
+-- Name: events events_user_id_fkey; Type: FK CONSTRAINT; Schema: imp_audit; Owner: postgres
+--
+
+ALTER TABLE ONLY imp_audit.events
+    ADD CONSTRAINT events_user_id_fkey FOREIGN KEY (user_id) REFERENCES imp_app.users(id);
+
+
+--
+-- Name: users; Type: ROW SECURITY; Schema: imp_app; Owner: postgres
+--
+
+ALTER TABLE imp_app.users ENABLE ROW LEVEL SECURITY;
+
+--
+-- Name: users users_select; Type: POLICY; Schema: imp_app; Owner: postgres
+--
+
+CREATE POLICY users_select ON imp_app.users FOR SELECT USING (true);
+
+
+--
+-- Name: SCHEMA imp_app; Type: ACL; Schema: -; Owner: postgres
+--
+
+GRANT USAGE ON SCHEMA imp_app TO PUBLIC;
+
+
+--
+-- Name: TABLE orders; Type: ACL; Schema: imp_app; Owner: postgres
+--
+
+GRANT SELECT,INSERT ON TABLE imp_app.orders TO PUBLIC;
+
+
+--
+-- Name: TABLE users; Type: ACL; Schema: imp_app; Owner: postgres
+--
+
+GRANT SELECT ON TABLE imp_app.users TO PUBLIC;
+
+
+--
+-- PostgreSQL database dump complete
+--
+
+\unrestrict Rhcdwy2WGDhj9Q1hKGNyv7beFEsbwg6bGgxjVYIVY9511ICWws8BXfu2kIXtqFa
+
diff --git a/pgpm/cli/__tests__/import-e2e.test.ts b/pgpm/cli/__tests__/import-e2e.test.ts
new file mode 100644
index 000000000..a3452ed03
--- /dev/null
+++ b/pgpm/cli/__tests__/import-e2e.test.ts
@@ -0,0 +1,153 @@
+/**
+ * e2e for `pgpm import` against live Postgres.
+ *
+ * Fixture: a real `pg_dump` output (committed at fixtures/import/dump.sql)
+ * with its preamble (`\restrict`, SET ..., set_config), two schemas, tables
+ * with a late-FK `ALTER TABLE ONLY ... ADD CONSTRAINT`, serial sequences +
+ * OWNED BY, a standalone sequence, function, trigger, policy, grants,
+ * comments, `CREATE EXTENSION pgcrypto`, and COPY data blocks.
+ *
+ * The source schema is applied directly to a scratch DB; the dump is
+ * imported at each granularity, deployed into a fresh DB, and the catalogs
+ * are asserted equivalent. Then verify passes and revert leaves the DB
+ * clean. `--with-data` additionally proves the seed fixtures land.
+ *
+ * PREREQUISITES: a running PostgreSQL instance via standard PG* env vars.
+ */
+import { copyBlockToInsert, diffCatalogSnapshots, preprocessDumpText, snapshotCatalog } from '@pgpmjs/export';
+import * as fs from 'fs';
+import * as path from 'path';
+import { teardownPgPools } from 'pg-cache';
+
+import { CLIDeployTestFixture } from '../test-utils';
+
+jest.setTimeout(180000);
+
+afterAll(async () => {
+  await teardownPgPools();
+});
+
+const WS = 'import-ws';
+const DUMP_PATH = path.join(__dirname, 'fixtures', 'import', 'dump.sql');
+
+describe('pgpm import e2e', () => {
+  let fixture: CLIDeployTestFixture;
+  let originalDb: any;
+  let wsDir: string;
+
+  beforeAll(async () => {
+    fixture = new CLIDeployTestFixture();
+    wsDir = path.join(fixture.tempFixtureDir, WS);
+    fs.mkdirSync(wsDir, { recursive: true });
+    fs.writeFileSync(path.join(wsDir, 'pgpm.json'), '{\n    "packages": [\n        "*"\n    ]\n}');
+    fs.copyFileSync(DUMP_PATH, path.join(wsDir, 'dump.sql'));
+
+    // Apply the source schema directly so we can assert catalog equivalence.
+    originalDb = await fixture.setupTestDatabase();
+    const { sql, copyBlocks } = preprocessDumpText(fs.readFileSync(DUMP_PATH, 'utf-8'));
+    await originalDb.query(sql);
+    // COPY blocks appear in pg_dump's data order (not FK order), so load
+    // them the way pg_restore would: with FK triggers disabled.
+    const inserts = copyBlocks.map(copyBlockToInsert).filter(Boolean).join('\n');
+    if (inserts) {
+      await originalDb.query(
+        `BEGIN;\nSET LOCAL session_replication_role = replica;\n${inserts}\nCOMMIT;`
+      );
+    }
+  });
+
+  afterAll(async () => {
+    await fixture.cleanup();
+  });
+
+  it('--dry-run prints the plan without writing anything', async () => {
+    await fixture.runTerminalCommands(
+      `
+      cd ${WS}
+      pgpm import dump.sql --pkg imp-dry --dry-run
+      `,
+      {}
+    );
+    expect(fs.existsSync(path.join(wsDir, 'imp-dry'))).toBe(false);
+  });
+
+  it.each(['atomic', 'object', 'consolidated'] as const)(
+    'import --granularity %s deploys with an equivalent catalog, verifies, and reverts clean',
+    async granularity => {
+      const pkg = `imp-${granularity}`;
+      await fixture.runTerminalCommands(
+        `
+        cd ${WS}
+        pgpm import dump.sql --pkg ${pkg} --granularity ${granularity}
+        `,
+        {}
+      );
+
+      const outDir = path.join(wsDir, pkg);
+      expect(fs.existsSync(path.join(outDir, 'pgpm.plan'))).toBe(true);
+      const control = fs.readFileSync(path.join(outDir, `${pkg}.control`), 'utf-8');
+      expect(control).toMatch(/requires = '.*pgcrypto.*'/);
+
+      const testDb = await fixture.setupTestDatabase();
+      await fixture.runTerminalCommands(
+        `
+        cd ${WS}/${pkg}
+        pgpm deploy --database ${testDb.name} --package ${pkg} --yes
+        `,
+        { database: testDb.name }
+      );
+
+      const snapOriginal = await snapshotCatalog(originalDb);
+      const snapImported = await snapshotCatalog(testDb);
+      expect(diffCatalogSnapshots(snapOriginal, snapImported)).toEqual([]);
+
+      await fixture.runTerminalCommands(
+        `
+        cd ${WS}/${pkg}
+        pgpm verify --database ${testDb.name} --package ${pkg} --yes
+        pgpm revert --database ${testDb.name} --package ${pkg} --yes
+        `,
+        { database: testDb.name }
+      );
+
+      expect(await testDb.exists('schema', 'imp_app')).toBe(false);
+      expect(await testDb.exists('schema', 'imp_audit')).toBe(false);
+      const remaining = await testDb.query(
+        `SELECT COUNT(*)::int AS count FROM pgpm_migrate.changes WHERE package = $1`,
+        [pkg]
+      );
+      expect(remaining.rows[0].count).toBe(0);
+    }
+  );
+
+  it('--with-data deploys COPY/INSERT data as seed fixtures', async () => {
+    await fixture.runTerminalCommands(
+      `
+      cd ${WS}
+      pgpm import dump.sql --pkg imp-data --with-data
+      `,
+      {}
+    );
+
+    const plan = fs.readFileSync(path.join(wsDir, 'imp-data', 'pgpm.plan'), 'utf-8');
+    expect(plan).toContain('schemas/imp_app/tables/users/fixtures/seed');
+    expect(plan).toContain('schemas/imp_app/tables/orders/fixtures/seed');
+
+    const testDb = await fixture.setupTestDatabase();
+    await fixture.runTerminalCommands(
+      `
+      cd ${WS}/imp-data
+      pgpm deploy --database ${testDb.name} --package imp-data --yes
+      `,
+      { database: testDb.name }
+    );
+
+    const users = await testDb.query('SELECT COUNT(*)::int AS count FROM imp_app.users');
+    expect(users.rows[0].count).toBe(2);
+    const orders = await testDb.query('SELECT note FROM imp_app.orders ORDER BY id');
+    expect(orders.rows.map((r: any) => r.note)).toEqual(['first\torder', null]);
+    // setval rode the sequence changes: nextval continues after the seeds
+    const next = await testDb.query("SELECT nextval('imp_app.order_seq')::int AS v");
+    expect(next.rows[0].v).toBeGreaterThan(101);
+  });
+});
diff --git a/pgpm/export/__tests__/dump-source.test.ts b/pgpm/export/__tests__/dump-source.test.ts
new file mode 100644
index 000000000..cc305f339
--- /dev/null
+++ b/pgpm/export/__tests__/dump-source.test.ts
@@ -0,0 +1,127 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { copyBlockToInsert, copyTargetOf, loadDumpSource, preprocessDumpText } from '../src/dump-source';
+
+describe('preprocessDumpText', () => {
+  it('strips psql backslash meta-commands and reports them', () => {
+    const { sql, metaCommands } = preprocessDumpText(
+      [
+        '\\restrict abc123',
+        'CREATE SCHEMA app;',
+        '\\connect mydb',
+        'CREATE TABLE app.t (id int);',
+        '\\unrestrict abc123'
+      ].join('\n')
+    );
+    expect(metaCommands).toEqual(['\\restrict abc123', '\\connect mydb', '\\unrestrict abc123']);
+    expect(sql).toContain('CREATE SCHEMA app;');
+    expect(sql).toContain('CREATE TABLE app.t (id int);');
+    expect(sql).not.toContain('\\connect');
+  });
+
+  it('extracts COPY ... FROM stdin blocks as a unit including the terminating \\.', () => {
+    const { sql, copyBlocks } = preprocessDumpText(
+      [
+        'CREATE TABLE app.t (id int, name text);',
+        'COPY app.t (id, name) FROM stdin;',
+        '1\talice',
+        '2\t\\N',
+        '\\.',
+        'CREATE INDEX t_idx ON app.t (id);'
+      ].join('\n')
+    );
+    expect(copyBlocks).toHaveLength(1);
+    expect(copyBlocks[0].statement).toBe('COPY app.t (id, name) FROM stdin;');
+    expect(copyBlocks[0].dataLines).toEqual(['1\talice', '2\t\\N']);
+    expect(sql).not.toContain('FROM stdin');
+    expect(sql).toContain('CREATE INDEX t_idx');
+  });
+
+  it('leaves backslash lines inside dollar-quoted bodies untouched', () => {
+    const body = [
+      'CREATE FUNCTION app.f() RETURNS text AS $$',
+      'BEGIN',
+      "  RETURN '\\connect is not a command here';",
+      'END;',
+      '$$ LANGUAGE plpgsql;'
+    ].join('\n');
+    const { sql, metaCommands } = preprocessDumpText(body);
+    expect(metaCommands).toEqual([]);
+    expect(sql).toBe(body);
+  });
+
+  it('warns when a COPY block is missing its terminator', () => {
+    const { copyBlocks, warnings } = preprocessDumpText(
+      ['COPY app.t (id) FROM stdin;', '1'].join('\n')
+    );
+    expect(copyBlocks).toHaveLength(1);
+    expect(warnings[0]).toMatch(/missing its terminating/);
+  });
+});
+
+describe('loadDumpSource', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgpm-dump-source-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('concatenates directory .sql files in sorted order', () => {
+    fs.writeFileSync(path.join(dir, '002-tables.sql'), 'CREATE TABLE app.t (id int);');
+    fs.writeFileSync(path.join(dir, '001-schema.sql'), 'CREATE SCHEMA app;');
+    fs.writeFileSync(path.join(dir, 'notes.txt'), 'not sql');
+    const source = loadDumpSource(dir);
+    expect(source.files.map(f => path.basename(f))).toEqual(['001-schema.sql', '002-tables.sql']);
+    expect(source.sql.indexOf('CREATE SCHEMA app;')).toBeLessThan(source.sql.indexOf('CREATE TABLE app.t'));
+  });
+
+  it('throws for a directory with no .sql files', () => {
+    expect(() => loadDumpSource(dir)).toThrow(/No \.sql files/);
+  });
+
+  it('loads a single file', () => {
+    const file = path.join(dir, 'dump.sql');
+    fs.writeFileSync(file, 'CREATE SCHEMA app;');
+    const source = loadDumpSource(file);
+    expect(source.files).toEqual([file]);
+    expect(source.sql).toBe('CREATE SCHEMA app;');
+  });
+});
+
+describe('copyTargetOf / copyBlockToInsert', () => {
+  it('parses schema-qualified targets and column lists', () => {
+    const target = copyTargetOf({ statement: 'COPY app.users (id, email) FROM stdin;', dataLines: [] });
+    expect(target).toEqual({ schema: 'app', name: 'users', columns: 'id, email' });
+  });
+
+  it('handles quoted identifiers', () => {
+    const target = copyTargetOf({ statement: 'COPY "my schema"."My Table" FROM stdin;', dataLines: [] });
+    expect(target.schema).toBe('my schema');
+    expect(target.name).toBe('My Table');
+  });
+
+  it('converts data rows to a multi-row INSERT with NULLs and escapes decoded', () => {
+    const insert = copyBlockToInsert({
+      statement: 'COPY app.users (id, note) FROM stdin;',
+      dataLines: ['1\tfirst\\torder', '2\t\\N', "3\tit's"]
+    });
+    expect(insert).toBe(
+      [
+        'INSERT INTO app.users (id, note) VALUES',
+        "  ('1', 'first\torder'),",
+        "  ('2', NULL),",
+        "  ('3', 'it''s');"
+      ].join('\n')
+    );
+  });
+
+  it('returns an empty string for a COPY block with no rows', () => {
+    expect(copyBlockToInsert({ statement: 'COPY app.t (id) FROM stdin;', dataLines: [] })).toBe('');
+  });
+});
diff --git a/pgpm/export/__tests__/import-rows.test.ts b/pgpm/export/__tests__/import-rows.test.ts
new file mode 100644
index 000000000..8c7e36963
--- /dev/null
+++ b/pgpm/export/__tests__/import-rows.test.ts
@@ -0,0 +1,163 @@
+import { preprocessDumpText } from '../src/dump-source';
+import { importDumpRows, MISC_CHANGE_PATH } from '../src/import';
+
+const sourceOf = (text: string) => ({ files: ['test.sql'], ...preprocessDumpText(text) });
+
+const PREAMBLE = [
+  'SET statement_timeout = 0;',
+  'SET lock_timeout = 0;',
+  "SELECT pg_catalog.set_config('search_path', '', false);",
+  'SET default_table_access_method = heap;'
+].join('\n');
+
+describe('importDumpRows', () => {
+  it('skips pg_dump preamble noise and counts it', async () => {
+    const result = await importDumpRows(sourceOf(`${PREAMBLE}\nCREATE SCHEMA app;`));
+    expect(result.summary.skippedPreamble).toBe(4);
+    expect(result.rows.map(r => r.deploy)).toEqual(['schemas/app/schema']);
+  });
+
+  it('attaches COMMENT/GRANT/OWNER riders to their host change', async () => {
+    const result = await importDumpRows(
+      sourceOf(
+        [
+          'CREATE SCHEMA app;',
+          'CREATE TABLE app.users (id int PRIMARY KEY);',
+          'ALTER SCHEMA app OWNER TO postgres;',
+          "COMMENT ON TABLE app.users IS 'users';",
+          "COMMENT ON COLUMN app.users.id IS 'pk';",
+          'GRANT SELECT ON TABLE app.users TO PUBLIC;',
+          'GRANT USAGE ON SCHEMA app TO PUBLIC;'
+        ].join('\n')
+      )
+    );
+    const byPath = new Map(result.rows.map(r => [r.deploy, r]));
+    const schema = byPath.get('schemas/app/schema')!;
+    const table = byPath.get('schemas/app/tables/users/table')!;
+    expect(schema.content).toContain('OWNER TO postgres');
+    expect(schema.content).toContain('GRANT USAGE ON SCHEMA app');
+    expect(table.content).toContain("COMMENT ON TABLE app.users IS 'users'");
+    expect(table.content).toContain("COMMENT ON COLUMN app.users.id IS 'pk'");
+    expect(table.content).toContain('GRANT SELECT ON');
+    expect(result.rows.some(r => r.deploy === MISC_CHANGE_PATH)).toBe(false);
+  });
+
+  it('folds pg_dump late-FK ALTER TABLE ONLY ... ADD CONSTRAINT at object granularity', async () => {
+    const result = await importDumpRows(
+      sourceOf(
+        [
+          'CREATE SCHEMA app;',
+          'CREATE TABLE app.orders (id int PRIMARY KEY, user_id int NOT NULL);',
+          'CREATE TABLE app.users (id int PRIMARY KEY);',
+          'ALTER TABLE ONLY app.orders ADD CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES app.users(id);'
+        ].join('\n')
+      ),
+      { granularity: 'consolidated' }
+    );
+    const orders = result.rows.find(r => r.deploy === 'schemas/app/tables/orders/table')!;
+    expect(orders.content).toContain('orders_user_fk');
+    expect(orders.deps).toContain('schemas/app/tables/users/table');
+    // prerequisites come before dependents in plan order
+    const paths = result.rows.map(r => r.deploy);
+    expect(paths.indexOf('schemas/app/tables/users/table')).toBeLessThan(
+      paths.indexOf('schemas/app/tables/orders/table')
+    );
+  });
+
+  it('routes CREATE EXTENSION into control requires', async () => {
+    const result = await importDumpRows(
+      sourceOf('CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA public;\nCREATE SCHEMA app;')
+    );
+    expect(result.controlRequires).toEqual(['pgcrypto']);
+    expect(result.rows.map(r => r.deploy)).toEqual(['schemas/app/schema']);
+  });
+
+  it('places unclassifiable statements in misc/ with a warning, never dropping them', async () => {
+    const result = await importDumpRows(
+      sourceOf('CREATE ROLE import_test_role;\nCREATE SCHEMA app;')
+    );
+    const misc = result.rows.find(r => r.deploy === MISC_CHANGE_PATH)!;
+    expect(misc.content).toContain('CREATE ROLE import_test_role');
+    expect(result.warnings.some(w => w.includes('CreateRoleStmt'))).toBe(true);
+    expect(result.summary.misc).toBe(1);
+  });
+
+  it('skips data by default with a warning', async () => {
+    const result = await importDumpRows(
+      sourceOf(
+        [
+          'CREATE SCHEMA app;',
+          'CREATE TABLE app.users (id int);',
+          'COPY app.users (id) FROM stdin;',
+          '1',
+          '\\.',
+          'INSERT INTO app.users (id) VALUES (2);'
+        ].join('\n')
+      )
+    );
+    expect(result.summary.skippedData).toBe(2);
+    expect(result.warnings.some(w => w.includes('--with-data'))).toBe(true);
+    expect(result.rows.some(r => r.deploy.includes('fixtures'))).toBe(false);
+  });
+
+  it('emits seed fixture changes with --with-data, depending on their table', async () => {
+    const result = await importDumpRows(
+      sourceOf(
+        [
+          'CREATE SCHEMA app;',
+          'CREATE TABLE app.users (id int PRIMARY KEY);',
+          'CREATE TABLE app.orders (id int PRIMARY KEY, user_id int REFERENCES app.users(id));',
+          'COPY app.users (id) FROM stdin;',
+          '1',
+          '\\.',
+          'COPY app.orders (id, user_id) FROM stdin;',
+          '10\t1',
+          '\\.'
+        ].join('\n')
+      ),
+      { withData: true }
+    );
+    const userSeed = result.rows.find(r => r.deploy === 'schemas/app/tables/users/fixtures/seed')!;
+    const orderSeed = result.rows.find(r => r.deploy === 'schemas/app/tables/orders/fixtures/seed')!;
+    expect(userSeed.content).toContain('INSERT INTO app.users');
+    expect(userSeed.deps).toContain('schemas/app/tables/users/table');
+    expect(orderSeed.deps).toContain('schemas/app/tables/orders/table');
+    // FK: orders seed must come after users seed
+    expect(orderSeed.deps).toContain('schemas/app/tables/users/fixtures/seed');
+    expect(result.summary.skippedData).toBe(0);
+  });
+
+  it('keeps change paths unique when the same object is altered repeatedly', async () => {
+    const result = await importDumpRows(
+      sourceOf(
+        [
+          'CREATE SCHEMA app;',
+          'CREATE TABLE app.users (id int PRIMARY KEY);',
+          'ALTER TABLE app.users ADD COLUMN email text;',
+          'ALTER TABLE app.users ADD COLUMN phone text;'
+        ].join('\n')
+      ),
+      { granularity: 'atomic' }
+    );
+    const paths = result.rows.map(r => r.deploy);
+    expect(new Set(paths).size).toBe(paths.length);
+    const table = result.rows.find(r => r.deploy === 'schemas/app/tables/users/table')!;
+    expect(table.content).toContain('email');
+    expect(table.content).toContain('phone');
+  });
+
+  it('supports flat naming (kind tokens dropped from paths)', async () => {
+    const result = await importDumpRows(
+      sourceOf(
+        [
+          'CREATE SCHEMA app;',
+          'CREATE FUNCTION app.touch() RETURNS int AS $$ SELECT 1 $$ LANGUAGE sql;'
+        ].join('\n')
+      ),
+      { naming: 'flat' }
+    );
+    const paths = result.rows.map(r => r.deploy);
+    expect(paths).toContain('schemas/app/procedures/touch');
+    expect(paths).not.toContain('schemas/app/procedures/touch/procedure');
+  });
+});
diff --git a/pgpm/export/src/import.ts b/pgpm/export/src/import.ts
index e7e5c522e..12204c878 100644
--- a/pgpm/export/src/import.ts
+++ b/pgpm/export/src/import.ts
@@ -102,6 +102,18 @@ const commentHostOf = (stmt: Record<string, any>): string | null => {
   return null;
 };
 
+/** Resolve the host object an ALTER ... OWNER TO statement targets. */
+const ownerHostOf = (stmt: Record<string, any>): string | null => {
+  const alter = stmt.AlterOwnerStmt;
+  if (!alter?.object) return null;
+  const { object } = alter;
+  if (object.String) return hostKey(null, object.String.sval);
+  if (object.TypeName) return keyOfParts(namesOf(object.TypeName.names));
+  if (object.ObjectWithArgs) return keyOfParts(namesOf(object.ObjectWithArgs.objname));
+  if (object.List) return keyOfParts(namesOf(object.List.items));
+  return null;
+};
+
 /** Resolve the host object a GRANT/REVOKE statement targets. */
 const grantHostOf = (stmt: Record<string, any>): string | null => {
   const grant = stmt.GrantStmt;
@@ -115,6 +127,21 @@ const grantHostOf = (stmt: Record<string, any>): string | null => {
   return null;
 };
 
+/**
+ * `ALTER SEQUENCE ... OWNED BY table.column` must ride the *table* change:
+ * the serial table's default already depends on the sequence, so attaching
+ * OWNED BY to the sequence change would create a cycle.
+ */
+const sequenceOwnedByHostOf = (stmt: Record<string, any>): string | null => {
+  const options: any[] = stmt.AlterSeqStmt?.options ?? [];
+  for (const opt of options) {
+    if (opt?.DefElem?.defname !== 'owned_by') continue;
+    const parts = namesOf(opt.DefElem.arg?.List?.items);
+    if (parts.length >= 2) return keyOfParts(parts.slice(0, -1));
+  }
+  return null;
+};
+
 /** The host object a rider statement (no creates) attaches to, if resolvable. */
 const riderHostOf = (facts: StatementFacts): string | null => {
   if (facts.references.length > 0) {
@@ -124,10 +151,52 @@ const riderHostOf = (facts: StatementFacts): string | null => {
   if (!facts.stmt) return null;
   if (facts.nodeTag === 'CommentStmt') return commentHostOf(facts.stmt);
   if (facts.nodeTag === 'GrantStmt') return grantHostOf(facts.stmt);
+  if (facts.nodeTag === 'AlterOwnerStmt') return ownerHostOf(facts.stmt);
   return null;
 };
 
+/**
+ * Order a change's statements creates-first (stable): granularity folding
+ * can re-emit a folded CREATE after riders (grants, owners, comments) that
+ * were originally adjacent to the unfolded one.
+ */
+const reorderChangeStatements = (content: string): string => {
+  const facts = classifyStatements(content);
+  if (facts.length < 2) return content;
+  const isCreate = (f: StatementFacts): boolean =>
+    !f.nodeTag.startsWith('Alter') && f.nodeTag !== 'GrantStmt' && f.nodeTag !== 'CommentStmt';
+  const creates = facts.filter(isCreate);
+  const riders = facts.filter(f => !isCreate(f));
+  const ordered = [...creates, ...riders];
+  if (ordered.every((f, i) => f === facts[i])) return content;
+  return ordered.map(f => statementText(content, f)).join('\n\n') + '\n';
+};
+
+/**
+ * Order a revert's statements drops-last (stable), mirroring the deploy
+ * reorder: REVOKEs and other inverses must run before the host object is
+ * dropped. Non-statement note lines (e.g. "-- revert not derivable") are
+ * preserved at the end.
+ */
+const reorderRevertStatements = (content: string): string => {
+  const facts = classifyStatements(content);
+  if (facts.length < 2) return content;
+  const isDrop = (f: StatementFacts): boolean => f.nodeTag.startsWith('Drop');
+  const ordered = [...facts.filter(f => !isDrop(f)), ...facts.filter(isDrop)];
+  if (ordered.every((f, i) => f === facts[i])) return content;
+  let leftover = content;
+  for (const f of facts) {
+    leftover = leftover.replace(content.slice(f.span.start, f.span.start + f.span.len), '');
+  }
+  const notes = leftover
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line.startsWith('--'));
+  return [...ordered.map(f => statementText(content, f)), ...notes].join('\n\n') + '\n';
+};
+
 const SET_CONFIG = /^SELECT\s+(pg_catalog\.)?set_config\s*\(/i;
+const SETVAL = /^SELECT\s+(pg_catalog\.)?setval\s*\(\s*'([^']+)'/i;
 
 const isPreamble = (facts: StatementFacts, text: string): boolean =>
   facts.nodeTag === 'VariableSetStmt' ||
@@ -160,6 +229,31 @@ const seedRevert = (schema: string | null, name: string): string => {
   return `DELETE FROM ${target};`;
 };
 
+/**
+ * Stable topological sort by intra-module deps: pg_dump orders objects
+ * alphabetically (orders before users), but pgpm deploys in plan order, so
+ * prerequisites must be written first.
+ */
+const sortRowsByDeps = (rows: PgpmRow[]): PgpmRow[] => {
+  const byName = new Map(rows.map(row => [row.deploy, row]));
+  const sorted: PgpmRow[] = [];
+  const state = new Map<string, 'visiting' | 'done'>();
+  const visit = (row: PgpmRow): void => {
+    const mark = state.get(row.deploy);
+    if (mark === 'done') return;
+    if (mark === 'visiting') return; // cycle: keep input order
+    state.set(row.deploy, 'visiting');
+    for (const dep of row.deps ?? []) {
+      const depRow = byName.get(dep);
+      if (depRow) visit(depRow);
+    }
+    state.set(row.deploy, 'done');
+    sorted.push(row);
+  };
+  for (const row of rows) visit(row);
+  return sorted;
+};
+
 /**
  * Classify a preprocessed dump and restructure it into pgpm change rows at
  * the requested granularity. Requires nothing beyond the `DumpSource` —
@@ -197,6 +291,7 @@ export const importDumpRows = async (
     nodeTag: string;
   }
   const pendingRiders: PendingRider[] = [];
+  const ownedSequences: { schema: string | null; name: string; tableKey: string; text: string }[] = [];
 
   for (const f of facts) {
     const text = statementText(source.sql, f);
@@ -213,6 +308,21 @@ export const importDumpRows = async (
       continue;
     }
 
+    const setval = f.nodeTag === 'SelectStmt' ? SETVAL.exec(text) : null;
+    if (setval) {
+      if (!withData) {
+        skippedData++;
+        continue;
+      }
+      // setval is sequence state (data): ride the sequence's change.
+      const parts = setval[2].split('.');
+      const host = parts.length > 1
+        ? hostKey(parts[0], parts.slice(1).join('.'))
+        : hostKey(null, parts[0]);
+      pendingRiders.push({ text, host, nodeTag: 'SelectStmt (setval)' });
+      continue;
+    }
+
     if (f.kind === 'seed_dml') {
       const target = f.creates[0];
       if (!withData) {
@@ -232,7 +342,35 @@ export const importDumpRows = async (
       continue;
     }
 
+    // `ALTER SEQUENCE ... OWNED BY table.column` is held out of the
+    // restructure (grouping would fold it into the sequence change, whose
+    // serial table depends on the sequence — a cycle) and appended to the
+    // table's change afterwards.
+    if (f.nodeTag === 'AlterSeqStmt' && f.stmt) {
+      const ownedBy = sequenceOwnedByHostOf(f.stmt);
+      if (ownedBy !== null) {
+        const seq = f.stmt.AlterSeqStmt?.sequence;
+        ownedSequences.push({
+          schema: seq?.schemaname ?? null,
+          name: seq?.relname ?? '',
+          tableKey: ownedBy,
+          text
+        });
+        continue;
+      }
+    }
+
     if (f.creates.length > 0) {
+      // pg_dump emits ALTERs (late FKs, owners, defaults) far from their
+      // CREATE; repositioning them right after it keeps each group's
+      // statements in a deployable order at every granularity.
+      const hostIndex = f.nodeTag.startsWith('Alter')
+        ? lastIndexOfKey.get(hostKey(f.creates[0].schema, f.creates[0].name))
+        : undefined;
+      if (hostIndex !== undefined) {
+        riderBuckets[hostIndex].push(text);
+        continue;
+      }
       const index = mainTexts.length;
       mainTexts.push(text);
       riderBuckets.push([]);
@@ -314,7 +452,13 @@ export const importDumpRows = async (
     });
   }
 
-  rows.push(...restructured.rows);
+  rows.push(
+    ...restructured.rows.map(row => ({
+      ...row,
+      content: reorderChangeStatements(row.content),
+      revert: reorderRevertStatements(row.revert)
+    }))
+  );
 
   // Seed fixture changes, one per table, after the schema changes.
   const seedsByTable = new Map<string, DataUnit[]>();
@@ -324,6 +468,7 @@ export const importDumpRows = async (
     else seedsByTable.set(unit.key, [unit]);
   }
   const taken = new Set(rows.map(row => row.deploy));
+  const seedPathByTablePath = new Map<string, string>();
   for (const units of seedsByTable.values()) {
     const { identity } = units[0];
     let deploy = pathFor(identity, { style });
@@ -333,6 +478,7 @@ export const importDumpRows = async (
       { kind: 'table', schema: identity.schema, name: identity.table! },
       { style }
     );
+    seedPathByTablePath.set(tablePath, deploy);
     rows.push({
       name: deploy,
       deploy,
@@ -343,13 +489,92 @@ export const importDumpRows = async (
     });
   }
 
+  // Seeds must respect FKs: if table B depends on table A and both have
+  // seeds, seed(B) also depends on seed(A).
+  for (const [tablePath, seedPath] of seedPathByTablePath) {
+    const tableRow = rows.find(row => row.deploy === tablePath);
+    const seedRow = rows.find(row => row.deploy === seedPath)!;
+    for (const dep of tableRow?.deps ?? []) {
+      const depSeed = seedPathByTablePath.get(dep);
+      if (depSeed && !seedRow.deps!.includes(depSeed)) {
+        seedRow.deps!.push(depSeed);
+      }
+    }
+  }
+
+  // Re-attach OWNED BY to the owning table's change; the sequence's own
+  // revert must then tolerate the sequence being dropped with the table.
+  for (const seq of ownedSequences) {
+    if (!seq.name) continue;
+    const [tableSchema, ...tableRest] = seq.tableKey.split('.');
+    const tablePath = pathFor(
+      { kind: 'table', schema: tableSchema || null, name: tableRest.join('.') },
+      { style }
+    );
+    const tableRow = rows.find(r => r.deploy === tablePath);
+    const seqPath = pathFor({ kind: 'sequence', schema: seq.schema, name: seq.name }, { style });
+    const seqRow = rows.find(r => r.deploy === seqPath);
+    if (tableRow) {
+      tableRow.content = `${tableRow.content.trimEnd()}\n\n${seq.text}`;
+      if (seqRow) {
+        tableRow.deps = tableRow.deps ?? [];
+        if (!tableRow.deps.includes(seqPath)) tableRow.deps.push(seqPath);
+      }
+    } else {
+      const miscRow = rows.find(r => r.deploy === MISC_CHANGE_PATH);
+      if (miscRow) {
+        miscRow.content = `${miscRow.content.trimEnd()}\n\n${seq.text}`;
+      } else {
+        rows.push({
+          name: MISC_CHANGE_PATH,
+          deploy: MISC_CHANGE_PATH,
+          deps: [],
+          content: seq.text,
+          revert: '',
+          verify: ''
+        });
+      }
+      warnings.push(`AlterSeqStmt OWNED BY targets a table not created in this dump — placed in ${MISC_CHANGE_PATH}: ${seq.text.split('\n')[0]}`);
+    }
+    if (seqRow && tableRow) {
+      const target = seq.schema ? `${seq.schema}.${seq.name}` : seq.name;
+      seqRow.revert = `DROP SEQUENCE IF EXISTS ${target};`;
+    }
+  }
+
+  // pg_dump wires serial columns via `SET DEFAULT nextval('...')` — a plain
+  // string the statement graph cannot see, so add the sequence dep here.
+  const NEXTVAL = /nextval\((?:CAST\()?'([^']+)'/g;
+  const rowsByPath = new Map(rows.map(row => [row.deploy, row]));
+  for (const row of rows) {
+    NEXTVAL.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = NEXTVAL.exec(row.content)) !== null) {
+      const parts = match[1].replace(/::regclass$/, '').split('.');
+      const seqPath = pathFor(
+        {
+          kind: 'sequence',
+          schema: parts.length > 1 ? parts[0] : null,
+          name: parts.length > 1 ? parts.slice(1).join('.') : parts[0]
+        },
+        { style }
+      );
+      if (seqPath !== row.deploy && rowsByPath.has(seqPath)) {
+        row.deps = row.deps ?? [];
+        if (!row.deps.includes(seqPath)) row.deps.push(seqPath);
+      }
+    }
+  }
+
+  const orderedRows = sortRowsByDeps(rows);
+
   return {
-    rows,
+    rows: orderedRows,
     controlRequires,
     warnings,
     summary: {
       statements: facts.length + source.copyBlocks.length + source.metaCommands.length,
-      changes: rows.length,
+      changes: orderedRows.length,
       skippedPreamble,
       skippedData: withData ? 0 : skippedData,
       misc: miscTexts.length

From 1c8ce141b17a52743f105619fbb85fb896063ce2 Mon Sep 17 00:00:00 2001
From: Dan Lynch <pyramation@gmail.com>
Date: Fri, 31 Jul 2026 23:54:13 +0000
Subject: [PATCH 4/6] fix(pgpm): link textual rider/serial deps after
 partitioning so partitioned imports deploy in order

---
 pgpm/cli/src/commands/import.ts |  3 +-
 pgpm/export/src/import.ts       | 64 +++++++++++++++++++++++++++++++++
 pgpm/export/src/index.ts        |  2 +-
 3 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/pgpm/cli/src/commands/import.ts b/pgpm/cli/src/commands/import.ts
index a0b9f1bb0..6d562eec1 100644
--- a/pgpm/cli/src/commands/import.ts
+++ b/pgpm/cli/src/commands/import.ts
@@ -3,6 +3,7 @@ import {
   ExportGranularity,
   importDumpRows,
   isExportGranularity,
+  linkTextualDeps,
   loadDumpSource,
   parsePartitionConfig,
   PartitionConfig,
@@ -138,7 +139,7 @@ export default async (
       packages = partitioned.packages.map(pkg => ({
         name: pkg.name,
         requires: [...result.controlRequires, ...pkg.requires],
-        rows: pkg.rows
+        rows: linkTextualDeps(pkg.rows)
       }));
     } catch (err) {
       if (err instanceof PartitionCycleError) {
diff --git a/pgpm/export/src/import.ts b/pgpm/export/src/import.ts
index 12204c878..b46f48c13 100644
--- a/pgpm/export/src/import.ts
+++ b/pgpm/export/src/import.ts
@@ -254,6 +254,70 @@ const sortRowsByDeps = (rows: PgpmRow[]): PgpmRow[] => {
   return sorted;
 };
 
+const CREATED_RELATION = /CREATE\s+(?:TABLE|SEQUENCE)\s+(?:IF\s+NOT\s+EXISTS\s+)?([\w."]+)/gi;
+const RELATION_REFS = [
+  /OWNED\s+BY\s+([\w."]+)\.[\w"]+\s*;/gi,
+  /nextval\((?:CAST\()?'([^']+)'/g,
+  /ALTER\s+TABLE\s+(?:ONLY\s+)?(?:IF\s+EXISTS\s+)?([\w."]+)/gi,
+  /COMMENT\s+ON\s+TABLE\s+([\w."]+)/gi,
+  /GRANT\s+[^;]*?\s+ON\s+(?:TABLE\s+)?([\w."]+)\s+TO\s/gi
+];
+
+const normalizeQualname = (raw: string): string =>
+  raw.replace(/"/g, '').replace(/::regclass$/, '');
+
+/**
+ * Re-link intra-package deps that only exist in statement *text* — riders
+ * (`ALTER TABLE`, `GRANT`, `COMMENT ON`, `OWNED BY`) and serial
+ * `nextval('seq')` defaults referencing a relation created by another row —
+ * after a pass (like partitioning) that regrouped statements and rebuilt
+ * dependencies from the statement graph alone. Deps that would create a
+ * cycle are dropped so the emitted plan stays deployable. Mutates `deps`
+ * and returns the rows re-sorted so prerequisites deploy first.
+ */
+export const linkTextualDeps = (rows: PgpmRow[]): PgpmRow[] => {
+  const byQualname = new Map<string, PgpmRow>();
+  for (const row of rows) {
+    CREATED_RELATION.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = CREATED_RELATION.exec(row.content)) !== null) {
+      byQualname.set(normalizeQualname(match[1]), row);
+    }
+  }
+  for (const row of rows) {
+    for (const pattern of RELATION_REFS) {
+      pattern.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(row.content)) !== null) {
+        const targetRow = byQualname.get(normalizeQualname(match[1]));
+        if (!targetRow || targetRow === row) continue;
+        row.deps = row.deps ?? [];
+        if (!row.deps.includes(targetRow.deploy)) row.deps.push(targetRow.deploy);
+      }
+    }
+  }
+
+  // Drop back-edges: a dep pointing at a row that transitively depends on
+  // this one would make the plan unsatisfiable.
+  const byName = new Map(rows.map(row => [row.deploy, row]));
+  const state = new Map<string, 'visiting' | 'done'>();
+  const prune = (row: PgpmRow): void => {
+    if (state.get(row.deploy)) return;
+    state.set(row.deploy, 'visiting');
+    row.deps = (row.deps ?? []).filter(dep => {
+      const depRow = byName.get(dep);
+      if (!depRow) return true;
+      if (state.get(depRow.deploy) === 'visiting') return false;
+      prune(depRow);
+      return true;
+    });
+    state.set(row.deploy, 'done');
+  };
+  for (const row of rows) prune(row);
+
+  return sortRowsByDeps(rows);
+};
+
 /**
  * Classify a preprocessed dump and restructure it into pgpm change rows at
  * the requested granularity. Requires nothing beyond the `DumpSource` —
diff --git a/pgpm/export/src/index.ts b/pgpm/export/src/index.ts
index d1e2a77c1..81aa60149 100644
--- a/pgpm/export/src/index.ts
+++ b/pgpm/export/src/index.ts
@@ -9,7 +9,7 @@ export { loadModuleSource, stripTransactionWrapper } from './module-source';
 export type { ModuleSource, ModuleSourceChange } from './module-source';
 export { copyBlockToInsert, copyTargetOf, loadDumpSource, preprocessDumpText } from './dump-source';
 export type { CopyBlock, CopyTarget, DumpSource } from './dump-source';
-export { importDumpRows, MISC_CHANGE_PATH } from './import';
+export { importDumpRows, linkTextualDeps, MISC_CHANGE_PATH } from './import';
 export type { ImportDumpRowsOptions, ImportDumpRowsResult, ImportDumpSummary } from './import';
 export { parsePartitionConfig, partitionExportRows } from './partition';
 export type { PartitionConfig, PartitionedPackageRows, PartitionExportRowsResult } from './partition';

From ba317179d4e453ade968745de752b23f52dc6383 Mon Sep 17 00:00:00 2001
From: Dan Lynch <pyramation@gmail.com>
Date: Fri, 31 Jul 2026 23:55:20 +0000
Subject: [PATCH 5/6] style: apply eslint --fix to import sources

---
 pgpm/cli/src/commands/import.ts |  2 +-
 pgpm/export/src/dump-source.ts  | 16 ++++++++--------
 pgpm/export/src/index.ts        |  4 ++--
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/pgpm/cli/src/commands/import.ts b/pgpm/cli/src/commands/import.ts
index 6d562eec1..bdc6c4c6b 100644
--- a/pgpm/cli/src/commands/import.ts
+++ b/pgpm/cli/src/commands/import.ts
@@ -11,7 +11,7 @@ import {
 } from '@pgpmjs/export';
 import { Logger } from '@pgpmjs/logger';
 import { PartitionCycleError } from '@pgpmjs/transform';
-import { CLIOptions, cliExitWithError, Inquirerer, ParsedArgs } from 'inquirerer';
+import { cliExitWithError, CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
 import * as path from 'path';
 
 import { checkOverwrite, writePackage } from '../utils/emit-package';
diff --git a/pgpm/export/src/dump-source.ts b/pgpm/export/src/dump-source.ts
index 6125fe5a7..60d7adb6b 100644
--- a/pgpm/export/src/dump-source.ts
+++ b/pgpm/export/src/dump-source.ts
@@ -170,14 +170,14 @@ const decodeCopyField = (field: string): string => {
     }
     const next = field[++i];
     switch (next) {
-      case 'b': out += '\b'; break;
-      case 'f': out += '\f'; break;
-      case 'n': out += '\n'; break;
-      case 'r': out += '\r'; break;
-      case 't': out += '\t'; break;
-      case 'v': out += '\v'; break;
-      case undefined: out += '\\'; break;
-      default: out += next;
+    case 'b': out += '\b'; break;
+    case 'f': out += '\f'; break;
+    case 'n': out += '\n'; break;
+    case 'r': out += '\r'; break;
+    case 't': out += '\t'; break;
+    case 'v': out += '\v'; break;
+    case undefined: out += '\\'; break;
+    default: out += next;
     }
   }
   return out;
diff --git a/pgpm/export/src/index.ts b/pgpm/export/src/index.ts
index f40130e86..60cc47fb6 100644
--- a/pgpm/export/src/index.ts
+++ b/pgpm/export/src/index.ts
@@ -1,5 +1,7 @@
 export type { CatalogQueryable, CatalogSnapshot } from './catalog-check';
 export { diffCatalogSnapshots, snapshotCatalog } from './catalog-check';
+export type { CopyBlock, CopyTarget, DumpSource } from './dump-source';
+export { copyBlockToInsert, copyTargetOf, loadDumpSource, preprocessDumpText } from './dump-source';
 export * from './export-data';
 export * from './export-graphql';
 export * from './export-graphql-meta';
@@ -28,8 +30,6 @@ export {
   normalizeOutdir,
   preparePackage,
   SERVICE_REQUIRED_EXTENSIONS} from './export-utils';
-export type { CopyBlock, CopyTarget, DumpSource } from './dump-source';
-export { copyBlockToInsert, copyTargetOf, loadDumpSource, preprocessDumpText } from './dump-source';
 export { GraphQLClient } from './graphql-client';
 export { buildFieldsFragment, getGraphQLQueryName, getGraphQLTypeName, graphqlRowToPostgresRow, GraphQLTypeInfo,mapGraphQLTypeToFieldType, unwrapGraphQLType } from './graphql-naming';
 export type { ImportDumpRowsOptions, ImportDumpRowsResult, ImportDumpSummary } from './import';

From 0d288769d2853e06b05779578e771925788af8ba Mon Sep 17 00:00:00 2001
From: Dan Lynch <pyramation@gmail.com>
Date: Sat, 1 Aug 2026 00:07:59 +0000
Subject: [PATCH 6/6] feat(pgpm): loud compatibility warnings for COPY data
 blocks and non-preamble psql meta-commands in pgpm import

---
 pgpm/cli/src/commands/import.ts           |  5 ++++
 pgpm/export/__tests__/dump-source.test.ts | 33 ++++++++++++++++++++++-
 pgpm/export/src/dump-source.ts            | 33 +++++++++++++++++++++++
 pgpm/export/src/index.ts                  |  2 +-
 4 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/pgpm/cli/src/commands/import.ts b/pgpm/cli/src/commands/import.ts
index bdc6c4c6b..217d493af 100644
--- a/pgpm/cli/src/commands/import.ts
+++ b/pgpm/cli/src/commands/import.ts
@@ -1,4 +1,5 @@
 import {
+  dumpCompatibilityWarnings,
   EXPORT_GRANULARITIES,
   ExportGranularity,
   importDumpRows,
@@ -129,6 +130,10 @@ export default async (
     log.info(`concatenated ${source.files.length} .sql files in sorted order`);
   }
 
+  for (const warning of dumpCompatibilityWarnings(source)) {
+    console.warn(`\nWARNING: ${warning}\n`);
+  }
+
   const result = await importDumpRows(source, { granularity, naming, withData });
 
   let packages: { name: string; requires: string[]; rows: typeof result.rows }[];
diff --git a/pgpm/export/__tests__/dump-source.test.ts b/pgpm/export/__tests__/dump-source.test.ts
index cc305f339..87654b435 100644
--- a/pgpm/export/__tests__/dump-source.test.ts
+++ b/pgpm/export/__tests__/dump-source.test.ts
@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 
-import { copyBlockToInsert, copyTargetOf, loadDumpSource, preprocessDumpText } from '../src/dump-source';
+import { copyBlockToInsert, copyTargetOf, dumpCompatibilityWarnings, loadDumpSource, preprocessDumpText } from '../src/dump-source';
 
 describe('preprocessDumpText', () => {
   it('strips psql backslash meta-commands and reports them', () => {
@@ -125,3 +125,34 @@ describe('copyTargetOf / copyBlockToInsert', () => {
     expect(copyBlockToInsert({ statement: 'COPY app.t (id) FROM stdin;', dataLines: [] })).toBe('');
   });
 });
+
+describe('dumpCompatibilityWarnings', () => {
+  it('warns loudly about COPY data blocks and recommends re-dump flags', () => {
+    const warnings = dumpCompatibilityWarnings({
+      copyBlocks: [{ statement: 'COPY app.t (id) FROM stdin;', dataLines: ['1'] }],
+      metaCommands: []
+    });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('NOT SQL');
+    expect(warnings[0]).toContain('pg_dump --schema-only');
+    expect(warnings[0]).toContain('pg_dump --inserts');
+  });
+
+  it('warns about non-preamble psql meta-commands', () => {
+    const warnings = dumpCompatibilityWarnings({
+      copyBlocks: [],
+      metaCommands: ['\\i other.sql']
+    });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('\\i');
+  });
+
+  it('is silent for a clean schema-only dump with only expected preamble', () => {
+    expect(
+      dumpCompatibilityWarnings({
+        copyBlocks: [],
+        metaCommands: ['\\restrict abc', '\\unrestrict abc', '\\connect db']
+      })
+    ).toEqual([]);
+  });
+});
diff --git a/pgpm/export/src/dump-source.ts b/pgpm/export/src/dump-source.ts
index 60d7adb6b..15c30aff1 100644
--- a/pgpm/export/src/dump-source.ts
+++ b/pgpm/export/src/dump-source.ts
@@ -133,6 +133,39 @@ export const loadDumpSource = (inputPath: string): DumpSource => {
   return { files, ...preprocessDumpText(text) };
 };
 
+/** psql meta-commands pg_dump always emits as preamble — expected noise. */
+const EXPECTED_META = /^\\(restrict|unrestrict|connect)\b/;
+
+/**
+ * Loud compatibility warnings for dump constructs we handle only best-effort
+ * because they are not SQL and cannot go through the real parser: COPY stdin
+ * data blocks and non-preamble psql meta-commands. The reliable path is to
+ * hand `pgpm import` pure parseable SQL.
+ */
+export const dumpCompatibilityWarnings = (
+  source: Pick<DumpSource, 'copyBlocks' | 'metaCommands'>
+): string[] => {
+  const warnings: string[] = [];
+  if (source.copyBlocks.length > 0) {
+    warnings.push(
+      `dump contains ${source.copyBlocks.length} COPY ... FROM stdin data block(s). ` +
+      `COPY data is NOT SQL and is handled by a best-effort text scanner — data could be missed or truncated. ` +
+      `For a guaranteed import, re-dump with:\n` +
+      `    pg_dump --schema-only            (schema only; recommended)\n` +
+      `    pg_dump --inserts                (data as parseable INSERT statements, for --with-data)`
+    );
+  }
+  const unexpected = source.metaCommands.filter(cmd => !EXPECTED_META.test(cmd));
+  if (unexpected.length > 0) {
+    warnings.push(
+      `dump contains ${unexpected.length} psql meta-command(s) beyond the standard pg_dump preamble ` +
+      `(e.g. ${unexpected[0].split(/\s/)[0]}). These are client-side psql commands, not SQL — they are stripped ` +
+      `and will NOT be part of the module. Feed pgpm import plain SQL (e.g. pg_dump output), not psql scripts.`
+    );
+  }
+  return warnings;
+};
+
 const COPY_TARGET = /^COPY\s+(.+?)(?:\s*\(([^)]*)\))?\s+FROM\s+stdin\s*;\s*$/i;
 
 /** The parsed target of a COPY statement. */
diff --git a/pgpm/export/src/index.ts b/pgpm/export/src/index.ts
index 60cc47fb6..032f94cc8 100644
--- a/pgpm/export/src/index.ts
+++ b/pgpm/export/src/index.ts
@@ -1,7 +1,7 @@
 export type { CatalogQueryable, CatalogSnapshot } from './catalog-check';
 export { diffCatalogSnapshots, snapshotCatalog } from './catalog-check';
 export type { CopyBlock, CopyTarget, DumpSource } from './dump-source';
-export { copyBlockToInsert, copyTargetOf, loadDumpSource, preprocessDumpText } from './dump-source';
+export { copyBlockToInsert, copyTargetOf, dumpCompatibilityWarnings, loadDumpSource, preprocessDumpText } from './dump-source';
 export * from './export-data';
 export * from './export-graphql';
 export * from './export-graphql-meta';