@simplysm/sd-claude 14.0.89 → 14.0.91

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

@@ -1,64 +1,105 @@
-# @simplysm/orm-common — 스키마 정의
+# @simplysm/orm-common — 스키마 정의 (Table / View / Procedure / column / index / relation)
 
-DB 객체(Table/View/Procedure)와 그 구성요소(Column/Index/관계)를 fluent 빌더로 선언하는 묶음. 모든 빌더는 immutable — 각 메서드가 새 인스턴스를 반환한다. 정의한 빌더는 `DbContext` 안에서 `this.queryable()`/`this.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)` → `TableBuilder` 시작점. 체이닝으로 database·schema·columns·primaryKey·indexes·relations 를 붙인다.
-
-- `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() 자동 조인의 근거.
+```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;
+}
+```
 
-추론 전용 가상 프로퍼티(런타임 값 없음, 타입만): `$inferSelect`(컬럼+관계, 관계는 optional), `$inferColumns`(컬럼만), `$inferInsert`(autoIncrement/nullable/default 제외 시 필수), `$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 Post = Table("Post")
+const User = Table("User")
   .database("mydb")
   .columns((c) => ({
     id: c.bigint().autoIncrement(),
-    authorId: c.bigint(),
-    title: c.varchar(200),
-    content: c.text().nullable(),
+    name: c.varchar(100),
+    email: c.varchar(200).nullable(),
   }))
   .primaryKey("id")
-  .indexes((i) => [i.index("authorId")])
-  .relations((r) => ({ author: r.foreignKey(["authorId"], () => User) }));
+  .indexes((i) => [i.index("email").unique()]);
 ```
 
 ## View / ViewBuilder
 
-`View(name)` → `ViewBuilder`. `query()` 로 SELECT Queryable 을 데이터 소스로 지정. View 는 컬럼 추론을 query 결과 타입(`TData`)에서 얻고, FK 는 등록하지 않으므로 관계는 relationKey 계열만 쓴다.
+```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` — 빈 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`).
+- `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.isActive, true)])
-      .select((u) => ({ id: u.id, name: u.name })),
+  .query((db: MainDb) =>
+    db.user().where((u) => [expr.eq(u.status, "active")]).select((u) => ({ id: u.id, name: u.name })),
   );
 ```
 
 ## Procedure / ProcedureBuilder
 
-`Procedure(name)` → `ProcedureBuilder`. 파라미터·반환 컬럼·본문 SQL 을 정의. `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<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`) 주의.
+- `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")
@@ -68,53 +109,52 @@ const GetUserById = Procedure("GetUserById")
   .body("SELECT id, name FROM User WHERE id = userId");
 ```
 
-## ColumnBuilder / createColumnFactory
+## column factory / ColumnBuilder
 
-`createColumnFactory()` 가 타입별 컬럼 생성 메서드를 반환하고, 각 메서드의 결과 `ColumnBuilder` 에 수식자를 체이닝한다.
+`columns`/`params`/`returns` 콜백 인자 `c` 가 column factory. 각 메서드는 `ColumnBuilder` 를 반환하고 `.autoIncrement()`/`.nullable()`/`.default()`/`.description()` 로 속성을 더한다(모두 immutable).
 
-타입 메서드(전부 인자 없음, 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`=소수 자릿수. 금액 등 정확값.
+- `int()` — INT(4바이트 정수).
+- `bigint()` — BIGINT(8바이트 정수). autoIncrement PK 에 주로 사용.
+- `float()` — FLOAT(단정밀도 실수).
+- `double()` — DOUBLE(배정밀도 실수).
+- `decimal(precision, scale?)` — 고정 소수점. `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)` — 컬럼 코멘트.
+- `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(),
+  price: c.decimal(10, 2),
   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
+## index factory / IndexBuilder
 
-`createIndexFactory<TColumnKey>()` → `{ index(...columns) }`. 반환 `IndexBuilder` 에 수식자 체이닝.
+`indexes` 콜백 인자 `i` 의 `index(...columns)` 로 시작해 fluent 로 옵션을 더한다.
 
