@simplysm/sd-claude 14.0.88 → 14.0.89

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

@@ -1,67 +1,64 @@
 # @simplysm/orm-common — 스키마 정의
 
-DB 객체(Table/View/Procedure)와 그 구성요소(Column/Index/관계)를 fluent 빌더로 선언하는 묶음. 모든 빌더는 immutable — 각 메서드가 새 인스턴스를 반환한다. 정의한 빌더는 `DbContext` 의 `queryable()`/`executable()` 로 등록한다.
+DB 객체(Table/View/Procedure)와 그 구성요소(Column/Index/관계)를 fluent 빌더로 선언하는 묶음. 모든 빌더는 immutable — 각 메서드가 새 인스턴스를 반환한다. 정의한 빌더는 `DbContext` 안에서 `this.queryable()`/`this.executable()` 로 등록한다.
 
 ## Table / TableBuilder
 
-테이블 정의 빌더. `Table(name)` 으로 시작해 메서드 체이닝.
+`Table(name)` → `TableBuilder` 시작점. 체이닝으로 database·schema·columns·primaryKey·indexes·relations 를 붙인다.
 
-- `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<TName>(name: TName): TableBuilder` — 이름만 가진 빈 빌더 생성. 이후 체이닝으로 정의를 쌓음.
+- `description(desc: string)` — 테이블 설명. DDL 코멘트로 쓰임. 스키마 문서화·DB 코멘트가 필요할 때.
+- `database(db: string)` — 소속 database 이름. dialect별 네임스페이스의 첫 분절. 멀티 DB 환경에서 필수.
+- `schema(schema: string)` — schema 이름. MSSQL(dbo)·PostgreSQL(public) 에서만 의미. MySQL 은 무시.
+- `columns(fn: (c) => Record<string, ColumnBuilder>)` — 컬럼 정의. `c` 는 `createColumnFactory()` 결과(int/varchar/... 타입 메서드). 타입 추론(`$inferSelect` 등)의 기준이 됨.
+- `primaryKey(...columns)` — PK 컬럼 키. 여러 개 넘기면 복합 PK. CUD 의 output(pkColNames)·include 의 FK↔PK 매칭에 사용.
+- `indexes(fn: (i) => IndexBuilder[])` — 인덱스 배열. `i` 는 `createIndexFactory()` 결과(`i.index(...cols)`). DDL `addIndex` 생성에 사용.
+- `relations(fn: (r) => Record<string, 관계빌더>)` — FK/역참조 관계. `r` 는 Table 일 때 foreignKey/foreignKeyTarget/relationKey/relationKeyTarget 모두 제공. include() 자동 조인의 근거.
+
+추론 전용 가상 프로퍼티(런타임 값 없음, 타입만): `$inferSelect`(컬럼+관계, 관계는 optional), `$inferColumns`(컬럼만), `$inferInsert`(autoIncrement/nullable/default 제외 시 필수), `$inferUpdate`(전부 optional).
 
 ```typescript
-const User = Table("User")
+const Post = Table("Post")
   .database("mydb")
   .columns((c) => ({
     id: c.bigint().autoIncrement(),
-    name: c.varchar(100),
-    email: c.varchar(200).nullable(),
+    authorId: c.bigint(),
+    title: c.varchar(200),
+    content: c.text().nullable(),
   }))
   .primaryKey("id")
-  .indexes((i) => [i.index("email").unique()])
-  .relations((r) => ({ posts: r.foreignKeyTarget(() => Post, "author") }));
+  .indexes((i) => [i.index("authorId")])
+  .relations((r) => ({ author: r.foreignKey(["authorId"], () => User) }));
 ```
 
 ## View / ViewBuilder
 
-뷰 정의 빌더. SELECT Queryable 로 데이터 소스를 정의. 관계는 RelationKey 만 가능(DB FK 미생성).
+`View(name)` → `ViewBuilder`. `query()` 로 SELECT Queryable 을 데이터 소스로 지정. View 는 컬럼 추론을 query 결과 타입(`TData`)에서 얻고, FK 는 등록하지 않으므로 관계는 relationKey 계열만 쓴다.
 
-- `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: string): ViewBuilder` — 빈 View 빌더.
+- `description(desc)` / `database(db)` / `schema(schema)` — Table 과 동일 의미.
+- `query<TViewData, TDb>(viewFn: (db: TDb) => Queryable<TViewData, any>)` — View 본문 SELECT. `db` 는 DbContext, 반환 Queryable 의 컬럼 구조가 View 컬럼이 됨. `queryable()` 등록 시 이 viewFn 을 실행해 컬럼 alias 를 재배치함.
+- `relations(fn: (r) => ...)` — 관계 정의. View 의 `r` 은 relationKey/relationKeyTarget 만 제공(DB FK 미생성). 반환 타입에 관계가 합쳐짐(`TData & InferDeepRelations`).
 
 ```typescript
 const ActiveUsers = View("ActiveUsers")
   .database("mydb")
-  .query((db: MyDb) => db.user().where((u) => [expr.eq(u.status, "active")]));
+  .query((db: MyDb) =>
+    db.user()
+      .where((u) => [expr.eq(u.isActive, true)])
+      .select((u) => ({ id: u.id, name: u.name })),
+  );
 ```
 
 ## Procedure / ProcedureBuilder
 
-저장 프로시저 정의 빌더. `DbContext.executable()` 로 등록해 `Executable` 로 실행.
+`Procedure(name)` → `ProcedureBuilder`. 파라미터·반환 컬럼·본문 SQL 을 정의. `DbContext.executable()` 로 등록해 `Executable` 로 실행한다.
 
