@simplysm/sd-claude 14.0.88 → 14.0.90

package/claude/references/sd-simplysm14/apis/orm-common/queryable.md

@@ -1,111 +1,154 @@
-# @simplysm/orm-common — Queryable (쿼리 작성)
+# @simplysm/orm-common — Queryable (쿼리 작성·실행 · 프로시저 · 검색)
 
-`db.user()` 등 등록된 팩토리 호출로 받는 체이닝 쿼리 빌더. 옵션·필터·조인을 immutable 체이닝으로 쌓은 뒤 종결 메서드로 실행한다. 콜백 인자 `columns`/`u` 등은 `QueryableRecord`(column → `ExprUnit` 프록시)이며, 표현식은 [expr.md](./expr.md) 로 만든다.
+`db.user()` 처럼 컨텍스트 멤버를 호출하면 `Queryable<TData, TFrom>` 를 받는다. immutable 체이닝으로 옵션·필터·조인·그룹을 쌓고, 종단 메서드(`execute`/`single`/`count`/`insert`/...)로 실행한다. where/select/orderBy 콜백 안에서는 [expr.md](./expr.md) 의 `expr` 로 표현식을 만든다. 프로시저는 `Executable`, 텍스트 검색 구문은 `parseSearchQuery` 가 처리한다.
 
-`Queryable<TData, TFrom>` — `TData` 결과 데이터 타입, `TFrom` 소스 TableBuilder(CUD 연산은 TableBuilder 기반에서만 가능, View/서브쿼리는 `never`).
+표준 조회 흐름(orm.md): `db.X()` → `joinSingle` 로 도출 컬럼 부착 → `select` 로 모든 도출을 한 번에 projection → projected 컬럼 이름으로 `where`/`orderBy` → `count` → `orderBy().limit().execute()`. SELECT 절에 `expr.subquery`/`expr.exists` 를 넣지 말고 `joinSingle` 로 1회 부착, `wrap()` 은 `distinct`/`groupBy` 뒤 `count` 등 프레임워크가 요구할 때만 사용.
 
-## 옵션 (SELECT 컬럼 / DISTINCT / LOCK)
+## Queryable — 조립 메서드 (체이닝)
 
-- `select(fn: (cols) => R): Queryable<...>` — SELECT column 재지정. `fn` 은 원본 column 프록시를 받아 `{별칭: ExprUnit | 리터럴 | 중첩객체}` 반환. CUD 소스성 상실(`TFrom=never`).
-- `distinct(): Queryable` — DISTINCT 적용. 이후 `count()` 직접 호출 불가(`wrap()` 필요).
-- `lock(): Queryable` — FOR UPDATE 행 잠금. 트랜잭션 내 배타 잠금이 필요할 때.
+옵션:
 
-## 행 제한 (TOP / LIMIT)
+- `select(fn)` — SELECT column 재정의. `fn(columns) => R` 의 R 이 새 결과 형태. 리터럴 상수는 자동으로 ExprUnit 래핑. 호출 후 CUD 불가(`TFrom` 소실).
+- `distinct()` — DISTINCT 적용. 이후 `count()` 하려면 `wrap()` 필요.
+- `lock()` — 행 잠금(FOR UPDATE). 트랜잭션 안에서 선택 행 배타 잠금. CUD 가능 상태 유지.
 
-- `top(count: number): Queryable` — 상위 N행. ORDER BY 없이도 사용 가능.
-- `limit(skip: number, take: number): Queryable` — 페이지네이션(OFFSET `skip`, LIMIT `take`). **ORDER BY 선행 필수**(없으면 throw).
+제한:
 
-## 정렬 (ORDER BY)
+- `top(count)` — 상위 N행. ORDER BY 없이도 사용 가능.
+- `limit(skip, take)` — 페이지네이션 OFFSET/LIMIT. `skip`=건너뛸 수, `take`=가져올 수. **먼저 `orderBy()` 호출 필수** — 없으면 throw.
 
-- `orderBy(fnOrKey, orderBy?: "ASC"|"DESC"): Queryable` — 정렬 조건 추가(여러 번 호출 시 순서대로 누적).
-  - `fnOrKey` — 정렬 column 을 반환하는 함수 `(cols) => ExprUnit`, 또는 체인 경로 문자열(`"id"`, `"user.name"` — `obj.getChainValue` 로 해석. 동적 정렬 루프용).
-  - `orderBy` — 방향. 기본 ASC.
+정렬:
 
-## 검색 (WHERE / search)
+- `orderBy(fnOrKey, orderBy?)` — 정렬 추가(여러 번 호출 시 순서대로). `fnOrKey`=정렬 column 반환 함수 또는 체인 경로 문자열(`"user.name"`, 동적 정렬용). `orderBy`="ASC"|"DESC"(기본 ASC).
 
-- `where(predicate: (cols) => WhereExprUnit[]): Queryable` — WHERE 조건 추가. 배열 내부는 AND, 여러 번 호출도 AND 누적. 조건은 `expr.eq` 등으로 생성.
-- `search(fn: (cols) => ExprUnit<string|undefined>[], searchText: string): Queryable` — 다중 column 텍스트 검색. `fn` 은 검색 대상 column 들, `searchText` 는 검색 문법 문자열(공백=OR, `+`=필수, `-`=제외, `"..."`=구문, `*`=와일드카드). 빈 문자열이면 변화 없이 self 반환. 내부적으로 `lower(col) LIKE pattern` 조합을 AND/OR 로 조립. (문법 상세: README 검색 파서)
+필터:
 
-```typescript
-db.user().where((u) => [expr.eq(u.isActive, true)]).search((u) => [u.name, u.email], "John -withdrawn");
-```
+- `where(predicate)` — WHERE 조건 추가(여러 번 호출 시 AND 결합). `predicate(columns) => WhereExprUnit[]`. 배열 내 여러 조건도 AND.
+- `search(fn, searchText)` — 텍스트 검색. `fn(columns) => ExprUnit<string|undefined>[]`(검색 대상 column 들), `searchText`=검색 구문(아래 `parseSearchQuery` 문법). 빈 문자열이면 무변경. 공백=OR, `+`=필수(AND), `-`=제외(NOT), `"구문"`=정확 일치(필수). 내부적으로 `expr.like(expr.lower(col), pattern)` 로 대소문자 무시 매칭.
 
