sqlstack 2.0.0 → 3.1.0

package/dist/cjs/testing/builder.js

@@ -0,0 +1,131 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testPostgres = testPostgres;
+const fs = __importStar(require("fs"));
+const parser_1 = require("./schema/parser");
+const ddl_1 = require("./schema/ddl");
+const allocator_1 = require("./postgres/allocator");
+const database_1 = require("./postgres/database");
+const allocator_2 = require("./postgres/allocator");
+const server_1 = require("./postgres/server");
+const loadData_1 = require("./postgres/loadData");
+function readRawSql(schema) {
+    return schema.sql.map((entry) => {
+        if (entry.kind === 'inline') {
+            return { label: `sql entry #${entry.index} (inline)`, sql: entry.sql };
+        }
+        try {
+            return {
+                label: `sql entry #${entry.index} (${entry.sourcePath})`,
+                sql: fs.readFileSync(entry.resolvedPath, 'utf8'),
+            };
+        }
+        catch (err) {
+            throw new server_1.TestPostgresServerError(`Cannot read raw SQL file for sql entry #${entry.index}: ${entry.resolvedPath} ` +
+                `(authored as "${entry.sourcePath}" in ${schema.source}): ${err.message}`);
+        }
+    });
+}
+function makeBuilder(state) {
+    return {
+        schema: state.schema,
+        ops: state.ops,
+        data(rows) {
+            const newOps = (0, loadData_1.toOperations)(state.schema, rows);
+            return makeBuilder({ ...state, ops: [...state.ops, ...newOps] });
+        },
+        async build() {
+            // Fail on pure planning errors (cycles, raw SQL file readability)
+            // before touching the server where possible.
+            const rawSql = readRawSql(state.schema);
+            const ddl = (0, ddl_1.generateDdl)(state.schema);
+            const effective = (0, loadData_1.composeRows)(state.schema, state.ops);
+            const allocated = await (0, allocator_1.allocateDatabase)(state.options);
+            let handle;
+            try {
+                handle = await (0, database_1.createDatabaseHandle)(allocated, state.options);
+                for (const statement of ddl) {
+                    try {
+                        await handle._pool.query(statement);
+                    }
+                    catch (err) {
+                        throw new server_1.TestPostgresServerError(`Failed to apply structured DDL from ${state.schema.source}: ${err.message}\n` +
+                            `Statement:\n${statement}`);
+                    }
+                }
+                for (const entry of rawSql) {
+                    try {
+                        // Simple-query protocol: the pg driver executes multi-statement
+                        // scripts directly when no parameters are passed.
+                        await handle._pool.query(entry.sql);
+                    }
+                    catch (err) {
+                        throw new server_1.TestPostgresServerError(`Failed to apply raw ${entry.label} from ${state.schema.source}: ${err.message}`);
+                    }
+                }
+                await (0, loadData_1.insertRows)((sql, params) => handle._pool.query(sql, params), state.schema, effective);
+                return handle;
+            }
+            catch (err) {
+                // Clean up partially created owned resources.
+                if (handle) {
+                    await handle._pool.end().catch(() => undefined);
+                }
+                await (0, allocator_2.dropDatabase)(allocated.name, state.options).catch(() => undefined);
+                throw err;
+            }
+        },
+    };
+}
+/**
+ * Persistent immutable test database builder.
+ *
+ * `schema` may be a parsed schema object, a YAML string, or a path to a
+ * .yml/.yaml file (raw .sql entries then resolve relative to that file's
+ * directory unless options.sourceDir overrides it).
+ */
+function testPostgres(schema, options = {}) {
+    const normalized = isNormalizedSchema(schema) ? schema : (0, parser_1.parseTestSchema)(schema, options);
+    return makeBuilder({ schema: normalized, ops: [], options: Object.freeze({ ...options }) });
+}
+function isNormalizedSchema(input) {
+    return (!!input &&
+        typeof input === 'object' &&
+        Array.isArray(input.tables) &&
+        Array.isArray(input.sql) &&
+        typeof input.source === 'string');
+}
+//# sourceMappingURL=builder.js.map