-- `index(...columns): IndexBuilder` — 인덱스 컬럼 지정(복합 가능).
-- `name(name)` — 인덱스 이름. 미지정 시 DDL 생성기가 자동 작명.
-- `unique()` — 유니크 인덱스. 중복 방지 제약.
-- `orderBy(...orderBy)` — 컬럼별 정렬 방향. 각 값 `"ASC"|"DESC"`, 컬럼 수와 개수 일치 필요. 정렬 최적화 인덱스에.
-- `description(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) => [
@@ -123,25 +163,42 @@ const GetUserById = Procedure("GetUserById")
 ])
 ```
 
-## 관계 빌더 (foreignKey / foreignKeyTarget / relationKey / relationKeyTarget)
+## relation factory
 
-`createRelationFactory(ownerFn)` 가 owner 종류에 따라 다른 factory 를 반환: Table 이면 FK 4종 전부, View 이면 relationKey 계열 2종만. `relations()` 콜백의 `r` 가 이 factory. 대상 테이블은 순환 참조 방지를 위해 `() => Table` 지연 함수로 전달.
+`relations` 콜백 인자 `r`. Table 은 4종 모두, View 는 `relationKey`/`relationKeyTarget` 만. 대상 빌더는 순환 참조 방지를 위해 모두 `() => Target` 지연 함수로 넘긴다. `description`/`single` 은 메서드 체이닝이 아니라 마지막 `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`.
+- `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`.
+
+각 `opts`:
+
+- `description?: string` — 관계 설명.
+- `single?: boolean` (target 계열만) — true=결과를 단일 객체(1:1), false/미지정=배열(1:N). `include()`/`$inferSelect` 의 해당 키 타입이 단일/배열로 갈린다.
 
 ```typescript
-// 자식 테이블: 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 }),
-}))
+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 }),
+  }));
 ```
 
-빌더 클래스(메타만 보관, 메서드 없음): `ForeignKeyBuilder`/`ForeignKeyTargetBuilder`/`RelationKeyBuilder`/`RelationKeyTargetBuilder`. 추론 타입: `RelationBuilderRecord`, `InferDeepRelations`(관계를 optional 로, 같은 테이블 재방문 시 순환 절단), `ExtractRelationTarget`/`ExtractRelationTargetResult`.
+주의: FK column 개수와 대상 테이블 PK 개수가 다르면 `include()`/join 시 "FK/PK column count mismatch" throw. PK 가 복합이면 FK column 도 같은 순서·개수로.
+
+## 빌더/추론 타입 (직접 참조 드묾)
 
-> 주의: description/single 은 반드시 factory `opts` 인자로 전달한다. `.description()`·`.single()` 메서드 체이닝은 TS 순환 참조(TS7022) 때문에 제거되어 존재하지 않는다.
+- `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` 의 관계 부분.

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

@@ -1,62 +1,67 @@
-# @simplysm/orm-common — 타입·실행 엔진 내부
+# @simplysm/orm-common — 하위 타입 / QueryDef AST / QueryBuilder / 결과 파싱
 
-executor·어댑터를 구현하거나 QueryDef/Expr AST·결과 메타를 직접 다루고, QueryDef 를 dialect SQL 로 렌더링하거나 raw 결과를 TS 객체로 환원할 때 참조하는 묶음. 일반 쿼리 작성에서는 expr/Queryable 가 이 타입들을 가려주므로 직접 쓸 일이 적다.
+executor·QueryBuilder 를 직접 구현하거나, `QueryDef`/`Expr` AST·column 타입을 다루거나, 원시 결과를 TS 객체로 환원할 때 참조하는 묶음. 일반 쿼리 작성에서는 expr/Queryable 가 이 타입들을 가려주므로 직접 쓸 일이 적다.
 
