reltype 0.1.1 → 0.1.3

package/README.md

@@ -8,93 +8,95 @@
 
 **Type-first relational modeling for PostgreSQL in TypeScript.**
 
-PostgreSQL 테이블을 TypeScript 코드로 정의하면, 모든 쿼리의 반환 타입이 자동으로 추론됩니다.
+Define your PostgreSQL tables in TypeScript code and get fully-typed query results automatically.
 
-- **타입 안전** — 스키마 정의에서 INSERT / SELECT / UPDATE 타입을 자동 추론
-- **camelCase ↔ snake_case** — DB 컬럼과 TypeScript 변수명을 자동 변환
-- **플루언트 쿼리 빌더** — `WHERE`, `OR`, `JOIN`, `GROUP BY`, `LIMIT`, `paginate`, `calculate`, `stream` 체인 지원
-- **대용량 최적화** — 커서 페이지네이션, 배치 처리, AsyncGenerator 스트리밍
-- **에러 분류** — `DbError`로 PostgreSQL 에러를 13가지 종류로 자동 분류
-- **훅 시스템** — 쿼리 전/후 라이프사이클 훅으로 모니터링·APM 연동
+- **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
+
+> 한국어 문서는 [README.ko.md](./README.ko.md) 를 참고하세요.
 
 ---
 
 ## Installation
 
 ```bash
-# reltype 설치
+# Install reltype
 npm install reltype
 
-# pg는 peerDependency — 직접 설치해야 합니다
+# pg is a peerDependency — install it separately
 npm install pg
 npm install --save-dev @types/pg
 ```
 
-> `pg` 버전 8.0.0 이상이 필요합니다.
+> Requires `pg` version 8.0.0 or higher.
 
 ---
 
 ## Environment Variables
 
-`.env` 파일을 프로젝트 루트에 생성합니다.
+Create a `.env` file in your project root.
 
 ```env
-# ── 필수 (CONNECTION_STRING 또는 DB_NAME 중 하나는 반드시 설정) ──────────────
+# ── Required (either CONNECTION_STRING or DB_NAME must be set) ───────────────
 
-# 방법 1: Connection String (우선 적용)
+# Option 1: Connection String (takes priority)
 DB_CONNECTION_STRING=postgresql://postgres:postgres@localhost:5432/mydb
 
-# 방법 2: 개별 설정
+# Option 2: Individual settings
 DB_HOST=127.0.0.1
 DB_PORT=5432
 DB_NAME=mydb
 DB_USER=postgres
 DB_PASSWORD=postgres
 
-# ── 선택 ────────────────────────────────────────────────────────────────────
+# ── Optional ─────────────────────────────────────────────────────────────────
 
-DB_SSL=false                      # SSL 활성화 여부
-DB_MAX=10                         # 최대 연결 풀 수
-DB_IDLE_TIMEOUT=30000             # idle 연결 해제 대기시간 (ms)
-DB_CONNECTION_TIMEOUT=2000        # 연결 타임아웃 (ms)
-DB_ALLOW_EXIT_ON_IDLE=false       # idle 상태에서 프로세스 종료 허용
-DB_STATEMENT_TIMEOUT=0            # SQL 문 실행 타임아웃 (ms, 0=무제한)
-DB_QUERY_TIMEOUT=0                # 쿼리 타임아웃 (ms, 0=무제한)
-DB_APPLICATION_NAME=my-app        # pg_stat_activity에 표시될 앱 이름
-DB_KEEP_ALIVE=true                # TCP keep-alive 활성화
-DB_KEEP_ALIVE_INITIAL_DELAY=10000 # keep-alive 최초 지연 (ms)
+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 ───────────────────────────────────────────────────────────────────
 
-LOGGER=true                       # 로거 활성화 (true / false)
-LOG_LEVEL=info                    # 로그 레벨 (debug / info / log / warn / error)
+LOGGER=true                       # Enable logger (true / false)
+LOG_LEVEL=info                    # Log level (debug / info / log / warn / error)
 ```
 
 ---
 
 ## Quick Start
 
