schematic-pg 0.1.8 → 0.1.11

package/dist/cli/templates/agents.md

@@ -0,0 +1,290 @@
+# schematic-pg Agent Guide
+
+Instructions for AI agents working in a schematic-pg project.
+
+## Overview
+
+schematic-pg is a single-file backend framework for PostgreSQL and Node.js. **`app.schema` is the single source of truth** — it drives SQL DDL, the type-safe DB client, REST API routes, Zod validators, and ACL policies.
+
+- One declarative schema file replaces scattered migrations, ORM models, and route handlers.
+- Generated code uses parameterized raw SQL (no ORM).
+- Framework runtime lives in `node_modules/schematic-pg` — it is not copied into your project.
+
+## Golden Rules
+
+1. **Never edit `generated/`** — it is overwritten on every `generate` / `dev` run.
+2. **Regenerate after changes** to `app.schema`, `src/routes/`, or `src/hooks/` (`schematic-pg generate` or `schematic-pg dev`).
+3. **Edit `app.schema`** for models, relations, policies, indexes, and triggers.
+4. **Use extension points** for app-specific logic: `src/routes/` (custom HTTP) and `src/hooks/` (lifecycle hooks).
+5. **Do not hand-write SQL** for CRUD — use the generated DB client or REST API.
+
+## Project Layout
+
+```
+my-app/
+├── app.schema              # Source of truth — edit this
+├── schema.sql              # Generated PostgreSQL DDL (read-only)
+├── AGENTS.md               # This file
+├── .env                    # DATABASE_URL, JWT_* settings
+├── docker-compose.yml      # Local PostgreSQL
+├── generated/              # Generated — do not edit
+│   ├── db.ts               # createDbClient(pool)
+│   ├── db-types.ts         # Model interfaces
+│   ├── app.ts              # Hono server entry point
+│   ├── routes/*.ts         # CRUD routers per model
+│   ├── policies.ts         # ACL from @policy
+│   └── schemas/validation.ts
+└── src/
+    ├── routes/             # Custom Hono routers (hand-written)
+    └── hooks/              # Lifecycle hooks (hand-written)
+```
+
+## Dev Workflow
+
+```bash
+make dev
+# or:
+docker compose up -d --wait
+npx schematic-pg dev
+```
+
+`dev` runs: generate → db:bootstrap → start server → watch `app.schema`.
+
+**Environment variables** (`.env`):
+
+| Variable | Purpose |
+|----------|---------|
+| `DATABASE_URL` | PostgreSQL connection string (required) |
+| `PORT` | HTTP port (default `3000`) |
+| `JWT_SECRET` | HMAC secret for Bearer JWT auth |
+| `JWT_ROLE_CLAIM` | JWT claim for role (default `role`) |
+| `JWT_USER_ID_CLAIM` | JWT claim for user id (default `sub`) |
+
+## Schema DSL Essentials
+
+```ts
+extensions { pgcrypto; uuid-ossp }
+
+enums {
+  UserRole { ADMIN, USER, PUBLIC }
+}
+
+models {
+  model User {
+    id:    UUID @id @default(gen_random_uuid())
+    email: VARCHAR(255) @unique
+    role:  UserRole @default(USER)
+
+    orders: Order[]
+
+    @policy(role: USER, allow: [select, update], where: "id = {{auth.user.id}}")
+    @policy(role: ADMIN, allow: all)
+
+    @@index(fields: [role])
+  }
+
+  model Order {
+    userId: UUID
+    user:   User @relation(fields: [userId], references: [id])
+  }
+}
+```
+
+**Key concepts:**
+
+- **Relations:** Put `@relation(fields: [...], references: [...])` on the FK-owning side. The inverse side is inferred.
+- **Policies:** `@policy(role: ..., allow: [select|insert|update|delete|all], where: "...")` — `where` supports `{{auth.user.id}}`.
+- **Validation:** `@regex(...)`, `@range(min: ..., max: ...)` flow into generated Zod schemas.
+- **Indexes / triggers:** `@@index(...)`, `@@trigger { timing, event, level, execute: """...""" }`.
+
+## Database Client
+
+Generated by `schematic-pg generate:client` (or `generate` / `dev`). Prisma-like API over parameterized SQL.
+
+**Key files:** `generated/db.ts`, `generated/db-types.ts` (do not edit).
+
+### How to Get `db`
+
+| Context | Access |
+|---------|--------|
+| Standalone script / test | `createDbClient(pool)` |
+| Custom route (`src/routes/*.ts`) | `c.get('db')` |
+| Lifecycle hook (`src/hooks/{Model}.ts`) | `ctx.db` |
+
+```typescript
+import { Pool } from 'pg';
+import { createDbClient } from './generated/db.js';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const db = createDbClient(pool);
+```
+
+**Model naming:** `User` → `db.user`, `ProductOrder` → `db.productOrder`. API fields are camelCase; SQL columns are snake_case (automatic mapping).
+
+### Per-Model Methods
+
+| Method | Notes |
+|--------|-------|
+| `create(data)` | Returns inserted row |
+| `findUnique(where, opts?)` | Single row by PK/unique; supports `include` |
+| `findFirst({ where, orderBy, include, … })` | First match |
+| `findMany({ where, orderBy, take, skip, include, … })` | List + pagination |
+| `count({ where })` | No `include` |
+| `update({ where, data })` | Returns updated row |
+| `updateMany({ where, data })` | Returns `{ count }` |
+| `delete(where)` / `deleteMany({ where })` | Returns deleted row(s) or count |
+
+### Basic Querying
+
+```typescript
+// Create
+await db.user.create({ email: 'a@b.com', name: 'Alice' });
+
+// Read
+await db.user.findUnique({ id });
+await db.user.findFirst({ where: { role: 'ADMIN' }, orderBy: { createdAt: 'desc' } });
+await db.user.findMany({ where: { isActive: true }, take: 10, skip: 0 });
+await db.user.count({ where: { role: 'ADMIN' } });
+
+// Update / delete
+await db.user.update({ where: { id }, data: { name: 'Bob' } });
+await db.user.delete({ id });
+```
+
+### Where Filters
+
+- Shorthand equality: `{ email: 'a@b.com' }`
+- Operators: `equals`, `contains`, `startsWith`, `endsWith`, `gt`, `gte`, `lt`, `lte`, `in`
+- Logical groups: `AND`, `OR`, `NOT`
+
+```typescript
+await db.user.findMany({
+  where: {
+    AND: [{ role: { in: ['ADMIN', 'USER'] } }, { isActive: true }],
+    NOT: { email: { contains: 'spam' } },
+  },
+});
+```
+
+### Eager Loading (`include`)
+
+Available on `findUnique`, `findFirst`, `findMany` — not on `count`. Use relation **field names** from the schema (`profile`, `orders`).
+
+```typescript
+await db.user.findMany({
+  include: {
+    profile: true,
+    orders: {
+      where: { status: 'PENDING' },
+      orderBy: { createdAt: 'desc' },
+      take: 5,
+      include: { products: { include: { product: true } } },
+    },
+  },
+});
+```
+
+Default strategy is split queries (avoids cartesian explosion). Pass `relationLoadStrategy: 'join'` for fewer round trips.
+
+### Types
+
+Import from `generated/db-types.js`: `{Model}`, `{Model}CreateInput`, `{Model}UpdateInput`, `{Model}WhereInput`, `{Model}Include`.
+
+- Fields with `@default` / auto-generated `@id` are optional on create input.
+- `DECIMAL` maps to `string`; optional fields are `T | null`.
+
+### Errors
+
+```typescript
+import { UniqueConstraintError } from 'schematic-pg/db/errors';
+
+try {
+  await db.user.create({ email: 'taken@b.com', name: 'X' });
+} catch (error) {
+  if (error instanceof UniqueConstraintError) {
+    console.log(error.fields); // ['email']
+  }
+}
+```
+
+Also available: `ForeignKeyConstraintError`, `DatabaseError`.
+
+### DB Access Rules
+
+- Prefer `ctx.db` / `c.get('db')` in routes and hooks — do not create ad-hoc pools.
+- Run `generate` (or `dev`) after schema changes before querying new models or fields.
+- Use generated `{Model}WhereInput` types — do not hand-build SQL strings.
+- Use `ctx.db` in `afterCreate` / `afterUpdate` / `afterDelete` for side effects (audit logs, related rows).
+
+## Extension Points
+
+### Custom Routes (`src/routes/`)
+
+| Rule | Example |
+|------|---------|
+| Location | `src/routes/**/*.ts` |
+| Export | `export default router` (`Hono<AppEnv>`) |
+| Mount path | File path relative to `src/routes/` |
+
+`src/routes/health.ts` → `GET /health`. Regenerate after adding files.
+
+```typescript
+import { Hono } from 'hono';
+import type { AppEnv } from 'schematic-pg/api/types';
+
+const router = new Hono<AppEnv>();
+
+router.get('/me', async (c) => {
+  const db = c.get('db');
+  const auth = c.get('auth');
+  // ...
+});
+
+export default router;
+```
+
+### Lifecycle Hooks (`src/hooks/`)
+
+| Rule | Example |
+|------|---------|
+| Location | `src/hooks/{Model}.ts` (PascalCase) |
+| Export | `export default defineHooks(...)` |
+| Scaffold | `schematic-pg hooks:add --model User` |
+
+Flow: `validate → assertPolicy → beforeHooks → db op → afterHooks → response`.
+
+- `await next()` to proceed; `return ctx.abort(status, msg)` to cancel.
+- `ctx.data` — mutable create/update payload (before hooks).
+- `ctx.result` — DB row (after hooks).
+- `ctx.db`, `ctx.auth` — available in all hooks.
+
+## CLI Cheat Sheet
+
+```bash
+schematic-pg generate              # schema.sql + db client + API
+schematic-pg dev [--no-watch]      # generate + bootstrap + server + watch
+schematic-pg start [--no-migrate]  # production: migrate + run server
+schematic-pg db:bootstrap            # first-time DDL apply
+schematic-pg db:diff [--name label]  # print or write migration
+schematic-pg db:migrate              # apply pending migrations
+schematic-pg hooks:add [--model X]   # scaffold src/hooks/{Model}.ts
+```
+
+## Auth & ACL
+
+- Models **without** `@policy` are open (no ACL checks).
+- Unauthenticated requests default to `{ role: 'PUBLIC' }`.
+- `@policy` `allow` maps to HTTP: GET→select, POST→insert, PUT→update, DELETE→delete.
+- Row-level `where` is injected on read/update/delete; POST checks permission only.
+
+## Generated Outputs (Read-Only)
+
+| Output | Purpose |
+|--------|---------|
+| `schema.sql` | Idempotent PostgreSQL DDL |
+| `generated/db.ts` | `createDbClient(pool)` |
+| `generated/db-types.ts` | TypeScript interfaces |
+| `generated/app.ts` | Hono server entry point |
+| `generated/routes/*.ts` | CRUD routers |
+| `generated/policies.ts` | ACL metadata |
+| `generated/schemas/validation.ts` | Zod validators |