-## Column 타입
+## 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?`.
+- `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"}`. `expr.cast` 의 targetType·DDL column 정의에 사용.
+- `ColumnPrimitiveMap` — TS 타입 이름 → 실제 타입 매핑: `string→string`, `number→number`, `boolean→boolean`, `DateTime→DateTime`, `DateOnly→DateOnly`, `Time→Time`, `Uuid→Uuid`, `Bytes→Bytes`.
+- `ColumnPrimitiveStr` — `keyof ColumnPrimitiveMap`(타입 이름 문자열). `ExprUnit.dataType`·`val` 의 dataType.
+- `ColumnPrimitive` — 저장 가능한 모든 원시 값 union + `undefined`(=NULL).
+- `dataTypeStrToColumnPrimitiveStr` (const) — SQL DataType 이름 → TS 타입 이름 매핑 객체(`int→"number"`, `varchar→"string"`, `datetime→"DateTime"` 등). `cast` 가 결과 타입 결정에 사용.
+- `InferColumnPrimitiveFromDataType<T>` — `DataType` 에서 TS 값 타입 추론.
+- `inferColumnPrimitiveStr(value)` — 런타임 값에서 `ColumnPrimitiveStr` 추론. NULL 이면 추론 불가 throw.
+- `ColumnMeta` — column 메타: `{ type: ColumnPrimitiveStr; dataType: DataType; autoIncrement?; nullable?; default?; description? }`. `ColumnBuilder.meta` 타입.
 
-## Database 타입
+## db 타입
 
-- `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` 입력.
+- `Dialect` — `"mysql" | "mssql" | "postgresql"`. 지원 DBMS(MySQL 8.0.14+, MSSQL 2012+, PostgreSQL 9.0+).
+- `dialects` (const) — `Dialect[]`(전체 목록). dialect별 테스트 매트릭스에 사용.
+- `DataRecord` — 재귀 결과 레코드 타입: `{ [key: string]: ColumnPrimitive | DataRecord | DataRecord[] }`. include 중첩(단일 객체/배열)을 표현.
+- `QueryBuildResult` — `build()` 반환: `{ sql: string; resultSetIndex?: number; resultSetStride?: number }`. `resultSetIndex`=결과를 가져올 셋 index(기본 0, 예 MySQL INSERT+OUTPUT 는 1). `resultSetStride`=다중 결과에서 N번째마다 추출(MySQL 배치 INSERT 의 `INSERT;SELECT;...` 에서 SELECT 만 모을 때).
+- `IsolationLevel` — 트랜잭션 격리 수준(자세히는 [db-context.md](./db-context.md)).
+- `DbContextExecutor` / `ResultMeta` / `Migration` — executor·결과 메타·마이그레이션 정의. [db-context.md](./db-context.md) 참조.
 
-## Executor / Migration 인터페이스
+## QueryDef AST (query-def.ts)
 
-- `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) 참조).
+`executeDefs`/`build` 가 다루는 쿼리 정의 AST. `Queryable.getXQueryDef()`·`DbContext.getXQueryDef()` 가 생성.
 
-## QueryDef AST
+- `QueryDefObjectName` — `{ database?; schema?; name }`. DB 객체 네임스페이스(MySQL `database.name`, MSSQL `database.schema.name`, PostgreSQL `schema.name`).
+- DML: `SelectQueryDef`(from/as/select/distinct/top/lock/where/joins/orderBy/limit/groupBy/having/with), `SelectQueryDefJoin`(SelectQueryDef + `isSingle?`), `InsertQueryDef`(records/overrideIdentity?/output?), `InsertIfNotExistsQueryDef`, `InsertIntoQueryDef`, `UpdateQueryDef`, `DeleteQueryDef`, `UpsertQueryDef`.
+- `CudOutputDef` — CUD OUTPUT 절: `{ columns: string[]; pkColNames: string[]; aiColName? }`. 삽입/갱신/삭제 행 회수 정의.
+- 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 }`, DDL 아님 — 트랜잭션 가능), `SchemaExistsQueryDef`.
+- `DDL_TYPES` (const) — DDL QueryDef type 문자열 배열. 트랜잭션 중 DDL 차단 판정(`switchFk` 는 제외)에 사용.
+- `DdlType` — `(typeof DDL_TYPES)[number]`.
+- `QueryDef` — 전체 union(DML + DDL + SwitchFk + SchemaExists). `executeDefs(defs: QueryDef[])` 의 원소 타입.
 