-- `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: string): ProcedureBuilder<never, never>` — 빈 프로시저 빌더.
+- `description(desc)` / `database(db)` / `schema(schema)` — Table 과 동일 의미.
+- `params(fn: (c) => Record<string, ColumnBuilder>)` — 입력 파라미터. `c` 는 컬럼 factory. dialect별 호출 구문 차이(MSSQL `@param`, MySQL/PG `param`) 주의.
+- `returns(fn: (c) => ...)` — 반환 결과 컬럼. 결과 행 타입 추론에 사용.
+- `body(sql: string)` — 본문 SQL(메타 키는 `query`). dialect별 구문 차이(MSSQL `@param`·`[User]`, PG `RETURN QUERY`) 주의.
 
 ```typescript
 const GetUserById = Procedure("GetUserById")
@@ -73,49 +70,51 @@ const GetUserById = Procedure("GetUserById")
 
 ## 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?`).
+`createColumnFactory()` 가 타입별 컬럼 생성 메서드를 반환하고, 각 메서드의 결과 `ColumnBuilder` 에 수식자를 체이닝한다.
+
+타입 메서드(전부 인자 없음, decimal/varchar/char 제외):
+
+- `int()` — INT(4B, ±2^31). 일반 정수.
+- `bigint()` — BIGINT(8B, ±2^63). ID·대용량 정수.
+- `float()` — FLOAT(4B 단정밀도). 근사 실수.
+- `double()` — DOUBLE(8B 배정밀도). 근사 실수 고정밀.
+- `decimal(precision, scale?)` — DECIMAL 고정소수점. `precision`=전체 자릿수, `scale`=소수 자릿수. 금액 등 정확값.
+- `varchar(length)` — 가변 길이 문자열. `length`=최대 길이.
+- `char(length)` — 고정 길이 문자열. `length`=고정 길이. 코드값 등.
+- `text()` — 대용량 텍스트(TEXT/LONGTEXT).
+- `binary()` — 바이너리(MySQL LONGBLOB / MSSQL VARBINARY(MAX) / PG BYTEA). 값 타입 `Bytes`.
+- `boolean()` — 불리언(MySQL TINYINT(1) / MSSQL BIT / PG BOOLEAN).
+- `datetime()` — 날짜+시간(`DateTime`).
+- `date()` — 날짜만(`DateOnly`).
+- `time()` — 시간만(`Time`).
+- `uuid()` — UUID(MySQL BINARY(16) / MSSQL UNIQUEIDENTIFIER / PG UUID). 값 타입 `Uuid`.
+
+수식자(`ColumnBuilder` 메서드):
+
+- `autoIncrement()` — 자동 증가. INSERT 추론에서 optional 처리, CUD output 의 aiColName 으로 식별. PK 자동키에.
+- `nullable()` — NULL 허용. 값 타입에 `undefined` 추가, INSERT 추론에서 optional. "값 없음" 가능 컬럼에.
+- `default(value)` — DDL 기본값. INSERT 추론에서 optional 처리. `"CURRENT_TIMESTAMP"` 같은 식 문자열도 허용.
+- `description(desc)` — 컬럼 코멘트.
 
 ```typescript
 .columns((c) => ({
   id: c.bigint().autoIncrement(),
-  status: c.varchar(20).default("active"),
   email: c.varchar(200).nullable(),
+  status: c.varchar(20).default("active"),
 }))
 ```
 
+추론 유틸 타입: `ColumnBuilderRecord`(컬럼 레코드), `InferColumns`(값 타입), `InferColumnExprs`(ExprInput 타입), `InferInsertColumns`/`InferUpdateColumns`/`RequiredInsertKeys`/`OptionalInsertKeys`(INSERT/UPDATE 추론), `DataToColumnBuilderRecord`(데이터→컬럼 변환, `insertInto` 대상 검증용).
+
 ## IndexBuilder / createIndexFactory
 
-`indexes()` 콜백의 `i` factory.
+`createIndexFactory<TColumnKey>()` → `{ index(...columns) }`. 반환 `IndexBuilder` 에 수식자 체이닝.
 
-- `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?`.
+- `index(...columns): IndexBuilder` — 인덱스 컬럼 지정(복합 가능).
+- `name(name)` — 인덱스 이름. 미지정 시 DDL 생성기가 자동 작명.
+- `unique()` — 유니크 인덱스. 중복 방지 제약.
+- `orderBy(...orderBy)` — 컬럼별 정렬 방향. 각 값 `"ASC"|"DESC"`, 컬럼 수와 개수 일치 필요. 정렬 최적화 인덱스에.
+- `description(description)` — 인덱스 코멘트.
 
 ```typescript
 .indexes((i) => [
@@ -124,39 +123,25 @@ modifier(생성된 ColumnBuilder 에 체이닝):
 ])
 ```
 
-## 관계 빌더 (relations 콜백의 r factory)
-
-Table 의 `relations()` 는 FK+RelationKey 둘 다, View 의 `relations()` 는 RelationKey 만 사용 가능.
+## 관계 빌더 (foreignKey / foreignKeyTarget / relationKey / relationKeyTarget)
 
-- `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`.
+`createRelationFactory(ownerFn)` 가 owner 종류에 따라 다른 factory 를 반환: Table 이면 FK 4종 전부, View 이면 relationKey 계열 2종만. `relations()` 콜백의 `r` 가 이 factory. 대상 테이블은 순환 참조 방지를 위해 `() => Table` 지연 함수로 전달.
 