-## 그룹 (GROUP BY / HAVING)
+그룹:
 
-- `groupBy(fn: (cols) => ExprUnit[]): Queryable` — GROUP BY. 이후 `count()` 직접 호출 불가(`wrap()` 필요).
-- `having(predicate: (cols) => WhereExprUnit[]): Queryable` — 그룹 필터(GROUP BY 이후). AND 누적.
+- `groupBy(fn)` — GROUP BY. `fn(columns) => ExprUnit<ColumnPrimitive>[]`. 호출 후 CUD 불가.
+- `having(predicate)` — GROUP BY 이후 필터. `predicate(columns) => WhereExprUnit[]`.
 
-## 조인 (JOIN / JOIN SINGLE / INCLUDE)
+조인:
 
-- `join<A, R>(as: A, fn: (qr, cols) => Queryable<R>): Queryable<TData & { [as]?: R[] }>` — 1:N LEFT JOIN, 결과에 **배열**로 추가. `qr` 는 `JoinQueryable`(`.from(table)`/`.select(cols)`/`.union(...)`), `cols` 는 바깥 column. 조인 조건은 반환 Queryable 의 `where` 로.
-- `joinSingle<A, R>(as, fn): Queryable<... & { [as]?: R }>` — N:1/1:1 LEFT JOIN, 결과에 **단일 객체**로 추가.
-- `include(fn: (item) => PathProxy): Queryable` — TableBuilder 의 FK/FKT 관계를 자동 조인. `fn` 은 타입 안전 경로 프록시(`item.user.company` 처럼 관계 필드만 접근 가능, ColumnPrimitive 필드는 접근 불가). 다단계·중복 include 지원. 관계 미정의 시 throw, View 기반 queryable 에선 사용 불가.
+- `join(as, fn)` — 1:N LEFT JOIN, 결과에 **배열**(`{ [as]?: R[] }`)로 부착. `fn(qr, parentCols) => Queryable` 안에서 `qr.from(Table).where(...)` 로 조인 본문 구성.
+- `joinSingle(as, fn)` — N:1/1:1 LEFT JOIN, 결과에 **단일 객체**(`{ [as]?: R }`)로 부착. 도출 컬럼(집계·boolean)을 outer 행에 붙일 때 표준 수단.
+- `include(fn)` — 빌더에 정의한 FK/FKT/RelationKey 관계 자동 JOIN. `fn(item) => item.user.company` 형태로 타입 안전 경로 지정(`PathProxy`, ColumnPrimitive 가 아닌 관계 필드만 접근 가능). 다단계·다중 호출 가능. 관계 미정의 시 throw.
 
-```typescript
-db.post().include((p) => p.user.company);
-db.user().join("posts", (qr, u) => qr.from(Post).where((p) => [expr.eq(p.userId, u.id)]));
-```
+서브쿼리/UNION:
 
-## 서브쿼리 / UNION / 재귀
+- `wrap()` — 현재 Queryable 을 서브쿼리(derived table)로 감쌈. `distinct()`/`groupBy()` 뒤 `count()` 처럼 프레임워크가 요구할 때만.
+- `static Queryable.union(...queries)` — 2개 이상 Queryable 을 UNION(중복 제거)으로 결합. 결과 위 fluent 연산자는 외부 union 결과에 적용. select 컬럼 이름·타입·순서를 양쪽 동일하게 맞춰야 함(orm-union.md). 2개 미만이면 throw.
 
-- `wrap(): Queryable<TData, never>` — 현재 쿼리를 서브쿼리로 래핑. `distinct()`/`groupBy()` 후 `count()` 하려면 필수.
-- `static Queryable.union<TData>(...queries): Queryable<TData, never>` — 여러 Queryable UNION(중복 제거). 최소 2개, 미만 시 throw. (`JoinQueryable.union` 도 동일 의미)
-- `recursive(fn: (qr: RecursiveQueryable) => Queryable): Queryable<TData, never>` — 재귀 CTE(WITH RECURSIVE). 계층 데이터 조회. `qr.from(table)`/`qr.select(cols)`/`qr.union(...)` 로 재귀 본문 정의, 재귀 측은 `self` 프로퍼티로 base 를 자기 참조.
+재귀:
 
-```typescript
-const count = await db.user().select((u) => ({ name: u.name })).distinct().wrap().count();
-```
+- `recursive(fn)` — WITH RECURSIVE CTE 생성(계층 데이터). `fn(cte) => cte.from(Table).where(...)` 안에서 `e.self[0]` 로 직전 단계 행을 참조.
+
+`db.user().join(...)`/`recursive(...)`/`Queryable.union(...)` 안에서 쓰는 `JoinQueryable`·`RecursiveQueryable` 의 `from`/`select`/`union` 은 콜백 인자로만 노출되며 직접 import 하지 않는다.
 
-## 종결 — SELECT 실행
+## Queryable — 종단 메서드
+
+조회:
 
 - `execute(): Promise<TData[]>` — SELECT 실행, 결과 배열.
 - `single(): Promise<TData | undefined>` — 단일 결과. 2건 이상이면 throw.