-### 1. 테이블 스키마 정의
+### 1. Define a Table Schema
 
 ```ts
 import { defineTable, col } from 'reltype';
 
 export const usersTable = defineTable('users', {
-  id:        col.serial().primaryKey(),       // SERIAL PRIMARY KEY (INSERT 시 optional)
+  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 (INSERT 시 optional)
+  lastName:  col.varchar(255).nullable(),     // VARCHAR(255) NULL (optional on INSERT)
   email:     col.text().notNull(),            // TEXT NOT NULL
-  isActive:  col.boolean().default(),         // BOOLEAN DEFAULT ... (INSERT 시 optional)
-  createdAt: col.timestamptz().defaultNow(),  // TIMESTAMPTZ DEFAULT NOW() (INSERT 시 optional)
+  isActive:  col.boolean().default(),         // BOOLEAN DEFAULT ... (optional on INSERT)
+  createdAt: col.timestamptz().defaultNow(),  // TIMESTAMPTZ DEFAULT NOW() (optional on INSERT)
 });
 ```
 
-### 2. 타입 자동 추론
+### 2. Automatic Type Inference
 
 ```ts
 import { InferRow, InferInsert, InferUpdate } from 'reltype';
 
-// SELECT 결과 타입
+// SELECT result type
 type User = InferRow<typeof usersTable>;
 // {
 //   id: number;
@@ -105,28 +107,28 @@ type User = InferRow<typeof usersTable>;
 //   createdAt: Date;
 // }
 
-// INSERT 입력 타입 (optional 컬럼 자동 제외)
+// INSERT input type (optional columns automatically excluded)
 type CreateUser = InferInsert<typeof usersTable>;
 // { firstName: string; email: string; lastName?: string | null; isActive?: boolean; createdAt?: Date }
 
-// UPDATE 입력 타입 (PK 제외, 전체 optional)
+// 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. 앱 진입점에서 dotenv 로드
+### 3. Load dotenv at Application Entry Point
 
-`reltype`은 `process.env`를 읽기만 합니다. `.env` 파일 로딩은 **애플리케이션 진입점**에서 직접 하세요.
+`reltype` only reads `process.env`. Load your `.env` file **at the application entry point**.
 
 ```ts
-// 애플리케이션 진입점 (index.ts / server.ts / app.ts)
-import 'dotenv/config';  // 반드시 다른 import 전에 위치
+// Application entry point (index.ts / server.ts / app.ts)
+import 'dotenv/config';  // Must be placed before other imports
 
-// 이후 reltype import
+// Then import reltype
 import { getDatabaseConfig, getPool } from 'reltype';
 ```
 
-### 4. Repository 생성
+### 4. Create a Repository
 
 ```ts
 import { createRepo } from 'reltype';
@@ -139,34 +141,34 @@ export const userRepo = createRepo(usersTable);
 
 ## Repository API
 
-### 전체 메서드 요약
+### Method Summary
 
-| 메서드 | 반환 타입 | 설명 |
+| Method | Return Type | Description |
 |---|---|---|
-| `create(data)` | `Promise<T>` | 단건 INSERT |
-| `update(id, data)` | `Promise<T \| null>` | PK 기준 UPDATE |
-| `delete(id)` | `Promise<boolean>` | PK 기준 DELETE |
+| `create(data)` | `Promise<T>` | INSERT a single 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 |
-| `select(where?)` | `QueryBuilder<T>` | 플루언트 빌더 시작점 |
-| `selectOne(where)` | `Promise<T \| null>` | 단건 조회 |
-| `raw(sql, params?)` | `Promise<R[]>` | Raw SQL 실행 |
-| `findAll(opts?)` | `Promise<T[]>` | 정적 전체 조회 |
-| `findById(id)` | `Promise<T \| null>` | PK 단건 조회 |
-| `findOne(where)` | `Promise<T \| null>` | 조건 단건 조회 |
-| `useHooks(h)` | `this` | 글로벌 훅 등록 |
+| `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 |
+| `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. 자동으로 생성되는 컬럼(serial, default, nullable)은 입력을 생략할 수 있습니다.
+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 또는 nullable)
+  // lastName, isActive, createdAt → optional (DB default or nullable)
 });
 // → User
 ```
@@ -175,10 +177,10 @@ const user = await userRepo.create({
 
 ## update
 
-PK를 기준으로 지정한 컬럼만 UPDATE합니다. 존재하지 않으면 `null`을 반환합니다.
+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,
@@ -186,7 +188,7 @@ const updated = await userRepo.update(1, {
 // → User | null
 
 if (!updated) {
-  throw new Error('사용자를 찾을 수 없습니다.');
+  throw new Error('User not found.');
 }
 ```
 