package/dist/cjs/testing/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../../src/testing/builder.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport { parseTestSchema } from './schema/parser';\nimport { generateDdl } from './schema/ddl';\nimport type { NormalizedTestSchema, ParseTestSchemaOptions } from './schema/types';\nimport { allocateDatabase } from './postgres/allocator';\nimport { createDatabaseHandle, TestPostgresDatabase } from './postgres/database';\nimport { dropDatabase } from './postgres/allocator';\nimport { TestPostgresServerError, TestServerOptions } from './postgres/server';\nimport { composeRows, DataOperation, insertRows, Row, toOperations } from './postgres/loadData';\n\nexport interface TestPostgresOptions extends TestServerOptions, ParseTestSchemaOptions {}\n\nexport interface TestPostgresBuilder {\n  /** The normalized immutable schema (useful for assertions/diagnostics). */\n  readonly schema: NormalizedTestSchema;\n  /** @internal Accumulated row operations (exposed for pure tests). */\n  readonly ops: readonly DataOperation[];\n  /** Returns a NEW derived builder; this builder is unchanged. */\n  data(rows: Record<string, Row[]>): TestPostgresBuilder;\n  /**\n   * Create a fresh isolated PostgreSQL database, apply DDL + raw SQL,\n   * insert effective scenario rows, and return the handle. Does not\n   * consume the builder: building twice yields two independent databases.\n   */\n  build(): Promise<TestPostgresDatabase>;\n}\n\ninterface BuilderState {\n  readonly schema: NormalizedTestSchema;\n  readonly ops: readonly DataOperation[];\n  readonly options: Readonly<TestPostgresOptions>;\n}\n\nfunction readRawSql(schema: NormalizedTestSchema): { label: string; sql: string }[] {\n  return schema.sql.map((entry) => {\n    if (entry.kind === 'inline') {\n      return { label: `sql entry #${entry.index} (inline)`, sql: entry.sql };\n    }\n    try {\n      return {\n        label: `sql entry #${entry.index} (${entry.sourcePath})`,\n        sql: fs.readFileSync(entry.resolvedPath, 'utf8'),\n      };\n    } catch (err) {\n      throw new TestPostgresServerError(\n        `Cannot read raw SQL file for sql entry #${entry.index}: ${entry.resolvedPath} ` +\n          `(authored as \"${entry.sourcePath}\" in ${schema.source}): ${(err as Error).message}`\n      );\n    }\n  });\n}\n\nfunction makeBuilder(state: BuilderState): TestPostgresBuilder {\n  return {\n    schema: state.schema,\n    ops: state.ops,\n    data(rows: Record<string, Row[]>): TestPostgresBuilder {\n      const newOps = toOperations(state.schema, rows);\n      return makeBuilder({ ...state, ops: [...state.ops, ...newOps] });\n    },\n    async build(): Promise<TestPostgresDatabase> {\n      // Fail on pure planning errors (cycles, raw SQL file readability)\n      // before touching the server where possible.\n      const rawSql = readRawSql(state.schema);\n      const ddl = generateDdl(state.schema);\n      const effective = composeRows(state.schema, state.ops);\n\n      const allocated = await allocateDatabase(state.options);\n      let handle: (TestPostgresDatabase & { _pool: any }) | undefined;\n      try {\n        handle = await createDatabaseHandle(allocated, state.options);\n        for (const statement of ddl) {\n          try {\n            await handle._pool.query(statement);\n          } catch (err) {\n            throw new TestPostgresServerError(\n              `Failed to apply structured DDL from ${state.schema.source}: ${(err as Error).message}\\n` +\n                `Statement:\\n${statement}`\n            );\n          }\n        }\n        for (const entry of rawSql) {\n          try {\n            // Simple-query protocol: the pg driver executes multi-statement\n            // scripts directly when no parameters are passed.\n            await handle._pool.query(entry.sql);\n          } catch (err) {\n            throw new TestPostgresServerError(\n              `Failed to apply raw ${entry.label} from ${state.schema.source}: ${(err as Error).message}`\n            );\n          }\n        }\n        await insertRows((sql, params) => handle!._pool.query(sql, params), state.schema, effective);\n        return handle;\n      } catch (err) {\n        // Clean up partially created owned resources.\n        if (handle) {\n          await handle._pool.end().catch(() => undefined);\n        }\n        await dropDatabase(allocated.name, state.options).catch(() => undefined);\n        throw err;\n      }\n    },\n  };\n}\n\n/**\n * Persistent immutable test database builder.\n *\n * `schema` may be a parsed schema object, a YAML string, or a path to a\n * .yml/.yaml file (raw .sql entries then resolve relative to that file's\n * directory unless options.sourceDir overrides it).\n */\nexport function testPostgres(\n  schema: string | object,\n  options: TestPostgresOptions = {}\n): TestPostgresBuilder {\n  const normalized =\n    isNormalizedSchema(schema) ? schema : parseTestSchema(schema as string | object, options);\n  return makeBuilder({ schema: normalized, ops: [], options: Object.freeze({ ...options }) });\n}\n\nfunction isNormalizedSchema(input: unknown): input is NormalizedTestSchema {\n  return (\n    !!input &&\n    typeof input === 'object' &&\n    Array.isArray((input as NormalizedTestSchema).tables) &&\n    Array.isArray((input as NormalizedTestSchema).sql) &&\n    typeof (input as NormalizedTestSchema).source === 'string'\n  );\n}\n"]}

package/dist/cjs/testing/index.d.ts

@@ -0,0 +1,14 @@
+export { testPostgres } from './builder';
+export type { TestPostgresBuilder, TestPostgresOptions } from './builder';
+export type { TestPostgresDatabase } from './postgres/database';
+export { testSqlite } from './sqlite/builder';
+export type { TestSqliteBuilder, TestSqliteOptions } from './sqlite/builder';
+export { TestSqliteError } from './sqlite/database';
+export type { TestSqliteDatabase } from './sqlite/database';
+export { parseTestSchema } from './schema/parser';
+export { normalizeTestSchema, TestSchemaError } from './schema/normalize';
+export { generateDdl } from './schema/ddl';
+export { TestDataError } from './postgres/loadData';
+export { TestPostgresServerError, DEFAULT_ADMIN_URL } from './postgres/server';
+export type { NormalizedTestSchema, NormalizedTable, NormalizedColumn, RawSqlEntry, ParseTestSchemaOptions, } from './schema/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC1E,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,sBAAsB,GACvB,MAAM,gBAAgB,CAAC"}

package/dist/cjs/testing/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ADMIN_URL = exports.TestPostgresServerError = exports.TestDataError = exports.generateDdl = exports.TestSchemaError = exports.normalizeTestSchema = exports.parseTestSchema = exports.TestSqliteError = exports.testSqlite = exports.testPostgres = void 0;
+var builder_1 = require("./builder");
+Object.defineProperty(exports, "testPostgres", { enumerable: true, get: function () { return builder_1.testPostgres; } });
+var builder_2 = require("./sqlite/builder");
+Object.defineProperty(exports, "testSqlite", { enumerable: true, get: function () { return builder_2.testSqlite; } });
+var database_1 = require("./sqlite/database");
+Object.defineProperty(exports, "TestSqliteError", { enumerable: true, get: function () { return database_1.TestSqliteError; } });
+var parser_1 = require("./schema/parser");
+Object.defineProperty(exports, "parseTestSchema", { enumerable: true, get: function () { return parser_1.parseTestSchema; } });
+var normalize_1 = require("./schema/normalize");
+Object.defineProperty(exports, "normalizeTestSchema", { enumerable: true, get: function () { return normalize_1.normalizeTestSchema; } });
+Object.defineProperty(exports, "TestSchemaError", { enumerable: true, get: function () { return normalize_1.TestSchemaError; } });
+var ddl_1 = require("./schema/ddl");
+Object.defineProperty(exports, "generateDdl", { enumerable: true, get: function () { return ddl_1.generateDdl; } });
+var loadData_1 = require("./postgres/loadData");
+Object.defineProperty(exports, "TestDataError", { enumerable: true, get: function () { return loadData_1.TestDataError; } });
+var server_1 = require("./postgres/server");
+Object.defineProperty(exports, "TestPostgresServerError", { enumerable: true, get: function () { return server_1.TestPostgresServerError; } });
+Object.defineProperty(exports, "DEFAULT_ADMIN_URL", { enumerable: true, get: function () { return server_1.DEFAULT_ADMIN_URL; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":";;;AAAA,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AAGrB,4CAA8C;AAArC,qGAAA,UAAU,OAAA;AAEnB,8CAAoD;AAA3C,2GAAA,eAAe,OAAA;AAExB,0CAAkD;AAAzC,yGAAA,eAAe,OAAA;AACxB,gDAA0E;AAAjE,gHAAA,mBAAmB,OAAA;AAAE,4GAAA,eAAe,OAAA;AAC7C,oCAA2C;AAAlC,kGAAA,WAAW,OAAA;AACpB,gDAAoD;AAA3C,yGAAA,aAAa,OAAA;AACtB,4CAA+E;AAAtE,iHAAA,uBAAuB,OAAA;AAAE,2GAAA,iBAAiB,OAAA","sourcesContent":["export { testPostgres } from './builder';\nexport type { TestPostgresBuilder, TestPostgresOptions } from './builder';\nexport type { TestPostgresDatabase } from './postgres/database';\nexport { testSqlite } from './sqlite/builder';\nexport type { TestSqliteBuilder, TestSqliteOptions } from './sqlite/builder';\nexport { TestSqliteError } from './sqlite/database';\nexport type { TestSqliteDatabase } from './sqlite/database';\nexport { parseTestSchema } from './schema/parser';\nexport { normalizeTestSchema, TestSchemaError } from './schema/normalize';\nexport { generateDdl } from './schema/ddl';\nexport { TestDataError } from './postgres/loadData';\nexport { TestPostgresServerError, DEFAULT_ADMIN_URL } from './postgres/server';\nexport type {\n  NormalizedTestSchema,\n  NormalizedTable,\n  NormalizedColumn,\n  RawSqlEntry,\n  ParseTestSchemaOptions,\n} from './schema/types';\n"]}

package/dist/cjs/testing/postgres/allocator.d.ts

@@ -0,0 +1,17 @@
+import { TestServerOptions } from './server';
+/**
+ * Unique, safe, bounded-length database name. Randomness plus a process
+ * counter keeps parallel builds (including across worker processes)
+ * collision-free. Always well under PostgreSQL's 63-byte identifier limit.
+ */
+export declare function nextDatabaseName(): string;
+export interface AllocatedDatabase {
+    readonly name: string;
+    readonly url: string;
+    readonly adminUrl: string;
+}
+/** Create a fresh uniquely named database on the configured test server. */
+export declare function allocateDatabase(options?: TestServerOptions): Promise<AllocatedDatabase>;
+/** Drop exactly the named database. Safe to call for an already-dropped db. */
+export declare function dropDatabase(name: string, options?: TestServerOptions): Promise<void>;
+//# sourceMappingURL=allocator.d.ts.map

package/dist/cjs/testing/postgres/allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocator.d.ts","sourceRoot":"","sources":["../../../../src/testing/postgres/allocator.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,iBAAiB,EAElB,MAAM,UAAU,CAAC;AAKlB;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAGzC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,4EAA4E;AAC5E,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgBlG;AAED,+EAA+E;AAC/E,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB/F"}

package/dist/cjs/testing/postgres/allocator.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextDatabaseName = nextDatabaseName;
+exports.allocateDatabase = allocateDatabase;
+exports.dropDatabase = dropDatabase;
+const crypto_1 = require("crypto");
+const server_1 = require("./server");
+const NAME_PREFIX = 'sqlstack_test_';
+let counter = 0;
+/**
+ * Unique, safe, bounded-length database name. Randomness plus a process
+ * counter keeps parallel builds (including across worker processes)
+ * collision-free. Always well under PostgreSQL's 63-byte identifier limit.
+ */
+function nextDatabaseName() {
+    counter += 1;
+    return `${NAME_PREFIX}${(0, crypto_1.randomBytes)(4).toString('hex')}_${counter}`;
+}
+/** Create a fresh uniquely named database on the configured test server. */
+async function allocateDatabase(options = {}) {
+    const adminUrl = (0, server_1.resolveAdminUrl)(options);
+    const name = nextDatabaseName();
+    const admin = await (0, server_1.connectAdmin)(options);
+    try {
+        await admin.query(`CREATE DATABASE "${name}"`);
+    }
+    catch (err) {
+        throw new server_1.TestPostgresServerError(`Failed to create test database "${name}" on ${(0, server_1.redact)(adminUrl)}: ${err.message}\n` +
+            `The admin connection must have CREATE DATABASE privilege ` +
+            `(set SQLSTACK_TEST_PG_URL or options.adminUrl; start the bundled server with npm run db:pg:up).`);
+    }
+    finally {
+        await admin.end().catch(() => undefined);
+    }
+    return { name, url: (0, server_1.withDatabase)(adminUrl, name), adminUrl };
+}
+/** Drop exactly the named database. Safe to call for an already-dropped db. */
+async function dropDatabase(name, options = {}) {
+    if (!name.startsWith(NAME_PREFIX)) {
+        throw new server_1.TestPostgresServerError(`Refusing to drop database "${name}": not an sqlstack test database (expected prefix ${NAME_PREFIX})`);
+    }
+    const admin = await (0, server_1.connectAdmin)(options);
+    try {
+        // FORCE (PG 13+) terminates lingering sessions so parallel teardown is robust.
+        await admin.query(`DROP DATABASE IF EXISTS "${name}" WITH (FORCE)`);
+    }
+    catch (err) {
+        throw new server_1.TestPostgresServerError(`Failed to drop test database "${name}" on ${(0, server_1.redact)((0, server_1.resolveAdminUrl)(options))}: ${err.message}`);
+    }
+    finally {
+        await admin.end().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=allocator.js.map

package/dist/cjs/testing/postgres/allocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocator.js","sourceRoot":"","sources":["../../../../src/testing/postgres/allocator.ts"],"names":[],"mappings":";;AAkBA,4CAGC;AASD,4CAgBC;AAGD,oCAiBC;AAlED,mCAAqC;AACrC,qCAOkB;AAElB,MAAM,WAAW,GAAG,gBAAgB,CAAC;AACrC,IAAI,OAAO,GAAG,CAAC,CAAC;AAEhB;;;;GAIG;AACH,SAAgB,gBAAgB;IAC9B,OAAO,IAAI,CAAC,CAAC;IACb,OAAO,GAAG,WAAW,GAAG,IAAA,oBAAW,EAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;AACtE,CAAC;AAQD,4EAA4E;AACrE,KAAK,UAAU,gBAAgB,CAAC,UAA6B,EAAE;IACpE,MAAM,QAAQ,GAAG,IAAA,wBAAe,EAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,gBAAgB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,MAAM,IAAA,qBAAY,EAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,KAAK,CAAC,oBAAoB,IAAI,GAAG,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,gCAAuB,CAC/B,mCAAmC,IAAI,QAAQ,IAAA,eAAM,EAAC,QAAQ,CAAC,KAAM,GAAa,CAAC,OAAO,IAAI;YAC5F,2DAA2D;YAC3D,iGAAiG,CACpG,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,MAAM,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAA,qBAAY,EAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC;AAC/D,CAAC;AAED,+EAA+E;AACxE,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,UAA6B,EAAE;IAC9E,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,gCAAuB,CAC/B,8BAA8B,IAAI,qDAAqD,WAAW,GAAG,CACtG,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,IAAA,qBAAY,EAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,+EAA+E;QAC/E,MAAM,KAAK,CAAC,KAAK,CAAC,4BAA4B,IAAI,gBAAgB,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,gCAAuB,CAC/B,iCAAiC,IAAI,QAAQ,IAAA,eAAM,EAAC,IAAA,wBAAe,EAAC,OAAO,CAAC,CAAC,KAAM,GAAa,CAAC,OAAO,EAAE,CAC3G,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,MAAM,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC","sourcesContent":["import { randomBytes } from 'crypto';\nimport {\n  connectAdmin,\n  redact,\n  resolveAdminUrl,\n  TestPostgresServerError,\n  TestServerOptions,\n  withDatabase,\n} from './server';\n\nconst NAME_PREFIX = 'sqlstack_test_';\nlet counter = 0;\n\n/**\n * Unique, safe, bounded-length database name. Randomness plus a process\n * counter keeps parallel builds (including across worker processes)\n * collision-free. Always well under PostgreSQL's 63-byte identifier limit.\n */\nexport function nextDatabaseName(): string {\n  counter += 1;\n  return `${NAME_PREFIX}${randomBytes(4).toString('hex')}_${counter}`;\n}\n\nexport interface AllocatedDatabase {\n  readonly name: string;\n  readonly url: string;\n  readonly adminUrl: string;\n}\n\n/** Create a fresh uniquely named database on the configured test server. */\nexport async function allocateDatabase(options: TestServerOptions = {}): Promise<AllocatedDatabase> {\n  const adminUrl = resolveAdminUrl(options);\n  const name = nextDatabaseName();\n  const admin = await connectAdmin(options);\n  try {\n    await admin.query(`CREATE DATABASE \"${name}\"`);\n  } catch (err) {\n    throw new TestPostgresServerError(\n      `Failed to create test database \"${name}\" on ${redact(adminUrl)}: ${(err as Error).message}\\n` +\n        `The admin connection must have CREATE DATABASE privilege ` +\n        `(set SQLSTACK_TEST_PG_URL or options.adminUrl; start the bundled server with npm run db:pg:up).`\n    );\n  } finally {\n    await admin.end().catch(() => undefined);\n  }\n  return { name, url: withDatabase(adminUrl, name), adminUrl };\n}\n\n/** Drop exactly the named database. Safe to call for an already-dropped db. */\nexport async function dropDatabase(name: string, options: TestServerOptions = {}): Promise<void> {\n  if (!name.startsWith(NAME_PREFIX)) {\n    throw new TestPostgresServerError(\n      `Refusing to drop database \"${name}\": not an sqlstack test database (expected prefix ${NAME_PREFIX})`\n    );\n  }\n  const admin = await connectAdmin(options);\n  try {\n    // FORCE (PG 13+) terminates lingering sessions so parallel teardown is robust.\n    await admin.query(`DROP DATABASE IF EXISTS \"${name}\" WITH (FORCE)`);\n  } catch (err) {\n    throw new TestPostgresServerError(\n      `Failed to drop test database \"${name}\" on ${redact(resolveAdminUrl(options))}: ${(err as Error).message}`\n    );\n  } finally {\n    await admin.end().catch(() => undefined);\n  }\n}\n"]}

package/dist/cjs/testing/postgres/database.d.ts

@@ -0,0 +1,21 @@
+import { TestServerOptions } from './server';
+/** The built test database handle. */
+export interface TestPostgresDatabase {
+    /** Normal PostgreSQL connection string identifying only this database. */
+    readonly url: string;
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+    /** Close helper connections and drop the owned database. Idempotent. */
+    dispose(): Promise<void>;
+}
+export interface OwnedDatabase {
+    readonly name: string;
+    readonly url: string;
+}
+/**
+ * Connect a helper pool to an allocated database and produce the handle.
+ * The handle owns exactly this database and drops it on dispose.
+ */
+export declare function createDatabaseHandle(owned: OwnedDatabase, options?: TestServerOptions): Promise<TestPostgresDatabase & {
+    _pool: any;
+}>;
+//# sourceMappingURL=database.d.ts.map

package/dist/cjs/testing/postgres/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../../src/testing/postgres/database.ts"],"names":[],"mappings":"AACA,OAAO,EAAmC,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE9E,sCAAsC;AACtC,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,wEAAwE;IACxE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,oBAAoB,GAAG;IAAE,KAAK,EAAE,GAAG,CAAA;CAAE,CAAC,CA4BhD"}

package/dist/cjs/testing/postgres/database.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDatabaseHandle = createDatabaseHandle;
+const allocator_1 = require("./allocator");
+const server_1 = require("./server");
+/**
+ * Connect a helper pool to an allocated database and produce the handle.
+ * The handle owns exactly this database and drops it on dispose.
+ */
+async function createDatabaseHandle(owned, options = {}) {
+    const pg = await (0, server_1.loadPg)();
+    const Pool = pg.Pool ?? pg.default?.Pool;
+    const pool = new Pool({ connectionString: owned.url, max: 4 });
+    let disposed = false;
+    return {
+        url: owned.url,
+        _pool: pool,
+        async query(sql, params = []) {
+            if (disposed) {
+                throw new server_1.TestPostgresServerError(`Test database "${owned.name}" has been disposed; no further queries are possible.`);
+            }
+            const res = await pool.query(sql, params);
+            return res.rows;
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            try {
+                await pool.end();
+            }
+            catch {
+                /* pool may already be closed */
+            }
+            await (0, allocator_1.dropDatabase)(owned.name, options);
+        },
+    };
+}
+//# sourceMappingURL=database.js.map

package/dist/cjs/testing/postgres/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../../src/testing/postgres/database.ts"],"names":[],"mappings":";;AAqBA,oDA+BC;AApDD,2CAA2C;AAC3C,qCAA8E;AAgB9E;;;GAGG;AACI,KAAK,UAAU,oBAAoB,CACxC,KAAoB,EACpB,UAA6B,EAAE;IAE/B,MAAM,EAAE,GAAG,MAAM,IAAA,eAAM,GAAE,CAAC;IAC1B,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/D,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO;QACL,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,KAAK,EAAE,IAAI;QACX,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,SAA6B,EAAE;YACtD,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,IAAI,gCAAuB,CAC/B,kBAAkB,KAAK,CAAC,IAAI,uDAAuD,CACpF,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAmB,CAAC,CAAC;YACvD,OAAO,GAAG,CAAC,IAAI,CAAC;QAClB,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;YACnB,CAAC;YAAC,MAAM,CAAC;gBACP,gCAAgC;YAClC,CAAC;YACD,MAAM,IAAA,wBAAY,EAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { dropDatabase } from './allocator';\nimport { loadPg, TestPostgresServerError, TestServerOptions } from './server';\n\n/** The built test database handle. */\nexport interface TestPostgresDatabase {\n  /** Normal PostgreSQL connection string identifying only this database. */\n  readonly url: string;\n  query(sql: string, params?: readonly unknown[]): Promise<unknown>;\n  /** Close helper connections and drop the owned database. Idempotent. */\n  dispose(): Promise<void>;\n}\n\nexport interface OwnedDatabase {\n  readonly name: string;\n  readonly url: string;\n}\n\n/**\n * Connect a helper pool to an allocated database and produce the handle.\n * The handle owns exactly this database and drops it on dispose.\n */\nexport async function createDatabaseHandle(\n  owned: OwnedDatabase,\n  options: TestServerOptions = {}\n): Promise<TestPostgresDatabase & { _pool: any }> {\n  const pg = await loadPg();\n  const Pool = pg.Pool ?? pg.default?.Pool;\n  const pool = new Pool({ connectionString: owned.url, max: 4 });\n  let disposed = false;\n  return {\n    url: owned.url,\n    _pool: pool,\n    async query(sql: string, params: readonly unknown[] = []) {\n      if (disposed) {\n        throw new TestPostgresServerError(\n          `Test database \"${owned.name}\" has been disposed; no further queries are possible.`\n        );\n      }\n      const res = await pool.query(sql, params as unknown[]);\n      return res.rows;\n    },\n    async dispose() {\n      if (disposed) return;\n      disposed = true;\n      try {\n        await pool.end();\n      } catch {\n        /* pool may already be closed */\n      }\n      await dropDatabase(owned.name, options);\n    },\n  };\n}\n"]}

package/dist/cjs/testing/postgres/loadData.d.ts

@@ -0,0 +1,31 @@
+import { SqlStackError } from '../../core/errors';
+import type { NormalizedTestSchema } from '../schema/types';
+export declare class TestDataError extends SqlStackError {
+    constructor(message: string);
+}
+export type Row = Record<string, unknown>;
+export interface DataOperation {
+    readonly table: string;
+    readonly row: Readonly<Row>;
+}
+/** Validate one `.data()` payload against the structured schema (fail-fast). */
+export declare function toOperations(schema: NormalizedTestSchema, data: Record<string, Row[]>): DataOperation[];
+/**
+ * Compose row operations into effective rows per table.
+ * PK tables: identity = ordered PK values; later writes replace, first
+ * occurrence keeps its position. No-PK tables: append in authored order.
+ */
+export declare function composeRows(schema: NormalizedTestSchema, ops: readonly DataOperation[]): Map<string, Row[]>;
+/**
+ * Deterministic insertion order for the tables that actually have rows,
+ * topologically sorted by declared references between those tables.
+ * Cycles fail with actionable guidance.
+ */
+export declare function planInsertOrder(schema: NormalizedTestSchema, tablesWithRows: readonly string[]): string[];
+/**
+ * Insert effective rows. Parameterized and batched per table by column
+ * signature; missing columns are omitted from the INSERT so PostgreSQL
+ * defaults apply, while explicit null is sent as NULL.
+ */
+export declare function insertRows(query: (sql: string, params: unknown[]) => Promise<unknown>, schema: NormalizedTestSchema, effective: Map<string, Row[]>): Promise<void>;
+//# sourceMappingURL=loadData.d.ts.map

package/dist/cjs/testing/postgres/loadData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadData.d.ts","sourceRoot":"","sources":["../../../../src/testing/postgres/loadData.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,qBAAa,aAAc,SAAQ,aAAa;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;CAC7B;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,MAAM,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,aAAa,EAAE,CAwCvG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,SAAS,aAAa,EAAE,GAC5B,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CA8BpB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,oBAAoB,EAAE,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAqCzG;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAC3D,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAuCf"}

package/dist/cjs/testing/postgres/loadData.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestDataError = void 0;
+exports.toOperations = toOperations;
+exports.composeRows = composeRows;
+exports.planInsertOrder = planInsertOrder;
+exports.insertRows = insertRows;
+const errors_1 = require("../../core/errors");
+const ddl_1 = require("../schema/ddl");
+class TestDataError extends errors_1.SqlStackError {
+    constructor(message) {
+        super(message);
+        this.name = 'TestDataError';
+    }
+}
+exports.TestDataError = TestDataError;
+/** Validate one `.data()` payload against the structured schema (fail-fast). */
+function toOperations(schema, data) {
+    const ops = [];
+    const tables = new Map(schema.tables.map((t) => [t.name, t]));
+    for (const [tableName, rows] of Object.entries(data)) {
+        const table = tables.get(tableName);
+        if (!table) {
+            const known = schema.tables.map((t) => t.name).join(', ') || '(none)';
+            throw new TestDataError(`.data(): unknown table "${tableName}". Structured tables declared in ${schema.source}: ${known}. ` +
+                `Tables created only through raw SQL cannot receive .data() rows; insert them via raw SQL instead.`);
+        }
+        if (!Array.isArray(rows)) {
+            throw new TestDataError(`.data(): rows for table "${tableName}" must be an array`);
+        }
+        const columnNames = new Set(table.columns.map((c) => c.name));
+        rows.forEach((row, i) => {
+            if (!row || typeof row !== 'object' || Array.isArray(row)) {
+                throw new TestDataError(`.data(): row #${i} for table "${tableName}" must be an object`);
+            }
+            for (const key of Object.keys(row)) {
+                if (!columnNames.has(key)) {
+                    throw new TestDataError(`.data(): unknown column "${key}" in row #${i} for table "${tableName}" ` +
+                        `(declared columns: ${[...columnNames].join(', ')})`);
+                }
+            }
+            for (const pk of table.primaryKey) {
+                if (row[pk] === undefined) {
+                    throw new TestDataError(`.data(): row #${i} for table "${tableName}" is missing primary-key column "${pk}" ` +
+                        `(primary key: ${table.primaryKey.join(', ')})`);
+                }
+            }
+            ops.push({ table: tableName, row });
+        });
+    }
+    return ops;
+}
+/**
+ * Compose row operations into effective rows per table.
+ * PK tables: identity = ordered PK values; later writes replace, first
+ * occurrence keeps its position. No-PK tables: append in authored order.
+ */
+function composeRows(schema, ops) {
+    const tables = new Map(schema.tables.map((t) => [t.name, t]));
+    const result = new Map();
+    const identityIndex = new Map();
+    for (const op of ops) {
+        const table = tables.get(op.table);
+        let rows = result.get(op.table);
+        if (!rows) {
+            rows = [];
+            result.set(op.table, rows);
+        }
+        if (table.primaryKey.length === 0) {
+            rows.push(op.row);
+            continue;
+        }
+        const identity = JSON.stringify(table.primaryKey.map((pk) => op.row[pk]));
+        let index = identityIndex.get(op.table);
+        if (!index) {
+            index = new Map();
+            identityIndex.set(op.table, index);
+        }
+        const existing = index.get(identity);
+        if (existing === undefined) {
+            index.set(identity, rows.length);
+            rows.push(op.row);
+        }
+        else {
+            rows[existing] = op.row;
+        }
+    }
+    return result;
+}
+/**
+ * Deterministic insertion order for the tables that actually have rows,
+ * topologically sorted by declared references between those tables.
+ * Cycles fail with actionable guidance.
+ */
+function planInsertOrder(schema, tablesWithRows) {
+    const inPlan = new Set(tablesWithRows);
+    const tables = schema.tables.filter((t) => inPlan.has(t.name));
+    // deps[t] = set of tables (with rows) that must be inserted before t
+    const deps = new Map();
+    for (const t of tables) {
+        const set = new Set();
+        for (const c of t.columns) {
+            if (c.references && c.references.table !== t.name && inPlan.has(c.references.table)) {
+                set.add(c.references.table);
+            }
+        }
+        deps.set(t.name, set);
+    }
+    const order = [];
+    const done = new Set();
+    let progressed = true;
+    while (progressed && order.length < tables.length) {
+        progressed = false;
+        for (const t of tables) {
+            if (done.has(t.name))
+                continue;
+            const pending = [...deps.get(t.name)].filter((d) => !done.has(d));
+            if (pending.length === 0) {
+                order.push(t.name);
+                done.add(t.name);
+                progressed = true;
+            }
+        }
+    }
+    if (order.length < tables.length) {
+        const cycle = tables.filter((t) => !done.has(t.name)).map((t) => t.name);
+        throw new TestDataError(`Cannot derive an insertion order: declared references between tables [${cycle.join(', ')}] form a cycle. ` +
+            `Insert this data via a raw "sql" entry (e.g. with deferred constraints), or restructure the references.`);
+    }
+    return order;
+}
+/**
+ * Insert effective rows. Parameterized and batched per table by column
+ * signature; missing columns are omitted from the INSERT so PostgreSQL
+ * defaults apply, while explicit null is sent as NULL.
+ */
+async function insertRows(query, schema, effective) {
+    const order = planInsertOrder(schema, [...effective.keys()]);
+    const declared = new Map(schema.tables.map((t) => [t.name, t.columns.map((c) => c.name)]));
+    for (const tableName of order) {
+        const rows = effective.get(tableName);
+        const columnOrder = declared.get(tableName);
+        // Group consecutive-compatible rows into batches sharing a column signature.
+        const batches = new Map();
+        for (const row of rows) {
+            const columns = columnOrder.filter((c) => row[c] !== undefined);
+            const sig = columns.join(',');
+            let batch = batches.get(sig);
+            if (!batch) {
+                batch = { columns, rows: [] };
+                batches.set(sig, batch);
+            }
+            batch.rows.push(row);
+        }
+        for (const { columns, rows: batchRows } of batches.values()) {
+            if (columns.length === 0) {
+                for (let i = 0; i < batchRows.length; i++) {
+                    await run(query, tableName, `INSERT INTO ${(0, ddl_1.quoteIdent)(tableName)} DEFAULT VALUES`, []);
+                }
+                continue;
+            }
+            const params = [];
+            const tuples = batchRows.map((row) => {
+                const placeholders = columns.map((c) => {
+                    params.push(row[c]);
+                    return `$${params.length}`;
+                });
+                return `(${placeholders.join(', ')})`;
+            });
+            const sql = `INSERT INTO ${(0, ddl_1.quoteIdent)(tableName)} (${columns.map(ddl_1.quoteIdent).join(', ')}) ` +
+                `VALUES ${tuples.join(', ')}`;
+            await run(query, tableName, sql, params);
+        }
+    }
+}
+async function run(query, tableName, sql, params) {
+    try {
+        await query(sql, params);
+    }
+    catch (err) {
+        throw new TestDataError(`Failed to insert scenario rows into table "${tableName}": ${err.message}`);
+    }
+}
+//# sourceMappingURL=loadData.js.map

package/dist/cjs/testing/postgres/loadData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadData.js","sourceRoot":"","sources":["../../../../src/testing/postgres/loadData.ts"],"names":[],"mappings":"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","sourcesContent":["import { SqlStackError } from '../../core/errors';\nimport { quoteIdent } from '../schema/ddl';\nimport type { NormalizedTestSchema } from '../schema/types';\n\nexport class TestDataError extends SqlStackError {\n  constructor(message: string) {\n    super(message);\n    this.name = 'TestDataError';\n  }\n}\n\nexport type Row = Record<string, unknown>;\n\nexport interface DataOperation {\n  readonly table: string;\n  readonly row: Readonly<Row>;\n}\n\n/** Validate one `.data()` payload against the structured schema (fail-fast). */\nexport function toOperations(schema: NormalizedTestSchema, data: Record<string, Row[]>): DataOperation[] {\n  const ops: DataOperation[] = [];\n  const tables = new Map(schema.tables.map((t) => [t.name, t]));\n  for (const [tableName, rows] of Object.entries(data)) {\n    const table = tables.get(tableName);\n    if (!table) {\n      const known = schema.tables.map((t) => t.name).join(', ') || '(none)';\n      throw new TestDataError(\n        `.data(): unknown table \"${tableName}\". Structured tables declared in ${schema.source}: ${known}. ` +\n          `Tables created only through raw SQL cannot receive .data() rows; insert them via raw SQL instead.`\n      );\n    }\n    if (!Array.isArray(rows)) {\n      throw new TestDataError(`.data(): rows for table \"${tableName}\" must be an array`);\n    }\n    const columnNames = new Set(table.columns.map((c) => c.name));\n    rows.forEach((row, i) => {\n      if (!row || typeof row !== 'object' || Array.isArray(row)) {\n        throw new TestDataError(`.data(): row #${i} for table \"${tableName}\" must be an object`);\n      }\n      for (const key of Object.keys(row)) {\n        if (!columnNames.has(key)) {\n          throw new TestDataError(\n            `.data(): unknown column \"${key}\" in row #${i} for table \"${tableName}\" ` +\n              `(declared columns: ${[...columnNames].join(', ')})`\n          );\n        }\n      }\n      for (const pk of table.primaryKey) {\n        if (row[pk] === undefined) {\n          throw new TestDataError(\n            `.data(): row #${i} for table \"${tableName}\" is missing primary-key column \"${pk}\" ` +\n              `(primary key: ${table.primaryKey.join(', ')})`\n          );\n        }\n      }\n      ops.push({ table: tableName, row });\n    });\n  }\n  return ops;\n}\n\n/**\n * Compose row operations into effective rows per table.\n * PK tables: identity = ordered PK values; later writes replace, first\n * occurrence keeps its position. No-PK tables: append in authored order.\n */\nexport function composeRows(\n  schema: NormalizedTestSchema,\n  ops: readonly DataOperation[]\n): Map<string, Row[]> {\n  const tables = new Map(schema.tables.map((t) => [t.name, t]));\n  const result = new Map<string, Row[]>();\n  const identityIndex = new Map<string, Map<string, number>>();\n  for (const op of ops) {\n    const table = tables.get(op.table)!;\n    let rows = result.get(op.table);\n    if (!rows) {\n      rows = [];\n      result.set(op.table, rows);\n    }\n    if (table.primaryKey.length === 0) {\n      rows.push(op.row);\n      continue;\n    }\n    const identity = JSON.stringify(table.primaryKey.map((pk) => op.row[pk]));\n    let index = identityIndex.get(op.table);\n    if (!index) {\n      index = new Map();\n      identityIndex.set(op.table, index);\n    }\n    const existing = index.get(identity);\n    if (existing === undefined) {\n      index.set(identity, rows.length);\n      rows.push(op.row);\n    } else {\n      rows[existing] = op.row;\n    }\n  }\n  return result;\n}\n\n/**\n * Deterministic insertion order for the tables that actually have rows,\n * topologically sorted by declared references between those tables.\n * Cycles fail with actionable guidance.\n */\nexport function planInsertOrder(schema: NormalizedTestSchema, tablesWithRows: readonly string[]): string[] {\n  const inPlan = new Set(tablesWithRows);\n  const tables = schema.tables.filter((t) => inPlan.has(t.name));\n  // deps[t] = set of tables (with rows) that must be inserted before t\n  const deps = new Map<string, Set<string>>();\n  for (const t of tables) {\n    const set = new Set<string>();\n    for (const c of t.columns) {\n      if (c.references && c.references.table !== t.name && inPlan.has(c.references.table)) {\n        set.add(c.references.table);\n      }\n    }\n    deps.set(t.name, set);\n  }\n  const order: string[] = [];\n  const done = new Set<string>();\n  let progressed = true;\n  while (progressed && order.length < tables.length) {\n    progressed = false;\n    for (const t of tables) {\n      if (done.has(t.name)) continue;\n      const pending = [...deps.get(t.name)!].filter((d) => !done.has(d));\n      if (pending.length === 0) {\n        order.push(t.name);\n        done.add(t.name);\n        progressed = true;\n      }\n    }\n  }\n  if (order.length < tables.length) {\n    const cycle = tables.filter((t) => !done.has(t.name)).map((t) => t.name);\n    throw new TestDataError(\n      `Cannot derive an insertion order: declared references between tables [${cycle.join(', ')}] form a cycle. ` +\n        `Insert this data via a raw \"sql\" entry (e.g. with deferred constraints), or restructure the references.`\n    );\n  }\n  return order;\n}\n\n/**\n * Insert effective rows. Parameterized and batched per table by column\n * signature; missing columns are omitted from the INSERT so PostgreSQL\n * defaults apply, while explicit null is sent as NULL.\n */\nexport async function insertRows(\n  query: (sql: string, params: unknown[]) => Promise<unknown>,\n  schema: NormalizedTestSchema,\n  effective: Map<string, Row[]>\n): Promise<void> {\n  const order = planInsertOrder(schema, [...effective.keys()]);\n  const declared = new Map(schema.tables.map((t) => [t.name, t.columns.map((c) => c.name)]));\n  for (const tableName of order) {\n    const rows = effective.get(tableName)!;\n    const columnOrder = declared.get(tableName)!;\n    // Group consecutive-compatible rows into batches sharing a column signature.\n    const batches = new Map<string, { columns: string[]; rows: Row[] }>();\n    for (const row of rows) {\n      const columns = columnOrder.filter((c) => row[c] !== undefined);\n      const sig = columns.join(',');\n      let batch = batches.get(sig);\n      if (!batch) {\n        batch = { columns, rows: [] };\n        batches.set(sig, batch);\n      }\n      batch.rows.push(row);\n    }\n    for (const { columns, rows: batchRows } of batches.values()) {\n      if (columns.length === 0) {\n        for (let i = 0; i < batchRows.length; i++) {\n          await run(query, tableName, `INSERT INTO ${quoteIdent(tableName)} DEFAULT VALUES`, []);\n        }\n        continue;\n      }\n      const params: unknown[] = [];\n      const tuples = batchRows.map((row) => {\n        const placeholders = columns.map((c) => {\n          params.push(row[c]);\n          return `$${params.length}`;\n        });\n        return `(${placeholders.join(', ')})`;\n      });\n      const sql =\n        `INSERT INTO ${quoteIdent(tableName)} (${columns.map(quoteIdent).join(', ')}) ` +\n        `VALUES ${tuples.join(', ')}`;\n      await run(query, tableName, sql, params);\n    }\n  }\n}\n\nasync function run(\n  query: (sql: string, params: unknown[]) => Promise<unknown>,\n  tableName: string,\n  sql: string,\n  params: unknown[]\n): Promise<void> {\n  try {\n    await query(sql, params);\n  } catch (err) {\n    throw new TestDataError(\n      `Failed to insert scenario rows into table \"${tableName}\": ${(err as Error).message}`\n    );\n  }\n}\n"]}