reltype 0.1.4 → 0.1.6

package/README.md

@@ -6,97 +6,160 @@
 [![node](https://img.shields.io/node/v/reltype.svg)](https://www.npmjs.com/package/reltype)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
 
-**Type-first relational modeling for PostgreSQL in TypeScript.**
+> 한국어 문서 → [README.ko.md](./README.ko.md)
 
-Define your PostgreSQL tables in TypeScript code and get fully-typed query results automatically.
+**The PostgreSQL query library that gets out of your way.**
 
-- **Type-safe** — INSERT / SELECT / UPDATE types are automatically inferred from your schema
-- **camelCase ↔ snake_case** — Automatic conversion between DB column names and TypeScript variables
-- **Fluent query builder** — Chain `WHERE`, `OR`, `JOIN`, `GROUP BY`, `LIMIT`, `paginate`, `calculate`, `stream` and more
-- **Large data optimization** — Cursor pagination, batch processing, AsyncGenerator streaming
-- **Error classification** — `DbError` automatically classifies PostgreSQL errors into 13 distinct kinds
-- **Hook system** — Before/after query lifecycle hooks for monitoring and APM integration
+No Prisma schema. No decorators. No code generation. No migrations.  
+Just TypeScript — define your table once, get fully-typed queries instantly.
 
-> 한국어 문서는 [README.ko.md](./README.ko.md) 를 참고하세요.
+```ts
+// Define once
+const usersTable = defineTable('users', {
+  id:        col.serial().primaryKey(),
+  firstName: col.varchar(255).notNull(),
+  email:     col.text().notNull(),
+  isActive:  col.boolean().default(),
+  createdAt: col.timestamptz().defaultNow(),
+});
+
+// Use everywhere — fully typed, zero boilerplate
+const page = await userRepo
+  .select({ isActive: true })
+  .where({ email: { operator: 'ILIKE', value: '%@gmail.com' } })
+  .orderBy([{ column: 'createdAt', direction: 'DESC' }])
+  .paginate({ page: 1, pageSize: 20 });
+// → { data: User[], count: 150, page: 1, pageSize: 20, nextAction: true, previousAction: false }
+```
+
+---
+
+## Why reltype?
+
+### The problem with existing tools
+
+| | Prisma | TypeORM | Drizzle | **reltype** |
+|---|---|---|---|---|
+| Schema definition | `schema.prisma` file | Decorators on class | TS schema | **TS schema** |
+| Code generation required | ✅ Yes | ❌ No | ❌ No | **❌ No** |
+| Migration CLI required | ✅ Yes | Optional | Optional | **❌ Never** |
+| camelCase ↔ snake_case | Manual config | Manual config | Manual config | **Automatic** |
+| Raw SQL support | Limited | Yes | Yes | **Yes** |
+| Bundle size | Heavy | Heavy | Light | **Minimal** |
+| Large data streaming | Plugin needed | Custom | Custom | **Built-in** |
+
+### What makes reltype different
+
+**1. Define once, types everywhere**  
+Write your schema in TypeScript. `INSERT`, `SELECT`, and `UPDATE` types are automatically inferred — no duplicated interfaces, no `@Entity`, no `model User {}`.
+
+**2. camelCase ↔ snake_case is fully automatic**  
+Your DB has `first_name`, `created_at`, `is_active`. Your TypeScript has `firstName`, `createdAt`, `isActive`. reltype handles the mapping in both directions, always, for free.
+
+**3. No build step, no CLI, no migration files**  
+`npm install reltype` and start writing queries. That's it.
+
+**4. Large-scale production ready**  
+Cursor-based pagination, AsyncGenerator streaming, batch processing, connection pool monitoring, structured error classification, and lifecycle hooks — all built in.
 
 ---
 
 ## Installation
 
 ```bash
-# Install reltype
-npm install reltype
-
-# pg is a peerDependency — install it separately
-npm install pg
+npm install reltype pg
 npm install --save-dev @types/pg
 ```
 
-> Requires `pg` version 8.0.0 or higher.
+> `pg` (node-postgres) is a peer dependency. Version 8.0.0+ required.
 
 ---
 
-## Environment Variables
+## 2-Minute Quick Start
 
-Create a `.env` file in your project root.
+### Step 1 — Environment Variables
 
 ```env
-# ── Required (either CONNECTION_STRING or DB_NAME must be set) ───────────────
-
-# Option 1: Connection String (takes priority)
-DB_CONNECTION_STRING=postgresql://postgres:postgres@localhost:5432/mydb
-
-# Option 2: Individual settings
+# .env
 DB_HOST=127.0.0.1
 DB_PORT=5432
 DB_NAME=mydb
 DB_USER=postgres
 DB_PASSWORD=postgres
+DB_MAX=10
+DB_CONNECTION_TIMEOUT=3000
+```
 
-# ── Optional ─────────────────────────────────────────────────────────────────
-
-DB_SSL=false                      # Enable SSL
-DB_MAX=10                         # Max connection pool size
-DB_IDLE_TIMEOUT=30000             # Idle connection timeout (ms)
-DB_CONNECTION_TIMEOUT=2000        # Connection acquisition timeout (ms)
-DB_ALLOW_EXIT_ON_IDLE=false       # Allow process exit when idle
-DB_STATEMENT_TIMEOUT=0            # SQL statement timeout (ms, 0 = unlimited)
-DB_QUERY_TIMEOUT=0                # Query timeout (ms, 0 = unlimited)
-DB_APPLICATION_NAME=my-app        # App name shown in pg_stat_activity
-DB_KEEP_ALIVE=true                # Enable TCP keep-alive
-DB_KEEP_ALIVE_INITIAL_DELAY=10000 # Initial keep-alive delay (ms)
-
-# ── Logging ───────────────────────────────────────────────────────────────────
+Or use a connection string:
 
-LOGGER=true                       # Enable logger (true / false)
-LOG_LEVEL=info                    # Log level (debug / info / log / warn / error)
+```env
+DB_CONNECTION_STRING=postgresql://postgres:postgres@localhost:5432/mydb
 ```
 
----
+### Step 2 — Load dotenv at entry point
+
+```ts
+// index.ts — must be the very first line
+import 'dotenv/config';
 
-## Quick Start
+import { getPool } from 'reltype';
+```
 
-### 1. Define a Table Schema
+### Step 3 — Define a table schema
 
 ```ts
+// schema/usersTable.ts
 import { defineTable, col } from 'reltype';
 
 export const usersTable = defineTable('users', {
-  id:        col.serial().primaryKey(),       // SERIAL PRIMARY KEY (optional on INSERT)
-  firstName: col.varchar(255).notNull(),      // VARCHAR(255) NOT NULL
-  lastName:  col.varchar(255).nullable(),     // VARCHAR(255) NULL (optional on INSERT)
-  email:     col.text().notNull(),            // TEXT NOT NULL
-  isActive:  col.boolean().default(),         // BOOLEAN DEFAULT ... (optional on INSERT)
-  createdAt: col.timestamptz().defaultNow(),  // TIMESTAMPTZ DEFAULT NOW() (optional on INSERT)
+  id:        col.serial().primaryKey(),
+  firstName: col.varchar(255).notNull(),
+  lastName:  col.varchar(255).nullable(),
+  email:     col.text().notNull(),
+  isActive:  col.boolean().default(),
+  createdAt: col.timestamptz().defaultNow(),
 });
+
+// Types are automatically available — no extra code needed
+// InferRow<typeof usersTable>    → full SELECT result type
+// InferInsert<typeof usersTable> → INSERT input (required/optional by modifier)
+// InferUpdate<typeof usersTable> → UPDATE input (PK excluded, all optional)
+```
+
+### Step 4 — Create a repository and query
+
+```ts
+import { createRepo } from 'reltype';
+import { usersTable } from './schema/usersTable';
+
+export const userRepo = createRepo(usersTable);
+
+// SELECT
+const users = await userRepo.select({ isActive: true })
+  .orderBy([{ column: 'createdAt', direction: 'DESC' }])
+  .limit(10);
+
+// INSERT
+const user = await userRepo.create({ firstName: 'Alice', email: 'alice@example.com' });
+
+// UPDATE
+const updated = await userRepo.update(user.id, { isActive: false });
+
+// DELETE
+const deleted = await userRepo.delete(user.id);
 ```
 
-### 2. Automatic Type Inference
+Done. You now have a fully-typed, production-ready data layer.
+
+---
+
+## Type Inference — The Core Magic
+
+Define your schema once. reltype infers all types automatically:
 
 ```ts
 import { InferRow, InferInsert, InferUpdate } from 'reltype';
 
-// SELECT result type
 type User = InferRow<typeof usersTable>;
 // {
 //   id: number;
@@ -107,528 +170,420 @@ type User = InferRow<typeof usersTable>;
 //   createdAt: Date;
 // }
 
-// INSERT input type (optional columns automatically excluded)
 type CreateUser = InferInsert<typeof usersTable>;
-// { firstName: string; email: string; lastName?: string | null; isActive?: boolean; createdAt?: Date }
+// {
+//   firstName: string;   ← required (notNull, no default)
+//   email: string;       ← required
+//   lastName?: string | null;  ← optional (nullable)
+//   isActive?: boolean;        ← optional (has DB default)
+//   createdAt?: Date;          ← optional (defaultNow)
+// }
+// id is excluded — serial auto-generates it
 
-// UPDATE input type (PK excluded, all fields optional)
 type UpdateUser = InferUpdate<typeof usersTable>;
-// { firstName?: string; lastName?: string | null; email?: string; isActive?: boolean; createdAt?: Date }
-```
-
-### 3. Load dotenv at Application Entry Point
-
-`reltype` only reads `process.env`. Load your `.env` file **at the application entry point**.
-
-```ts
-// Application entry point (index.ts / server.ts / app.ts)
-import 'dotenv/config';  // Must be placed before other imports
-
-// Then import reltype
-import { getDatabaseConfig, getPool } from 'reltype';
+// {
+//   firstName?: string;
+//   lastName?: string | null;
+//   email?: string;
+//   isActive?: boolean;
+//   createdAt?: Date;
+// }
+// id is excluded — it's the lookup key
 ```
 
-### 4. Create a Repository
-
-```ts
-import { createRepo } from 'reltype';
-import { usersTable } from './schema';
-
-export const userRepo = createRepo(usersTable);
-```
+If you change a column in the schema, TypeScript will immediately catch every call site that's now incorrect. **Your schema is the single source of truth.**
 
 ---
 
 ## Repository API
 
-### Method Summary
-
-| Method | Return Type | Description |
+| Method | Returns | Description |
 |---|---|---|
-| `create(data)` | `Promise<T>` | INSERT a single row |
+| `create(data)` | `Promise<T>` | INSERT one row |
 | `update(id, data)` | `Promise<T \| null>` | UPDATE by primary key |
 | `delete(id)` | `Promise<boolean>` | DELETE by primary key |
-| `upsert(data, col?)` | `Promise<T>` | INSERT or UPDATE |
-| `bulkCreate(rows)` | `Promise<T[]>` | INSERT multiple rows |
-| `select(where?)` | `QueryBuilder<T>` | Start a fluent query builder |
-| `selectOne(where)` | `Promise<T \| null>` | Fetch a single row |
+| `upsert(data, col?)` | `Promise<T>` | INSERT or UPDATE on conflict |
+| `bulkCreate(rows)` | `Promise<T[]>` | INSERT multiple rows in one query |
+| `select(where?)` | `QueryBuilder<T>` | Start a fluent query |
+| `selectOne(where)` | `Promise<T \| null>` | Fetch one row |
 | `raw(sql, params?)` | `Promise<R[]>` | Execute raw SQL |
-| `findAll(opts?)` | `Promise<T[]>` | Static full query |
-| `findById(id)` | `Promise<T \| null>` | Fetch single row by PK |
-| `findOne(where)` | `Promise<T \| null>` | Fetch single row by condition |
-| `useHooks(h)` | `this` | Register global hooks |
-
----
-
-## create
-
-INSERT a single row. Columns with `serial`, `default`, or `nullable` modifiers are optional.
-
-```ts
-const user = await userRepo.create({
-  firstName: 'John',
-  email:     'john@example.com',
-  // lastName, isActive, createdAt → optional (DB default or nullable)
-});
-// → User
-```
-
----
-
-## update
-
-UPDATE only the specified columns by primary key. Returns `null` if the row does not exist.
-
-```ts
-// Partial update
-const updated = await userRepo.update(1, {
-  firstName: 'Jane',
-  isActive:  false,
-});
-// → User | null
-
-if (!updated) {
-  throw new Error('User not found.');
-}
-```
-
----
-
-## delete
-
-DELETE by primary key. Returns `true` if a row was deleted, `false` if not found.
-
-```ts
-const deleted = await userRepo.delete(1);
-// → boolean
-
-if (!deleted) {
-  throw new Error('User not found.');
-}
-```
-
----
-
-## upsert
-
-INSERT or UPDATE based on a conflict column.
-
-```ts
-// By PK (id) — default
-const user = await userRepo.upsert({
-  id:        1,
-  firstName: 'John',
-  email:     'john@example.com',
-});
-
-// By another unique column (snake_case)
-const user = await userRepo.upsert(
-  { firstName: 'John', email: 'john@example.com' },
-  'email',
-);
-// → User
-```
-
----
-
-## bulkCreate
-
-Insert multiple rows with a single `INSERT` query.
-
-```ts
-const created = await userRepo.bulkCreate([
-  { firstName: 'Alice', email: 'alice@example.com' },
-  { firstName: 'Bob',   email: 'bob@example.com'   },
-]);
-// → User[]
-```
+| `findAll(opts?)` | `Promise<T[]>` | Simple query with filter/sort/limit |
+| `findById(id)` | `Promise<T \| null>` | Fetch by primary key |
+| `findOne(where)` | `Promise<T \| null>` | Fetch by equality conditions |
+| `useHooks(h)` | `this` | Register global lifecycle hooks |
 
 ---
 
-## select — Fluent Query Builder
+## Fluent Query Builder
 
-`repo.select(where?)` returns a `QueryBuilder`.  
-Chain methods and then `await` or call `.exec()` to execute.
+`repo.select(where?)` returns a `QueryBuilder`. Chain methods freely, then `await` to execute.
 
-### Basic Query
-
-```ts
-// Fetch all (await directly — thenable)
-const users = await userRepo.select();
-
-// With initial WHERE condition
-const users = await userRepo.select({ isActive: true });
-```
-
-### WHERE — AND Conditions
+### Filtering (WHERE / OR)
 
 ```ts
 // Simple equality
-const users = await userRepo.select().where({ isActive: true });
-
-// Comparison operator
-const users = await userRepo.select()
-  .where({ createdAt: { operator: '>=', value: new Date('2024-01-01') } });
-
-// IN
-const users = await userRepo.select()
-  .where({ id: { operator: 'IN', value: [1, 2, 3] } });
+const users = await userRepo.select({ isActive: true });
 
-// IS NULL
+// Operators: =, !=, >, <, >=, <=, LIKE, ILIKE, IN, NOT IN, IS NULL, IS NOT NULL
 const users = await userRepo.select()
-  .where({ deletedAt: { operator: 'IS NULL' } });
+  .where({ createdAt: { operator: '>=', value: new Date('2024-01-01') } })
+  .where({ id:        { operator: 'IN', value: [1, 2, 3] }             });
 
-// LIKE / ILIKE (case-insensitive)
-const users = await userRepo.select()
-  .where({ email: { operator: 'ILIKE', value: '%@gmail.com' } });
-```
-
-Supported operators: `=` `!=` `>` `<` `>=` `<=` `LIKE` `ILIKE` `IN` `NOT IN` `IS NULL` `IS NOT NULL`
-
-### OR — OR Conditions
-
-Each `.or()` call adds an OR clause.  
-When AND conditions are present, the result is `WHERE (AND conditions) OR (OR conditions)`.
-
-```ts
-// firstName ILIKE '%john%' OR email ILIKE '%john%'
+// OR conditions
 const users = await userRepo.select({ isActive: true })
   .or({ firstName: { operator: 'ILIKE', value: '%john%' } })
   .or({ email:     { operator: 'ILIKE', value: '%john%' } });
 // → WHERE (is_active = true) OR (first_name ILIKE '%john%') OR (email ILIKE '%john%')
+
+// NULL check
+const unverified = await userRepo.select()
+  .where({ verifiedAt: { operator: 'IS NULL' } });
 ```
 
-### ORDER BY
+### Sorting, Paging, Grouping
 
 ```ts
-const users = await userRepo.select()
-  .orderBy([{ column: 'createdAt', direction: 'DESC' }]);
-
-// Multiple sort columns
 const users = await userRepo.select()
   .orderBy([
     { column: 'isActive',  direction: 'DESC' },
     { column: 'createdAt', direction: 'ASC'  },
-  ]);
-```
-
-### LIMIT / OFFSET
-
-```ts
-const users = await userRepo.select()
-  .orderBy([{ column: 'id', direction: 'ASC' }])
+  ])
   .limit(20)
-  .offset(40);
-// Page 3 (0-indexed offset)
-```
-
-### GROUP BY
+  .offset(40);  // Page 3
 
-```ts
-const result = await userRepo.select()
+// GROUP BY + aggregate
+const stats = await userRepo.select()
   .groupBy(['isActive'])
-  .calculate([
-    { fn: 'COUNT', alias: 'count' },
-  ]);
-// → { count: '42' }
+  .calculate([{ fn: 'COUNT', alias: 'count' }]);
 ```
 
 ### JOIN
 
 ```ts
-// LEFT JOIN
 const result = await userRepo.select({ isActive: true })
   .join({ table: 'orders', on: 'users.id = orders.user_id', type: 'LEFT' })
-  .columns(['users.id', 'users.email'])
+  .columns(['users.id', 'users.email', 'COUNT(orders.id) AS orderCount'])
   .groupBy(['users.id', 'users.email'])
-  .orderBy([{ column: 'id', direction: 'ASC' }])
-  .exec();
-```
-
-JOIN types: `INNER` `LEFT` `RIGHT` `FULL`
-
-### Column Selection (columns)
-
-```ts
-const users = await userRepo.select()
-  .columns(['id', 'email', 'firstName'])
   .exec();
 ```
 
----
-
-## selectOne
-
-Shorthand for `select(where).one()`. Returns the first matching row.
-
-```ts
-const user = await userRepo.selectOne({ email: 'john@example.com' });
-// → User | null
-
-const user = await userRepo.selectOne({ id: 1 });
-if (!user) throw new Error('not found');
-```
-
----
+> JOIN types: `INNER` · `LEFT` · `RIGHT` · `FULL`
 
-## calculate — Aggregate Functions
-
-Runs `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` aggregations.
+### Debug — Preview SQL before running
 
 ```ts
-// Total count
-const result = await userRepo.select().calculate([{ fn: 'COUNT', alias: 'count' }]);
-const total = parseInt(String(result.count), 10);
+const { sql, params } = userRepo.select({ isActive: true })
+  .orderBy([{ column: 'createdAt', direction: 'DESC' }])
+  .limit(20)
+  .toSQL();
 
-// Multiple aggregations
-const stats = await userRepo.select({ isActive: true })
-  .calculate([
-    { fn: 'COUNT', alias: 'count' },
-    { fn: 'AVG',   column: 'score', alias: 'avgScore' },
-    { fn: 'MAX',   column: 'score', alias: 'maxScore' },
-  ]);
-// → { count: '42', avgScore: '87.5', maxScore: '100' }
+console.log(sql);
+// SELECT * FROM users WHERE is_active = $1 ORDER BY created_at DESC LIMIT $2
+console.log(params);
+// [ true, 20 ]
 ```
 
 ---
 
-## paginate — OFFSET Pagination
+## Pagination
 
-Runs COUNT and DATA queries in parallel.
+### OFFSET pagination — for standard lists
 
 ```ts
 const result = await userRepo.select({ isActive: true })
   .orderBy([{ column: 'createdAt', direction: 'DESC' }])
   .paginate({ page: 1, pageSize: 20 });
 
-// result shape
 // {
-//   data:           User[],   // Current page data
-//   count:          150,      // Total matching rows
+//   data:           User[],
+//   count:          150,     ← total matching rows (COUNT query runs automatically)
 //   page:           1,
 //   pageSize:       20,
-//   nextAction:     true,     // Next page exists
-//   previousAction: false,    // Previous page exists
+//   nextAction:     true,    ← has next page
+//   previousAction: false,   ← no previous page
 // }
 ```
 
-> For tables with millions of rows, use `cursorPaginate()` instead.
+### Cursor pagination — for massive tables
 
----
-
-## cursorPaginate — Cursor-based Pagination (Large Data)
-
-Uses `WHERE id > last_id` instead of OFFSET scanning.  
-Assigning an indexed column as `cursorColumn` ensures consistent speed even with tens of millions of rows.
+OFFSET gets slower with every page. Cursor pagination doesn't.  
+`WHERE id > last_id` scans no extra rows, regardless of how deep you are.
 
 ```ts
-// First page
+// Page 1
 const p1 = await userRepo.select({ isActive: true })
   .cursorPaginate({ pageSize: 20, cursorColumn: 'id' });
+// → { data: [...], nextCursor: 'eyJpZCI6MjB9', pageSize: 20, hasNext: true }
 
-// p1 = { data: [...], nextCursor: 'xxx', pageSize: 20, hasNext: true }
-
-// Next page
-if (p1.hasNext) {
-  const p2 = await userRepo.select({ isActive: true })
-    .cursorPaginate({ pageSize: 20, cursorColumn: 'id', cursor: p1.nextCursor });
-}
+// Page 2 — pass the cursor
+const p2 = await userRepo.select({ isActive: true })
+  .cursorPaginate({ pageSize: 20, cursorColumn: 'id', cursor: p1.nextCursor });
 
-// Descending cursor (createdAt DESC)
-const result = await userRepo.select()
+// Descending (newest first)
+const latest = await userRepo.select()
   .cursorPaginate({ pageSize: 20, cursorColumn: 'createdAt', direction: 'desc' });
 ```
 
-| `paginate` | `cursorPaginate` |
-|---|---|
-| Provides total count | No total count |
-| Navigate by page number | Next / previous only |
-| Slows down on large tables | Consistent speed always |
+| | `paginate` | `cursorPaginate` |
+|---|---|---|
+| Total count | ✅ Yes | ❌ No |
+| Page number navigation | ✅ Yes | ❌ Next/Prev only |
+| Performance at row 1,000,000 | ❌ Slow | ✅ Constant speed |
+| Best for | Admin tables, standard lists | Feeds, logs, large exports |
 
 ---
 
-## forEach — Batch Processing
+## Large Data Processing
+
+### Batch processing (forEach)
 
-Processes data in chunks without loading everything into memory.  
-Ideal for large-scale ETL, bulk email sending, and data migration.
+Load 10 million rows without crashing your server. Processes in chunks, never holds everything in memory.
 
 ```ts
+// Send email to every active user — without loading all users at once
 await userRepo.select({ isActive: true })
   .orderBy([{ column: 'id', direction: 'ASC' }])
   .forEach(async (batch) => {
-    // batch: User[] (default 500 rows per chunk)
-    await sendEmailBatch(batch);
+    await sendEmailBatch(batch);  // batch: User[] (200 rows at a time)
   }, { batchSize: 200 });
 ```
 
----
+### Streaming (AsyncGenerator)
 
-## stream — Streaming (AsyncGenerator)
-
-Iterates rows one by one with `for await...of`.  
-Internally fetches in batches to keep memory usage low.
+Row-by-row processing with `for await...of`. Perfect for real-time pipelines.
 
 ```ts
-// Direct for await...of (Symbol.asyncIterator supported)
 for await (const user of userRepo.select({ isActive: true })) {
-  await processRow(user);
+  await processRow(user);  // one row at a time, low memory usage
 }
 
-// With custom batch size
+// Custom batch size for internal fetching
 for await (const user of userRepo.select().stream({ batchSize: 1000 })) {
-  await processRow(user);
+  await writeToFile(user);
 }
 ```
 
----
+### EXPLAIN — query plan analysis
+
+```ts
+// Check if your index is being used
+const plan = await userRepo.select({ isActive: true })
+  .orderBy([{ column: 'createdAt', direction: 'DESC' }])
+  .explain(true);  // true = EXPLAIN ANALYZE (actually runs the query)
 
-## raw — Raw SQL Execution
+console.log(plan);
+// Index Scan using users_created_at_idx on users ...
+```
+
+---
 
-Write SQL directly when complex queries are needed.  
-Result column names are automatically converted from `snake_case` to `camelCase`.
+## Aggregate Functions
 
 ```ts
-// repo.raw()
-const users = await userRepo.raw<UserRow>(
-  'SELECT * FROM users WHERE first_name ILIKE $1 ORDER BY created_at DESC',
-  ['%john%'],
-);
+// Single aggregation
+const result = await userRepo.select().calculate([{ fn: 'COUNT', alias: 'count' }]);
+const total = parseInt(String(result.count), 10);  // → 1042
 
-// QueryBuilder.raw() — standalone, no repository needed
-import { QueryBuilder } from 'reltype';
+// Multiple aggregations with filter
+const stats = await userRepo.select({ isActive: true })
+  .calculate([
+    { fn: 'COUNT', alias: 'total'    },
+    { fn: 'AVG',   column: 'score', alias: 'avgScore' },
+    { fn: 'MAX',   column: 'score', alias: 'maxScore' },
+  ]);
+// → { total: '850', avgScore: '72.4', maxScore: '100' }
+```
 
-const rows = await QueryBuilder.raw(
-  `SELECT u.id, u.email, COUNT(o.id) AS order_count
+---
+
+## Raw SQL
+
+When the query builder isn't enough, drop into raw SQL. You still get camelCase conversion.
+
+```ts
+// Via repository
+const users = await userRepo.raw<{ id: number; orderCount: number }>(
+  `SELECT u.id, COUNT(o.id) AS order_count
    FROM users u
    LEFT JOIN orders o ON u.id = o.user_id
    WHERE u.is_active = $1
-   GROUP BY u.id, u.email`,
+   GROUP BY u.id`,
   [true],
 );
+// → [{ id: 1, orderCount: 5 }, ...]  ← order_count → orderCount automatically
+
+// Standalone (no repository)
+import { QueryBuilder } from 'reltype';
+
+const rows = await QueryBuilder.raw(
+  'SELECT * FROM users WHERE first_name ILIKE $1',
+  ['%john%'],
+);
 ```
 
 ---
 
-## explain — Query Plan Analysis
+## CRUD Methods
 
-Inspect index usage and identify performance bottlenecks.
+### create
 
 ```ts
-// EXPLAIN
-const plan = await userRepo.select({ isActive: true }).explain();
-console.log(plan);
+const user = await userRepo.create({
+  firstName: 'Alice',
+  email:     'alice@example.com',
+  // isActive, createdAt → optional (DB handles defaults)
+});
+// → User (full row returned via RETURNING *)
+```
 
-// EXPLAIN ANALYZE (includes actual execution statistics)
-const plan = await userRepo.select({ isActive: true })
-  .orderBy([{ column: 'createdAt', direction: 'DESC' }])
-  .explain(true);
+### update
+
+```ts
+// Only updates the fields you pass
+const updated = await userRepo.update(1, {
+  firstName: 'Alicia',
+  isActive:  true,
+});
+// → User | null (null if ID not found)
 ```
 
----
+### delete
 
-## toSQL — Preview SQL (Debugging)
+```ts
+const ok = await userRepo.delete(1);
+// → true if deleted, false if not found
+```
 
-Returns the generated SQL and params without executing the query.
+### upsert
 
 ```ts
-const { sql, params } = userRepo.select({ isActive: true })
-  .orderBy([{ column: 'createdAt', direction: 'DESC' }])
-  .limit(20)
-  .toSQL();
+// Conflict on primary key (default)
+await userRepo.upsert({ id: 1, firstName: 'Bob', email: 'bob@example.com' });
 
-console.log(sql);
-// SELECT * FROM users WHERE is_active = $1 ORDER BY created_at DESC LIMIT $2
-console.log(params);
-// [ true, 20 ]
+// Conflict on another unique column
+await userRepo.upsert(
+  { firstName: 'Bob', email: 'bob@example.com' },
+  'email',  // snake_case column name
+);
+```
+
+### bulkCreate
+
+```ts
+const users = await userRepo.bulkCreate([
+  { firstName: 'Alice', email: 'alice@example.com' },
+  { firstName: 'Bob',   email: 'bob@example.com'   },
+  { firstName: 'Carol', email: 'carol@example.com' },
+]);
+// → User[]  (single INSERT query, RETURNING *)
 ```
 
 ---
 
-## hooks — Query Lifecycle Hooks
+## Lifecycle Hooks
 
-### Per-query Hooks
+Monitor every query, integrate APM, or log slow queries — without touching your business logic.
+
+### Per-query hooks
 
 ```ts
 const users = await userRepo.select({ isActive: true })
   .hooks({
-    beforeExec: ({ sql, params }) => logger.debug('About to run SQL:', sql),
-    afterExec:  ({ rows, elapsed }) => metrics.record('db.query.duration', elapsed),
-    onError:    ({ err, sql }) => alerting.send({ err, sql }),
+    beforeExec: ({ sql, params }) => {
+      console.log('[SQL]', sql);
+    },
+    afterExec: ({ rows, elapsed }) => {
+      if (elapsed > 500) console.warn('Slow query:', elapsed, 'ms');
+      metrics.record('db.query.duration', elapsed);
+    },
+    onError: ({ err, sql }) => {
+      alerting.send({ message: err.message, sql });
+    },
   })
   .paginate({ page: 1, pageSize: 20 });
 ```
 
-### Repository-level Global Hooks
+### Repository-level global hooks
 
-Automatically applied to all `select()` builders on this repository.
+Set once, applied to every `select()` on this repository automatically.
 
 ```ts
 userRepo.useHooks({
   beforeExec: ({ sql }) => logger.debug('SQL:', sql),
   afterExec:  ({ elapsed }) => metrics.histogram('db.latency', elapsed),
-  onError:    ({ err }) => logger.error('DB error', { message: err.message }),
+  onError:    ({ err })   => logger.error('DB error', { kind: err.kind }),
 });
-
-// All subsequent select() calls will use the hooks
-const users = await userRepo.select({ isActive: true }).exec();
 ```
 
 ---
 
-## Static CRUD (findAll / findById / findOne)
-
-Use static methods for simple queries.
-
-```ts
-// Fetch all
-const users = await userRepo.findAll();
-
-// With filter, sort, and pagination
-const users = await userRepo.findAll({
-  where:   { isActive: true },
-  orderBy: [{ col: 'createdAt', dir: 'DESC' }],
-  limit:   10,
-  offset:  0,
-});
+## Error Handling
 
-// Single row by PK
-const user = await userRepo.findById(1);         // User | null
+### DbError — structured PostgreSQL error classification
 
-// Single row by condition (equality only)
-const user = await userRepo.findOne({ email: 'john@example.com' }); // User | null
-```
+Every DB error is automatically wrapped in a `DbError`. It separates what's safe to show users from what stays in your logs.
 
-> For operators like `LIKE`, `IN`, or `OR`, use `repo.select()` instead.
+```ts
+import { DbError } from 'reltype';
 
----
+try {
+  await userRepo.create({ firstName: 'Alice', email: 'alice@example.com' });
+} catch (err) {
+  if (err instanceof DbError) {
+    // ✅ Safe to send to the client
+    res.status(409).json(err.toUserPayload());
+    // → { error: 'A duplicate value already exists.', kind: 'uniqueViolation', isRetryable: false }
 
-## Column Types
+    // 🔒 Internal details — never expose these
+    logger.error('db error', err.toLogContext());
+    // → { pgCode: '23505', table: 'users', constraint: 'users_email_key', detail: '...' }
 
-| Method | PostgreSQL Type | TypeScript Type |
-|---|---|---|
-| `col.serial()` | `SERIAL` | `number` |
-| `col.integer()` | `INTEGER` | `number` |
-| `col.bigint()` | `BIGINT` | `bigint` |
-| `col.numeric()` | `NUMERIC` | `number` |
-| `col.varchar(n?)` | `VARCHAR(n)` | `string` |
-| `col.text()` | `TEXT` | `string` |
-| `col.boolean()` | `BOOLEAN` | `boolean` |
-| `col.timestamp()` | `TIMESTAMP` | `Date` |
-| `col.timestamptz()` | `TIMESTAMPTZ` | `Date` |
-| `col.date()` | `DATE` | `Date` |
-| `col.uuid()` | `UUID` | `string` |
-| `col.jsonb<T>()` | `JSONB` | `T` (default `unknown`) |
+    // Retry logic for transient errors
+    if (err.isRetryable) await retry(operation);
+  }
+}
+```
 
-### Column Modifiers
+### Express integration example
 
 ```ts
-col.text().notNull()           // NOT NULL (default state)
-col.text().nullable()          // Allow NULL, optional on INSERT
-col.integer().primaryKey()     // PRIMARY KEY, optional on INSERT
-col.boolean().default()        // DB DEFAULT, optional on INSERT
-col.timestamptz().defaultNow() // DEFAULT NOW(), optional on INSERT
+app.post('/users', async (req, res) => {
+  try {
+    const user = await userRepo.create(req.body);
+    res.status(201).json(user);
+  } catch (err) {
+    if (err instanceof DbError) {
+      const status =
+        err.kind === 'uniqueViolation'   ? 409 :
+        err.kind === 'notNullViolation'  ? 400 :
+        err.kind === 'foreignKeyViolation' ? 422 :
+        err.isRetryable                  ? 503 : 500;
+      res.status(status).json(err.toUserPayload());
+    } else {
+      res.status(500).json({ error: 'Unexpected error.' });
+    }
+  }
+});
 ```
 
+### Error kind reference
+
+| Kind | PostgreSQL Code | Description | isRetryable |
+|---|---|---|---|
+| `uniqueViolation` | 23505 | UNIQUE constraint violated | false |
+| `foreignKeyViolation` | 23503 | FK constraint violated | false |
+| `notNullViolation` | 23502 | NOT NULL constraint violated | false |
+| `checkViolation` | 23514 | CHECK constraint violated | false |
+| `deadlock` | 40P01 | Deadlock detected | **true** |
+| `serializationFailure` | 40001 | Serialization failure | **true** |
+| `connectionFailed` | 08xxx | Connection failure | **true** |
+| `tooManyConnections` | 53300 | Pool exhausted | **true** |
+| `queryTimeout` | 57014 | Query timed out | false |
+| `undefinedTable` | 42P01 | Table not found | false |
+| `undefinedColumn` | 42703 | Column not found | false |
+| `invalidInput` | 22xxx | Invalid data format | false |
+| `unknown` | other | Unclassified error | false |
+
 ---
 
 ## Transaction
@@ -636,12 +591,13 @@ col.timestamptz().defaultNow() // DEFAULT NOW(), optional on INSERT
 ```ts
 import { runInTx } from 'reltype';
 
-const result = await runInTx(async (client) => {
-  await userRepo.create({ firstName: 'Alice', email: 'alice@example.com' });
-  await userRepo.create({ firstName: 'Bob',   email: 'bob@example.com'   });
-  return 'done';
+await runInTx(async (client) => {
+  // Both operations run in the same transaction
+  const user  = await userRepo.create({ firstName: 'Alice', email: 'alice@example.com' });
+  const order = await orderRepo.create({ userId: user.id, total: 9900 });
+  return { user, order };
 });
-// Automatically rolls back if any operation fails
+// Automatically ROLLBACK if any operation throws
 ```
 
 ---
@@ -649,119 +605,109 @@ const result = await runInTx(async (client) => {
 ## Connection Pool
 
 ```ts
-import { getPool, withClient, closePool } from 'reltype';
-
-// Direct pool access
-const pool = getPool();
-
-// Borrow a client and run a raw query
-const rows = await withClient(async (client) => {
-  const result = await client.query('SELECT NOW()');
-  return result.rows;
-});
+import { getPool, getPoolStatus, checkPoolHealth, closePool } from 'reltype';
 
-// On application shutdown
-await closePool();
-```
-
----
-
-## Raw Query Builders
-
-Build queries directly without a repository.
+// Real-time pool metrics
+const status = getPoolStatus();
+// {
+//   isInitialized: true,
+//   totalCount:    8,   ← total connections open
+//   idleCount:     3,   ← ready to use
+//   waitingCount:  0,   ← requests waiting (0 = healthy)
+//   isHealthy:     true
+// }
 
-```ts
-import { buildSelect, buildInsert, buildUpdate, buildDelete, buildUpsert, buildBulkInsert, withClient } from 'reltype';
+// Ping the DB server (SELECT 1)
+const alive = await checkPoolHealth();  // → boolean
 
-// SELECT
-const { sql, params } = buildSelect('users', {
-  where:   { isActive: true },
-  orderBy: [{ col: 'createdAt', dir: 'DESC' }],
-  limit:   5,
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await closePool();
+  process.exit(0);
 });
+```
 
-// INSERT
-const built = buildInsert('users', { firstName: 'John', email: 'john@example.com' });
-
-// UPDATE
-const built = buildUpdate('users', { firstName: 'Jane' }, { id: 1 });
-
-// DELETE
-const built = buildDelete('users', { id: 1 });
-
-// UPSERT
-const built = buildUpsert('users', { id: 1, firstName: 'John', email: 'john@example.com' }, 'id');
+### Recommended pool configuration
 
-// BULK INSERT
-const built = buildBulkInsert('users', [
-  { firstName: 'Alice', email: 'alice@example.com' },
-  { firstName: 'Bob',   email: 'bob@example.com'   },
-]);
-
-// Execute
-await withClient(async (client) => {
-  const result = await client.query(sql, params);
-  return result.rows;
-});
+```env
+DB_MAX=10                  # Max connections (match your Postgres max_connections)
+DB_CONNECTION_TIMEOUT=3000 # ⚠️  Must set — otherwise exhausted pool waits forever
+DB_IDLE_TIMEOUT=30000      # Release idle connections after 30s
+DB_STATEMENT_TIMEOUT=10000 # Kill runaway queries after 10s
 ```
 
-> All query builders automatically convert camelCase keys to snake_case column names.
+> If `DB_CONNECTION_TIMEOUT` is not set, reltype will warn on startup. An exhausted pool will hang indefinitely without this value.
 
 ---
 
-## Case Conversion Utilities
+## PostgreSQL Schema Support
 
 ```ts
-import { toCamel, toSnake, keysToCamel, keysToSnake } from 'reltype';
+// Dot notation
+const logsTable = defineTable('audit.activity_logs', { ... });
 
-toCamel('first_name')   // 'firstName'
-toSnake('firstName')    // 'first_name'
+// Explicit option
+const usersTable = defineTable('users', { ... }, { schema: 'auth' });
 
-keysToCamel({ first_name: 'John', created_at: new Date() })
-// { firstName: 'John', createdAt: Date }
-
-keysToSnake({ firstName: 'John', createdAt: new Date() })
-// { first_name: 'John', created_at: Date }
+// → SQL: INSERT INTO "auth"."users" ...
+// Identifiers are always quoted to avoid reserved word conflicts
 ```
 
 ---
 
-## Logger
+## Column Types
 
-```ts
-import { Logger } from 'reltype';
+| Method | PostgreSQL Type | TypeScript Type |
+|---|---|---|
+| `col.serial()` | `SERIAL` | `number` |
+| `col.integer()` | `INTEGER` | `number` |
+| `col.bigint()` | `BIGINT` | `bigint` |
+| `col.numeric()` | `NUMERIC` | `number` |
+| `col.varchar(n?)` | `VARCHAR(n)` | `string` |
+| `col.text()` | `TEXT` | `string` |
+| `col.boolean()` | `BOOLEAN` | `boolean` |
+| `col.timestamp()` | `TIMESTAMP` | `Date` |
+| `col.timestamptz()` | `TIMESTAMPTZ` | `Date` |
+| `col.date()` | `DATE` | `Date` |
+| `col.uuid()` | `UUID` | `string` |
+| `col.jsonb<T>()` | `JSONB` | `T` (default `unknown`) |
 
-const logger = Logger.fromEnv(process.env as Record<string, string | undefined>, {
-  prefix: '[MyApp]',
-  level:  'info',
-});
+### Modifiers
 
-logger.debug('debug message');
-logger.info('info message');
-logger.warn('warn message');
-logger.error('error message', new Error('oops'));
+```ts
+col.text().notNull()           // required on INSERT
+col.text().nullable()          // optional on INSERT, allows NULL
+col.integer().primaryKey()     // optional on INSERT, serial/auto
+col.boolean().default()        // optional on INSERT (DB has a DEFAULT)
+col.timestamptz().defaultNow() // optional on INSERT (DEFAULT NOW())
 ```
 
-Enable with environment variables: `LOGGER=true`, `LOG_LEVEL=debug`.
-
 ---
 
 ## Extending BaseRepo
 
-Extend `BaseRepo` to add custom methods.
+Add domain-specific methods to your repository:
 
 ```ts
 import { BaseRepo, InferRow } from 'reltype';
 import { usersTable } from './schema';
 
 class UserRepo extends BaseRepo<typeof usersTable> {
-  async findActiveUsers(): Promise<InferRow<typeof usersTable>[]> {
+  findActive(): Promise<InferRow<typeof usersTable>[]> {
     return this.findAll({ where: { isActive: true } });
   }
 
-  async findByEmail(email: string): Promise<InferRow<typeof usersTable> | null> {
+  findByEmail(email: string): Promise<InferRow<typeof usersTable> | null> {
     return this.findOne({ email });
   }
+
+  async search(query: string, page: number) {
+    return this.select()
+      .or({ firstName: { operator: 'ILIKE', value: `%${query}%` } })
+      .or({ email:     { operator: 'ILIKE', value: `%${query}%` } })
+      .orderBy([{ column: 'createdAt', direction: 'DESC' }])
+      .paginate({ page, pageSize: 20 });
+  }
 }
 
 export const userRepo = new UserRepo(usersTable);
@@ -769,186 +715,128 @@ export const userRepo = new UserRepo(usersTable);
 
 ---
 
-## Error Handling
-
-### DbError — PostgreSQL Error Classification
-
-All DB errors are automatically converted to `DbError`.  
-`DbError` separates internal log details from user-facing messages.
-
-```ts
-import { DbError } from 'reltype';
-
-try {
-  await userRepo.create({ firstName: 'Alice', email: 'alice@example.com' });
-} catch (err) {
-  if (err instanceof DbError) {
-    // Safe to expose to users
-    console.log(err.toUserPayload());
-    // { error: 'A duplicate value already exists.', kind: 'uniqueViolation', isRetryable: false }
+## Logging
 
-    // Internal logging details
-    console.log(err.toLogContext());
-    // { pgCode: '23505', kind: 'uniqueViolation', table: 'users', constraint: '...', ... }
-
-    // Check if retryable
-    if (err.isRetryable) {
-      // retry logic
-    }
-  }
-}
+```env
+LOGGER=true          # Enable logging
+LOG_LEVEL=debug      # debug | info | log | warn | error
+LOG_FORMAT=json      # text (dev, colored) | json (prod, log collectors)
 ```
 
-### Example with Express
-
-```ts
-app.post('/users', async (req, res) => {
-  try {
-    const user = await userRepo.create(req.body);
-    res.status(201).json(user);
-  } catch (err) {
-    if (err instanceof DbError) {
-      const status = err.kind === 'uniqueViolation' ? 409
-                   : err.kind === 'notNullViolation' ? 400
-                   : err.isRetryable               ? 503
-                   : 500;
-      res.status(status).json(err.toUserPayload());
-    } else {
-      res.status(500).json({ error: 'An unexpected error occurred.' });
-    }
-  }
-});
+**Development output (`text` format):**
+```
+2026-01-01T00:00:00.000Z [Pool] INFO  Pool created { max: 10, connectionTimeoutMillis: 3000 }
+2026-01-01T00:00:00.000Z [Repo] DEBUG SQL: SELECT * FROM users WHERE is_active = $1 [ true ]
+2026-01-01T00:00:00.000Z [Repo] DEBUG Done (8ms) rowCount=42
 ```
 
-### DbErrorKind Reference
+**Production output (`json` format, for Datadog / CloudWatch / Grafana Loki):**
+```json
+{"ts":"2026-01-01T00:00:00.000Z","level":"INFO","prefix":"[Pool]","msg":"Pool created","meta":[{"max":10}]}
+{"ts":"2026-01-01T00:00:00.000Z","level":"ERROR","prefix":"[Repo]","msg":"Query failed [users]","meta":[{"pgCode":"23505","kind":"uniqueViolation","constraint":"users_email_key"}]}
+```
 
-| kind | PostgreSQL SQLSTATE | Description | isRetryable |
-|---|---|---|---|
-| `uniqueViolation` | 23505 | UNIQUE constraint violation | false |
-| `foreignKeyViolation` | 23503 | Foreign key constraint violation | false |
-| `notNullViolation` | 23502 | NOT NULL constraint violation | false |
-| `checkViolation` | 23514 | CHECK constraint violation | false |
-| `deadlock` | 40P01 | Deadlock detected | **true** |
-| `serializationFailure` | 40001 | Serialization failure | **true** |
-| `connectionFailed` | 08xxx | Connection failure | **true** |
-| `tooManyConnections` | 53300 | Too many connections | **true** |
-| `queryTimeout` | 57014 | Query timeout | false |
-| `undefinedTable` | 42P01 | Table does not exist | false |
-| `undefinedColumn` | 42703 | Column does not exist | false |
-| `invalidInput` | 22xxx | Invalid input format | false |
-| `unknown` | other | Unclassified error | false |
+| Level | Prefix | When |
+|---|---|---|
+| INFO | [Pool] | Pool created / closed |
+| WARN | [Pool] | No connectionTimeoutMillis / max connections reached |
+| ERROR | [Pool] | Idle client error / connection acquisition failed |
+| DEBUG | [Repo] | Every SQL + elapsed time |
+| ERROR | [Repo] | Query failed (pgCode, kind, elapsed) |
+| DEBUG | [Tx] | Transaction started / committed |
+| WARN | [Tx] | Rollback |
+| ERROR | [Tx] | Rollback failed |
 
 ---
 
-## Pool Monitoring
-
-```ts
-import { getPoolStatus, checkPoolHealth } from 'reltype';
+## All Environment Variables
 
-// Get current pool status
-const status = getPoolStatus();
-console.log(status);
-// {
-//   totalCount:   5,     // Total connections created
-//   idleCount:    3,     // Idle connections
-//   waitingCount: 0,     // Requests waiting for a connection
-//   isHealthy:    true   // Pool is healthy
-// }
-
-// Health check against the DB server (SELECT 1)
-const isAlive = await checkPoolHealth();
-```
-
-### Preventing Too Many Connections
+```env
+# ── Connection ────────────────────────────────────────────────────────────────
+DB_CONNECTION_STRING=             # postgresql://user:pass@host:5432/db (priority)
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_NAME=mydb
+DB_USER=postgres
+DB_PASSWORD=postgres
 
-Always configure pool size and timeouts in your `.env`.
+# ── Pool ──────────────────────────────────────────────────────────────────────
+DB_MAX=10                         # Max pool size
+DB_IDLE_TIMEOUT=30000             # Idle connection release (ms)
+DB_CONNECTION_TIMEOUT=3000        # Max wait to acquire connection (ms) — ALWAYS SET THIS
+DB_ALLOW_EXIT_ON_IDLE=false       # Allow process exit when pool is empty
+DB_STATEMENT_TIMEOUT=0            # Max statement execution time (ms, 0 = unlimited)
+DB_QUERY_TIMEOUT=0                # Max query time (ms, 0 = unlimited)
+DB_SSL=false                      # Enable SSL
+DB_KEEP_ALIVE=true                # TCP keep-alive
+DB_KEEP_ALIVE_INITIAL_DELAY=10000 # Keep-alive initial delay (ms)
+DB_APPLICATION_NAME=my-app        # Name visible in pg_stat_activity
 
-```env
-DB_MAX=10                    # Max pool size (default: 10)
-DB_CONNECTION_TIMEOUT=3000   # Connection acquisition timeout in ms (infinite wait if not set — warning)
-DB_IDLE_TIMEOUT=30000        # Idle connection release time in ms
-DB_STATEMENT_TIMEOUT=10000   # Max SQL statement execution time in ms
+# ── Logging ───────────────────────────────────────────────────────────────────
+LOGGER=true
+LOG_LEVEL=info                    # debug | info | log | warn | error
+LOG_FORMAT=text                   # text | json
 ```
 
-> If `DB_CONNECTION_TIMEOUT` is not set, requests will wait indefinitely when the pool is exhausted.  
-> Always configure this value.
-
 ---
 
-## Log System
+## FAQ
 
-### Format Configuration
+**Q. Do I need to run migrations?**  
+No. reltype does not manage your database schema. Use your preferred migration tool (Flyway, Liquibase, `psql`, etc.). reltype only generates and executes SQL queries.
 
-```env
-LOGGER=true         # Enable logger
-LOG_LEVEL=debug     # debug / info / log / warn / error
-LOG_FORMAT=json     # text (default) / json (recommended for production)
-```
+**Q. Can I use it with an existing database?**  
+Yes. Define your `defineTable(...)` to match your existing columns. reltype reads from whatever is in Postgres.
 
-### text format (development)
+**Q. What if I have a very complex query?**  
+Use `repo.raw(sql, params)` or `QueryBuilder.raw(sql, params)` for full SQL control. You still get camelCase conversion on results.
 
-```
-2024-01-01T00:00:00.000Z [Pool] INFO  Pool created { max: 10, ... }
-2024-01-01T00:00:00.000Z [Repo] DEBUG SQL: SELECT * FROM users WHERE id = $1 [ 1 ]
-2024-01-01T00:00:00.000Z [Repo] DEBUG Done (12ms) rowCount=1
-```
+**Q. Can I use this with NestJS / Fastify / Koa?**  
+Yes. reltype is framework-agnostic. It only depends on `pg`.
 
-### json format (production / log aggregators)
+**Q. Is it safe against SQL injection?**  
+All values in `where`, `create`, `update`, etc. are passed as parameterized queries (`$1`, `$2`, ...). Never string-interpolated. The only surface to be careful about is the `on` clause in `.join()` — always construct that from static strings in your code.
 
-```json
-{"ts":"2024-01-01T00:00:00.000Z","level":"INFO","prefix":"[Pool]","msg":"Pool created","meta":[{"max":10}]}
-{"ts":"2024-01-01T00:00:00.000Z","level":"ERROR","prefix":"[Repo]","msg":"Query failed [users]","meta":[{"pgCode":"23505","kind":"uniqueViolation","constraint":"users_email_key"}]}
-```
-
-### Log Event Reference
-
-| Level | Prefix | Event |
-|---|---|---|
-| INFO | [Pool] | Pool created / Pool closed |
-| WARN | [Pool] | connectionTimeoutMillis not configured |
-| WARN | [Pool] | Max connections reached |
-| DEBUG | [Pool] | New connection / Connection removed |
-| ERROR | [Pool] | Idle client error / Client acquisition failed |
-| DEBUG | [Repo] | SQL executed + elapsed time |
-| ERROR | [Repo] | Query failed (pgCode, kind, elapsed included) |
-| DEBUG | [Tx] | Transaction started / committed |
-| WARN | [Tx] | Transaction rolled back |
-| ERROR | [Tx] | Rollback failed |
+**Q. How is it different from Drizzle ORM?**  
+Both are TypeScript-first and lightweight. reltype's key advantages are automatic camelCase↔snake_case conversion (Drizzle requires manual column naming), built-in cursor pagination, streaming, and batch processing out of the box, and a structured `DbError` system with user-safe messages.
 
 ---
 
 ## Architecture
 
 ```
-src/
-├── index.ts                  ← Public API entry point
-├── configs/env.ts            ← DB config parsing
+reltype/
+├── index.ts                        ← Public API
+├── configs/env.ts                  ← DB config helper
 ├── utils/
-│   ├── logger.ts             ← Logger class
-│   └── reader.ts             ← Env parser, PostgresConfig
+│   ├── logger.ts                   ← Logger (text/json format)
+│   ├── dbError.ts                  ← DbError classification
+│   └── reader.ts                   ← Env parser, PostgresConfig
 └── features/
-    ├── schema/               ← defineTable, col, InferRow/Insert/Update
-    ├── transform/            ← camelCase ↔ snake_case conversion
-    ├── connection/           ← Pool management, Transaction
-    ├── query/                ← SQL query builders (select/insert/update/delete/upsert/bulkInsert)
-    └── repository/           ← BaseRepo, createRepo, IRepo
+    ├── schema/                     ← defineTable, col, InferRow/Insert/Update
+    ├── transform/                  ← camelCase ↔ snake_case
+    ├── connection/                 ← Pool, withClient, runInTx
+    ├── query/                      ← QueryBuilder, build* functions
+    └── repository/                 ← BaseRepo, createRepo
 ```
 
 ---
 
 ## Contributing
 
-Bug reports, feature suggestions, and pull requests are all welcome.  
-→ [Issues](https://github.com/psh-suhyun/reltype/issues) · [Pull Requests](https://github.com/psh-suhyun/reltype/pulls)
+Bug reports, feature ideas, and PRs are very welcome.
+
+→ [Open an Issue](https://github.com/psh-suhyun/reltype/issues)  
+→ [Submit a PR](https://github.com/psh-suhyun/reltype/pulls)
 
 ---
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
+See [CHANGELOG.md](./CHANGELOG.md).
 
 ---
 
 ## License
 
-MIT
+MIT © [psh-suhyun](https://github.com/psh-suhyun)