-`type QueryDef` 는 DML+DDL+Utils+Meta 의 union. executor 의 `executeDefs` 가 받고 QueryBuilder 가 SQL 로 변환.
+## Expr AST (expr.ts)
 
-- 공통: `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.
+`ExprUnit.expr`/`WhereExprUnit.expr` 가 담는 JSON AST. QueryBuilder 의 ExprRenderer 가 SQL 로 변환.
 
-## Expr AST
+- `Expr` — 전체 표현식 union(값 `ExprColumn`/`ExprValue`/`ExprRaw`, 문자열/숫자/날짜/조건/집계/기타/window `ExprWindow`/시스템 `ExprSubquery`). select/orderBy 등.
+- `WhereExpr` — WHERE 전용 union(비교 `ExprEq`/`ExprGt`/.../`ExprIn`/`ExprInQuery`/`ExprExists` + 논리 `ExprNot`/`ExprAnd`/`ExprOr`). where/having.
+- 개별 인터페이스(`ExprEq`, `ExprConcat`, `ExprCount`, `ExprCast`, `ExprWindow` 등) — 각 `expr.*` 함수가 만드는 노드. `type` discriminant + 피연산자 필드.
+- `DateUnit` — `"year"|"month"|"day"|"hour"|"minute"|"second"`. dateDiff/dateAdd.
+- `WinFn` — window 함수 노드 union(`WinFnRowNumber`/`WinFnRank`/`WinFnLag`/`WinFnSum`/...). `WinSpec` — `{ partitionBy?: Expr[]; orderBy?: [Expr,("ASC"|"DESC")?][] }`(OVER 절).
 
-- `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` 디스크리미네이터 + 피연산자 필드를 가진 평범한 데이터 객체.
+## QueryBuilder (QueryDef → SQL)
 
-## dialect QueryBuilder (SQL 렌더러)
+직접 SQL 문자열이 필요하거나 dialect 동작을 검증할 때.
 
-QueryDef → SQL 문자열 변환. executor 구현체가 사용.
+- `createQueryBuilder(dialect: Dialect): QueryBuilderBase` — dialect 에 맞는 QueryBuilder 생성(`mysql`→Mysql, `mssql`→Mssql, `postgresql`→Postgresql).
+- `QueryBuilderBase` (abstract) — `build(def: QueryDef): QueryBuildResult` 가 공개 진입점. `def.type` 으로 동적 dispatch. 나머지는 protected/abstract(dialect 구현).
+- `MysqlQueryBuilder` / `MssqlQueryBuilder` / `PostgresqlQueryBuilder` — dialect별 구현. 보통 `createQueryBuilder` 로 얻음.
+- `ExprRendererBase` (abstract) — Expr→SQL 렌더러. `render(expr): string`, `renderWhere(exprs): string` 공개. `wrap(name)`/`escapeString`/`escapeValue` 는 dialect abstract.
+- `MysqlExprRenderer` / `MssqlExprRenderer` / `PostgresqlExprRenderer` — dialect별 렌더러.
 
-- `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·표현식 변환에 사용.
+```typescript
+const sql = createQueryBuilder("mysql").build(queryable.getSelectQueryDef()).sql;
+```
 
-## 결과 파싱 유틸
+## 결과 파싱
 
-executor 가 DB raw 결과를 TS 객체로 환원할 때 사용. 일반 사용자는 직접 호출하지 않음.
+executor 가 원시 행을 받은 뒤 `ResultMeta` 로 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 결과만 모을 때).
+- `parseQueryResult<T>(rawResults, meta): Promise<T[] | undefined>` — 원시 결과 배열 + `ResultMeta` 로 타입 변환·JOIN 중첩. JOIN 없으면 단순 파싱, 있으면 그룹키 기준 재귀 그룹핑(O(n) Map). 입력 비었거나 파싱 후 전부 빈 객체면 `undefined`. 100건마다 이벤트 루프 양보(async 전용). isSingle 관계에 서로 다른 결과가 섞이면 throw.
+- `pickResultSets<T>(rawResults, buildResult): T[]` — 다중 결과셋에서 `QueryBuildResult` 의 `resultSetIndex`/`resultSetStride` 에 따라 필요한 셋만 추출. index 없으면 첫 셋, stride 없으면 index 셋 단일, stride 있으면 index 부터 stride 간격으로 concat(MySQL 배치 INSERT 의 SELECT 만 모을 때).

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