-- `first(): Promise<TData | undefined>` — 첫 결과(내부적으로 `top(1)`).
-- `count(fn?: (cols) => ExprUnit): Promise<number>` — 행 수. `fn` 지정 시 해당 column 카운트. `distinct()`/`groupBy()` 직후 호출 시 throw(`wrap()` 먼저).
-- `exists(): Promise<boolean>` — 조건 충족 행 존재 여부(`top(1)` 후 길이 검사).
-- `getSelectQueryDef(): SelectQueryDef` / `getResultMeta(outputColumns?): ResultMeta` — 실행용 def·결과 메타 생성(executor·서브쿼리 합성에서 사용).
+- `first(): Promise<TData | undefined>` — 첫 행만(내부적으로 `top(1)`). 복수여도 에러 없음.
+- `count(fn?): Promise<number>` — 행 수. `fn?`=셀 column 지정(미지정 시 전체). `distinct()`/`groupBy()` 직후 호출하면 throw(→ `wrap()` 먼저).
+- `exists(): Promise<boolean>` — 조건 매칭 행 존재 여부(내부 `top(1)`).
+
+CUD(모두 `TFrom` 이 TableBuilder 일 때만 — `select`/`groupBy` 후엔 불가):
+
+- `insert(records)` / `insert(records, outputColumns)` — 다건 INSERT. `records: $inferInsert[]`. MSSQL 1000행 제한 때문에 1000개씩 청크 분할. `outputColumns: K[]` 지정 시 삽입된 행에서 그 column 만 배열로 반환(AI/PK 값 회수). 빈 배열이면 no-op.
+- `insertIfNotExists(record)` / `(record, outputColumns)` — 현재 WHERE 조건 매칭 행이 없을 때만 1건 INSERT. output 지정 시 삽입 행 1개 반환.
+- `insertInto(targetTable)` / `(targetTable, outputColumns)` — 현재 SELECT 결과를 다른 테이블에 INSERT INTO ... SELECT. `targetTable` 의 column 구조가 현재 결과와 호환해야 함.
+- `update(recordFwd)` / `(recordFwd, outputColumns)` — UPDATE. `recordFwd(cols) => QueryableWriteRecord<$inferUpdate>`(갱신할 column→값). 값은 `ExprInput`(리터럴 직접 가능, `expr.val` 불필요). output 지정 시 갱신 행 반환.
+- `delete()` / `delete(outputColumns)` — DELETE. output 지정 시 삭제 행 반환.
+- `upsert(updateFn)` / `upsert(insertFn, outputColumns?)` / `upsert(updateFn, insertFn)` / `upsert(updateFn, insertFn, outputColumns)` — WHERE 매칭 행 있으면 UPDATE, 없으면 INSERT(MERGE). `updateFn(cols) => 갱신값`, `insertFn(updateRecord) => 삽입값`(생략 시 update 값 재사용). output 지정 시 영향 행 반환.
+
+QueryDef 생성기(실행 없이 AST 만): `getSelectQueryDef()`, `getInsertQueryDef(records, outputColumns?)`, `getInsertIfNotExistsQueryDef(...)`, `getInsertIntoQueryDef(...)`, `getUpdateQueryDef(...)`, `getDeleteQueryDef(...)`, `getUpsertQueryDef(...)`, `getResultMeta(outputColumns?)`. executor 우회·디버깅·배치 조립용.
 
-## 종결 — INSERT
+기타:
 
-각 INSERT 는 `outputColumns` 미전달 시 `void`, 전달 시 해당 column 만 뽑은 레코드를 반환(반환 자동증가 PK 수신 등).
-- `insert(records: TFrom["$inferInsert"][], outputColumns?): Promise<void | Pick<...>[]>` — 다건 INSERT. MSSQL 1000행 제한 때문에 1000건씩 청크 분할. AI column 에 명시값 있으면 자동 overrideIdentity.
-- `insertIfNotExists(record, outputColumns?): Promise<void | Pick<...>>` — 현재 WHERE 조건 매칭이 없을 때만 INSERT.
-- `insertInto(targetTable, outputColumns?): Promise<void | Pick<...>[]>` — 현재 SELECT 결과를 다른 테이블에 INSERT INTO ... SELECT. `targetTable` column 구조가 현재 데이터와 호환되어야 함(타입 매칭).
-- `getInsertQueryDef` / `getInsertIfNotExistsQueryDef` / `getInsertIntoQueryDef` — 각 def 생성기.
+- `switchFk(enabled)` — 이 Queryable 의 소스 테이블 FK 제약을 활성/비활성. 트랜잭션 안에서 가능.
+- `readonly meta` — 내부 조립 상태(from/where/joins/columns 등). 직접 수정하지 않음.
 
 ```typescript
-const [inserted] = await db.user().insert([{ name: "Hong" }], ["id"]);
+// 표준 조회 (orm.md 흐름)
+const items = await db.order()
+  .joinSingle("state", (q, p) =>
+    q.from(OrderLine).where((l) => [expr.eq(l.orderId, p.id)])
+      .select((l) => ({ sumQty: expr.sum(l.qty), doneCnt: expr.count(l.doneAt) })),
+  )
+  .select((p) => ({
+    id: p.id,
+    sumQty: expr.coalesce(p.state!.sumQty, 0),
+    isDone: expr.gt(p.state!.doneCnt, 0),
+  }))
+  .where((r) => [expr.eq(r.isDone, true)])
+  .orderBy((r) => r.id, "DESC")
+  .limit(0, 50)
+  .execute();
+
+// CUD — 리터럴 직접 전달
+await db.user().where((u) => [expr.eq(u.id, 1)]).update((u) => ({ name: "새이름" }));
+const [inserted] = await db.user().insert([{ name: "홍길동" }], ["id"]);
 ```
 
-## 종결 — UPDATE / DELETE
+## queryable / executable (팩토리 함수)
 
-- `update(recordFwd: (cols) => QueryableWriteRecord, outputColumns?): Promise<void | Pick<...>[]>` — UPDATE. `recordFwd` 는 column → 갱신값(`ExprInput`) 매핑 반환. 기존 값 참조 가능(`expr.mul(p.price, ...)`). WHERE 는 미리 체이닝.
-- `delete(outputColumns?): Promise<void | Pick<...>[]>` — DELETE. WHERE 미리 체이닝.
-- `getUpdateQueryDef` / `getDeleteQueryDef` — def 생성기.
+`DbContext` 내부에서 `this.queryable()`/`this.executable()` 로 쓰는 게 일반적이지만, 모듈 함수 형태도 export 됨.
 
