@rawsql-ts/ztd-cli 0.14.4 → 0.16.0

package/dist/utils/sqlLintHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlLintHelpers.js","sourceRoot":"","sources":["../../src/utils/sqlLintHelpers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rawsql-ts/ztd-cli",
-  "version": "0.14.4",
+  "version": "0.16.0",
   "description": "DB-agnostic scaffolding and DDL helpers for Zero Table Dependency projects",
   "main": "dist/index.js",
   "bin": {
@@ -22,11 +22,17 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@testcontainers/postgresql": "^10.28.0",
     "chokidar": "^5.0.0",
     "commander": "^12.0.0",
-    "diff": "^5.1.0",
-    "@rawsql-ts/testkit-core": "0.14.4",
-    "rawsql-ts": "0.14.4"
+    "diff": "^8.0.3",
+    "fast-glob": "^3.3.3",
+    "pg": "^8.11.1",
+    "testcontainers": "^10.28.0",
+    "@rawsql-ts/adapter-node-pg": "^0.15.1",
+    "@rawsql-ts/testkit-postgres": "^0.15.1",
+    "@rawsql-ts/testkit-core": "^0.15.1",
+    "rawsql-ts": "^0.16.0"
   },
   "devDependencies": {
     "@types/diff": "^5.0.1",
@@ -41,6 +47,7 @@
     "README.md"
   ],
   "scripts": {
+    "prebuild": "pnpm --filter @rawsql-ts/testkit-core build && pnpm --filter @rawsql-ts/testkit-postgres build && pnpm --filter @rawsql-ts/adapter-node-pg build",
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "lint": "eslint src --ext .ts",

package/templates/AGENTS.md

@@ -4,7 +4,7 @@ This application uses **Zero Table Dependency (ZTD)** as an internal development
 ZTD is not part of the application's runtime behavior; rather, it provides a framework for:
 
 - Maintaining consistent SQL across the project
-- Keeping schema, domain specifications, and enums synchronized
+- Keeping schema metadata and generated artifacts synchronized
 - Ensuring deterministic SQL unit tests
 - Enabling structured collaboration between humans and AI
 
@@ -26,10 +26,35 @@ This section documents how ZTD is used inside this repository as a development m
 - After cloning the repository (or in a clean environment), run `npx ztd ztd-config`.
 - If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `npx ztd ztd-config`.
 
+---
+
+## TypeScript validation (required)
+
+After any code change, TypeScript type checking **must** be performed and must pass.
+
+- Run the project-appropriate typecheck command (e.g. `pnpm typecheck`).
+- If generated files are involved, run generators first, then re-run typecheck.
+- If typecheck fails, fix errors by root cause, not only the first reported error.
+- A change is not considered complete unless typecheck is green.
+CI pipelines SHOULD run `npx ztd ztd-config` before typecheck and tests (recommended).
+
+Rationale:  
+In ZTD-based development, many schema or SQL inconsistencies surface first as TypeScript errors via generated row maps and DTOs.
+Type checking is a primary correctness signal, not an optional step.
+
+---
+
 ## ZTD Implementation Guide (src/)
 
 The `src/` directory should contain pure TypeScript logic that operates on the row interfaces generated by `tests/generated/ztd-row-map.generated.ts`. Tests should import the row map, repositories should import DTOs, and fixtures must stay under `tests/`. Keep production code decoupled from the generated row map to preserve the distinction between implementation and test scaffolding.
 
+### Runtime dependency boundaries (important)
+
+- Code under `src/` MUST NOT import anything from `tests/` or `tests/generated/`.
+- Generated row-maps are test-only artifacts and MUST NEVER influence runtime behavior.
+- Mapper and writer runtime utilities MUST NOT depend on ZTD internals or generated helpers.
+- All schema compatibility checks (column existence, enum coverage, forbidden columns, etc.) MUST be enforced in tests, never in production code.
+
 ### Repository Classes: What to Care About
 
 #### Scope and Responsibility
@@ -37,10 +62,28 @@ The `src/` directory should contain pure TypeScript logic that operates on the r
 - Avoid embedding business logic, thresholds, or data reshaping inside repositories.
 - Treat repositories as thin adapters over SQL.
 
+#### Mandatory testing rule (important)
+
+Whenever a repository class is created or modified, corresponding tests **must** be created or updated.
+
+Rules:
+- Every public repository method must be covered by tests.
+- Tests must call repository methods, not raw SQL files or SQL strings.
+- ZTD fixtures are the only allowed source of database state in tests.
+- A repository change without tests is considered incomplete.
+- Every repository or test modification must be followed by `pnpm --filter <package> test` (replace `<package>` with the template package name).
+  - `tests/support/global-setup.ts` already uses `@testcontainers/postgresql`, so the suite stands up a Postgres container automatically whenever `DATABASE_URL` is absent.
+  - If the suite fails, fix the root cause and rerun the command until it passes before considering the repository change complete.
+
+Rationale:  
+ZTD derives much of its value from deterministic, repository-level tests.
+Without tests, schema drift and SQL inconsistencies cannot be detected.
+
 #### SQL Management
-- Prefer keeping SQL in separate `.sql` files.
-  - If no explicit instruction is given, separate SQL into files by default.
-- Repository classes should reference SQL files by name, not inline long SQL strings.
+- Keep every SELECT statement in a dedicated `.sql` file under `src/sql/` (match the repository name, e.g. `src/sql/user-accounts.sql`).
+  - Load the SQL via `fs.readFileSync` or similar helpers so the repository never embeds long SQL strings inline.
+  - Inline SQL is forbidden unless a human explicitly requests an override; follow the `.sql` file convention by default.
+  - Repository classes should reference those SQL files; the file name should match the repository class or the query method to keep the code/spec alignment clear.
 
 #### Specifications and Documentation
 - If a markdown file with the same base name as the repository or SQL exists, read it before implementation.
@@ -66,6 +109,32 @@ The `src/` directory should contain pure TypeScript logic that operates on the r
 - Do not introduce intermediate `*Row` types when SQL already returns DTO-compatible shapes.
 - Define separate Row types only when SQL intentionally returns database-shaped (snake_case) rows, and always convert them explicitly.
 
+---
+
+### Mapper + writer guardrails (template-specific)
+
+- In this project, `src/repositories/user-accounts.ts` is the authoritative mapper for the columns defined by the DDL; it MUST enumerate those columns explicitly so downstream logic never infers metadata at runtime.
+- Writer helpers in the same module MUST emit SQL for `public.user_account` only and MUST remain limited to the explicit insert/update/delete helpers shown there; DO NOT introduce ad-hoc schema discovery.
+- `tests/writer-constraints.test.ts` MUST consume `userAccountWriterColumnSets` together with `tests/generated/ztd-row-map.generated.ts` so CUD callers only reference columns that exist on `public.user_account`.
+- When the schema of `public.user_account` changes, update `src/repositories/user-accounts.ts` column metadata, keep `tests/writer-constraints.test.ts` expectations aligned, and re-run `npx ztd ztd-config` so the generated row map stays synchronized with the tests.
+
+#### Writer safety contract (important)
+
+- Allowed:
+  - Insert, update, and delete helpers tied to a single table with explicitly enumerated column sets.
+  - Explicit `RETURNING` clauses that list permitted columns.
+  - Patch-style updates that only touch writable columns listed in `userAccountWriterColumnSets`.
+- Forbidden:
+  - Generic writers that accept arbitrary table or column names.
+  - Runtime schema or enum discovery (e.g., querying `information_schema`) to drive writer column lists.
+  - Writers that embed joins or subqueries beyond simple `RETURNING` clauses.
+If these constraints are insufficient, write the SQL manually.
+
+#### Mapper strictness policy
+
+- Mapping is strict by default: SQL must return exactly the DTO-shaped results that `src/repositories/user-accounts.ts` exposes; missing or mismatched columns are bugs that tests MUST surface.
+- Non-strict behaviors (coercions, key transforms, etc.) MUST be enabled explicitly via named presets or configuration; relying on implicit or silent defaults is prohibited.
+
 ### Sequence / identity column policy (important)
 
 - Sequence / identity columns (auto-generated IDs) are infrastructure concerns.
@@ -76,14 +145,11 @@ The `src/` directory should contain pure TypeScript logic that operates on the r
 ### No test-driven fallbacks in production code (important)
 
 - Do not add fallbacks in `src/` that exist only to accommodate ZTD/testkit/rewriter limitations.
-- If a query fails to be rewritten into ZTD form (e.g. rawsql-ts parsing/rewrite failure), do not paper over it by changing runtime behavior, adding `max(id)+1`, or introducing alternative logic paths.
-- Instead, stop and report the issue with evidence:
-  - The exact SQL that fails
-  - The error message / symptoms
-  - A minimal reproduction (smallest query that triggers the failure)
-  - The expected behavior (what ZTD/testkit should have produced)
+- If a query fails to be rewritten into ZTD form, do not change runtime behavior to compensate.
+- Report tooling issues with minimal reproduction and expected behavior.
 
-Rationale: Production code must not diverge from the intended SQL semantics due to tooling constraints. Tooling issues should be fixed in the tooling layer (rawsql-ts / ztd / testkit), not by altering runtime logic.
+Rationale:  
+Production code must not diverge from intended SQL semantics due to tooling constraints.
 
 ---
 
@@ -93,7 +159,8 @@ Testing under ZTD follows dedicated, directory-scoped rules.
 
 - Test design, execution mode selection, and constraints are defined in:
   - `templates/tests/AGENTS.md`
-- This file intentionally avoids duplicating test-specific operational rules to prevent divergence.
+- Tests validate repository behavior and returned DTOs.
+- Raw SQL files or SQL strings must not be tested directly.
 
 ---
 
@@ -104,19 +171,15 @@ Testing under ZTD follows dedicated, directory-scoped rules.
   /ddl
     *.sql               <- physical schema definitions
 
-  /domain-specs
-    *.md                <- one behavioral SELECT per file (one SQL block)
-
-  /enums
-    *.md                <- one enum definition per file (one SQL block)
-
   README.md             <- documentation for the layout
-  AGENTS.md             <- combined guidance for DDL, enums, and specs
+  AGENTS.md             <- combined guidance for DDL
 
 /src                    <- application & repository logic
 /tests                  <- ZTD tests, fixtures, row-maps
 ```
 
+Only `ztd/ddl` is part of the template contract. Do not create or assume any other `ztd` subdirectories unless the project explicitly adds them.
+
 The file `tests/generated/ztd-layout.generated.ts` ensures ZTD CLI always points to the correct directories.
 
 ---
@@ -124,8 +187,7 @@ The file `tests/generated/ztd-layout.generated.ts` ensures ZTD CLI always points
 # Protected directories and edit ownership (important)
 
 - DDL editing is human-led: `ztd/ddl/`
-- Domain specs editing is human-led: `ztd/domain-specs/`
-- Enums editing is human-led: `ztd/enums/`
+- `ztd/ddl` is the sole human-owned directory inside `/ztd`; other directories must not be assumed or created without explicit instructions.
 - Application code is shared ownership: `src/`
 - Tests are shared ownership: `tests/`
   - Detailed test constraints live in `templates/tests/AGENTS.md`.
@@ -140,21 +202,17 @@ Additionally:
 
 ### 1. Humans own the definitions
 - Physical schema (DDL)
-- Domain semantics (domain-specs)
-- Enumerations (enums)
 - Repository interfaces
 
 ### 2. AI assists with implementation
 - Generating repository SQL
 - Updating fixtures
 - Producing intermediate TypeScript structures
-- Ensuring SQL adheres to DDL, enums, and domain-specs
+- Ensuring SQL adheres to DDL
 
 ### 3. ZTD enforces consistency
 ZTD tests verify that:
 - SQL logic matches DDL shapes
-- SQL semantics match domain-specs
-- SQL values match enumerations
 
 If anything diverges, ZTD failures surface immediately and deterministically.
 
@@ -184,11 +242,11 @@ Changing method signatures, adding new repository methods, etc.
 
 1. Modify the repository interface or implementation in `/src`.
 2. Use AI assistance to generate or update the SQL implementation.
-3. If the generated SQL conflicts with domain-specs or enums, update definitions first.
+3. If the generated SQL conflicts with DDL or other human-maintained references, update the authoritative source first.
 4. Run ZTD tests.
 5. Regenerate config if SQL output shape changed.
 
-Flow: Interface to SQL to Specs (if needed) to Tests
+Flow: Interface to SQL to Tests
 
 ---
 
@@ -197,31 +255,19 @@ Bug fixes, refactoring, rewriting queries.
 
 1. Edit SQL inside the repository.
 2. Run ZTD tests.
-3. If intended behavior changes, update the appropriate file in `ztd/domain-specs/`.
+3. If intended behavior changes, coordinate any necessary DDL updates before adjusting dependent code.
 4. Update fixtures as needed.
 5. Regenerate config if result shape changed.
 
-Flow: SQL to Domain-specs to Tests
-
----
-
-# Workflow D - Starting From Enum or Domain Specification Changes
-Business rule changes or conceptual model updates.
-
-Flow: Specs or Enums to SQL to Tests to (DDL if required)
+Flow: SQL to Tests
 
 ---
 
 # Combined Real-World Examples
 
-- Adding a new contract state:
-  enums to domain-spec to SQL to config to tests
-
-- Adding a new table:
-  DDL to config to SQL to fixtures to tests
-
-- Fixing business logic:
-  SQL to domain-spec to tests
+- Adding a new contract state: DDL to SQL to config to tests
+- Adding a new table: DDL to SQL to fixtures/tests
+- Fixing business logic: SQL to tests
 
 ZTD ensures the development always converges into a consistent, validated workflow.
 
@@ -232,8 +278,6 @@ ZTD ensures the development always converges into a consistent, validated workfl
 Humans maintain:
 
 - Schema definitions (`ztd/ddl`)
-- Domain logic definitions (`ztd/domain-specs`)
-- Domain enumerations (`ztd/enums`)
 - Repository interfaces and architectural decisions
 - Acceptance and review of AI-generated patches
 
@@ -245,12 +289,10 @@ Humans decide what is correct.
 
 AI must:
 
-- Use domain-specs as the semantic source of truth
-- Use enums as the canonical vocabulary source
-- Use DDL as the physical structure constraint
-- Generate SQL consistent with all definitions
-- Update fixtures when needed
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction
+- Use DDL as the physical structure constraint and never assume any additional `ztd` directories exist unless explicitly added.
+- Generate SQL consistent with DDL.
+- Update fixtures when needed.
+- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction.
 
 AI decides how to implement, but not what is correct.
 

package/templates/README.md

@@ -5,31 +5,28 @@ This project organizes all SQL‑related artifacts under the `ztd/` directory, s
 ```
 /ztd
   /ddl
-    *.sql            <- schema definitions
-  /domain-specs
-    *.md             <- one behavior per file (one SQL block)
-  /enums
-    *.md             <- one enum per file (one SQL block)
+    *.sql            <- schema definitions (required)
   README.md          <- documentation for the layout
-  AGENTS.md          <- combined guidance for people and agents
+  AGENTS.md          <- combined guidance for DDL
 
 /src                 <- application & repository code
 /tests               <- ZTD tests, fixtures, generated maps
 ```
 
+Only `ztd/ddl` is part of the template contract. Do not create or assume other `ztd` subdirectories unless the project explicitly adds them.
+
 ## Generated files (important)
 
 `tests/generated/` is auto-generated and must never be committed to git.
-
-After cloning the repository (or in a clean environment), run:
+After cloning the repository (or in a clean environment), run (strongly recommended):
 
 ```bash
 npx ztd ztd-config
 ```
 
-If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `npx ztd ztd-config`.
+If TypeScript reports missing modules or type errors because `tests/generated/` is missing, rerun `npx ztd ztd-config`.
 
-`tests/generated/ztd-layout.generated.ts` declares the directories above so the CLI and your tests always point at the correct files.
+`tests/generated/ztd-layout.generated.ts` declares the directories above so the CLI and your tests always point at the intended files. The authoritative directory remains `ztd/ddl/`; do not read or assume additional `ztd` subdirectories.
 
 ---
 
@@ -60,12 +57,21 @@ export function getSqlClient(): SqlClient {
 
 ---
 
+# Mapper + writer sample
+
+- This scaffold already exposes `src/repositories/user-accounts.ts`, which maps `public.user_account` rows together with optional `public.user_profile` data through `@rawsql-ts/sql-contract/mapper` and emits insert/update/remove helpers via `@rawsql-ts/sql-contract/writer`.
+- The SQL used here is defined in `src/repositories/user-accounts.ts`; the template tests exercise that implementation and `ztd/ddl` is the authoritative source for every column and constraint.
+- Two template tests demonstrate how to run the stitch:
+  - `tests/user-profiles.test.ts` seeds fixtures, executes the query through the mapper, and verifies the DTO shape.
+  - `tests/writer-constraints.test.ts` reads `userAccountWriterColumnSets` plus `tests/generated/ztd-row-map.generated.ts` so writer callers stay within the approved column set when referencing `public.user_account`.
+- Regenerate `tests/generated/ztd-row-map.generated.ts` (`npx ztd ztd-config`) before running the example tests so the row map reflects any schema changes.
+- The example tests require a real PostgreSQL connection via `DATABASE_URL`; they automatically skip when the variable is missing so local tooling stays fast.
+
 # Principles
 
 ### 1. Humans own the *definitions*
 - DDL (physical schema)
-- Domain specifications (business logic -> SQL semantics)
-- Enums (canonical domain values)
+  Only `ztd/ddl` is part of the template contract; other subdirectories should not be assumed.
 
 ### 2. AI owns the *implementation*
 - Repository SQL generation
@@ -75,9 +81,8 @@ export function getSqlClient(): SqlClient {
 
 ### 3. ZTD ensures these stay in sync
 ZTD acts as the consistency layer ensuring:
-- DDL ↔ SQL shape consistency
-- domain-specs ↔ query logic consistency
-- enums ↔ code‑level constants consistency
+- DDL → SQL shape consistency
+- Do not rely on other directories unless the project explicitly adds them.
 
 If any part diverges, ZTD tests fail deterministically.
 
@@ -115,22 +120,22 @@ Different tasks start from different entry points. Choose the workflow that matc
 
 1. Modify the repository interface or class in `/src`.
 2. Allow AI to generate the SQL needed to satisfy the interface.
-3. If the query contradicts domain-specs or enums, update specs first.
+3. If the query contradicts DDL, reconcile the authoritative definition before continuing.
 4. Run ZTD tests to confirm logic is consistent.
 5. Regenerate ZTD config if result shapes changed.
 
 **Flow:**  
-**repository interface -> SQL -> (update specs if needed) -> tests**
+**repository interface -> SQL -> tests**
 
 ---
 
-# Workflow C — Starting From *Repository SQL Logic Changes*  
+# Workflow C — Starting From Repository SQL Logic Changes
 (Fixing a bug, optimizing logic, rewriting a query)
 
 1. Edit SQL inside the repository.
-2. Run existing ZTD tests.
-3. If the intended behavior changes, update `ztd/domain-specs/`.
-4. Update fixtures if necessary.
+2. Run ZTD tests.
+3. If the intended behavior changes, update the DDL before adjusting dependent logic and keep documentation aligned with the confirmed schema.
+4. Update fixtures as necessary.
 5. If SQL result shape changed, run:
 
    ```bash
@@ -138,62 +143,30 @@ Different tasks start from different entry points. Choose the workflow that matc
    ```
 
 **Flow:**  
-**SQL -> domain-specs (if needed) -> fixtures/tests**
-
----
-
-# Workflow D — Starting From *Enums or Domain Spec Changes*  
-(Business rules change, new status added, new definition created)
-
-## For enums:
-
-1. Update the relevant `.md` file under `ztd/enums/`.
-2. Regenerate row-map:
-
-   ```bash
-   npx ztd ztd-config
-   ```
-
-3. Update SQL referencing enum values.
-4. Update domain-specs or repository SQL if behaviors change.
-5. Update fixtures and tests.
-
-## For domain-specs:
-
-1. Modify the `.md` spec in `ztd/domain-specs/`.
-2. Update SQL in `/src` to follow the new semantics.
-3. Update tests and fixtures.
-4. Update DDL only if the new behavior requires schema changes.
-
-**Flow:**  
-**spec/enums -> SQL -> tests -> (DDL if required)**
+**SQL -> fixtures/tests**
 
 ---
 
 # Combined Real‑World Flow Examples
 
 - **Add a new contract status**  
-  enums -> domain-spec -> SQL -> config -> tests
+  DDL -> SQL -> config -> tests
 
 - **Add a new table**  
   DDL -> config -> SQL -> fixtures -> tests
 
 - **Fix business logic**  
-  SQL -> domain-spec -> tests
-
-ZTD ensures all changes converge into the same consistency pipeline.
+  SQL -> tests
 
+ZTD ensures all changes converge into a consistent, validated workflow.
 ---
 
 # Human Responsibilities
 
-Humans maintain:
-
-- Business logic definitions (`domain-specs`)
-- Physical schema (`ddl`)
-- Domain vocabularies (`enums`)
-- High‑level repository interfaces
-- Acceptance of AI-generated changes
+- Humans maintain:
+  - Physical schema (`ddl`)
+  - High‑level repository interfaces
+  - Acceptance of AI-generated changes
 
 Humans decide “what is correct.”
 
@@ -203,12 +176,11 @@ Humans decide “what is correct.”
 
 AI must:
 
-- Use domain-specs as the **semantic source of truth**
-- Use enums as the **canonical vocabulary source**
-- Use DDL as the **physical shape constraint**
-- Generate repository SQL consistent with all three
-- Regenerate fixtures and tests as instructed
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` unless explicitly asked
+  - Use DDL as the **physical shape constraint** and primary source of truth.
+  - Do not assume any additional `ztd` directories exist unless a human explicitly creates them.
+  - Generate repository SQL consistent with DDL and the documented behavior.
+  - Regenerate fixtures and tests as instructed.
+  - Never modify `ztd/AGENTS.md` or `ztd/README.md` unless explicitly asked.
 
 AI decides “how to implement” within those constraints.
 
@@ -237,3 +209,9 @@ ZTD is the verification engine guaranteeing correctness.
 ZTD enables a workflow where **humans define meaning**, **AI writes implementation**, and **tests guarantee correctness**.
 
 The project layout and workflows above ensure long-term maintainability, clarity, and full reproducibility of SQL logic independent of physical database state.
+
+## Recommended local verification
+
+- `npx ztd ztd-config` (Recommended)
+- `pnpm -C packages/ztd-cli test` (Recommended)
+- `templates/tests/user-profiles.test.ts` runs only when `DATABASE_URL` is configured; otherwise it skips automatically.

package/templates/dist/drivers/pg-testkit/src/driver/PgTestkitClient.d.ts

@@ -0,0 +1,38 @@
+import type { QueryResult, QueryResultRow } from 'pg';
+import type { CreatePgTestkitClientOptions, PgQueryInput, PgQueryable, TableRowsFixture } from '../types';
+/**
+ * Lightweight client that rewrites CRUD/SELECT statements into fixture-backed SELECTs
+ * and delegates execution to a real `pg` connection.
+ *
+ * Consumers can use this in place of `pg.Client` during tests; production code can stay
+ * unaware of pg-testkit as long as it relies on the standard `query` API.
+ */
+export declare class PgTestkitClient {
+    private readonly options;
+    private readonly scopedRows?;
+    private connection?;
+    private readonly rewriter;
+    private readonly tableNameResolver;
+    constructor(options: CreatePgTestkitClientOptions, scopedRows?: TableRowsFixture[] | undefined, seedConnection?: PgQueryable);
+    /**
+     * Executes SQL after rewriting it to use fixture-backed CTEs. CRUD statements are converted
+     * to result-producing SELECTs; unsupported DDL is ignored.
+     *
+     * @param textOrConfig SQL text or pg QueryConfig
+     * @param values Optional positional parameters
+     * @returns pg-style QueryResult with rows simulated from fixtures
+     */
+    query<T extends QueryResultRow = QueryResultRow>(textOrConfig: PgQueryInput, values?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Derives a scoped client that overlays additional fixtures while reusing the same connection.
+     */
+    withFixtures(fixtures: TableRowsFixture[]): PgTestkitClient;
+    /**
+     * Disposes the underlying connection or returns it to the pool if `release` is available.
+     */
+    close(): Promise<void>;
+    private getConnection;
+    private buildEmptyResult;
+}
+/** Factory that instantiates a `PgTestkitClient` with the provided fixture-driven options. */
+export declare const createPgTestkitClient: (options: CreatePgTestkitClientOptions) => PgTestkitClient;