@@ -1,16 +1,16 @@
 # @simplysm/orm-node
 
-Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실제 DB(MySQL/MSSQL/PostgreSQL)에 연결·실행하는 ORM 런타임. 고수준 진입점(`createOrm`)과 저수준 연결(`createDbConn`/`DbConn`)을 함께 제공.
+Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실제 DB(MySQL/MSSQL/PostgreSQL)에 연결·실행하는 ORM 런타임. 고수준 진입점(`createOrm`)과 저수준 연결(`createDbConn`/`DbConn`)을 함께 노출.
 
 ## 사용 트리거 인덱스
 
-- **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)
+- **createOrm / Orm / OrmOptions** — `DbContext` 서브클래스로 ORM 인스턴스를 만들고 `connect`/`connectWithoutTransaction` 으로 트랜잭션 경계를 잡아 query 를 돌릴 때. (아래 "ORM 진입" 군)
+- **NodeDbContextExecutor** — `DbContext` 에 직접 주입할 executor 를 손수 만들 때(`createOrm` 이 내부에서 자동 생성하므로 직접 쓸 일은 드묾). (아래 "ORM 진입" 군 및 db-conn.md)
+- **createDbConn / DbConn / DbConnConfig 계열 / getDialectFromConfig / DB_CONN_\* 상수** — ORM 없이 raw SQL·파라미터 쿼리·bulk insert·수동 트랜잭션을 직접 다루거나 dialect별 접속 설정을 작성할 때. 자세히: [db-conn.md](./db-conn.md)
 
 ## ORM 진입
 
-`DbContext` 서브클래스와 연결 설정을 받아 트랜잭션 경계를 관리하는 고수준 진입. query DSL 자체는 `@simplysm/orm-common` 의 `DbContext` 가 제공하고, 이 군은 그 컨텍스트를 실제 연결에 묶는 역할.
+`DbContext` 서브클래스와 접속 설정을 받아 연결·트랜잭션 경계를 관리하는 고수준 진입. query DSL 자체는 `@simplysm/orm-common` 의 `DbContext` 가 제공하고, 이 군은 그 컨텍스트를 실제 DB 연결에 묶는 역할.
 
 ### createOrm
 
@@ -22,69 +22,69 @@ function createOrm<T extends DbContext>(
 ): Orm<T>
 ```
 
-`DbContext` 서브클래스를 받아 `Orm<T>` 를 반환. 인스턴스는 메서드 호출마다 새로 만들어지므로 `Orm` 객체는 재사용 가능.
+`DbContext` 서브클래스를 받아 `Orm<T>` 를 반환. DB 인스턴스는 `connect`/`connectWithoutTransaction` 호출마다 새로 생성되므로 반환된 `Orm` 객체 자체는 재사용 가능.
 
-- 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·스키마만 바꿔 쓸 때.
+- DbClass — `DbContext` 를 상속한 생성자. `(executor, { database, schema? })` 시그니처 고정. query 진입점(`this.queryable(Entity)`)을 정의한 사용자 DB 클래스를 넘김. 어떤 엔티티 집합을 다룰지 결정하는 자리.
+- config — `DbConnConfig`(dialect별 분기 유니온, [db-conn.md](./db-conn.md) 참조). 접속 대상·인증 정보. DBMS 종류·호스트·계정이 여기서 정해짐.
+- options? — `OrmOptions`. config 의 `database`/`schema` 를 덮어쓰는 우선 옵션. 같은 접속 정보로 DB·스키마만 바꿔 쓸 때(다중 테넌트 등) 지정.
 
-database 해석: `options.database` → `config.database` 순으로 찾고, 둘 다 없거나 빈 문자열이면 `"database는 필수입니다"` throw. schema 도 `options.schema` → `config.schema` 순.
+database 해석: `options.database` → `config.database` 순으로 찾고, 둘 다 없거나 빈 문자열이면 `"database는 필수입니다"` throw. schema 해석도 `options.schema` → `config.schema` 순(없으면 `undefined` 유지).
 
 ```typescript