-## 종결 — UPSERT
+- `queryable(db, tableOrView, as?)` — `() => Queryable` 팩토리. `as?` 미지정 시 호출마다 새 alias(`db.getNextAlias()`), 지정 시 고정. 반환 Queryable 의 column 은 빌더 정의로부터 구성(View 는 `viewFn` 평가).
+- `executable(db, builder)` — `() => Executable` 팩토리.
 
-- `upsert(updateFn, insertFn?, outputColumns?): Promise<void | Pick<...>[]>` — WHERE 매칭 있으면 UPDATE, 없으면 INSERT.
-  - `updateFn: (cols) => QueryableWriteRecord` — 갱신/삽입 공통값(insertFn 생략 시 INSERT 도 이 값 사용).
-  - `insertFn?: (updateRecord) => QueryableWriteRecord` — INSERT 전용값(update 결과를 받아 변형). UPDATE/INSERT 데이터가 다를 때.
-  - `outputColumns?` — 반환 column.
-- `getUpsertQueryDef(...)` — def 생성기.
+## Executable (프로시저 실행)
 
 ```typescript
-await db.user()
-  .where((u) => [expr.eq(u.email, "t@t.com")])
-  .upsert(() => ({ name: expr.val("string", "x"), email: expr.val("string", "t@t.com") }));
+class Executable<TParams, TReturns> {
+  getExecProcQueryDef(params?): ExecProcQueryDef;
+  execute(params): Promise<InferColumnExprs<TReturns>[][]>;
+}
 ```
 
-## DDL Helper / 기타
+- `execute(params)` — 프로시저 실행. `params`=`returns`/`params` 정의에 맞는 `InferColumnExprs<TParams>`(리터럴 또는 ExprUnit). 결과는 **결과셋 배열의 배열**(다중 SELECT 가능) — 단일 결과셋이면 `result[0]`.
+- `getExecProcQueryDef(params?)` — 실행 없이 QueryDef 반환. params 가 있는데 프로시저에 파라미터 정의가 없으면 throw.
+
+```typescript
+const [rows] = await db.getUserById().execute({ userId: 1n });
+```
+
+## parseSearchQuery / ParsedSearchQuery
+
+`search()` 가 내부로 쓰지만 직접 호출도 가능. 검색 구문 문자열을 SQL LIKE 패턴으로 분해.
+
+```typescript
+function parseSearchQuery(searchText: string): ParsedSearchQuery;
+interface ParsedSearchQuery { or: string[]; must: string[]; not: string[]; }
+```
+
+- `or: string[]` — 일반 검색어(공백 구분, OR). 와일드카드 없으면 `%term%`(부분 일치).
+- `must: string[]` — `+term` 또는 `"정확 구문"`(AND 필수).
+- `not: string[]` — `-term`(NOT 제외).
+- 와일드카드 `*` → `%`(`app*`→`app%` 시작 일치). 이스케이프: `\\` `\*` `\%` `\"` `\+` `\-` 는 리터럴. 닫히지 않은 `"` 는 일반 텍스트로 처리.
+
+```typescript
+parseSearchQuery('apple "delicious fruit" -banana +strawberry');
+// { or: ["%apple%"], must: ["%delicious fruit%", "%strawberry%"], not: ["%banana%"] }
+```
+
+## getMatchedPrimaryKeys
+
+```typescript
+function getMatchedPrimaryKeys(fkCols: string[], targetTable: TableBuilder): string[];
+```
 
-- `switchFk(enabled: boolean): Promise<void>` — 이 테이블 FK 제약 활성/비활성(트랜잭션 내 가능). TableBuilder/ViewBuilder 기반에서만.
-- `queryable(db, tableOrView, as?): () => Queryable` — Table/View 용 Queryable 팩토리 함수(보통 `DbContext.queryable()` 가 호출). `as` 미지정 시 자동 alias.
-- `getMatchedPrimaryKeys(fkCols, targetTable): string[]` — FK column 배열과 대상 PK 매칭(개수 불일치 시 throw). include 내부 헬퍼.
+- FK column 배열을 대상 테이블 PK 와 매칭해 PK column 이름 배열 반환. 개수 불일치 시 throw. `include()` 가 관계 조건을 만들 때 내부 사용 — 직접 호출은 드묾.
 
-## 관련 타입
+## 결과/입력 변환 타입
 
-- `QueryableRecord<TData>` — column → `ExprUnit` 프록시 레코드(콜백 인자 타입).
-- `QueryableWriteRecord<TData>` — column → `ExprInput`(쓰기 콜백 반환 타입).
-- `UnwrapQueryableRecord<R>` — `select` 결과 `ExprUnit` 언래핑 → 데이터 타입.
-- `PathProxy<TObject>` — `include` 경로 수집용 타입 안전 프록시(관계 필드만 노출).
+- `QueryableRecord<TData>` — 결과 데이터 → column 프록시 타입. 각 ColumnPrimitive 가 `ExprUnit<T>`, 중첩 관계는 재귀. where/select 등 콜백 인자 타입.
+- `QueryableWriteRecord<TData>` — 쓰기용. 각 필드가 `ExprInput<T>`. `update`/`upsert` 콜백 반환 타입.
+- `UnwrapQueryableRecord<R>` — `select` 결과를 다시 데이터 타입으로 역추론(ExprUnit→값).
+- `PathProxy<TObject>` — `include` 경로 지정용 프록시 타입(관계 필드만 접근).

package/claude/references/sd-simplysm14/apis/orm-common/schema.md

@@ -1,21 +1,39 @@
-# @simplysm/orm-common — 스키마 정의
+# @simplysm/orm-common — 스키마 정의 (Table / View / Procedure / column / index / relation)
 