-각 관계 빌더의 `meta`:
-- `ForeignKeyBuilder.meta` / `RelationKeyBuilder.meta` — `ownerFn`/`columns`/`targetFn`/`description?`.
-- `ForeignKeyTargetBuilder.meta` / `RelationKeyTargetBuilder.meta` — `targetTableFn`/`relationName`/`description?`/`isSingle?`.
-
-> 주의: `description`/`single` 은 메서드 체이닝(`.description()`)이 아니라 factory 의 `opts` 인자로 전달한다(순환 참조 TS7022 회피).
+- `r.foreignKey(columns, () => Target, opts?)` — N:1 FK 관계(DB FK 제약 생성). `columns`=현재 테이블의 FK 컬럼들. `opts.description`=관계 설명. include 시 단일 객체로 로드. → `ForeignKeyBuilder`.
+- `r.foreignKeyTarget(() => Target, relationName, opts?)` — 1:N 역참조(DB FK 미생성, 상대 FK 를 역으로 봄). `relationName`=상대 테이블의 FK 관계 이름. `opts.single:true`=1:1 단일 객체로 로드(미지정/false 면 배열). `opts.description`=설명. → `ForeignKeyTargetBuilder`.
+- `r.relationKey(columns, () => Target, opts?)` — N:1 논리 관계(DB FK 미생성). foreignKey 와 동일하나 제약 없음. View 에서도 사용 가능. → `RelationKeyBuilder`.
+- `r.relationKeyTarget(() => Target, relationName, opts?)` — 1:N 논리 역참조(DB FK 미생성). foreignKeyTarget 과 동일. `opts.single`/`opts.description` 동일. View 에서도 사용 가능. → `RelationKeyTargetBuilder`.
 
 ```typescript
-const Post = Table("Post")
-  .columns((c) => ({ id: c.bigint().autoIncrement(), authorId: c.bigint() }))
-  .primaryKey("id")
-  .relations((r) => ({ author: r.foreignKey(["authorId"], () => User, { description: "작성자" }) }));
+// 자식 테이블: N:1
+.relations((r) => ({ author: r.foreignKey(["authorId"], () => User, { description: "작성자" }) }))
+// 부모 테이블: 1:N 역참조 + 1:1 단일
+.relations((r) => ({
+  posts: r.foreignKeyTarget(() => Post, "author"),
+  profile: r.foreignKeyTarget(() => Profile, "user", { single: true }),
+}))
 ```
 
-## 타입 추론 유틸 / 레코드 타입
-
-빌더에서 export 되는 추론 헬퍼·레코드 타입(직접 타입 작성 시):
+빌더 클래스(메타만 보관, 메서드 없음): `ForeignKeyBuilder`/`ForeignKeyTargetBuilder`/`RelationKeyBuilder`/`RelationKeyTargetBuilder`. 추론 타입: `RelationBuilderRecord`, `InferDeepRelations`(관계를 optional 로, 같은 테이블 재방문 시 순환 절단), `ExtractRelationTarget`/`ExtractRelationTargetResult`.
 
