feat(pgpm): loud compatibility warnings for COPY data blocks and non-preamble psql meta-commands in pgpm import

Author: pyramation

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 }[];

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([]);
+  });
+});

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. */

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';