-DB 객체(Table/View/Procedure)와 그 구성요소(Column/Index/관계)를 fluent 빌더로 선언하는 묶음. 모든 빌더는 immutable — 각 메서드가 새 인스턴스를 반환한다. 정의한 빌더는 `DbContext` 의 `queryable()`/`executable()` 로 등록한다.
+DB 객체(Table/View/Procedure)와 그 구성요소(column/index/관계)를 fluent 빌더로 선언하는 묶음. 모든 빌더는 immutable — 각 메서드가 새 인스턴스를 반환한다. 정의한 빌더는 `DbContext` 안에서 `this.queryable()`/`this.executable()` 로 등록한다. column 은 기본 `NOT NULL`; `.nullable()`/`.default(...)` 는 도메인 근거가 있을 때만 붙인다(orm.md).
 
 ## Table / TableBuilder
 
-테이블 정의 빌더. `Table(name)` 으로 시작해 메서드 체이닝.
+```typescript
+function Table<TName extends string>(name: TName): TableBuilder<TName, {}, {}>;
+
+class TableBuilder<TName, TColumns, TRelations> {
+  readonly meta: { name; description?; database?; schema?; columns?; primaryKey?; relations?; indexes? };
+  readonly $inferSelect;   // columns + 관계(optional)
+  readonly $inferColumns;  // column 값 타입만
+  readonly $inferInsert;   // INSERT 타입 (autoIncrement/nullable/default 는 optional)
+  readonly $inferUpdate;   // UPDATE 타입 (전부 optional)
+
+  description(desc: string): TableBuilder;
+  database(db: string): TableBuilder;
+  schema(schema: string): TableBuilder;
+  columns(fn: (c) => TNewColumns): TableBuilder;
+  primaryKey(...columns: (keyof TColumns)[]): TableBuilder;
+  indexes(fn: (i) => IndexBuilder[]): TableBuilder;
+  relations(fn: (r) => TRelations): TableBuilder;
+}
+```
 
-- `Table<TName>(name: TName): TableBuilder` — 빈 테이블 빌더 생성.
-- `TableBuilder.description(desc: string)` — 테이블 설명. DDL Comment 로 사용.
-- `TableBuilder.database(db: string)` — 소속 database 이름.
-- `TableBuilder.schema(schema: string)` — schema 이름(MSSQL=dbo, PostgreSQL=public). MySQL 은 무시.
-- `TableBuilder.columns(fn: (c) => Record<string, ColumnBuilder>)` — column 정의. `c` 는 column factory(아래 ColumnBuilder factory). 타입 추론의 핵심.
-- `TableBuilder.primaryKey(...columns: string[])` — PK column 지정. 여러 개 전달 시 복합 PK.
-- `TableBuilder.indexes(fn: (i) => IndexBuilder[])` — index 정의. `i` 는 index factory.
-- `TableBuilder.relations(fn: (r) => Record<string, RelationBuilder>)` — FK/역참조 관계 정의. `r` 은 relation factory(FK + RelationKey 모두 사용 가능).
-- `TableBuilder.meta` — 위 설정이 담긴 메타(`name`/`description`/`database`/`schema`/`columns`/`primaryKey`/`relations`/`indexes`). 런타임에서 읽음.
-- 타입 추론 프로퍼티(값은 없고 타입만): `$inferSelect`(column+관계 전체), `$inferColumns`(column 만), `$inferInsert`(autoIncrement/nullable/default 는 optional), `$inferUpdate`(전부 optional).
+- `Table(name)` — 빈 `TableBuilder` 생성. 이후 fluent 메서드로 채운다.
+- `description(desc)` — 테이블 설명. CREATE TABLE 시 DDL comment 로 들어감.
+- `database(db)` — 데이터베이스명 고정. 미지정 시 `DbContext` 의 기본 database.
+- `schema(schema)` — 스키마명(MSSQL/PostgreSQL). MySQL 무시.
+- `columns(fn)` — column factory `c` 를 받아 `{ name: c.타입() }` 레코드를 반환. 아래 column factory 참조. 호출 후 `$inferColumns` 등 타입이 갱신.
+- `primaryKey(...columns)` — PK column 이름(들). 여러 개 넘기면 복합 PK.
+- `indexes(fn)` — index factory `i` 를 받아 `IndexBuilder[]` 반환.
+- `relations(fn)` — relation factory `r` 를 받아 FK/역참조 관계 레코드 반환. Table 은 `foreignKey`/`foreignKeyTarget`/`relationKey`/`relationKeyTarget` 모두 사용 가능.
+- `$inferSelect` — SELECT 결과 타입(컬럼 + include 가능한 관계는 optional). `queryable` 콜백 인자의 원천.
+- `$inferInsert` / `$inferUpdate` — `insert`/`update` 입력 타입. INSERT 는 autoIncrement·nullable·default column 이 optional, UPDATE 는 전부 optional.
 
 ```typescript
 const User = Table("User")
@@ -26,42 +44,62 @@ const User = Table("User")
     email: c.varchar(200).nullable(),
   }))
   .primaryKey("id")
-  .indexes((i) => [i.index("email").unique()])
-  .relations((r) => ({ posts: r.foreignKeyTarget(() => Post, "author") }));
+  .indexes((i) => [i.index("email").unique()]);
 ```
 
 ## View / ViewBuilder
 
-뷰 정의 빌더. SELECT Queryable 로 데이터 소스를 정의. 관계는 RelationKey 만 가능(DB FK 미생성).
+```typescript
+function View(name: string): ViewBuilder;
+
+class ViewBuilder<TDbContext, TData, TRelations> {
+  readonly meta: { name; description?; database?; schema?; viewFn?; relations? };
+  readonly $inferSelect;  // TData
+
+  description(desc): ViewBuilder;
+  database(db): ViewBuilder;
+  schema(schema): ViewBuilder;
+  query(viewFn: (db) => Queryable<TViewData, any>): ViewBuilder;
+  relations(fn: (r) => T): ViewBuilder;
+}
+```
 