-- `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) 대상 타입 추출.
+> 주의: description/single 은 반드시 factory `opts` 인자로 전달한다. `.description()`·`.single()` 메서드 체이닝은 TS 순환 참조(TS7022) 때문에 제거되어 존재하지 않는다.

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

@@ -1,52 +1,62 @@
-# @simplysm/orm-common — QueryDef / Expr / Column 타입
-
-executor·QueryBuilder 를 직접 구현하거나 AST·결과 메타를 다룰 때 참조하는 저수준 타입군. 일반 쿼리 작성에선 직접 쓸 일이 적다.
-
-## Column / DataType 타입
-
-- `type DataType` — SQL 데이터 타입 union: `{type:"int"}`/`{type:"bigint"}`/`{type:"float"}`/`{type:"double"}`/`{type:"decimal";precision;scale?}`/`{type:"varchar";length}`/`{type:"char";length}`/`{type:"text"}`/`{type:"binary"}`/`{type:"boolean"}`/`{type:"datetime"}`/`{type:"date"}`/`{type:"time"}`/`{type:"uuid"}`.
-- `type ColumnPrimitiveMap` — TS 타입 이름 → 실제 타입: `string`/`number`/`boolean`/`DateTime`/`DateOnly`/`Time`/`Uuid`/`Bytes`.
-- `type ColumnPrimitiveStr` — 위 키(`"string"|"number"|...`).
-- `type ColumnPrimitive` — 모든 원시 값 union + `undefined`(NULL 표현).
-- `const dataTypeStrToColumnPrimitiveStr` — SQL 타입명 → TS 타입명 매핑 객체(`int`→`"number"`, `datetime`→`"DateTime"` 등).
-- `type InferColumnPrimitiveFromDataType<T>` — `DataType` → TS 타입 추론(`cast` 결과 타입).
-- `inferColumnPrimitiveStr(value): ColumnPrimitiveStr` — 런타임 값에서 타입명 추론. NULL 이면 throw(추론 불가).
-- `interface ColumnMeta` — column 메타: `type: ColumnPrimitiveStr`/`dataType: DataType`/`autoIncrement?`/`nullable?`/`default?`/`description?`.
-
-## Database / Executor / 결과 타입
-
-- `type Dialect = "mysql" | "mssql" | "postgresql"` — 지원 dialect.
-- `const dialects: Dialect[]` — 전체 dialect 목록(dialect별 테스트 루프용).
-- `type IsolationLevel` — 격리 수준: `"READ_UNCOMMITTED"`(dirty read 허용)/`"READ_COMMITTED"`(기본, 커밋된 것만)/`"REPEATABLE_READ"`(반복 읽기 일관)/`"SERIALIZABLE"`(완전 직렬화·가장 엄격).
-- `type DataRecord` — 재귀 결과 레코드(`ColumnPrimitive | DataRecord | DataRecord[]`). include 중첩 표현.
-- `interface DbContextExecutor` — DB I/O 주입 인터페이스: `connect()`/`close()`/`beginTransaction(isolationLevel?)`/`commitTransaction()`/`rollbackTransaction()`/`executeDefs(defs, resultMetas?)`.
-- `interface ResultMeta` — 결과 변환 메타: `columns: Record<string, ColumnPrimitiveStr>`(키→타입)/`joins: Record<string, {isSingle}>`(조인 alias→단일/배열). `parseQueryResult` 입력.
-- `interface QueryBuildResult` — `QueryBuilder.build()` 반환: `sql: string`/`resultSetIndex?`(가져올 결과셋, 기본 0)/`resultSetStride?`(N번째마다 추출, MySQL 배치 INSERT 용).
-- `interface Migration` — `name: string`/`up: (db) => Promise<void>`.
-
-## Expr AST 타입
-
-`type Expr` — 전체 표현식 union. `type WhereExpr` — WHERE 전용 union(비교+논리). 각 멤버는 `type` 판별자 + 인자 필드를 가진 인터페이스. 모두 `type` 리터럴로 구분되며, 사용자는 `expr.*` 빌더로 생성하므로 직접 만들 일은 거의 없음.
-
-- 값: `ExprColumn`(`path: string[]`) / `ExprValue`(`value`) / `ExprRaw`(`sql`/`params`).
-- 비교(WhereExpr): `ExprEq`/`ExprGt`/`ExprLt`/`ExprGte`/`ExprLte`(각 `source`/`target`), `ExprBetween`(`source`/`from?`/`to?`), `ExprIsNull`(`arg`), `ExprLike`/`ExprRegexp`(`source`/`pattern`), `ExprIn`(`source`/`values`), `ExprInQuery`(`source`/`query`), `ExprExists`(`query`).
-- 논리(WhereExpr): `ExprNot`(`arg`), `ExprAnd`/`ExprOr`(`conditions`).
-- 문자열: `ExprConcat`/`ExprLeft`/`ExprRight`/`ExprTrim`/`ExprPadStart`/`ExprReplace`/`ExprUpper`/`ExprLower`/`ExprLength`/`ExprByteLength`/`ExprSubstring`/`ExprIndexOf`.
-- 숫자: `ExprAbs`/`ExprRound`(`digits`)/`ExprCeil`/`ExprFloor`.
-- 날짜: `ExprYear`/`ExprMonth`/`ExprDay`/`ExprHour`/`ExprMinute`/`ExprSecond`/`ExprIsoWeek`/`ExprIsoWeekStartDate`/`ExprIsoYearMonth`/`ExprDateDiff`(`unit`/`from`/`to`)/`ExprDateAdd`(`unit`/`source`/`value`)/`ExprFormatDate`(`format`).
-- 조건: `ExprCoalesce`/`ExprNullIf`/`ExprIs`/`ExprSwitch`(`cases`/`else`)/`ExprIf`(`condition`/`then`/`else?`).
-- 집계: `ExprCount`(`arg?`/`distinct?`)/`ExprSum`/`ExprAvg`/`ExprMax`/`ExprMin`.
-- 기타: `ExprGreatest`/`ExprLeast`/`ExprRowNum`/`ExprRandom`/`ExprCast`(`source`/`targetType`).
-- Window: `ExprWindow`(`fn: WinFn`/`spec: WinSpec`). `WinFn` union = `WinFnRowNumber`/`WinFnRank`/`WinFnDenseRank`/`WinFnNtile`(`n`)/`WinFnLag`/`WinFnLead`(`column`/`offset?`/`default?`)/`WinFnFirstValue`/`WinFnLastValue`/`WinFnSum`/`WinFnAvg`/`WinFnCount`/`WinFnMin`/`WinFnMax`. `WinSpec` = `{ partitionBy?: Expr[]; orderBy?: [Expr, ("ASC"|"DESC")?][] }`.
-- 시스템: `ExprSubquery`(`queryDef`).
-- `type DateUnit = "year"|"month"|"day"|"hour"|"minute"|"second"`.
-
-## QueryDef AST 타입
-
-`type QueryDef` — 전체 쿼리 정의 union(DML+DDL+Utils+Meta). `executeDefs`/`build` 입력.
-
-- DML: `SelectQueryDef`(`from`/`as`/`select?`/`distinct?`/`top?`/`lock?`/`where?`/`joins?`/`orderBy?`/`limit?`/`groupBy?`/`having?`/`with?`), `SelectQueryDefJoin`(+`isSingle?`), `InsertQueryDef`(`records`/`overrideIdentity?`/`output?`), `InsertIfNotExistsQueryDef`(`record`/`existsSelectQuery`), `InsertIntoQueryDef`(`recordsSelectQuery`), `UpdateQueryDef`(`record`/`where?`/`joins?`...), `DeleteQueryDef`, `UpsertQueryDef`(`existsSelectQuery`/`insertRecord`/`updateRecord`).
-- DDL: `ClearSchemaQueryDef`, `CreateTableQueryDef`(`columns`/`primaryKey?`)/`DropTableQueryDef`/`RenameTableQueryDef`/`TruncateQueryDef`, `AddColumnQueryDef`/`DropColumnQueryDef`/`ModifyColumnQueryDef`/`RenameColumnQueryDef`, `AddPrimaryKeyQueryDef`/`DropPrimaryKeyQueryDef`, `AddForeignKeyQueryDef`(`foreignKey: {name/fkColumns/targetTable/targetPkColumns}`)/`DropForeignKeyQueryDef`, `AddIndexQueryDef`(`index: {name/columns/unique?}`)/`DropIndexQueryDef`, `CreateViewQueryDef`/`DropViewQueryDef`, `CreateProcQueryDef`(`params?`/`returns?`/`query`)/`DropProcQueryDef`/`ExecProcQueryDef`(`params`).
-- Utils/Meta: `SwitchFkQueryDef`(`enabled`), `SchemaExistsQueryDef`.
-- 공통: `QueryDefObjectName`(`database?`/`schema?`/`name`) — DB 객체 이름(MySQL=`db.name`, MSSQL=`db.schema.name`, PG=`schema.name`). `CudOutputDef`(`columns`/`pkColNames`/`aiColName?`) — CUD OUTPUT 절.
-- `const DDL_TYPES` — DDL 타입명 배열(트랜잭션 내 DDL 차단 검사용. `switchFk` 는 제외 — 트랜잭션 내 허용). `type DdlType` — 그 union.
+# @simplysm/orm-common — 타입·실행 엔진 내부
+
+executor·어댑터를 구현하거나 QueryDef/Expr AST·결과 메타를 직접 다루고, QueryDef 를 dialect SQL 로 렌더링하거나 raw 결과를 TS 객체로 환원할 때 참조하는 묶음. 일반 쿼리 작성에서는 expr/Queryable 가 이 타입들을 가려주므로 직접 쓸 일이 적다.
+
+## Column 타입
+
+- `type DataType` — SQL 타입 union. `{type:"int"}`/`{type:"bigint"}`/`{type:"float"}`/`{type:"double"}`/`{type:"decimal";precision;scale?}`/`{type:"varchar";length}`/`{type:"char";length}`/`{type:"text"}`/`{type:"binary"}`/`{type:"boolean"}`/`{type:"datetime"}`/`{type:"date"}`/`{type:"time"}`/`{type:"uuid"}`. cast/DDL 에서 사용.
+- `type ColumnPrimitiveMap` — TS 타입 이름→실제 타입(`string`/`number`/`boolean`/`DateTime`/`DateOnly`/`Time`/`Uuid`/`Bytes`).
+- `type ColumnPrimitiveStr` — 위 맵의 키(`"string"` 등). ExprUnit.dataType 의 타입.
+- `type ColumnPrimitive` — 저장 가능한 모든 원시값 `| undefined`(undefined=NULL).
+- `const dataTypeStrToColumnPrimitiveStr` — SQL 타입명→TS 타입명 매핑 객체(`int→"number"`, `datetime→"DateTime"` 등).
+- `type InferColumnPrimitiveFromDataType<T>` — DataType 에서 TS 타입 추론(cast 결과 타입).
+- `function inferColumnPrimitiveStr(value): ColumnPrimitiveStr` — 런타임 값에서 타입명 추론. NULL 이면 throw(추론 불가).
+- `interface ColumnMeta` — 컬럼 메타: `type`(ColumnPrimitiveStr), `dataType`, `autoIncrement?`, `nullable?`, `default?`, `description?`.
+
+## Database 타입
+
+- `type Dialect = "mysql" | "mssql" | "postgresql"` — 지원 DBMS.
+- `const dialects: Dialect[]` — 전 dialect 목록(테스트 `it.each` 등에).
+- `type IsolationLevel` — `"READ_UNCOMMITTED"|"READ_COMMITTED"|"REPEATABLE_READ"|"SERIALIZABLE"`. 트랜잭션 격리(엄격도 순).
+- `type DataRecord` — 재귀 결과 행 타입(`{ [k]: ColumnPrimitive | DataRecord | DataRecord[] }`). include 중첩 표현.
+- `interface QueryBuildResult` — QueryBuilder.build() 반환: `sql`(렌더된 SQL), `resultSetIndex?`(가져올 결과셋 인덱스, 기본 0), `resultSetStride?`(N번째마다 추출, MySQL 배치 INSERT 의 SELECT 만 모을 때).
+- `interface ResultMeta` — 결과 변환 메타: `columns`(컬럼키→ColumnPrimitiveStr), `joins`(조인키→`{isSingle}`). `parseQueryResult` 입력.
+
+## Executor / Migration 인터페이스
+
+- `interface DbContextExecutor` — DB 연결·실행 계약(orm-node 등이 구현). `connect()`/`close()`/`beginTransaction(isolationLevel?)`/`commitTransaction()`/`rollbackTransaction()`/`executeDefs<T>(defs, resultMetas?): Promise<T[][]>`. 새 DB 어댑터 작성 시 이 면을 채움.
+- `interface Migration` — `{ name; up(db) }` ([db-context.md](./db-context.md) 참조).
+
+## QueryDef AST
+
+`type QueryDef` 는 DML+DDL+Utils+Meta 의 union. executor 의 `executeDefs` 가 받고 QueryBuilder 가 SQL 로 변환.
+
+- 공통: `interface QueryDefObjectName` — `{ database?; schema?; name }`(dialect별 네임스페이스: MySQL `db.name`, MSSQL `db.schema.name`, PG `schema.name`). `interface CudOutputDef` — `{ columns; pkColNames; aiColName? }`(CUD OUTPUT).
+- DML: `SelectQueryDef`(from/select/where/joins/orderBy/limit/groupBy/having/with/distinct/top/lock), `SelectQueryDefJoin`(+`isSingle?`), `InsertQueryDef`(records/overrideIdentity?/output?), `InsertIfNotExistsQueryDef`(record/existsSelectQuery), `InsertIntoQueryDef`(recordsSelectQuery), `UpdateQueryDef`(record/where/joins), `DeleteQueryDef`, `UpsertQueryDef`(existsSelectQuery/insertRecord/updateRecord).
+- DDL: `ClearSchemaQueryDef`, `CreateTableQueryDef`/`DropTableQueryDef`/`RenameTableQueryDef`/`TruncateQueryDef`, `AddColumnQueryDef`/`DropColumnQueryDef`/`ModifyColumnQueryDef`/`RenameColumnQueryDef`, `AddPrimaryKeyQueryDef`/`DropPrimaryKeyQueryDef`/`AddForeignKeyQueryDef`/`DropForeignKeyQueryDef`/`AddIndexQueryDef`/`DropIndexQueryDef`, `CreateViewQueryDef`/`DropViewQueryDef`/`CreateProcQueryDef`/`DropProcQueryDef`/`ExecProcQueryDef`.
+- Utils/Meta: `SwitchFkQueryDef`(`table`/`enabled`), `SchemaExistsQueryDef`.
+- `const DDL_TYPES` — DDL QueryDef 의 `type` 문자열 배열(`switchFk` 제외 — 트랜잭션 내 허용). `transact` 중 DDL 차단 검사·검증에. `type DdlType` — 그 union.
+
+## Expr AST
+
+- `type Expr` — 값/문자열/숫자/날짜/조건/집계/window 표현식의 전체 union.
+- `type WhereExpr` — 비교·논리·NULL·LIKE·IN·EXISTS 등 WHERE 전용 union.
+- `type DateUnit = "year"|"month"|"day"|"hour"|"minute"|"second"` — dateDiff/dateAdd 단위.
+- `interface WinSpec` — `{ partitionBy?: Expr[]; orderBy?: [Expr, ("ASC"|"DESC")?][] }`(window OVER 절 AST).
+- 노드별 인터페이스: `ExprColumn`(`path`), `ExprValue`(`value`), `ExprRaw`(`sql`/`params`), 비교 `ExprEq`/`ExprGt`/`ExprLt`/`ExprGte`/`ExprLte`/`ExprBetween`/`ExprIsNull`/`ExprLike`/`ExprRegexp`/`ExprIn`/`ExprInQuery`/`ExprExists`, 논리 `ExprNot`/`ExprAnd`/`ExprOr`, 문자열·숫자·날짜·조건·집계·기타(`ExprConcat`...`ExprSubquery`), window `ExprWindow` 등. 각 노드는 `type` 디스크리미네이터 + 피연산자 필드를 가진 평범한 데이터 객체.
+
+## dialect QueryBuilder (SQL 렌더러)
+
+QueryDef → SQL 문자열 변환. executor 구현체가 사용.
+
+- `createQueryBuilder(dialect: Dialect): QueryBuilderBase` — dialect 에 맞는 빌더 인스턴스 생성(mysql→Mysql, mssql→Mssql, postgresql→Postgresql).
+- `abstract class QueryBuilderBase` — 렌더링 기반. `build(def): QueryBuildResult` 가 `def.type` 이름의 메서드로 동적 dispatch(미지원 타입이면 throw). 공통 절 렌더링(WHERE/ORDER BY/GROUP BY/HAVING/JOIN/FROM)은 구현, dialect 차이는 abstract(select/insert/... DML, 각 DDL, tableName/renderJoin). LATERAL/CROSS APPLY 필요 감지(`needsLateral`), 재귀 self 조인 감지(`isRecursiveSelfJoin`) 보조.
+- `class MysqlQueryBuilder` / `class MssqlQueryBuilder` / `class PostgresqlQueryBuilder` — `QueryBuilderBase` 의 dialect 구현체.
+- `abstract class ExprRendererBase` — `Expr`/`WhereExpr` 노드를 SQL 조각으로 렌더링하는 추상 기반. `class MysqlExprRenderer`/`class MssqlExprRenderer`/`class PostgresqlExprRenderer` 가 dialect 구현. QueryBuilder 내부에서 식별자 wrap·표현식 변환에 사용.
+
+## 결과 파싱 유틸
+
+executor 가 DB raw 결과를 TS 객체로 환원할 때 사용. 일반 사용자는 직접 호출하지 않음.
+
+- `parseQueryResult<T>(rawResults, meta: ResultMeta): Promise<T[] | undefined>` — flat raw 행 배열을 `meta.columns`(키→타입)로 타입 변환하고 `meta.joins`(키→`{isSingle}`)로 중첩 그룹핑. 입력이 비었거나 파싱 후 전부 빈 객체면 undefined. async 전용(100행마다 이벤트 루프 양보). `isSingle:true` 관계에 서로 다른 다건이 매칭되면 throw.
+- `pickResultSets<T>(rawResults: T[][], buildResult): T[]` — 다중 결과셋 추출. `resultSetIndex` 없으면 첫 셋, `resultSetStride` 없으면 해당 인덱스 셋, 있으면 인덱스부터 stride 간격으로 concat(MySQL 배치 INSERT 의 SELECT 결과만 모을 때).

package/claude/references/sd-simplysm14/apis/orm-node/README.md

@@ -1,53 +1,90 @@
 # @simplysm/orm-node
 
-Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실 DB(MSSQL/MySQL/PostgreSQL)에 연결해 구동하는 ORM 실행 계층. 고수준 `createOrm` 팩토리와 저수준 연결(`DbConn`) 계층을 함께 제공.
+Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실제 DB(MySQL/MSSQL/PostgreSQL)에 연결·실행하는 ORM 런타임. 고수준 진입점(`createOrm`)과 저수준 연결(`createDbConn`/`DbConn`)을 함께 제공.
 
 ## 사용 트리거 인덱스
 
-- **createOrm / Orm / OrmOptions** — `DbContext` 서브클래스 + 연결설정으로 ORM 인스턴스를 만들고 `connect`/`connectWithoutTransaction` 콜백 안에서 쿼리 실행할 때. 앱에서 ORM 을 쓰는 일반 진입점. (아래 인라인 군)
-- **저수준 DB 연결 계층** (`createDbConn`, `DbConn`, `DbConnConfig`+dialect별 Config, `NodeDbContextExecutor`, `getDialectFromConfig`, `DB_CONN_*` 상수) — ORM 추상화 없이 직접 SQL·파라미터 쿼리·bulk insert·수동 트랜잭션을 다루거나 `DbContext` 의 executor 를 직접 구성할 때. 자세히: [db-conn.md](./db-conn.md)
+- **createOrm / Orm / OrmOptions** — `DbContext` 서브클래스로 ORM 인스턴스를 만들고 트랜잭션 단위로 query 를 돌릴 때. (이 README 아래 "ORM 진입" 군)
+- **NodeDbContextExecutor** — `DbContext` 에 직접 주입할 executor 를 손수 만들 때(보통 `createOrm` 이 내부에서 처리하므로 직접 쓸 일은 드묾). (이 README 아래 "ORM 진입" 군)
+- **createDbConn / DbConn / 설정 타입 / DB_CONN_\* / getDialectFromConfig** — ORM 없이 raw SQL·bulk insert·트랜잭션을 직접 다루거나 dialect 별 연결을 손수 제어할 때. 자세히: [db-conn.md](./db-conn.md)
 
-## ORM 팩토리 (createOrm)
+## ORM 진입
 
-`DbContext` 서브클래스와 연결설정을 받아, 호출마다 새 `DbContext` 인스턴스를 만들고 트랜잭션 단위 실행을 관리하는 가장 일반적인 진입점.
+`DbContext` 서브클래스와 연결 설정을 받아 트랜잭션 경계를 관리하는 고수준 진입. query DSL 자체는 `@simplysm/orm-common` 의 `DbContext` 가 제공하고, 이 군은 그 컨텍스트를 실제 연결에 묶는 역할.
 
 ### createOrm
 
 ```typescript