-class MyDb extends DbContext {
+class TestDb 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());  // 트랜잭션 안
+const orm = createOrm(TestDb, mysqlConfig, { database: "TestDb" });
+await orm.connect(async (db) => {
+  await db.user().insert([{ id: 100, name: "orm-test" }]);
+  return db.user().execute();
+}); // 트랜잭션 안에서 실행 후 자동 커밋
 ```
 
 ### Orm
 
 ```typescript
 interface Orm<T extends DbContext> {
-  readonly DbClass; readonly config: DbConnConfig; readonly options?: OrmOptions;
+  readonly DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T;
+  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 인스턴스를 새로 만들어 연결→콜백→정리.
+`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` 의 결과가 됨.
+- DbClass / config / options — `createOrm` 에 넘긴 값을 그대로 읽기 전용으로 보관. 같은 설정으로 재연결·진단할 때 참조.
+- connect — 콜백을 **트랜잭션 안에서** 실행. 콜백이 정상 종료하면 커밋, throw 하면 롤백 후 그 오류를 다시 throw. 여러 쓰기를 원자적으로 묶어야 할 때.
+- isolationLevel? — `"READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE"`(`@simplysm/orm-common`). 트랜잭션 격리 수준. 미지정 시 연결의 `defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED`. 더티 리드를 막아야 하면 `READ_COMMITTED` 이상으로 올림.
+- connectWithoutTransaction — 콜백을 **트랜잭션 없이** 실행. 읽기 전용이거나, 콜백 내부에서 `db.transaction(...)` 으로 부분 트랜잭션을 직접 열어 일부 구간만 원자화할 때.
+- callback — 연결된 DbContext 인스턴스(`T`)를 받아 query 를 수행하고 임의 값 `R` 을 반환. 그 반환값이 `connect`/`connectWithoutTransaction` 의 결과가 됨.
+
+```typescript
+// 읽기는 트랜잭션 없이, 그 안에서 일부 쓰기만 부분 트랜잭션으로
+await orm.connectWithoutTransaction(async (db) => {
+  await db.transaction(async () => {
+    await db.user().insert([{ id: 300, name: "partial-tx" }]);
+  });
+  return db.user().execute();
+});
+```
 
 ### OrmOptions
 
 ```typescript
-interface OrmOptions { database?: string; schema?: string; }
+interface OrmOptions {
+  database?: string;
+  schema?: string;
+}
 ```
 
 `createOrm` 3번째 인자. config 보다 우선 적용.
 
-- database?: 사용할 DB 이름. config 의 `database` 대신 쓸 때. 다중 테넌트처럼 접속 정보는 같고 DB 만 다를 때.
-- schema?: 스키마 이름(예: MSSQL `dbo`, PostgreSQL `public`). MySQL 은 스키마 개념이 없어 보통 미지정.
+- database? — 사용할 DB 이름. config 의 `database` 대신 쓸 때. 접속 정보는 같고 DB 만 다른 다중 테넌트 상황에서 인스턴스별로 지정.
+- schema? — 스키마 이름(예: MSSQL `dbo`, PostgreSQL `public`). MySQL 은 스키마 개념이 없어 보통 미지정.
 
 ### NodeDbContextExecutor
 
-`DbContextExecutor`(`@simplysm/orm-common`) 의 Node 구현체. `createOrm` 이 내부에서 생성·주입하므로 직접 다룰 일은 드묾. `DbContext` 를 `createOrm` 없이 손수 조립할 때만 사용.
-
-```typescript
-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[][]>;
-}
-```
-
-- 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 별 개별 실행.
+`@simplysm/orm-common` 의 `DbContextExecutor` 를 Node 환경에서 구현한 클래스. `createOrm` 이 내부에서 생성·주입하므로 직접 다룰 일은 드묾. `DbContext` 를 `createOrm` 없이 손수 조립할 때만 사용. 생성자·메서드 전체 시그니처와 동작은 [db-conn.md](./db-conn.md) 의 동명 섹션 참조.