-- `View(name: string): ViewBuilder` — 빈 뷰 빌더 생성.
-- `ViewBuilder.description(desc: string)` — 뷰 설명(DDL Comment).
-- `ViewBuilder.database(db: string)` — 소속 database 이름.
-- `ViewBuilder.schema(schema: string)` — schema 이름(MSSQL/PostgreSQL).
-- `ViewBuilder.query(viewFn: (db) => Queryable)` — 뷰 본문 SELECT 정의. `db` 는 DbContext, 반환은 Queryable.
-- `ViewBuilder.relations(fn: (r) => ...)` — 관계 정의(`relationKey`/`relationKeyTarget` 만).
-- `ViewBuilder.meta` — `name`/`description`/`database`/`schema`/`viewFn`/`relations`.
-- `$inferSelect` — 뷰 데이터 타입(타입 추론용).
+- `View(name)` — 빈 `ViewBuilder` 생성.
+- `query(viewFn)` — 뷰 본문 SELECT 를 `db` 를 받는 함수로 정의. 반환 `Queryable` 의 select 결과가 뷰 데이터 타입이 됨. `queryable(this, View)` 등록 시 이 함수가 평가되어 column 이 구성된다.
+- `relations(fn)` — 뷰는 `relationKey`/`relationKeyTarget` 만 사용 가능(DB FK 미생성). `foreignKey` 는 타입상 불가.
+- `description`/`database`/`schema` — Table 과 동일 의미.
 
 ```typescript
 const ActiveUsers = View("ActiveUsers")
   .database("mydb")
-  .query((db: MyDb) => db.user().where((u) => [expr.eq(u.status, "active")]));
+  .query((db: MainDb) =>
+    db.user().where((u) => [expr.eq(u.status, "active")]).select((u) => ({ id: u.id, name: u.name })),
+  );
 ```
 
 ## Procedure / ProcedureBuilder
 
-저장 프로시저 정의 빌더. `DbContext.executable()` 로 등록해 `Executable` 로 실행.
+```typescript
+function Procedure(name: string): ProcedureBuilder<never, never>;
+
+class ProcedureBuilder<TParams, TReturns> {
+  readonly meta: { name; description?; database?; schema?; params?; returns?; query? };
+  readonly $params; readonly $returns;
+
+  description(desc): ProcedureBuilder;
+  database(db): ProcedureBuilder;
+  schema(schema): ProcedureBuilder;
+  params(fn: (c) => T): ProcedureBuilder;
+  returns(fn: (c) => T): ProcedureBuilder;
+  body(sql: string): ProcedureBuilder;
+}
+```
 
-- `Procedure(name: string): ProcedureBuilder` — 빈 프로시저 빌더 생성.
-- `ProcedureBuilder.description(desc: string)` — 설명(DDL Comment).
-- `ProcedureBuilder.database(db: string)` — 소속 database.
-- `ProcedureBuilder.schema(schema: string)` — schema 이름.
-- `ProcedureBuilder.params(fn: (c) => Record<string, ColumnBuilder>)` — 입력 파라미터 정의(column factory 사용).
-- `ProcedureBuilder.returns(fn: (c) => Record<string, ColumnBuilder>)` — 반환 결과 column 정의.
-- `ProcedureBuilder.body(sql: string)` — 본문 SQL. DBMS별 구문 차이 주의(MySQL: `param`, MSSQL: `@param`, PostgreSQL: `RETURN QUERY` 필요).
-- `ProcedureBuilder.meta` — `name`/`description`/`database`/`schema`/`params`/`returns`/`query`.
-- `$params` / `$returns` — 타입 추론용.
+- `Procedure(name)` — 빈 빌더 생성.
+- `params(fn)` — 입력 파라미터를 column factory 로 정의. `Executable.execute(params)` 의 입력 타입이 됨.
+- `returns(fn)` — 결과 column 정의. `execute` 결과 행 타입이 됨.
+- `body(sql)` — 프로시저 본문 SQL. DBMS별 구문 차이 주의(MySQL: `userId`, MSSQL: `@userId`, PostgreSQL: `RETURN QUERY` 필요).
+- `description`/`database`/`schema` — Table 과 동일.
 
 ```typescript
 const GetUserById = Procedure("GetUserById")
@@ -71,51 +109,52 @@ const GetUserById = Procedure("GetUserById")
   .body("SELECT id, name FROM User WHERE id = userId");
 ```
 