-createOrm<T extends DbContext>(
+function createOrm<T extends DbContext>(
   DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T,
   config: DbConnConfig,
   options?: OrmOptions,
 ): Orm<T>
 ```
 
-- `DbClass` — `@simplysm/orm-common` 의 `DbContext` 를 상속한 사용자 클래스 생성자. 내부에서 `NodeDbContextExecutor(config)` 와 `{ database, schema }` 를 주입해 인스턴스화함.
-- `config: DbConnConfig` — DB 접속 정보. `dialect` 로 DBMS 분기. 상세 필드는 db-conn.md.
-- `options?: OrmOptions` — `config` 의 `database`/`schema` 보다 **우선** 적용(값이 있을 때만 덮어씀). 같은 `config` 로 DB/스키마만 바꿔 붙일 때 사용.
-- 반환 `Orm<T>` — 아래 필드·메서드를 가진 객체.
+`DbContext` 서브클래스를 받아 `Orm<T>` 를 반환. 인스턴스는 메서드 호출마다 새로 만들어지므로 `Orm` 객체는 재사용 가능.
 
-`database` 가 `options` 와 `config` 양쪽 모두에서 없거나 빈 문자열이면 연결 시 `"database는 필수입니다"` throw.
+- DbClass: `DbContext` 를 상속한 생성자. `executor`(연결 실행자)와 `{ database, schema? }` 를 받는 시그니처 고정. query 진입점(`this.queryable(Entity)`)을 정의한 사용자 DB 클래스를 넘김.
+- config: `DbConnConfig`(dialect 별 분기 유니온, [db-conn.md](./db-conn.md) 참조). 접속 대상·인증 정보.
+- options?: `OrmOptions`. config 의 `database`/`schema` 를 덮어쓰는 우선 옵션. 같은 접속 정보로 DB·스키마만 바꿔 쓸 때.
+
+database 해석: `options.database` → `config.database` 순으로 찾고, 둘 다 없거나 빈 문자열이면 `"database는 필수입니다"` throw. schema 도 `options.schema` → `config.schema` 순.
+
+```typescript
+class MyDb extends DbContext {
+  user = this.queryable(User);
+}
+const orm = createOrm(MyDb, { dialect: "mysql", host: "localhost", port: 3306, username: "root", password: "pw", database: "mydb" });
+await orm.connect(async (db) => db.user().execute());  // 트랜잭션 안
+```
+
+### Orm
+
+```typescript
+interface Orm<T extends DbContext> {
+  readonly DbClass; readonly config: DbConnConfig; readonly options?: OrmOptions;
+  connect<R>(callback: (conn: T) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>;
+  connectWithoutTransaction<R>(callback: (conn: T) => Promise<R>): Promise<R>;
+}
+```
+
+`createOrm` 반환 타입. 매 호출마다 DB 인스턴스를 새로 만들어 연결→콜백→정리.
+
+- connect: 콜백을 **트랜잭션 안에서** 실행. 콜백 정상 종료 시 커밋, throw 시 롤백.
+- isolationLevel?: `"READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE"`(`@simplysm/orm-common`). 트랜잭션 격리 수준. 미지정 시 연결의 `defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED`. 더티 리드를 막아야 하면 `READ_COMMITTED` 이상.
+- connectWithoutTransaction: 콜백을 **트랜잭션 없이** 실행. 콜백 내부에서 `db.transaction(...)` 으로 부분 트랜잭션을 직접 열 때 사용(examples 테스트 패턴).
+- callback: 연결된 DbContext 인스턴스(`T`)를 받아 query 를 수행하고 임의 값 `R` 을 반환. 그 반환값이 `connect`/`connectWithoutTransaction` 의 결과가 됨.
 
 ### OrmOptions
 
-- `database?: string` — DB 이름. 지정 시 `config.database` 대신 사용(우선).
-- `schema?: string` — 스키마 이름(MSSQL `dbo`, PostgreSQL `public` 등). 지정 시 `config.schema` 대신 사용(우선). MySQL 은 스키마 개념이 없어 보통 생략.
+```typescript
+interface OrmOptions { database?: string; schema?: string; }
+```
+
+`createOrm` 3번째 인자. config 보다 우선 적용.
 
-### Orm<T>
+- database?: 사용할 DB 이름. config 의 `database` 대신 쓸 때. 다중 테넌트처럼 접속 정보는 같고 DB 만 다를 때.
+- schema?: 스키마 이름(예: MSSQL `dbo`, PostgreSQL `public`). MySQL 은 스키마 개념이 없어 보통 미지정.
 
-- `DbClass` (readonly) — 생성에 쓰인 `DbContext` 생성자 그대로 노출.
-- `config` (readonly) — 생성에 쓰인 `DbConnConfig` 그대로 노출.
-- `options?` (readonly) — 생성에 쓰인 `OrmOptions` 그대로 노출.
-- `connect<R>(callback: (conn: T) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>` — 새 `DbContext` 를 만들어 **트랜잭션 안에서** 콜백 실행하고 콜백 반환값을 그대로 반환. `isolationLevel` 로 격리수준 지정(미지정 시 연결설정의 기본 격리수준). 커밋·롤백·연결 종료는 `DbContext.connect` 가 관리.
-- `connectWithoutTransaction<R>(callback: (conn: T) => Promise<R>): Promise<R>` — **트랜잭션 없이** 연결만 열고 콜백 실행. DDL 처럼 트랜잭션 밖에서 돌려야 하거나 콜백 내부에서 `db.transaction(...)` 을 직접 제어할 때 사용.
+### NodeDbContextExecutor
 
-사용 예:
+`DbContextExecutor`(`@simplysm/orm-common`) 의 Node 구현체. `createOrm` 이 내부에서 생성·주입하므로 직접 다룰 일은 드묾. `DbContext` 를 `createOrm` 없이 손수 조립할 때만 사용.
 
 ```typescript
-class MyDb extends DbContext {
-  user = this.queryable(User);
+class NodeDbContextExecutor implements DbContextExecutor {
+  constructor(config: DbConnConfig);
+  connect(): Promise<void>; close(): Promise<void>;
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(): Promise<void>; rollbackTransaction(): Promise<void>;
+  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
+  bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: DataRecord[]): Promise<void>;
+  executeDefs<T>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>;
 }
-const orm = createOrm(MyDb, { dialect: "mysql", host: "localhost", username: "root", password: "pw", database: "mydb" });
-const users = await orm.connect(async (db) => db.user().execute(), "READ_COMMITTED");
-await orm.connectWithoutTransaction(async (db) => db.transaction(async () => { /* ... */ }));
 ```
+
+- constructor(config): `DbConnConfig` 로 dialect 를 결정(`getDialectFromConfig`). `connect()` 호출 전까지 실제 연결은 열지 않음.
+- connect/close: 내부적으로 `createDbConn` 으로 연결 생성 후 open/close. `connect` 미호출 상태에서 다른 메서드 호출 시 `DB_CONN_ERRORS.NOT_CONNECTED` 로 throw.
+- begin/commit/rollbackTransaction: 연결의 트랜잭션 제어를 그대로 위임. `isolationLevel?` 은 위 `Orm.connect` 와 동일 의미.
+- executeParametrized: 파라미터 바인딩 query 1건 실행. dialect 별 placeholder 차이는 [db-conn.md](./db-conn.md) 참조.
+- bulkInsert: 네이티브 bulk API 로 대량 삽입. tableName, 컬럼명→`ColumnMeta` 매핑, 레코드 배열을 넘김.
+- executeDefs: `QueryDef[]` 를 dialect 별 query builder 로 SQL 변환 후 실행하고 `resultMetas` 로 결과 파싱. `resultMetas` 가 전부 null 이면 결과가 불필요한 것으로 보고 모든 def 를 하나의 SQL 로 합쳐 1회 실행, `defs.length` 만큼 빈 배열을 반환(인터페이스 계약 유지). 그 외엔 def 별 개별 실행.