package/dist/cli/templates.d.ts

@@ -1,9 +1,11 @@
-export declare const APP_SCHEMA_TEMPLATE = "extensions {\n\n}\n\nenums {\n\n}\n\nmodels {\n  model User {\n    id:        UUID        @id @default(gen_random_uuid())\n    email:     VARCHAR(255) @unique\n    name:      VARCHAR(150)\n    createdAt: TIMESTAMP   @default(now())\n  }\n}\n";
-export declare const ENV_TEMPLATE = "DATABASE_URL=postgresql://postgrest:postgrest@localhost:5432/postgrest\nJWT_SECRET=\nJWT_ROLE_CLAIM=role\nJWT_USER_ID_CLAIM=sub\n";
+export declare const AGENTS_TEMPLATE: string;
+export declare const APP_SCHEMA_TEMPLATE = "extensions {\n\n}\n\nenums {\n  UserRole { ADMIN, USER }\n}\n\nmodels {\n  model User {\n    id:           UUID         @id @default(gen_random_uuid())\n    email:        VARCHAR(255) @unique\n    name:         VARCHAR(150)?\n    role:         UserRole     @default(USER)\n    passwordHash: VARCHAR(255)? @omit @unfilterable\n    createdAt:    TIMESTAMP    @default(now())\n\n    @policy(role: USER, allow: [select, update], where: \"id = {{auth.user.id}}\")\n    @policy(role: ADMIN, allow: all)\n  }\n}\n";
+export declare const ENV_TEMPLATE = "DATABASE_URL=postgresql://postgrest:postgrest@localhost:5432/postgrest\nJWT_SECRET=\nAUTH_PEPPER=\nAUTH_ACCESS_TOKEN_TTL=1h\nJWT_ROLE_CLAIM=role\nJWT_USER_ID_CLAIM=sub\n";
 export declare const GITIGNORE_TEMPLATE = "node_modules/\ndist/\n.env\ndocker_data/\n.DS_Store\n*.log\nnpm-debug.log*\n";