-## ColumnBuilder / createColumnFactory
-
-`columns()`/`params()`/`returns()` 콜백의 `c` 로 받는 factory. 타입별 메서드로 column 을 만든 뒤 modifier 체이닝.
-
-factory 타입 메서드:
-- `c.int()` — INT(4바이트). 값 타입 `number`.
-- `c.bigint()` — BIGINT(8바이트). 값 타입 `number`(bigint 아님).
-- `c.float()` — FLOAT(4바이트 단정밀도). `number`.
-- `c.double()` — DOUBLE(8바이트 배정밀도). `number`.
-- `c.decimal(precision, scale?)` — DECIMAL 고정소수점. `precision` 전체 자릿수, `scale` 소수 자릿수(선택). `number`.
-- `c.varchar(length)` — VARCHAR(가변). `length` 최대 길이. `string`.
-- `c.char(length)` — CHAR(고정). `string`.
-- `c.text()` — TEXT 대용량. `string`.
-- `c.binary()` — 바이너리(MySQL=LONGBLOB, MSSQL=VARBINARY(MAX), PostgreSQL=BYTEA). `Bytes`.
-- `c.boolean()` — BOOLEAN(MySQL=TINYINT(1), MSSQL=BIT, PostgreSQL=BOOLEAN). `boolean`.
-- `c.datetime()` — DATETIME(날짜+시간). `DateTime`.
-- `c.date()` — DATE(날짜만). `DateOnly`.
-- `c.time()` — TIME(시간만). `Time`.
-- `c.uuid()` — UUID(MySQL=BINARY(16), MSSQL=UNIQUEIDENTIFIER, PostgreSQL=UUID). `Uuid`.
-
-modifier(생성된 ColumnBuilder 에 체이닝):
-- `.autoIncrement()` — 자동 증가. INSERT 타입에서 optional 처리. (PK 식별 시 OUTPUT 의 aiColName 으로도 사용)
-- `.nullable()` — NULL 허용. 값 타입에 `undefined` 추가, INSERT 타입에서 optional.
-- `.default(value)` — INSERT 시 미지정 기본값. INSERT 타입에서 optional. (예: `"CURRENT_TIMESTAMP"`)
-- `.description(desc)` — column 설명(DDL Comment).
-- `ColumnBuilder.meta` — `ColumnMeta`(`type`/`dataType`/`autoIncrement?`/`nullable?`/`default?`/`description?`).
+## column factory / ColumnBuilder
+
+`columns`/`params`/`returns` 콜백 인자 `c` 가 column factory. 각 메서드는 `ColumnBuilder` 를 반환하고 `.autoIncrement()`/`.nullable()`/`.default()`/`.description()` 로 속성을 더한다(모두 immutable).
+
+타입 메서드:
+
+- `int()` — INT(4바이트 정수).
+- `bigint()` — BIGINT(8바이트 정수). autoIncrement PK 에 주로 사용.
+- `float()` — FLOAT(단정밀도 실수).
+- `double()` — DOUBLE(배정밀도 실수).
+- `decimal(precision, scale?)` — 고정 소수점. `precision`=전체 자릿수, `scale`=소수 자릿수(선택). 금액 등 정밀도 필요 시.
+- `varchar(length)` — 가변 길이 문자열. `length`=최대 길이.
+- `char(length)` — 고정 길이 문자열.
+- `text()` — 대용량 텍스트.
+- `binary()` — 바이너리(MySQL LONGBLOB / MSSQL VARBINARY(MAX) / PostgreSQL BYTEA). 값 타입 `Bytes`.
+- `boolean()` — 불리언(MySQL TINYINT(1) / MSSQL BIT / PostgreSQL BOOLEAN).
+- `datetime()` — 날짜+시간. 값 타입 `DateTime`.
+- `date()` — 날짜만. 값 타입 `DateOnly`.
+- `time()` — 시간만. 값 타입 `Time`.
+- `uuid()` — UUID(MySQL BINARY(16) / MSSQL UNIQUEIDENTIFIER / PostgreSQL UUID). 값 타입 `Uuid`.
+
+`ColumnBuilder` 속성 메서드:
+
+- `autoIncrement()` — INSERT 시 자동 증가. INSERT 타입에서 optional 처리. PK 자동 증가 column 에.
+- `nullable()` — NULL 허용. 값 타입에 `undefined` 추가, INSERT optional. 도메인상 값이 없을 수 있을 때만.
+- `default(value)` — INSERT 시 미지정이면 사용할 기본값. INSERT optional 처리. 사용자가 명시 지시한 경우에만.
+- `description(desc)` — column 설명(DDL comment).
 
 ```typescript
 .columns((c) => ({
   id: c.bigint().autoIncrement(),
-  status: c.varchar(20).default("active"),
+  price: c.decimal(10, 2),
   email: c.varchar(200).nullable(),
+  status: c.varchar(20).default("active"),
 }))
 ```
 
-## IndexBuilder / createIndexFactory
+## index factory / IndexBuilder
 
-`indexes()` 콜백의 `i` factory.
+`indexes` 콜백 인자 `i` 의 `index(...columns)` 로 시작해 fluent 로 옵션을 더한다.
 
-- `i.index(...columns: string[]): IndexBuilder` — index 생성. 여러 column 전달 시 복합 index.
-- `IndexBuilder.name(name)` — index 이름 지정(미지정 시 자동).
-- `IndexBuilder.unique()` — 유니크 index.
-- `IndexBuilder.orderBy(...orderBy: ("ASC"|"DESC")[])` — column 별 정렬 방향. column 수와 인자 수 일치 필요.
-- `IndexBuilder.description(description)` — index 설명(DDL Comment).
-- `IndexBuilder.meta` — `columns`/`name?`/`unique?`/`orderBy?`/`description?`.
+- `i.index(...columns)` — index 대상 column 이름(들). 여러 개면 복합 index.
+- `.name(name)` — index 이름 지정. 미지정 시 자동 생성.
+- `.unique()` — 유니크 index.
+- `.orderBy(...orderBy)` — column별 정렬 방향 배열("ASC"|"DESC"). column 수와 길이 일치해야 함.
+- `.description(description)` — index 설명(DDL comment).
 
 ```typescript
 .indexes((i) => [
@@ -124,39 +163,42 @@ modifier(생성된 ColumnBuilder 에 체이닝):
 ])
 ```
 
-## 관계 빌더 (relations 콜백의 r factory)
+## relation factory
 
-Table 의 `relations()` 는 FK+RelationKey 둘 다, View 의 `relations()` 는 RelationKey 만 사용 가능.
+`relations` 콜백 인자 `r`. Table 은 4종 모두, View 는 `relationKey`/`relationKeyTarget` 만. 대상 빌더는 순환 참조 방지를 위해 모두 `() => Target` 지연 함수로 넘긴다. `description`/`single` 은 메서드 체이닝이 아니라 마지막 `opts` 인자로 전달(체이닝은 TS7022 유발로 제거됨).
 