@@ -194,14 +196,14 @@ if (!updated) {
 
 ## delete
 
-PK를 기준으로 삭제합니다. 삭제된 row가 있으면 `true`, 없으면 `false`를 반환합니다.
+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('사용자를 찾을 수 없습니다.');
+  throw new Error('User not found.');
 }
 ```
 
@@ -209,17 +211,17 @@ if (!deleted) {
 
 ## upsert
 
-충돌 컬럼 기준으로 INSERT 또는 UPDATE합니다.
+INSERT or UPDATE based on a conflict column.
 
 ```ts
-// PK(id) 기준 (기본값)
+// By PK (id) — default
 const user = await userRepo.upsert({
   id:        1,
   firstName: 'John',
   email:     'john@example.com',
 });
 
-// 다른 unique 컬럼 기준 (snake_case)
+// By another unique column (snake_case)
 const user = await userRepo.upsert(
   { firstName: 'John', email: 'john@example.com' },
   'email',
@@ -231,7 +233,7 @@ const user = await userRepo.upsert(
 
 ## bulkCreate
 
-여러 row를 단일 `INSERT` 쿼리로 삽입합니다.
+Insert multiple rows with a single `INSERT` query.
 
 ```ts
 const created = await userRepo.bulkCreate([
@@ -243,28 +245,28 @@ const created = await userRepo.bulkCreate([
 
 ---
 
-## select — 플루언트 쿼리 빌더
+## select — Fluent Query Builder
 
-`repo.select(where?)`는 `QueryBuilder`를 반환합니다.  
-메서드를 체인으로 조합한 후 `await` 하거나 `.exec()` 로 실행합니다.
+`repo.select(where?)` returns a `QueryBuilder`.  
+Chain methods and then `await` or call `.exec()` to execute.
 
-### 기본 조회
+### Basic Query
 
 ```ts
-// 전체 조회 (await 직접 사용 가능)
+// Fetch all (await directly — thenable)
 const users = await userRepo.select();
 
-// 초기 WHERE 조건
+// With initial WHERE condition
 const users = await userRepo.select({ isActive: true });
 ```
 
-### WHERE — AND 조건
+### WHERE — AND Conditions
 
 ```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') } });
 
@@ -276,17 +278,17 @@ const users = await userRepo.select()
 const users = await userRepo.select()
   .where({ deletedAt: { operator: 'IS NULL' } });
 
-// LIKE / ILIKE (대소문자 무시)
+// LIKE / ILIKE (case-insensitive)
 const users = await userRepo.select()
   .where({ email: { operator: 'ILIKE', value: '%@gmail.com' } });
 ```
 
-지원하는 연산자: `=` `!=` `>` `<` `>=` `<=` `LIKE` `ILIKE` `IN` `NOT IN` `IS NULL` `IS NOT NULL`
+Supported operators: `=` `!=` `>` `<` `>=` `<=` `LIKE` `ILIKE` `IN` `NOT IN` `IS NULL` `IS NOT NULL`
 
-### OR — OR 조건
+### OR — OR Conditions
 
-`.or()`를 여러 번 호출하면 각각 OR로 연결됩니다.  
-AND 조건이 있을 경우 `WHERE (AND 조건들) OR (OR 조건들)` 형태로 생성됩니다.
+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%'
@@ -302,7 +304,7 @@ const users = await userRepo.select({ isActive: true })
 const users = await userRepo.select()
   .orderBy([{ column: 'createdAt', direction: 'DESC' }]);
 
-// 다중 정렬
+// Multiple sort columns
 const users = await userRepo.select()
   .orderBy([
     { column: 'isActive',  direction: 'DESC' },
@@ -317,7 +319,7 @@ const users = await userRepo.select()
   .orderBy([{ column: 'id', direction: 'ASC' }])
   .limit(20)
   .offset(40);
-// 3페이지 (0-indexed offset)
+// Page 3 (0-indexed offset)
 ```
 
 ### GROUP BY
@@ -343,9 +345,9 @@ const result = await userRepo.select({ isActive: true })
   .exec();
 ```
 
-JOIN 타입: `INNER` `LEFT` `RIGHT` `FULL`
+JOIN types: `INNER` `LEFT` `RIGHT` `FULL`
 
-### 컬럼 지정 (columns)
+### Column Selection (columns)
 
 ```ts
 const users = await userRepo.select()
@@ -357,7 +359,7 @@ const users = await userRepo.select()
 
 ## selectOne
 
-`select(where).one()` 의 단축형입니다. 조건에 맞는 첫 번째 row를 반환합니다.
+Shorthand for `select(where).one()`. Returns the first matching row.
 
 ```ts
 const user = await userRepo.selectOne({ email: 'john@example.com' });
@@ -369,16 +371,16 @@ if (!user) throw new Error('not found');
 
 ---
 
-## calculate — 집계 함수
+## calculate — Aggregate Functions
 
-`COUNT`, `SUM`, `AVG`, `MIN`, `MAX`를 실행합니다.
+Runs `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` aggregations.
 
 ```ts
-// 전체 카운트
+// Total count
 const result = await userRepo.select().calculate([{ fn: 'COUNT', alias: 'count' }]);
 const total = parseInt(String(result.count), 10);
 
-// 다중 집계
+// Multiple aggregations
 const stats = await userRepo.select({ isActive: true })
   .calculate([
     { fn: 'COUNT', alias: 'count' },
@@ -390,89 +392,89 @@ const stats = await userRepo.select({ isActive: true })
 
 ---
 
-## paginate — OFFSET 페이지네이션
+## paginate — OFFSET Pagination
 
-COUNT 쿼리와 DATA 쿼리를 병렬로 실행합니다.
+Runs COUNT and DATA queries in parallel.
 
 ```ts
 const result = await userRepo.select({ isActive: true })
   .orderBy([{ column: 'createdAt', direction: 'DESC' }])
   .paginate({ page: 1, pageSize: 20 });
 
-// result 구조
+// result shape
 // {
-//   data:           User[],   // 현재 페이지 데이터
-//   count:          150,      // 전체 row 수 (필터 적용)
+//   data:           User[],   // Current page data
+//   count:          150,      // Total matching rows
 //   page:           1,
 //   pageSize:       20,
-//   nextAction:     true,     // 다음 페이지 존재 여부
-//   previousAction: false,    // 이전 페이지 존재 여부
+//   nextAction:     true,     // Next page exists
+//   previousAction: false,    // Previous page exists
 // }
 ```
 
-> 수백만 건 이상의 테이블에서는 `cursorPaginate()` 를 사용하세요.
+> For tables with millions of rows, use `cursorPaginate()` instead.
 
 ---
 
-## cursorPaginate — 커서 기반 페이지네이션 (대용량)
+## cursorPaginate — Cursor-based Pagination (Large Data)
 
-OFFSET 스캔 없이 `WHERE id > last_id` 방식으로 동작합니다.  
-인덱스가 있는 컬럼을 `cursorColumn`으로 지정하면 수천만 건에서도 일정한 속도를 유지합니다.
+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.
 
 ```ts
-// 첫 페이지
+// First page
 const p1 = await userRepo.select({ isActive: true })
   .cursorPaginate({ pageSize: 20, cursorColumn: 'id' });
 
 // 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 });
 }
 
-// 내림차순 커서 (createdAt DESC)
+// Descending cursor (createdAt DESC)
 const result = await userRepo.select()
   .cursorPaginate({ pageSize: 20, cursorColumn: 'createdAt', direction: 'desc' });
 ```
 
 | `paginate` | `cursorPaginate` |
 |---|---|
-| 전체 count 제공 | count 미제공 |
-| page 번호로 이동 | 이전/다음만 가능 |
-| 대용량에서 느려짐 | 항상 일정한 속도 |
+| Provides total count | No total count |
+| Navigate by page number | Next / previous only |
+| Slows down on large tables | Consistent speed always |
 
 ---
 
-## forEach — 배치 처리
+## forEach — Batch Processing
 
-전체 데이터를 메모리에 올리지 않고 청크 단위로 처리합니다.  
-대용량 ETL, 이메일 일괄 발송, 데이터 마이그레이션에 적합합니다.
+Processes data in chunks without loading everything into memory.  
+Ideal for large-scale ETL, bulk email sending, and data migration.
 
 ```ts
 await userRepo.select({ isActive: true })
   .orderBy([{ column: 'id', direction: 'ASC' }])
   .forEach(async (batch) => {
-    // batch: User[] (기본 500개씩)
+    // batch: User[] (default 500 rows per chunk)
     await sendEmailBatch(batch);
   }, { batchSize: 200 });
 ```
 
 ---
 
-## stream — 스트리밍 (AsyncGenerator)
+## stream — Streaming (AsyncGenerator)
 
-`for await...of` 루프로 row를 하나씩 순회합니다.  
-내부적으로 배치 단위로 DB를 조회하여 메모리 효율을 유지합니다.
+Iterates rows one by one with `for await...of`.  
+Internally fetches in batches to keep memory usage low.
 
 ```ts
-// for await...of 직접 사용 (Symbol.asyncIterator 지원)
+// Direct for await...of (Symbol.asyncIterator supported)
 for await (const user of userRepo.select({ isActive: true })) {
   await processRow(user);
 }
 
-// 배치 크기 지정
+// With custom batch size
 for await (const user of userRepo.select().stream({ batchSize: 1000 })) {
   await processRow(user);
 }
@@ -480,19 +482,19 @@ for await (const user of userRepo.select().stream({ batchSize: 1000 })) {
 
 ---
 
-## raw — Raw SQL 직접 실행
+## raw — Raw SQL Execution
 
-복잡한 쿼리가 필요할 때 SQL을 직접 작성합니다.  
-결과 컬럼명은 `snake_case → camelCase`로 자동 변환됩니다.
+Write SQL directly when complex queries are needed.  
+Result column names are automatically converted from `snake_case` to `camelCase`.
 
 ```ts
-// repo.raw() 사용
+// repo.raw()
 const users = await userRepo.raw<UserRow>(
   'SELECT * FROM users WHERE first_name ILIKE $1 ORDER BY created_at DESC',
   ['%john%'],
 );
 
-// QueryBuilder.raw() — 레포지토리 없이 독립적으로 사용
+// QueryBuilder.raw() — standalone, no repository needed
 import { QueryBuilder } from 'reltype';
 
 const rows = await QueryBuilder.raw(
@@ -507,16 +509,16 @@ const rows = await QueryBuilder.raw(
 
 ---
 
-## explain — 쿼리 플랜 분석
+## explain — Query Plan Analysis
 
-인덱스 사용 여부 및 성능 병목을 확인합니다.
+Inspect index usage and identify performance bottlenecks.
 
 ```ts
 // EXPLAIN
 const plan = await userRepo.select({ isActive: true }).explain();
 console.log(plan);
 
-// EXPLAIN ANALYZE (실제 실행 통계 포함)
+// EXPLAIN ANALYZE (includes actual execution statistics)
 const plan = await userRepo.select({ isActive: true })
   .orderBy([{ column: 'createdAt', direction: 'DESC' }])
   .explain(true);
@@ -524,9 +526,9 @@ const plan = await userRepo.select({ isActive: true })
 
 ---
 
-## toSQL — SQL 미리 확인 (디버깅)
+## toSQL — Preview SQL (Debugging)
 
-실제 실행 없이 생성될 SQL과 params를 반환합니다.
+Returns the generated SQL and params without executing the query.
 
 ```ts
 const { sql, params } = userRepo.select({ isActive: true })
@@ -542,46 +544,46 @@ console.log(params);
 
 ---
 
-## hooks — 쿼리 라이프사이클 훅
+## hooks — Query Lifecycle Hooks
 
-### 쿼리별 훅
+### Per-query Hooks
 
 ```ts
 const users = await userRepo.select({ isActive: true })
   .hooks({
-    beforeExec: ({ sql, params }) => logger.debug('SQL 실행 예정:', sql),
+    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 }),
   })
   .paginate({ page: 1, pageSize: 20 });
 ```
 
-### 레포지토리 전역 훅
+### Repository-level Global Hooks
 
-레포지토리의 모든 `select()` 빌더에 자동 적용됩니다.
+Automatically applied to all `select()` builders on this repository.
 
 ```ts
 userRepo.useHooks({
   beforeExec: ({ sql }) => logger.debug('SQL:', sql),
   afterExec:  ({ elapsed }) => metrics.histogram('db.latency', elapsed),
-  onError:    ({ err }) => logger.error('DB 오류', { kind: err.message }),
+  onError:    ({ err }) => logger.error('DB error', { message: err.message }),
 });
 
-// 이후 모든 select()에 훅이 적용됨
+// All subsequent select() calls will use the hooks
 const users = await userRepo.select({ isActive: true }).exec();
 ```
 
 ---
 
-## 정적 CRUD (findAll / findById / findOne)
+## 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' }],
@@ -589,20 +591,20 @@ const users = await userRepo.findAll({
   offset:  0,
 });
 
-// PK로 단건 조회
+// Single row by PK
 const user = await userRepo.findById(1);         // User | null
 
-// 조건으로 단건 조회 (단순 등호만 지원)
+// Single row by condition (equality only)
 const user = await userRepo.findOne({ email: 'john@example.com' }); // User | null
 ```
 
-> 연산자(LIKE, IN, OR 등)가 필요한 경우 `repo.select()` 를 사용하세요.
+> For operators like `LIKE`, `IN`, or `OR`, use `repo.select()` instead.
 
 ---
 
 ## Column Types
 
-| 메서드 | PostgreSQL 타입 | TypeScript 타입 |
+| Method | PostgreSQL Type | TypeScript Type |
 |---|---|---|
 | `col.serial()` | `SERIAL` | `number` |
 | `col.integer()` | `INTEGER` | `number` |
@@ -615,16 +617,16 @@ const user = await userRepo.findOne({ email: 'john@example.com' }); // User | nu
 | `col.timestamptz()` | `TIMESTAMPTZ` | `Date` |
 | `col.date()` | `DATE` | `Date` |
 | `col.uuid()` | `UUID` | `string` |
-| `col.jsonb<T>()` | `JSONB` | `T` (기본 `unknown`) |
+| `col.jsonb<T>()` | `JSONB` | `T` (default `unknown`) |
 
 ### Column Modifiers
 
 ```ts
-col.text().notNull()      // NOT NULL (기본 상태)
-col.text().nullable()     // NULL 허용, INSERT 시 optional
-col.integer().primaryKey() // PRIMARY KEY, INSERT 시 optional
-col.boolean().default()   // DB DEFAULT, INSERT 시 optional
-col.timestamptz().defaultNow() // DEFAULT NOW(), INSERT 시 optional
+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
 ```
 
 ---
@@ -639,7 +641,7 @@ const result = await runInTx(async (client) => {
   await userRepo.create({ firstName: 'Bob',   email: 'bob@example.com'   });
   return 'done';
 });
-// 하나라도 실패 시 자동 ROLLBACK
+// Automatically rolls back if any operation fails
 ```
 
 ---
@@ -649,16 +651,16 @@ const result = await runInTx(async (client) => {
 ```ts
 import { getPool, withClient, closePool } from 'reltype';
 
-// Pool 직접 접근
+// Direct pool access
 const pool = getPool();
 
-// Client 빌려서 Raw 쿼리 실행
+// Borrow a client and run a raw query
 const rows = await withClient(async (client) => {
   const result = await client.query('SELECT NOW()');
   return result.rows;
 });
 
-// 애플리케이션 종료 시
+// On application shutdown
 await closePool();
 ```
 
@@ -666,7 +668,7 @@ await closePool();
 
 ## Raw Query Builders
 
-Repository 없이 직접 쿼리를 빌드할 수 있습니다.
+Build queries directly without a repository.
 
 ```ts
 import { buildSelect, buildInsert, buildUpdate, buildDelete, buildUpsert, buildBulkInsert, withClient } from 'reltype';
@@ -696,14 +698,14 @@ const built = buildBulkInsert('users', [
   { firstName: 'Bob',   email: 'bob@example.com'   },
 ]);
 
-// 실행
+// Execute
 await withClient(async (client) => {
   const result = await client.query(sql, params);
   return result.rows;
 });
 ```
 
-> 모든 쿼리 빌더는 camelCase key → snake_case 컬럼명으로 자동 변환합니다.
+> All query builders automatically convert camelCase keys to snake_case column names.
 
 ---
 
@@ -740,13 +742,13 @@ logger.warn('warn message');
 logger.error('error message', new Error('oops'));
 ```
 
-환경 변수 `LOGGER=true`, `LOG_LEVEL=debug` 으로 활성화합니다.
+Enable with environment variables: `LOGGER=true`, `LOG_LEVEL=debug`.
 
 ---
 
 ## Extending BaseRepo
 
-커스텀 메서드를 추가하려면 `BaseRepo`를 상속합니다.
+Extend `BaseRepo` to add custom methods.
 
 ```ts
 import { BaseRepo, InferRow } from 'reltype';
@@ -769,10 +771,10 @@ export const userRepo = new UserRepo(usersTable);
 
 ## Error Handling
 
-### DbError — PostgreSQL 에러 분류
+### DbError — PostgreSQL Error Classification
 
-모든 DB 에러는 자동으로 `DbError`로 변환됩니다.  
-`DbError`는 내부 로그용 상세 정보와 사용자 노출용 메시지를 분리합니다.
+All DB errors are automatically converted to `DbError`.  
+`DbError` separates internal log details from user-facing messages.
 
 ```ts
 import { DbError } from 'reltype';
@@ -781,23 +783,23 @@ 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: '이미 존재하는 값입니다.', kind: 'uniqueViolation', isRetryable: false }
+    // { error: 'A duplicate value already exists.', kind: 'uniqueViolation', isRetryable: false }
 
-    // 내부 로깅용 상세 정보
+    // Internal logging details
     console.log(err.toLogContext());
     // { pgCode: '23505', kind: 'uniqueViolation', table: 'users', constraint: '...', ... }
 
-    // 재시도 가능 여부 확인
+    // Check if retryable
     if (err.isRetryable) {
-      // 재시도 로직
+      // retry logic
     }
   }
 }
 ```
 
-### Express에서 사용하는 예시
+### Example with Express
 
 ```ts
 app.post('/users', async (req, res) => {
@@ -812,29 +814,29 @@ app.post('/users', async (req, res) => {
                    : 500;
       res.status(status).json(err.toUserPayload());
     } else {
-      res.status(500).json({ error: '알 수 없는 오류가 발생했습니다.' });
+      res.status(500).json({ error: 'An unexpected error occurred.' });
     }
   }
 });
 ```
 
-### DbErrorKind 전체 목록
+### DbErrorKind Reference
 
-| kind | PostgreSQL SQLSTATE | 설명 | isRetryable |
+| kind | PostgreSQL SQLSTATE | Description | isRetryable |
 |---|---|---|---|
-| `uniqueViolation` | 23505 | UNIQUE 제약 위반 | false |
-| `foreignKeyViolation` | 23503 | FK 제약 위반 | false |
-| `notNullViolation` | 23502 | NOT NULL 위반 | false |
-| `checkViolation` | 23514 | CHECK 제약 위반 | false |
-| `deadlock` | 40P01 | 교착 상태 | **true** |
-| `serializationFailure` | 40001 | 직렬화 실패 | **true** |
-| `connectionFailed` | 08xxx | 연결 실패 | **true** |
-| `tooManyConnections` | 53300 | 연결 수 초과 | **true** |
-| `queryTimeout` | 57014 | 쿼리 타임아웃 | false |
-| `undefinedTable` | 42P01 | 테이블 없음 | false |
-| `undefinedColumn` | 42703 | 컬럼 없음 | false |
-| `invalidInput` | 22xxx | 잘못된 입력 형식 | false |
-| `unknown` | 기타 | 분류 불가 | false |
+| `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 |
 
 ---
 
@@ -843,75 +845,75 @@ app.post('/users', async (req, res) => {
 ```ts
 import { getPoolStatus, checkPoolHealth } from 'reltype';
 
-// 현재 Pool 상태 조회
+// Get current pool status
 const status = getPoolStatus();
 console.log(status);
 // {
-//   totalCount:   5,     // 총 생성된 연결 수
-//   idleCount:    3,     // 유휴 연결 수
-//   waitingCount: 0,     // 연결 대기 중인 요청 수
-//   isHealthy:    true   // 정상 여부
+//   totalCount:   5,     // Total connections created
+//   idleCount:    3,     // Idle connections
+//   waitingCount: 0,     // Requests waiting for a connection
+//   isHealthy:    true   // Pool is healthy
 // }
 
-// DB 서버와의 연결 헬스체크 (SELECT 1)
+// Health check against the DB server (SELECT 1)
 const isAlive = await checkPoolHealth();
 ```
 
-### Too Many Connections 방지
+### Preventing Too Many Connections
 
-`.env`에서 Pool 크기와 타임아웃을 반드시 설정하세요.
+Always configure pool size and timeouts in your `.env`.
 
 ```env
-DB_MAX=10                    # 최대 연결 풀 크기 (기본값: 10)
-DB_CONNECTION_TIMEOUT=3000   # 연결 획득 타임아웃 ms (미설정 시 무한 대기 경고)
-DB_IDLE_TIMEOUT=30000        # 유휴 연결 해제 시간 ms
-DB_STATEMENT_TIMEOUT=10000   # SQL 문 최대 실행 시간 ms
+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
 ```
 
-> `DB_CONNECTION_TIMEOUT`이 설정되지 않으면 Pool 소진 시 요청이 무한 대기합니다.  
-> 반드시 설정하세요.
+> If `DB_CONNECTION_TIMEOUT` is not set, requests will wait indefinitely when the pool is exhausted.  
+> Always configure this value.
 
 ---
 
 ## Log System
 
-### 포맷 설정
+### Format Configuration
 
 ```env
-LOGGER=true         # 로거 활성화
+LOGGER=true         # Enable logger
 LOG_LEVEL=debug     # debug / info / log / warn / error
-LOG_FORMAT=json     # text(기본) / json(프로덕션 권장)
+LOG_FORMAT=json     # text (default) / json (recommended for production)
 ```
 
-### text 포맷 (개발 환경)
+### text format (development)
 
 ```
-2024-01-01T00:00:00.000Z [Pool] INFO Pool 생성 완료 { max: 10, ... }
+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 완료 (12ms) rowCount=1
+2024-01-01T00:00:00.000Z [Repo] DEBUG Done (12ms) rowCount=1
 ```
 
-### json 포맷 (프로덕션 / 로그 수집기)
+### json format (production / log aggregators)
 
 ```json
-{"ts":"2024-01-01T00:00:00.000Z","level":"INFO","prefix":"[Pool]","msg":"Pool 생성 완료","meta":[{"max":10}]}
-{"ts":"2024-01-01T00:00:00.000Z","level":"ERROR","prefix":"[Repo]","msg":"쿼리 실패 [users]","meta":[{"pgCode":"23505","kind":"uniqueViolation","constraint":"users_email_key"}]}
+{"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
 
-| 레벨 | prefix | 이벤트 |
+| Level | Prefix | Event |
 |---|---|---|
-| INFO | [Pool] | Pool 생성 완료 / Pool 종료 |
-| WARN | [Pool] | connectionTimeoutMillis 미설정 경고 |
-| WARN | [Pool] | 최대 연결 수 도달 |
-| DEBUG | [Pool] | 새 연결 생성 / 연결 제거 |
-| ERROR | [Pool] | 유휴 클라이언트 오류 / 클라이언트 획득 실패 |
-| DEBUG | [Repo] | SQL 실행 + 소요시간 |
-| ERROR | [Repo] | 쿼리 실패 (pgCode, kind, 소요시간 포함) |
-| DEBUG | [Tx] | 트랜잭션 시작 / 커밋 |
-| WARN | [Tx] | 트랜잭션 롤백 |
-| ERROR | [Tx] | 롤백 실패 |
+| 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 |
 
 ---
 
@@ -919,16 +921,16 @@ LOG_FORMAT=json     # text(기본) / json(프로덕션 권장)
 
 ```
 src/
-├── index.ts                  ← 공개 API 진입점
-├── configs/env.ts            ← DB 설정 파싱
+├── index.ts                  ← Public API entry point
+├── configs/env.ts            ← DB config parsing
 ├── utils/
-│   ├── logger.ts             ← Logger 클래스
-│   └── reader.ts             ← env 파서, PostgresConfig
+│   ├── logger.ts             ← Logger class
+│   └── reader.ts             ← Env parser, PostgresConfig
 └── features/
     ├── schema/               ← defineTable, col, InferRow/Insert/Update
-    ├── transform/            ← camelCase ↔ snake_case 변환
-    ├── connection/           ← Pool 관리, Transaction
-    ├── query/                ← SQL 쿼리 빌더 (select/insert/update/delete/upsert/bulkInsert)
+    ├── transform/            ← camelCase ↔ snake_case conversion
+    ├── connection/           ← Pool management, Transaction
+    ├── query/                ← SQL query builders (select/insert/update/delete/upsert/bulkInsert)
     └── repository/           ← BaseRepo, createRepo, IRepo
 ```
 
@@ -936,14 +938,14 @@ src/
 
 ## Contributing
 
-버그 리포트, 기능 제안, PR 모두 환영합니다.  
+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)
 
 ---
 
 ## Changelog
 
-전체 변경 이력은 [CHANGELOG.md](./CHANGELOG.md) 를 참고하세요.
+See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
 
 ---