-export declare const DOCKER_COMPOSE_TEMPLATE = "services:\n  postgres:\n    image: postgis/postgis:16-3.4\n    container_name: schematic-pg\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgrest\n      POSTGRES_PASSWORD: postgrest\n      POSTGRES_DB: postgrest\n    volumes:\n      - ./docker_data/postgres:/var/lib/postgresql/data\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgrest -d postgrest\"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n";
+export declare const DOCKER_COMPOSE_TEMPLATE = "services:\n  postgres:\n    image: postgres:18.4-bookworm\n    container_name: schematic-pg\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgrest\n      POSTGRES_PASSWORD: postgrest\n      POSTGRES_DB: postgrest\n    volumes:\n      - ./docker_data/postgres:/var/lib/postgresql/data\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgrest -d postgrest\"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n";
 export declare const TSCONFIG_TEMPLATE = "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"NodeNext\",\n    \"moduleResolution\": \"NodeNext\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"outDir\": \"dist\",\n    \"rootDir\": \".\"\n  },\n  \"include\": [\"generated/**/*\", \"src/**/*\"]\n}\n";
 export declare const MAKEFILE_TEMPLATE = ".PHONY: dev\n\ndev:\n\tdocker compose up -d --wait\n\tnpx schematic-pg dev\n";
 export declare const HEALTH_ROUTE_TEMPLATE = "import { Hono } from 'hono';\nimport type { AppEnv } from 'schematic-pg/api/types';\n\nconst router = new Hono<AppEnv>();\nrouter.get('/', (c) => c.json({ ok: true }));\nexport default router;\n";