-- `r.foreignKey(columns: string[], targetFn: () => Table, opts?: { description? })` — N:1 FK(DB FK 제약 생성). `columns` 는 owner 의 FK column, `targetFn` 은 지연 평가 대상 테이블. → `ForeignKeyBuilder`.
-- `r.foreignKeyTarget(targetTableFn: () => Table, relationName: string, opts?: { single?: boolean; description? })` — 1:N 역참조(DB FK 생성 측의 반대편). `relationName` 은 대상 테이블에 정의된 FK 관계 이름. `single:true` 면 단일 객체(1:1), 기본은 배열. → `ForeignKeyTargetBuilder`.
-- `r.relationKey(columns, targetFn, opts?)` — N:1 논리 관계(DB FK **미생성**). View 에서도 사용. → `RelationKeyBuilder`.
-- `r.relationKeyTarget(targetTableFn, relationName, opts?: { single?; description? })` — 1:N 논리 역참조(DB FK 미생성). `single:true` → 단일. → `RelationKeyTargetBuilder`.
+- `r.foreignKey(columns, () => Target, opts?)` — N:1 FK 관계(DB FK 제약 **생성**). `columns`=현재 테이블 FK column 배열, 대상은 그 테이블의 PK 와 매칭. `opts.description?`. → `ForeignKeyBuilder`.
+- `r.foreignKeyTarget(() => Target, relationName, opts?)` — FK 역참조(1:N, DB FK 생성 측의 역방향). `relationName`=대상 테이블에서 이쪽을 가리키는 FK 관계 이름. `opts.single: true` 면 1:1 단일 객체, 아니면 배열. `opts.description?`. → `ForeignKeyTargetBuilder`.
+- `r.relationKey(columns, () => Target, opts?)` — N:1 논리 관계(DB FK **미생성**). FK 와 동일하나 제약 없음. View 에서도 사용. → `RelationKeyBuilder`.
+- `r.relationKeyTarget(() => Target, relationName, opts?)` — 1:N/1:1 논리 역참조(DB FK 미생성). `opts.single`/`opts.description` 동일. → `RelationKeyTargetBuilder`.
 
-각 관계 빌더의 `meta`:
-- `ForeignKeyBuilder.meta` / `RelationKeyBuilder.meta` — `ownerFn`/`columns`/`targetFn`/`description?`.
-- `ForeignKeyTargetBuilder.meta` / `RelationKeyTargetBuilder.meta` — `targetTableFn`/`relationName`/`description?`/`isSingle?`.
+각 `opts`:
 
-> 주의: `description`/`single` 은 메서드 체이닝(`.description()`)이 아니라 factory 의 `opts` 인자로 전달한다(순환 참조 TS7022 회피).
+- `description?: string` — 관계 설명.
+- `single?: boolean` (target 계열만) — true=결과를 단일 객체(1:1), false/미지정=배열(1:N). `include()`/`$inferSelect` 의 해당 키 타입이 단일/배열로 갈린다.
 
 ```typescript
 const Post = Table("Post")
   .columns((c) => ({ id: c.bigint().autoIncrement(), authorId: c.bigint() }))
   .primaryKey("id")
   .relations((r) => ({ author: r.foreignKey(["authorId"], () => User, { description: "작성자" }) }));
+
+const User = Table("User")
+  .columns((c) => ({ id: c.bigint().autoIncrement(), name: c.varchar(100) }))
+  .primaryKey("id")
+  .relations((r) => ({
+    posts: r.foreignKeyTarget(() => Post, "author"),
+    profile: r.foreignKeyTarget(() => Profile, "user", { single: true }),
+  }));
 ```
 
-## 타입 추론 유틸 / 레코드 타입
+주의: FK column 개수와 대상 테이블 PK 개수가 다르면 `include()`/join 시 "FK/PK column count mismatch" throw. PK 가 복합이면 FK column 도 같은 순서·개수로.
 
-빌더에서 export 되는 추론 헬퍼·레코드 타입(직접 타입 작성 시):
+## 빌더/추론 타입 (직접 참조 드묾)
 
-- `ColumnBuilderRecord` — `Record<string, ColumnBuilder>`. `columns()` 반환 타입.
-- `InferColumns<TBuilders>` — column 레코드 → 값 타입 객체.
-- `InferColumnExprs<TBuilders>` — column 레코드 → `ExprInput` 입력 타입 객체(프로시저 params).
-- `InferInsertColumns<TBuilders>` — INSERT 타입(필수/optional 분리).
-- `InferUpdateColumns<TBuilders>` — UPDATE 타입(전부 Partial).
-- `RequiredInsertKeys` / `OptionalInsertKeys` — INSERT 필수/선택 key 추출.
-- `DataToColumnBuilderRecord<TData>` — 데이터 레코드 → column 빌더 레코드(insertInto 타입 매칭용).
-- `RelationBuilderRecord` — 4개 관계 빌더 union 의 레코드.
-- `InferDeepRelations<TRelations, TVisited?>` — 관계 정의 → 심층 관계 타입(전부 optional, 동일 테이블 재방문 시 순환 차단).
-- `ExtractRelationTarget` / `ExtractRelationTargetResult` — 단일(N:1)/배열·단일(1:N) 대상 타입 추출.
+- `ColumnBuilderRecord` — `Record<string, ColumnBuilder<...>>`. `columns`/`params`/`returns` 반환 타입.
+- `RelationBuilderRecord` — 4종 relation 빌더의 union 레코드. `relations` 반환 타입.
+- `InferColumns<T>` / `InferInsertColumns<T>` / `InferUpdateColumns<T>` / `InferColumnExprs<T>` — column 레코드에서 각각 값 타입 / INSERT 입력 / UPDATE 입력 / `ExprInput` 입력 타입을 추론. `$inferColumns` 등 내부 사용.
+- `RequiredInsertKeys<T>` / `OptionalInsertKeys<T>` — INSERT 시 필수/선택 column key 분리(autoIncrement·nullable·default 가 선택).
+- `DataToColumnBuilderRecord<TData>` — 데이터 레코드 → column 빌더 레코드 역변환. `insertInto` 의 대상 테이블 제약에 사용.
+- `InferDeepRelations<T>` / `ExtractRelationTarget<T>` / `ExtractRelationTargetResult<T>` — 관계 정의에서 심층 결과 타입을 optional 로 추론(같은 테이블 재방문 시 순환 차단). `$inferSelect` 의 관계 부분.