+export declare const AUTH_ROUTE_TEMPLATE = "import { createAuthRouter } from 'schematic-pg/api/auth/routes';\n\nexport default createAuthRouter();\n";
 export declare function createPackageJsonTemplate(projectName: string): string;
 export declare function createHookFileTemplate(modelName: string): string;

package/dist/cli/templates.js

@@ -1,23 +1,35 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
 import { PACKAGE_NAME, PACKAGE_VERSION } from '../constants.js';
+const templatesDir = path.dirname(fileURLToPath(import.meta.url));
+export const AGENTS_TEMPLATE = readFileSync(path.join(templatesDir, 'templates', 'agents.md'), 'utf8');
 export const APP_SCHEMA_TEMPLATE = `extensions {
 
 }
 
 enums {
-
+  UserRole { ADMIN, USER }
 }
 
 models {
   model User {
-    id:        UUID        @id @default(gen_random_uuid())
-    email:     VARCHAR(255) @unique
-    name:      VARCHAR(150)
-    createdAt: TIMESTAMP   @default(now())
+    id:           UUID         @id @default(gen_random_uuid())
+    email:        VARCHAR(255) @unique
+    name:         VARCHAR(150)?
+    role:         UserRole     @default(USER)
+    passwordHash: VARCHAR(255)? @omit @unfilterable
+    createdAt:    TIMESTAMP    @default(now())
+
+    @policy(role: USER, allow: [select, update], where: "id = {{auth.user.id}}")
+    @policy(role: ADMIN, allow: all)
   }
 }
 `;
 export const ENV_TEMPLATE = `DATABASE_URL=postgresql://postgrest:postgrest@localhost:5432/postgrest
 JWT_SECRET=
+AUTH_PEPPER=
+AUTH_ACCESS_TOKEN_TTL=1h
 JWT_ROLE_CLAIM=role
 JWT_USER_ID_CLAIM=sub
 `;
@@ -31,7 +43,7 @@ npm-debug.log*
 `;
 export const DOCKER_COMPOSE_TEMPLATE = `services:
   postgres:
-    image: postgis/postgis:16-3.4
+    image: postgres:18.4-bookworm
     container_name: schematic-pg
     restart: unless-stopped
     ports:
@@ -75,6 +87,10 @@ const router = new Hono<AppEnv>();
 router.get('/', (c) => c.json({ ok: true }));
 export default router;
 `;
+export const AUTH_ROUTE_TEMPLATE = `import { createAuthRouter } from '${PACKAGE_NAME}/api/auth/routes';
+
+export default createAuthRouter();
+`;
 export function createPackageJsonTemplate(projectName) {
     return JSON.stringify({
         name: projectName,

package/dist/cli/wait-for-database.js

@@ -8,7 +8,7 @@ export async function pingDatabase(client) {
 }
 export async function waitForDatabase(options = {}) {
     const maxAttempts = options.maxAttempts ?? 30;
-    const intervalMs = options.intervalMs ?? 1000;
+    const intervalMs = options.intervalMs ?? 3000;
     const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const ownClient = options.client ? null : new DatabaseClient();
     const client = options.client ?? ownClient;

package/dist/db/db-client-generator.js

@@ -31,10 +31,13 @@ export class DbClientGenerator {
             "import type { Pool } from 'pg';",
             `import { createModelClient } from '${PACKAGE_NAME}/db/model-client';`,
             `import { hydrateModelMeta } from '${PACKAGE_NAME}/db/model-meta';`,
+            `import type { Queryable } from '${PACKAGE_NAME}/db/queryable';`,
+            `import { createRawClient } from '${PACKAGE_NAME}/db/raw';`,
+            `import { runInTransaction } from '${PACKAGE_NAME}/db/transaction';`,
             `import type {\n  ${imports},\n} from './db-types.js';`,
             `import {\n  ${this.schema.models.map((model) => `${getClientExportName(model.name)}ModelMeta`).join(',\n  ')},\n} from './db-model-meta.js';`,
             '',
-            'export function createDbClient(pool: Pool) {',
+            'function buildModels(executor: Queryable) {',
             ...metaHydrations,
             `  const modelRegistry = new Map([`,
             ...registryEntries.map((entry) => `    ${entry},`),
@@ -42,6 +45,21 @@ export class DbClientGenerator {
             '',
             '  return {',
             clientEntries.map((entry) => `    ${entry},`).join('\n'),
+            '    ...createRawClient(executor),',
+            '  };',
+            '}',
+            '',
+            '/** All model clients scoped to a single transaction. Nested `$transaction` is unsupported. */',
+            'export type TxClient = ReturnType<typeof buildModels>;',
+            '',
+            'export function createDbClient(pool: Pool) {',
+            '  async function $transaction<T>(fn: (tx: TxClient) => Promise<T>): Promise<T> {',
+            '    return runInTransaction(pool, (client) => fn(buildModels(client)));',
+            '  }',
+            '',
+            '  return {',
+            '    ...buildModels(pool),',
+            '    $transaction,',
             '  };',
             '}',
             '',
@@ -65,7 +83,7 @@ export class DbClientGenerator {
     }
     generateClientEntry(modelName) {
         const clientKey = getClientExportName(modelName);
-        return `${clientKey}: createModelClient<${modelName}, ${modelName}CreateInput, ${modelName}UpdateInput, ${modelName}WhereInput, ${modelName}OrderByInput>(${clientKey}Meta, pool, modelRegistry)`;
+        return `${clientKey}: createModelClient<${modelName}, ${modelName}CreateInput, ${modelName}UpdateInput, ${modelName}WhereInput, ${modelName}OrderByInput>(${clientKey}Meta, executor, modelRegistry)`;
     }
 }
 export function generateDbClientFiles(schema) {

package/dist/db/include/executor.d.ts

@@ -1,3 +1,3 @@
-import type { Pool } from 'pg';
+import type { Queryable } from '../queryable.js';
 import type { LoadNode } from './planner.js';
-export declare function loadIncludes(parentRows: Record<string, unknown>[], plan: LoadNode, pool: Pool): Promise<void>;
+export declare function loadIncludes(parentRows: Record<string, unknown>[], plan: LoadNode, executor: Queryable): Promise<void>;

package/dist/db/include/executor.js

@@ -2,7 +2,7 @@ import { mapPgError } from '../errors.js';
 import { mapRows } from '../row-mapper.js';
 import { WhereTranslator } from '../where-translator.js';
 import { dedupeKeys, extractParentKeys, stitch } from './hydrator.js';
-export async function loadIncludes(parentRows, plan, pool) {
+export async function loadIncludes(parentRows, plan, executor) {
     for (const childPlan of plan.children) {
         const relation = childPlan.relation;
         if (!relation) {
@@ -13,8 +13,8 @@ export async function loadIncludes(parentRows, plan, pool) {
             assignEmptyRelation(parentRows, relation);
             continue;
         }
-        const childRows = await fetchRelationRows(childPlan, parentKeys, pool);
-        await loadIncludes(childRows, childPlan, pool);
+        const childRows = await fetchRelationRows(childPlan, parentKeys, executor);
+        await loadIncludes(childRows, childPlan, executor);
         stitch(parentRows, childRows, relation);
     }
 }
@@ -23,13 +23,13 @@ function assignEmptyRelation(parentRows, relation) {
         parent[relation.name] = relation.unique ? null : [];
     }
 }
-async function fetchRelationRows(node, parentKeys, pool) {
+async function fetchRelationRows(node, parentKeys, executor) {
     const relation = node.relation;
     if (!relation) {
         return [];
     }
     const query = buildRelationSelect(node, parentKeys);
-    const rows = await executeQuery(pool, query.sql, query.params, node.model);
+    const rows = await executeQuery(executor, query.sql, query.params, node.model);
     return mapRows(rows, node.model);
 }
 function buildRelationSelect(node, parentKeys) {
@@ -79,9 +79,9 @@ function buildOrderByClause(plan) {
     }
     return parts.length > 0 ? `ORDER BY ${parts.join(', ')}` : '';
 }
-async function executeQuery(pool, sql, params, model) {
+async function executeQuery(executor, sql, params, model) {
     try {
-        const result = await pool.query(sql, params);
+        const result = await executor.query(sql, params);
         return result.rows;
     }
     catch (error) {

package/dist/db/include/json-agg.d.ts

@@ -1,5 +1,5 @@
-import type { Pool } from 'pg';
 import type { ModelMeta } from '../model-meta.js';
 import type { FindArgs } from '../query-builder.js';
+import type { Queryable } from '../queryable.js';
 import type { LoadNode } from './planner.js';
-export declare function fetchRootWithJsonAgg<T extends Record<string, unknown>>(model: ModelMeta, plan: LoadNode, args: FindArgs, pool: Pool): Promise<T[]>;
+export declare function fetchRootWithJsonAgg<T extends Record<string, unknown>>(model: ModelMeta, plan: LoadNode, args: FindArgs, executor: Queryable): Promise<T[]>;

package/dist/db/include/json-agg.js

@@ -2,9 +2,9 @@ import { mapPgError } from '../errors.js';
 import { QueryBuilder } from '../query-builder.js';
 import { mapRow } from '../row-mapper.js';
 const ROOT_ALIAS = 'root';
-export async function fetchRootWithJsonAgg(model, plan, args, pool) {
+export async function fetchRootWithJsonAgg(model, plan, args, executor) {
     const query = buildJsonAggRootQuery(model, plan, args);
-    const rows = await executeQuery(pool, query.sql, query.params, model);
+    const rows = await executeQuery(executor, query.sql, query.params, model);
     return rows.map((row) => hydrateJsonAggRow(row, model, plan));
 }
 function buildJsonAggRootQuery(model, plan, args) {
@@ -90,9 +90,9 @@ function hydrateJsonObject(value, plan) {
     }
     return mapped;
 }
-async function executeQuery(pool, sql, params, model) {
+async function executeQuery(executor, sql, params, model) {
     try {
-        const result = await pool.query(sql, params);
+        const result = await executor.query(sql, params);
         return result.rows;
     }
     catch (error) {

package/dist/db/include/load.d.ts

@@ -1,8 +1,8 @@
-import type { Pool } from 'pg';
 import type { ModelMeta } from '../model-meta.js';
 import type { FindArgs } from '../query-builder.js';
+import type { Queryable } from '../queryable.js';
 import type { IncludeInput, IncludeOptions } from './types.js';
-export declare function fetchWithIncludes<T extends Record<string, unknown>>(model: ModelMeta, registry: Map<string, ModelMeta>, pool: Pool, rootArgs: FindArgs & {
+export declare function fetchWithIncludes<T extends Record<string, unknown>>(model: ModelMeta, registry: Map<string, ModelMeta>, executor: Queryable, rootArgs: FindArgs & {
     include?: IncludeInput;
 }, options?: IncludeOptions): Promise<T[]>;
-export declare function attachIncludes<T extends Record<string, unknown>>(model: ModelMeta, registry: Map<string, ModelMeta>, pool: Pool, rootRows: T[], include: IncludeInput, rootArgs: FindArgs, options?: IncludeOptions): Promise<T[]>;
+export declare function attachIncludes<T extends Record<string, unknown>>(model: ModelMeta, registry: Map<string, ModelMeta>, executor: Queryable, rootRows: T[], include: IncludeInput, rootArgs: FindArgs, options?: IncludeOptions): Promise<T[]>;

package/dist/db/include/load.js

@@ -4,7 +4,7 @@ import { mapRows } from '../row-mapper.js';
 import { loadIncludes } from './executor.js';
 import { fetchRootWithJsonAgg } from './json-agg.js';
 import { buildLoadPlan } from './planner.js';
-export async function fetchWithIncludes(model, registry, pool, rootArgs, options = {}) {
+export async function fetchWithIncludes(model, registry, executor, rootArgs, options = {}) {
     if (!rootArgs.include) {
         throw new Error('fetchWithIncludes requires include');
     }
@@ -14,14 +14,14 @@ export async function fetchWithIncludes(model, registry, pool, rootArgs, options
     plan.take = rootArgs.take;
     plan.skip = rootArgs.skip;
     if (plan.strategy === 'join') {
-        return fetchRootWithJsonAgg(model, plan, rootArgs, pool);
+        return fetchRootWithJsonAgg(model, plan, rootArgs, executor);
     }
-    const rows = await executeRootSelect(model, pool, rootArgs);
+    const rows = await executeRootSelect(model, executor, rootArgs);
     const mapped = mapRows(rows, model);
-    await loadIncludes(mapped, plan, pool);
+    await loadIncludes(mapped, plan, executor);
     return mapped;
 }
-export async function attachIncludes(model, registry, pool, rootRows, include, rootArgs, options = {}) {
+export async function attachIncludes(model, registry, executor, rootRows, include, rootArgs, options = {}) {
     if (rootRows.length === 0) {
         return rootRows;
     }
@@ -30,14 +30,14 @@ export async function attachIncludes(model, registry, pool, rootRows, include, r
     plan.orderBy = rootArgs.orderBy;
     plan.take = rootArgs.take;
     plan.skip = rootArgs.skip;
-    await loadIncludes(rootRows, plan, pool);
+    await loadIncludes(rootRows, plan, executor);
     return rootRows;
 }
-async function executeRootSelect(model, pool, args) {
+async function executeRootSelect(model, executor, args) {
     const builder = new QueryBuilder(model);
     const query = builder.select(args);
     try {
-        const result = await pool.query(query.sql, query.params);
+        const result = await executor.query(query.sql, query.params);
         return result.rows;
     }
     catch (error) {

package/dist/db/index.d.ts

@@ -4,6 +4,10 @@ export { getDatabaseUrl } from './config.js';
 export { QueryBuilder } from './query-builder.js';
 export { WhereTranslator } from './where-translator.js';
 export { createModelClient } from './model-client.js';
+export type { Queryable } from './queryable.js';
+export { createRawClient } from './raw.js';
+export type { RawClient } from './raw.js';
+export { runInTransaction } from './transaction.js';
 export { TypeGenerator, generateDbTypes } from './type-generator.js';
 export { DbClientGenerator, generateDbClientFiles } from './db-client-generator.js';
 export { buildModelMeta, buildModelMetaSnapshot, hydrateModelMeta } from './model-meta.js';

package/dist/db/index.js

@@ -4,6 +4,8 @@ export { getDatabaseUrl } from './config.js';
 export { QueryBuilder } from './query-builder.js';
 export { WhereTranslator } from './where-translator.js';
 export { createModelClient } from './model-client.js';
+export { createRawClient } from './raw.js';
+export { runInTransaction } from './transaction.js';
 export { TypeGenerator, generateDbTypes } from './type-generator.js';
 export { DbClientGenerator, generateDbClientFiles } from './db-client-generator.js';
 export { buildModelMeta, buildModelMetaSnapshot, hydrateModelMeta } from './model-meta.js';

package/dist/db/model-client.d.ts

@@ -1,6 +1,6 @@
-import type { Pool } from 'pg';
 import type { IncludeInput, IncludeOptions } from './include/types.js';
 import type { ModelMeta } from './model-meta.js';
+import type { Queryable } from './queryable.js';
 export type ModelRegistry = Map<string, ModelMeta>;
 export interface SelectArgs<TWhere, TOrderBy> {
     where?: TWhere;
@@ -35,4 +35,4 @@ export interface ModelClient<T, TCreate, TUpdate, TWhere, TOrderBy> {
         count: number;
     }>;
 }
-export declare function createModelClient<T, TCreate, TUpdate, TWhere, TOrderBy>(model: ModelMeta, pool: Pool, registry?: ModelRegistry): ModelClient<T, TCreate, TUpdate, TWhere, TOrderBy>;
+export declare function createModelClient<T, TCreate, TUpdate, TWhere, TOrderBy>(model: ModelMeta, executor: Queryable, registry?: ModelRegistry): ModelClient<T, TCreate, TUpdate, TWhere, TOrderBy>;

package/dist/db/model-client.js

@@ -2,11 +2,11 @@ import { mapPgError } from './errors.js';
 import { fetchWithIncludes } from './include/load.js';
 import { QueryBuilder } from './query-builder.js';
 import { mapRow, mapRows } from './row-mapper.js';
-export function createModelClient(model, pool, registry) {
+export function createModelClient(model, executor, registry) {
     const builder = new QueryBuilder(model);
     async function execute(sql, params) {
         try {
-            const result = await pool.query(sql, params);
+            const result = await executor.query(sql, params);
             return result.rows;
         }
         catch (error) {
@@ -16,7 +16,7 @@ export function createModelClient(model, pool, registry) {
     async function selectRows(args = {}) {
         const findArgs = toFindArgs(args);
         if (args.include && registry) {
-            return fetchWithIncludes(model, registry, pool, {
+            return fetchWithIncludes(model, registry, executor, {
                 ...findArgs,
                 include: args.include,
             }, {

package/dist/db/queryable.d.ts

@@ -0,0 +1,5 @@
+import type { QueryResult, QueryResultRow } from 'pg';
+/** Minimal executor satisfied by both pg `Pool` and `PoolClient`. */
+export interface Queryable {
+    query<T extends QueryResultRow>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+}

package/dist/db/queryable.js

@@ -0,0 +1 @@
+export {};