@simplysm/orm-common 13.0.96 → 13.0.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "13.0.96",
+  "version": "13.0.97",
   "description": "Simplysm Package - ORM Module (common)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -20,6 +20,6 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@simplysm/core-common": "13.0.96"
+    "@simplysm/core-common": "13.0.97"
   }
 }

package/README.md

@@ -1,112 +0,0 @@
-# @simplysm/orm-common
-
-플랫폼 중립적인 ORM 핵심 모듈. 스키마 정의, 타입 안전한 쿼리 빌더, DDL 관리, MySQL/PostgreSQL/MSSQL 방언 지원.
-
-## 설치
-
-```bash
-npm install @simplysm/orm-common
-```
-
-**의존성:** `@simplysm/core-common`
-
-## 문서
-
-| 카테고리 | 설명 |
-|---------|------|
-| [스키마 정의](docs/schema.md) | Table, View, Procedure, Column, Relation, Index 빌더 |
-| [쿼리 & 표현식](docs/query.md) | Queryable, Executable, expr 표현식 빌더 |
-| [DDL & 초기화](docs/ddl.md) | DDL 메서드, 스키마 초기화, 마이그레이션 |
-
-## 빠른 시작
-
-### DbContext 정의
-
-```typescript
-import { defineDbContext, createDbContext, Table, expr } from "@simplysm/orm-common";
-
-// 테이블 정의
-const User = Table("user")
-  .columns((c) => ({
-    id: c.int().autoIncrement(),
-    name: c.varchar(100),
-    email: c.varchar(200).nullable(),
-    createdAt: c.datetime(),
-  }))
-  .primaryKey("id")
-  .indexes((i) => [i.index("email").unique()]);
-
-const Order = Table("order")
-  .columns((c) => ({
-    id: c.int().autoIncrement(),
-    userId: c.int(),
-    amount: c.decimal(10, 2),
-  }))
-  .primaryKey("id")
-  .relations((r) => ({
-    user: r.foreignKey(["userId"], () => User),
-  }));
-
-// DbContext 정의 (스키마 블루프린트)
-const MyDb = defineDbContext({
-  tables: { user: User, order: Order },
-});
-
-// DbContext 인스턴스 생성 (런타임)
-const db = createDbContext(MyDb, executor, { database: "mydb" });
-```
-
-### 쿼리 실행
-
-```typescript
-await db.connect(async () => {
-  // SELECT
-  const users = await db.user()
-    .where((c) => [expr.eq(c.name, "Alice")])
-    .orderBy((c) => c.createdAt, "DESC")
-    .execute();
-
-  // JOIN (관계 기반)
-  const orders = await db.order()
-    .include((c) => c.user)
-    .where((c) => [expr.gt(c.amount, 100)])
-    .execute();
-
-  // 집계
-  const stats = await db.order()
-    .select((c) => ({
-      userId: c.userId,
-      total: expr.sum(c.amount),
-      count: expr.count(),
-    }))
-    .groupBy((c) => [c.userId])
-    .execute();
-
-  // INSERT
-  await db.user().insert([{ name: "Bob", email: "bob@example.com", createdAt: new DateTime() }]);
-
-  // INSERT 후 ID 반환
-  const [inserted] = await db.user().insert(
-    [{ name: "Charlie", createdAt: new DateTime() }],
-    ["id"],
-  );
-
-  // UPDATE
-  await db.user()
-    .where((c) => [expr.eq(c.id, 1)])
-    .update((c) => ({ name: expr.val("string", "Alice2") }));
-
-  // DELETE
-  await db.user()
-    .where((c) => [expr.eq(c.id, 1)])
-    .delete();
-});
-```
-
-### 지원 방언
-
-| 방언 | 값 | 최소 버전 |
-|------|-----|----------|
-| MySQL | `"mysql"` | 8.0.14+ |
-| MSSQL | `"mssql"` | 2012+ |
-| PostgreSQL | `"postgresql"` | 9.0+ |

package/docs/ddl.md

@@ -1,300 +0,0 @@
-# DDL & 초기화
-
-`createDbContext()`로 생성된 DbContext 인스턴스에서 사용하는 DDL 메서드.
-
-**중요:** DDL 연산은 트랜잭션 내에서 실행할 수 없다. `connectWithoutTransaction()` 내에서 사용해야 한다.
-
-## 스키마 초기화
-
-```typescript
-await db.connectWithoutTransaction(async () => {
-  // 정의된 모든 테이블/뷰/프로시저 자동 생성
-  await db.initialize();
-
-  // 기존 스키마 삭제 후 재생성
-  await db.initialize({ force: true });
-
-  // 특정 DB만 초기화
-  await db.initialize({ dbs: ["mydb"] });
-});
-```
-
-### initialize API
-
-```
-db.initialize(options?: {
-  dbs?: string[];      // 초기화할 DB 목록 (생략 시 전체)
-  force?: boolean;     // true이면 기존 스키마 삭제 후 재생성
-}): Promise<void>
-```
-
-## 테이블 DDL
-
-```typescript
-// 테이블 생성 (TableBuilder 전달)
-await db.createTable(User);
-
-// 테이블 삭제 (QueryDefObjectName 전달)
-await db.dropTable({ name: "user", database: "mydb" });
-
-// 테이블 이름 변경
-await db.renameTable({ name: "user" }, "users_v2");
-```
-
-## 컬럼 DDL
-
-```typescript
-import { createColumnFactory } from "@simplysm/orm-common";
-const c = createColumnFactory();
-
-// 컬럼 추가
-await db.addColumn({ name: "user" }, "phone", c.varchar(20).nullable());
-
-// 컬럼 수정
-await db.modifyColumn({ name: "user" }, "phone", c.varchar(50).nullable());
-
-// 컬럼 이름 변경
-await db.renameColumn({ name: "user" }, "phone", "phoneNumber");
-
-// 컬럼 삭제
-await db.dropColumn({ name: "user" }, "phone");
-```
-
-## 키/인덱스 DDL
-
-```typescript
-// PK
-await db.addPrimaryKey({ name: "user" }, ["id"]);
-await db.dropPrimaryKey({ name: "user" });
-
-// FK
-await db.addForeignKey({ name: "order" }, "user", userRelationDef);
-await db.dropForeignKey({ name: "order" }, "user");
-
-// 인덱스
-await db.addIndex({ name: "user" }, indexBuilder);
-await db.dropIndex({ name: "user" }, ["email"]);
-```
-
-## 뷰/프로시저 DDL
-
-```typescript
-await db.createView(UserSummary);
-await db.dropView({ name: "user_summary" });
-
-await db.createProc(GetUserOrders);
-await db.dropProc({ name: "get_user_orders" });
-```
-
-## 스키마 관리
-
-```typescript
-// 스키마 존재 여부
-const exists = await db.schemaExists("mydb", "dbo");
-
-// 스키마 내 모든 테이블 삭제
-await db.clearSchema({ database: "mydb", schema: "dbo" });
-
-// 테이블 TRUNCATE
-await db.truncate({ name: "user" });
-
-// FK 제약조건 토글
-await db.switchFk({ name: "user" }, false); // FK 비활성화
-// ... 벌크 작업 ...
-await db.switchFk({ name: "user" }, true);  // FK 활성화
-```
-
-## DDL 메서드 API
-
-### 테이블/뷰/프로시저
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `createTable` | `(table: TableBuilder) => Promise<void>` | 테이블 생성 |
-| `dropTable` | `(table: QueryDefObjectName) => Promise<void>` | 테이블 삭제 |
-| `renameTable` | `(table: QueryDefObjectName, newName: string) => Promise<void>` | 테이블 이름 변경 |
-| `createView` | `(view: ViewBuilder) => Promise<void>` | 뷰 생성 |
-| `dropView` | `(view: QueryDefObjectName) => Promise<void>` | 뷰 삭제 |
-| `createProc` | `(proc: ProcedureBuilder) => Promise<void>` | 프로시저 생성 |
-| `dropProc` | `(proc: QueryDefObjectName) => Promise<void>` | 프로시저 삭제 |
-
-### 컬럼
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `addColumn` | `(table, columnName, column: ColumnBuilder) => Promise<void>` | 컬럼 추가 |
-| `dropColumn` | `(table, column: string) => Promise<void>` | 컬럼 삭제 |
-| `modifyColumn` | `(table, columnName, column: ColumnBuilder) => Promise<void>` | 컬럼 수정 |
-| `renameColumn` | `(table, column, newName) => Promise<void>` | 컬럼 이름 변경 |
-
-### 키/인덱스
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `addPrimaryKey` | `(table, columns: string[]) => Promise<void>` | PK 추가 |
-| `dropPrimaryKey` | `(table) => Promise<void>` | PK 삭제 |
-| `addForeignKey` | `(table, relationName, relationDef) => Promise<void>` | FK 추가 |
-| `dropForeignKey` | `(table, relationName) => Promise<void>` | FK 삭제 |
-| `addIndex` | `(table, indexBuilder) => Promise<void>` | 인덱스 추가 |
-| `dropIndex` | `(table, columns: string[]) => Promise<void>` | 인덱스 삭제 |
-
-### 스키마
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `schemaExists` | `(database, schema?) => Promise<boolean>` | 스키마 존재 여부 |
-| `clearSchema` | `(params: { database, schema? }) => Promise<void>` | 스키마 내 모든 테이블 삭제 |
-| `truncate` | `(table) => Promise<void>` | 테이블 TRUNCATE |
-| `switchFk` | `(table, enabled: boolean) => Promise<void>` | FK 제약조건 on/off |
-
-## 연결 & 트랜잭션
-
-```typescript
-// 자동 트랜잭션 (connect -> begin -> callback -> commit/rollback -> close)
-const result = await db.connect(async () => {
-  await db.user().insert([{ name: "Alice", createdAt: new DateTime() }]);
-  return await db.user().execute();
-}, "SERIALIZABLE"); // 격리 수준 선택
-
-// 트랜잭션 없이 연결 (DDL 작업 등)
-await db.connectWithoutTransaction(async () => {
-  await db.initialize();
-});
-
-// 수동 트랜잭션 (connectWithoutTransaction 내에서)
-await db.connectWithoutTransaction(async () => {
-  // DDL 먼저 실행 (트랜잭션 밖)
-  await db.createTable(NewTable);
-
-  // 이후 트랜잭션 내에서 DML 실행
-  await db.transaction(async () => {
-    await db.user().insert([{ name: "Bob", createdAt: new DateTime() }]);
-  });
-});
-```
-
-### 연결 API
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `connect` | `(fn, isolationLevel?) => Promise<T>` | 자동 트랜잭션 (connect -> begin -> fn -> commit/rollback -> close) |
-| `connectWithoutTransaction` | `(fn) => Promise<T>` | 트랜잭션 없이 연결 (DDL용) |
-| `transaction` | `(fn, isolationLevel?) => Promise<T>` | 수동 트랜잭션 (connectWithoutTransaction 내에서) |
-
-격리 수준: `"READ_UNCOMMITTED"`, `"READ_COMMITTED"`, `"REPEATABLE_READ"`, `"SERIALIZABLE"`
-
-## DbContextExecutor 인터페이스
-
-Node.js(`@simplysm/orm-node`)나 서비스 클라이언트(`@simplysm/service-client`)에서 구현.
-
-```typescript
-interface DbContextExecutor {
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-  executeDefs<T>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>;
-}
-```
-
-## 마이그레이션
-
-`defineDbContext`의 `migrations` 옵션으로 스키마 변경사항을 관리한다. `initialize()` 호출 시 아직 실행되지 않은 마이그레이션만 실행된다.
-
-```typescript
-const MyDb = defineDbContext({
-  tables: { user: User },
-  migrations: [
-    {
-      name: "20260105_001_create_user_table",
-      up: async (db) => {
-        await db.createTable(User);
-      },
-    },
-    {
-      name: "20260106_001_add_email_column",
-      up: async (db) => {
-        const c = createColumnFactory();
-        await db.addColumn({ name: "user" }, "email", c.varchar(200).nullable());
-      },
-    },
-  ],
-});
-```
-
-### Migration 인터페이스
-
-```typescript
-interface Migration {
-  name: string;
-  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
-}
-```
-
-실행된 마이그레이션은 `_migration` 테이블에 기록된다.
-
-```typescript
-// 마이그레이션 코드 조회
-const migrations = await db._migration().execute();
-```
-
-## DbTransactionError
-
-트랜잭션 관련 에러를 DBMS 독립적으로 처리하기 위한 에러 클래스.
-
-```typescript
-import { DbTransactionError, DbErrorCode } from "@simplysm/orm-common";
-
-// DbErrorCode:
-// - NO_ACTIVE_TRANSACTION: 활성 트랜잭션 없음
-// - TRANSACTION_ALREADY_STARTED: 트랜잭션 이미 시작됨
-// - DEADLOCK: 데드락 발생
-// - LOCK_TIMEOUT: 잠금 타임아웃
-```
-
-### DbTransactionError API
-
-```typescript
-class DbTransactionError extends Error {
-  readonly name: "DbTransactionError";
-  readonly code: DbErrorCode;
-  readonly originalError?: unknown;
-  constructor(code: DbErrorCode, message: string, originalError?: unknown);
-}
-```
-
-## QueryDef 생성기
-
-DDL 메서드 외에도 `get*QueryDef()` 메서드로 QueryDef만 생성할 수 있다 (직접 실행하지 않음).
-
-```typescript
-const def = db.getCreateTableQueryDef(User);
-const def2 = db.getAddColumnQueryDef({ name: "user" }, "phone", c.varchar(20));
-// ... 등. 모든 DDL 메서드에 대응하는 get*QueryDef() 메서드가 있다.
-```
-
-| 생성기 | 대응 DDL 메서드 |
-|--------|---------------|
-| `getCreateTableQueryDef` | `createTable` |
-| `getCreateViewQueryDef` | `createView` |
-| `getCreateProcQueryDef` | `createProc` |
-| `getCreateObjectQueryDef` | Table/View/Procedure 자동 판별 |
-| `getDropTableQueryDef` | `dropTable` |
-| `getRenameTableQueryDef` | `renameTable` |
-| `getDropViewQueryDef` | `dropView` |
-| `getDropProcQueryDef` | `dropProc` |
-| `getAddColumnQueryDef` | `addColumn` |
-| `getDropColumnQueryDef` | `dropColumn` |
-| `getModifyColumnQueryDef` | `modifyColumn` |
-| `getRenameColumnQueryDef` | `renameColumn` |
-| `getAddPrimaryKeyQueryDef` | `addPrimaryKey` |
-| `getDropPrimaryKeyQueryDef` | `dropPrimaryKey` |
-| `getAddForeignKeyQueryDef` | `addForeignKey` |
-| `getAddIndexQueryDef` | `addIndex` |
-| `getDropForeignKeyQueryDef` | `dropForeignKey` |
-| `getDropIndexQueryDef` | `dropIndex` |
-| `getClearSchemaQueryDef` | `clearSchema` |
-| `getSchemaExistsQueryDef` | `schemaExists` |
-| `getTruncateQueryDef` | `truncate` |
-| `getSwitchFkQueryDef` | `switchFk` |

package/docs/query.md

@@ -1,644 +0,0 @@
-# 쿼리 & 표현식
-
-## Queryable -- SELECT 쿼리 빌더
-
-### 기본 조회
-
-```typescript
-// 전체 조회
-const users = await db.user().execute();
-
-// 단건 조회 (2건 이상이면 throw)
-const user = await db.user()
-  .where((c) => [expr.eq(c.id, 1)])
-  .single();
-
-// 첫 번째 결과 (여러 건이어도 첫 번째만 반환)
-const latest = await db.user()
-  .orderBy((c) => c.createdAt, "DESC")
-  .first();
-
-// 행 수
-const count = await db.user()
-  .where((c) => [expr.eq(c.isActive, true)])
-  .count();
-
-// 존재 여부
-const hasAdmin = await db.user()
-  .where((c) => [expr.eq(c.role, "admin")])
-  .exists();
-```
-
-### Queryable API
-
-#### 실행 메서드
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `execute` | `() => Promise<TData[]>` | SELECT 실행, 결과 배열 반환 |
-| `single` | `() => Promise<TData \| undefined>` | 단건 반환 (2건 이상이면 throw) |
-| `first` | `() => Promise<TData \| undefined>` | 첫 번째 결과 반환 |
-| `count` | `(fn?) => Promise<number>` | 행 수 반환. distinct/groupBy 이후에는 wrap() 필요 |
-| `exists` | `() => Promise<boolean>` | 데이터 존재 여부 |
-
-#### 조건 메서드 (체이닝)
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `where` | `(fn: (cols) => WhereExprUnit[]) => Queryable` | WHERE 조건 (여러 번 호출 시 AND 결합) |
-| `search` | `(fn: (cols) => ExprUnit[], text: string) => Queryable` | 텍스트 검색 |
-| `orderBy` | `(fn: (cols) => ExprUnit, dir?) => Queryable` | 정렬 (기본 ASC, 여러 번 호출 가능) |
-| `top` | `(count: number) => Queryable` | 상위 N건 (ORDER BY 없이 사용 가능) |
-| `limit` | `(skip: number, take: number) => Queryable` | 페이징 (ORDER BY 필수) |
-| `select` | `(fn: (cols) => Record) => Queryable` | 컬럼 선택/변환 |
-| `distinct` | `() => Queryable` | 중복 제거 |
-| `lock` | `() => Queryable` | FOR UPDATE 잠금 |
-| `groupBy` | `(fn: (cols) => ExprUnit[]) => Queryable` | 그룹화 |
-| `having` | `(fn: (cols) => WhereExprUnit[]) => Queryable` | 그룹 필터링 |
-
-#### JOIN 메서드
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `join` | `(as, fn: (qr, cols) => Queryable) => Queryable` | LEFT JOIN (1:N, 배열) |
-| `joinSingle` | `(as, fn: (qr, cols) => Queryable) => Queryable` | LEFT JOIN (N:1, 단일 객체) |
-| `include` | `(fn: (item) => PathProxy) => Queryable` | 관계 기반 자동 JOIN |
-
-#### 서브쿼리/유틸리티
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `wrap` | `() => Queryable` | 서브쿼리로 래핑 |
-| `Queryable.union` | `(...queries) => Queryable` | UNION (최소 2개) |
-| `recursive` | `(fn: (cte) => Queryable) => Queryable` | 재귀 CTE |
-
-#### CUD 메서드
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `insert` | `(records, outputColumns?) => Promise` | INSERT (1000건 단위 자동 분할) |
-| `insertIfNotExists` | `(record, outputColumns?) => Promise` | 조건부 INSERT |
-| `insertInto` | `(targetTable, outputColumns?) => Promise` | INSERT INTO ... SELECT |
-| `update` | `(fn: (cols) => Record, outputColumns?) => Promise` | UPDATE |
-| `delete` | `(outputColumns?) => Promise` | DELETE |
-| `upsert` | `(updateFn, insertFn?, outputColumns?) => Promise` | UPSERT (UPDATE or INSERT) |
-| `switchFk` | `(enabled: boolean) => Promise<void>` | FK 제약조건 on/off |
-
-### 필터링 (WHERE)
-
-```typescript
-db.user()
-  .where((c) => [
-    expr.eq(c.name, "Alice"),           // name = 'Alice'
-    expr.gt(c.score, 80),              // score > 80
-    expr.between(c.createdAt, from, to), // BETWEEN
-    expr.like(c.email, "%@gmail.com"),  // LIKE
-    expr.in(c.role, ["admin", "user"]), // IN
-    expr.null(c.deletedAt),            // IS NULL
-  ])
-  // 배열은 자동 AND 결합. OR는 명시적으로:
-  .where((c) => [
-    expr.or([
-      expr.eq(c.role, "admin"),
-      expr.gt(c.score, 90),
-    ]),
-  ])
-```
-
-where()를 여러 번 호출하면 AND로 결합된다.
-
-### 텍스트 검색 (search)
-
-```typescript
-// 여러 컬럼에서 텍스트 검색
-db.user()
-  .search((c) => [c.name, c.email], "John +admin -withdrawn")
-```
-
-검색 문법: `term`(OR), `+term`(AND 필수), `-term`(NOT 제외), `"exact"`(정확히 + 필수), `wild*`(접두사). 내부적으로 `parseSearchQuery()`를 사용하여 SQL LIKE 패턴으로 변환한다.
-
-### 정렬 (ORDER BY)
-
-```typescript
-// orderBy는 컬럼 하나씩, 여러 번 호출 가능
-db.user()
-  .orderBy((c) => c.createdAt, "DESC")
-  .orderBy((c) => c.name)  // 기본: ASC
-```
-
-### 페이징
-
-```typescript
-// top: ORDER BY 없이도 사용 가능
-db.user().top(10)
-
-// limit: ORDER BY 필수 (skip, take)
-db.user()
-  .orderBy((c) => c.createdAt, "DESC")
-  .limit(20, 10)  // 20건 건너뛰고 10건 가져오기
-```
-
-### 컬럼 선택 (SELECT)
-
-```typescript
-db.user()
-  .select((c) => ({
-    id: c.id,
-    upperName: expr.upper(c.name),
-    emailDomain: expr.right(c.email, 10),
-  }))
-```
-
-### 그룹화 (GROUP BY)
-
-```typescript
-db.order()
-  .select((c) => ({
-    userId: c.userId,
-    total: expr.sum(c.amount),
-    count: expr.count(),
-    avg: expr.avg(c.amount),
-  }))
-  .groupBy((c) => [c.userId])
-  .having((c) => [expr.gt(expr.count(), 5)])
-```
-
-### JOIN
-
-```typescript
-// LEFT JOIN (1:N, 배열로 결과에 추가)
-db.user()
-  .join("posts", (qr, u) =>
-    qr.from(Post)
-      .where((p) => [expr.eq(p.userId, u.id)])
-  )
-// 결과: { id, name, posts: [{ id, title }, ...] }
-
-// LEFT JOIN SINGLE (N:1, 단일 객체로 결과에 추가)
-db.order()
-  .joinSingle("user", (qr, o) =>
-    qr.from(User)
-      .where((u) => [expr.eq(u.id, o.userId)])
-  )
-// 결과: { id, amount, user: { id, name } | undefined }
-
-// 관계 자동 로드 (include) -- 정의된 관계 기반 자동 JOIN
-db.order()
-  .include((c) => c.user)        // N:1 관계 로드
-  .include((c) => c.user.company) // 중첩 관계
-```
-
-### 서브쿼리
-
-```typescript
-// 스칼라 서브쿼리
-db.user().select((c) => ({
-  name: c.name,
-  orderCount: expr.subquery("number",
-    db.order()
-      .where((o) => [expr.eq(o.userId, c.id)])
-      .select(() => ({ cnt: expr.count() }))
-  ),
-}))
-
-// IN 서브쿼리
-db.user().where((c) => [
-  expr.inQuery(c.id,
-    db.order()
-      .where((o) => [expr.gt(o.amount, 1000)])
-      .select((o) => ({ userId: o.userId }))
-  ),
-])
-
-// EXISTS
-db.user().where((c) => [
-  expr.exists(db.order().where((o) => [expr.eq(o.userId, c.id)])),
-])
-```
-
-### 잠금 (FOR UPDATE)
-
-```typescript
-await db.connect(async () => {
-  const user = await db.user()
-    .where((c) => [expr.eq(c.id, 1)])
-    .lock()
-    .single();
-});
-```
-
-### DISTINCT
-
-```typescript
-db.user().select((c) => ({ role: c.role })).distinct()
-```
-
-### 서브쿼리 래핑 (wrap)
-
-DISTINCT나 GROUP BY 이후 count() 등을 사용하려면 wrap()으로 서브쿼리화해야 한다.
-
-```typescript
-const count = await db.user()
-  .select((c) => ({ name: c.name }))
-  .distinct()
-  .wrap()
-  .count();
-```
-
-### UNION
-
-```typescript
-const combined = Queryable.union(
-  db.user().where((c) => [expr.eq(c.type, "admin")]),
-  db.user().where((c) => [expr.eq(c.type, "manager")]),
-);
-```
-
-### 재귀 쿼리 (CTE)
-
-```typescript
-// 계층 데이터 조회 (조직도, 카테고리 트리 등)
-db.employee()
-  .where((e) => [expr.null(e.managerId)])  // 루트 노드
-  .recursive((cte) =>
-    cte.from(Employee)
-      .where((e) => [expr.eq(e.managerId, e.self[0].id)])
-  )
-```
-
----
-
-## CUD 연산
-
-`select()`, `groupBy()`, `join()` 이후에는 CUD 불가 (타입 레벨에서 차단).
-
-### INSERT
-
-```typescript
-// 기본 삽입
-await db.user().insert([
-  { name: "Alice", email: "alice@example.com", createdAt: new DateTime() },
-  { name: "Bob", createdAt: new DateTime() },
-]);
-
-// INSERT 후 컬럼 반환 (OUTPUT)
-const [inserted] = await db.user().insert(
-  [{ name: "Alice", createdAt: new DateTime() }],
-  ["id"],  // 반환받을 컬럼
-);
-// inserted.id -> 자동 생성된 ID
-
-// 조건부 INSERT (WHERE 조건에 맞는 데이터가 없을 때만)
-await db.user()
-  .where((c) => [expr.eq(c.email, "test@test.com")])
-  .insertIfNotExists({ name: "testing", email: "test@test.com", createdAt: new DateTime() });
-
-// INSERT INTO ... SELECT
-await db.user()
-  .select((c) => ({ name: c.name, createdAt: c.createdAt }))
-  .where((c) => [expr.eq(c.isArchived, false)])
-  .insertInto(ArchivedUser);
-```
-
-### UPDATE
-
-```typescript
-await db.user()
-  .where((c) => [expr.eq(c.id, 1)])
-  .update((c) => ({ name: expr.val("string", "Alice2") }));
-
-// 기존 값 참조
-await db.product()
-  .update((p) => ({
-    price: expr.mul(p.price, expr.val("number", 1.1)),
-  }));
-
-// OUTPUT으로 변경된 데이터 반환
-const updated = await db.user()
-  .where((c) => [expr.eq(c.id, 1)])
-  .update(
-    (c) => ({ name: expr.val("string", "Alice2") }),
-    ["id", "name"],
-  );
-```
-
-### DELETE
-
-```typescript
-await db.user()
-  .where((c) => [expr.eq(c.id, 1)])
-  .delete();
-
-// OUTPUT으로 삭제된 데이터 반환
-const deleted = await db.user()
-  .where((c) => [expr.eq(c.isExpired, true)])
-  .delete(["id", "name"]);
-```
-
-### UPSERT (UPDATE or INSERT)
-
-```typescript
-// 동일 데이터로 UPDATE/INSERT
-await db.user()
-  .where((c) => [expr.eq(c.email, "test@test.com")])
-  .upsert(() => ({
-    name: expr.val("string", "testing"),
-    email: expr.val("string", "test@test.com"),
-  }));
-
-// UPDATE/INSERT 데이터가 다른 경우
-await db.user()
-  .where((c) => [expr.eq(c.email, "test@test.com")])
-  .upsert(
-    () => ({ loginCount: expr.val("number", 1) }),                    // UPDATE용
-    (update) => ({ ...update, email: expr.val("string", "test@test.com") }),  // INSERT용
-  );
-```
-
-### FK 토글
-
-```typescript
-// Queryable에서 직접 FK on/off
-await db.user().switchFk(false);  // FK 비활성화
-// ... 벌크 작업 ...
-await db.user().switchFk(true);   // FK 활성화
-```
-
----
-
-## Executable -- 프로시저 실행
-
-```typescript
-const MyDb = defineDbContext({
-  tables: { user: User },
-  procedures: { getUserOrders: GetUserOrders },
-});
-
-const db = createDbContext(MyDb, executor, { database: "mydb" });
-
-await db.connect(async () => {
-  const results = await db.getUserOrders().execute({ userId: 1 });
-});
-```
-
-### Executable API
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `execute` | `(params) => Promise<TReturns[][]>` | 프로시저 실행 |
-| `getExecProcQueryDef` | `(params?) => QueryDef` | QueryDef만 생성 (실행 안 함) |
-
----
-
-## expr -- 표현식 빌더
-
-방언 독립적인 SQL 표현식을 생성한다. JSON AST(Expr)를 생성하며, QueryBuilder가 각 DBMS(MySQL, MSSQL, PostgreSQL)에 맞게 변환한다.
-
-### 값/조건
-
-| 함수 | 설명 |
-|------|------|
-| `expr.val(type, value)` | 리터럴 값 |
-| `expr.col(type, alias, key)` | 컬럼 참조 |
-| `expr.raw(type)\`sql\`` | Raw SQL (태그 템플릿) |
-| `expr.eq(a, b)` | `=` (NULL 안전) |
-| `expr.gt(a, b)` | `>` |
-| `expr.lt(a, b)` | `<` |
-| `expr.gte(a, b)` | `>=` |
-| `expr.lte(a, b)` | `<=` |
-| `expr.between(src, from?, to?)` | BETWEEN |
-| `expr.null(src)` | IS NULL |
-| `expr.like(src, pattern)` | LIKE |
-| `expr.regexp(src, pattern)` | 정규식 매칭 |
-| `expr.in(src, values)` | IN (값 목록) |
-| `expr.inQuery(src, query)` | IN (서브쿼리) |
-| `expr.exists(query)` | EXISTS |
-| `expr.not(cond)` | NOT |
-| `expr.and(conds)` | AND |
-| `expr.or(conds)` | OR |
-
-### 문자열 함수
-
-| 함수 | 설명 |
-|------|------|
-| `expr.concat(...args)` | 연결 (NULL=빈문자열) |
-| `expr.left(src, len)` | 왼쪽 N자 |
-| `expr.right(src, len)` | 오른쪽 N자 |
-| `expr.substring(src, start, len?)` | 부분 문자열 (1-based) |
-| `expr.trim(src)` | 양쪽 공백 제거 |
-| `expr.padStart(src, len, fill)` | 왼쪽 패딩 (LPAD) |
-| `expr.replace(src, from, to)` | 치환 |
-| `expr.upper(src)` / `expr.lower(src)` | 대/소문자 |
-| `expr.length(src)` | 문자 길이 (CHAR_LENGTH) |
-| `expr.byteLength(src)` | 바이트 길이 (LENGTH/DATALENGTH) |
-| `expr.indexOf(src, search)` | 위치 (1-based, 0=없음) |
-
-### 수학 함수
-
-| 함수 | 설명 |
-|------|------|
-| `expr.abs(src)` | 절대값 |
-| `expr.round(src, digits)` | 반올림 |
-| `expr.ceil(src)` / `expr.floor(src)` | 올림/내림 |
-
-### 날짜 함수
-
-| 함수 | 설명 |
-|------|------|
-| `expr.year(src)` / `expr.month(src)` / `expr.day(src)` | 연/월/일 추출 |
-| `expr.hour(src)` / `expr.minute(src)` / `expr.second(src)` | 시/분/초 추출 |
-| `expr.dateDiff(unit, from, to)` | 날짜 차이 |
-| `expr.dateAdd(unit, src, value)` | 날짜 더하기 |
-| `expr.formatDate(src, format)` | 날짜 포맷 (FORMAT/DATE_FORMAT) |
-| `expr.isoWeek(src)` | ISO 주차 |
-| `expr.isoWeekStartDate(src)` | ISO 주 시작일 |
-| `expr.isoYearMonth(src)` | ISO 연월 (YYYYMM 형식) |
-
-단위(`DateUnit`): `"year"`, `"month"`, `"day"`, `"hour"`, `"minute"`, `"second"`
-
-### 집계 함수
-
-| 함수 | 설명 |
-|------|------|
-| `expr.count(arg?, distinct?)` | 행 수 |
-| `expr.sum(arg)` | 합계 |
-| `expr.avg(arg)` | 평균 |
-| `expr.max(arg)` / `expr.min(arg)` | 최대/최소 |
-
-### 조건 함수
-
-```typescript
-// CASE WHEN
-expr.switch<string>()
-  .case(expr.gt(c.score, 90), "A")
-  .case(expr.gt(c.score, 80), "B")
-  .default("C")
-
-// IF (단순 삼항)
-expr.if(expr.gt(c.score, 60), "pass", "fail")
-
-// WHERE -> boolean 컬럼
-expr.is(expr.gt(c.score, 80))  // true/false
-
-// NULLIF (source === value이면 NULL 반환)
-expr.nullIf(c.status, "unknown")
-```
-
-### 윈도우 함수
-
-```typescript
-// 순위
-expr.rowNumber({ partitionBy: [c.dept], orderBy: [[c.score, "DESC"]] })
-expr.rank({ orderBy: [[c.score, "DESC"]] })
-expr.denseRank({ orderBy: [[c.score, "DESC"]] })
-expr.ntile(4, { orderBy: [[c.score, "DESC"]] })
-
-// 탐색
-expr.lag(c.score, 1, 0, { orderBy: [[c.createdAt, "ASC"]] })
-expr.lead(c.score, 1, undefined, { orderBy: [[c.createdAt, "ASC"]] })
-expr.firstValue(c.score, { orderBy: [[c.createdAt, "ASC"]] })
-expr.lastValue(c.score, { orderBy: [[c.createdAt, "ASC"]] })
-
-// 윈도우 집계
-expr.sumOver(c.amount, { partitionBy: [c.dept] })
-expr.avgOver(c.amount, { partitionBy: [c.dept] })
-expr.countOver({ partitionBy: [c.dept] })
-expr.minOver(c.amount, { partitionBy: [c.dept] })
-expr.maxOver(c.amount, { partitionBy: [c.dept] })
-```
-
-### 기타
-
-| 함수 | 설명 |
-|------|------|
-| `expr.cast(src, targetType)` | 타입 변환 |
-| `expr.greatest(...args)` | 최대값 |
-| `expr.least(...args)` | 최소값 |
-| `expr.rowNum()` | 행 번호 (전체) |
-| `expr.random()` | 랜덤 0~1 |
-| `expr.subquery(type, queryable)` | 스칼라 서브쿼리 |
-
----
-
-## ExprUnit / WhereExprUnit
-
-Queryable 콜백에서 컬럼 참조 시 자동으로 `ExprUnit`으로 래핑된다.
-
-```typescript
-// ExprUnit<TPrimitive> -- 타입 안전한 표현식 래퍼
-class ExprUnit<TPrimitive extends ColumnPrimitive> {
-  readonly dataType: ColumnPrimitiveStr;
-  readonly expr: Expr;
-  get n(): ExprUnit<NonNullable<TPrimitive>>;  // nullable 제거
-}
-
-// WhereExprUnit -- WHERE 절용 표현식 래퍼
-class WhereExprUnit {
-  readonly expr: WhereExpr;
-}
-
-// ExprInput -- ExprUnit 또는 리터럴 값을 받는 입력 타입
-type ExprInput<TPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
-```
-
----
-
-## 검색 파서
-
-사용자 검색 문법을 SQL LIKE 패턴으로 변환.
-
-```typescript
-import { parseSearchQuery } from "@simplysm/orm-common";
-
-parseSearchQuery('apple +fruit -rotten "green apple" wild*');
-// {
-//   or: ["%apple%", "wild%"],
-//   must: ["%green apple%", "%fruit%"],
-//   not: ["%rotten%"],
-// }
-```
-
-### parseSearchQuery API
-
-```
-parseSearchQuery(searchText: string): ParsedSearchQuery
-
-interface ParsedSearchQuery {
-  or: string[];    // OR 조건 (LIKE 패턴)
-  must: string[];  // AND 필수 조건 (LIKE 패턴)
-  not: string[];   // NOT 제외 조건 (LIKE 패턴)
-}
-```
-
-문법: `term`(OR), `+term`(AND 필수), `-term`(NOT 제외), `"exact"`(정확히 + 필수), `wild*`(접두사)
-
-이스케이프: `\\` (리터럴 `\`), `\*` (리터럴 `*`), `\%` (리터럴 `%`), `\"` (리터럴 `"`), `\+` (리터럴 `+`), `\-` (리터럴 `-`)
-
----
-
-## QueryBuilder
-
-QueryDef(JSON AST)를 DBMS별 SQL 문자열로 변환한다.
-
-```typescript
-import { createQueryBuilder } from "@simplysm/orm-common";
-import type { Dialect } from "@simplysm/orm-common";
-
-const builder = createQueryBuilder("mysql");  // "mysql" | "mssql" | "postgresql"
-const result = builder.build(queryDef);
-// result.sql -> SQL 문자열
-```
-
-### createQueryBuilder API
-
-```
-createQueryBuilder(dialect: Dialect): QueryBuilderBase
-```
-
-| 방언 | 구현 클래스 |
-|------|-----------|
-| `"mysql"` | `MysqlQueryBuilder` |
-| `"mssql"` | `MssqlQueryBuilder` |
-| `"postgresql"` | `PostgresqlQueryBuilder` |
-
----
-
-## parseQueryResult
-
-DB 쿼리 결과를 ResultMeta 기반으로 TypeScript 객체로 변환한다. 타입 파싱과 JOIN 결과 중첩을 처리한다.
-
-```typescript
-import { parseQueryResult } from "@simplysm/orm-common";
-
-// 단순 타입 파싱
-const raw = [{ id: "1", createdAt: "2026-01-07T10:00:00.000Z" }];
-const meta = { columns: { id: "number", createdAt: "DateTime" }, joins: {} };
-const result = await parseQueryResult(raw, meta);
-// [{ id: 1, createdAt: DateTime(...) }]
-
-// JOIN 결과 중첩
-const raw2 = [
-  { id: 1, name: "User1", "posts.id": 10, "posts.title": "Post1" },
-  { id: 1, name: "User1", "posts.id": 11, "posts.title": "Post2" },
-];
-const meta2 = {
-  columns: { id: "number", name: "string", "posts.id": "number", "posts.title": "string" },
-  joins: { posts: { isSingle: false } },
-};
-const result2 = await parseQueryResult(raw2, meta2);
-// [{ id: 1, name: "User1", posts: [{ id: 10, title: "Post1" }, { id: 11, title: "Post2" }] }]
-```
-
-### parseQueryResult API
-
-```
-parseQueryResult<TRecord>(
-  rawResults: Record<string, unknown>[],
-  meta: ResultMeta,
-): Promise<TRecord[] | undefined>
-
-interface ResultMeta {
-  columns: Record<string, ColumnPrimitiveStr>;
-  joins: Record<string, { isSingle: boolean }>;
-}
-```

package/docs/schema.md

@@ -1,325 +0,0 @@
-# 스키마 정의
-
-## Table
-
-불변 빌더 패턴으로 테이블을 정의한다. 모든 메서드는 새 인스턴스를 반환한다.
-
-```typescript
-import { Table } from "@simplysm/orm-common";
-
-const User = Table("user")
-  .description("사용자 테이블")
-  .database("mydb")           // 선택
-  .schema("dbo")              // MSSQL/PostgreSQL, 선택
-  .columns((c) => ({
-    id: c.int().autoIncrement(),
-    name: c.varchar(100),
-    email: c.varchar(200).nullable(),
-    role: c.varchar(20).default("user"),
-    bio: c.text().nullable(),
-    avatar: c.binary().nullable(),
-    score: c.decimal(10, 2).nullable(),
-    active: c.boolean().default(true),
-    birthday: c.date().nullable(),
-    loginTime: c.time().nullable(),
-    createdAt: c.datetime(),
-    externalId: c.uuid().nullable(),
-  }))
-  .primaryKey("id")                          // 복합 PK 지원: .primaryKey("col1", "col2")
-  .indexes((i) => [
-    i.index("email").unique(),
-    i.index("name", "role").orderBy("ASC", "DESC"),
-    i.index("createdAt").name("ix_created"),
-  ])
-  .relations((r) => ({
-    orders: r.foreignKeyTarget(() => Order, "user"),  // 1:N
-    profile: r.foreignKeyTarget(() => Profile, "user").single(), // 1:1
-  }));
-```
-
-### Table API
-
-```
-Table(name: string): TableBuilder
-```
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `description` | `(desc: string) => TableBuilder` | 테이블 설명 (DDL 코멘트) |
-| `database` | `(db: string) => TableBuilder` | 데이터베이스 이름 |
-| `schema` | `(schema: string) => TableBuilder` | 스키마 이름 (MSSQL: dbo, PostgreSQL: public) |
-| `columns` | `(fn: (c) => Record) => TableBuilder` | 컬럼 정의 |
-| `primaryKey` | `(...columns: string[]) => TableBuilder` | PK 설정 (복합 PK 지원) |
-| `indexes` | `(fn: (i) => IndexBuilder[]) => TableBuilder` | 인덱스 정의 |
-| `relations` | `(fn: (r) => Record) => TableBuilder` | 관계 정의 |
-
-### 컬럼 타입
-
-| 메서드 | SQL 타입 | TypeScript 타입 |
-|--------|---------|----------------|
-| `c.int()` | INT | `number` |
-| `c.bigint()` | BIGINT | `number` |
-| `c.float()` | FLOAT | `number` |
-| `c.double()` | DOUBLE | `number` |
-| `c.decimal(p, s?)` | DECIMAL(p,s) | `number` |
-| `c.varchar(len)` | VARCHAR(len) | `string` |
-| `c.char(len)` | CHAR(len) | `string` |
-| `c.text()` | LONGTEXT/TEXT | `string` |
-| `c.boolean()` | BIT/TINYINT(1) | `boolean` |
-| `c.datetime()` | DATETIME | `DateTime` |
-| `c.date()` | DATE | `DateOnly` |
-| `c.time()` | TIME | `Time` |
-| `c.binary()` | LONGBLOB/VARBINARY/BYTEA | `Bytes` |
-| `c.uuid()` | UNIQUEIDENTIFIER/UUID | `Uuid` |
-
-### 컬럼 수정자
-
-```typescript
-c.int().autoIncrement()     // 자동 증가 (INSERT 시 선택적)
-c.varchar(100).nullable()   // NULL 허용 (타입에 undefined 추가)
-c.varchar(20).default("x")  // 기본값 (INSERT 시 선택적)
-c.varchar(100).description("설명")
-```
-
-### 타입 추론
-
-```typescript
-User.$inferSelect   // { id: number; name: string; email: string | undefined; ... }
-User.$inferInsert   // { name: string; createdAt: DateTime; } & { id?: number; email?: string; ... }
-User.$inferUpdate   // { id?: number; name?: string; ... } (모든 필드 선택적)
-User.$inferColumns  // { id: number; name: string; email: string | undefined; ... } (관계 제외)
-```
-
----
-
-## 관계 (Relation)
-
-### foreignKey -- N:1 (DB FK 생성)
-
-```typescript
-const Order = Table("order")
-  .columns((c) => ({
-    id: c.int().autoIncrement(),
-    userId: c.int(),
-  }))
-  .primaryKey("id")
-  .relations((r) => ({
-    user: r.foreignKey(["userId"], () => User),  // Order.userId -> User.id
-  }));
-```
-
-### foreignKeyTarget -- 1:N / 1:1 (역참조)
-
-```typescript
-const User = Table("user")
-  .columns((c) => ({ id: c.int().autoIncrement(), name: c.varchar(100) }))
-  .primaryKey("id")
-  .relations((r) => ({
-    orders: r.foreignKeyTarget(() => Order, "user"),          // 1:N (배열)
-    profile: r.foreignKeyTarget(() => Profile, "user").single(), // 1:1 (단일 객체)
-  }));
-```
-
-### relationKey / relationKeyTarget -- 논리적 관계 (DB FK 없음)
-
-View에서도 사용 가능. DB에 FK 제약조건을 생성하지 않는다.
-
-```typescript
-.relations((r) => ({
-  category: r.relationKey(["categoryId"], () => Category),
-  items: r.relationKeyTarget(() => Item, "parent"),
-}))
-```
-
-### 관계 빌더 API
-
-| 빌더 | 용도 | DB FK 생성 |
-|------|------|----------|
-| `ForeignKeyBuilder` | N:1 관계 (FK 컬럼 소유) | O |
-| `ForeignKeyTargetBuilder` | 1:N / 1:1 역참조 | O (대상 테이블) |
-| `RelationKeyBuilder` | N:1 논리적 관계 | X |
-| `RelationKeyTargetBuilder` | 1:N / 1:1 논리적 역참조 | X |
-
-공통 메서드:
-
-| 메서드 | 설명 |
-|--------|------|
-| `.description(desc)` | 관계 설명 |
-| `.single()` | 1:1 관계 (ForeignKeyTargetBuilder, RelationKeyTargetBuilder만 해당) |
-
----
-
-## View
-
-```typescript
-import { View, expr } from "@simplysm/orm-common";
-
-const UserSummary = View("user_summary")
-  .database("mydb")
-  .query<typeof MyDb>((db) =>
-    db.user()
-      .select((c) => ({
-        userId: c.id,
-        userName: c.name,
-        orderCount: expr.count(),
-        totalAmount: expr.sum(c.amount),
-      }))
-      .groupBy((c) => [c.id, c.name])
-  )
-  .relations((r) => ({
-    user: r.relationKey(["userId"], () => User),
-  }));
-```
-
-### View API
-
-```
-View(name: string): ViewBuilder
-```
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `description` | `(desc: string) => ViewBuilder` | 뷰 설명 |
-| `database` | `(db: string) => ViewBuilder` | 데이터베이스 이름 |
-| `schema` | `(schema: string) => ViewBuilder` | 스키마 이름 |
-| `query` | `(viewFn: (db) => Queryable) => ViewBuilder` | 뷰 쿼리 정의 |
-| `relations` | `(fn: (r) => Record) => ViewBuilder` | 관계 정의 (relationKey만 가능) |
-
-**DbContext 등록:**
-
-```typescript
-const MyDb = defineDbContext({
-  tables: { user: User },
-  views: { userSummary: UserSummary },
-});
-```
-
----
-
-## Procedure
-
-```typescript
-import { Procedure } from "@simplysm/orm-common";
-
-const GetUserOrders = Procedure("get_user_orders")
-  .database("mydb")
-  .params((c) => ({
-    userId: c.int(),
-    fromDate: c.date().nullable(),
-  }))
-  .returns((c) => ({
-    orderId: c.int(),
-    amount: c.decimal(10, 2),
-    createdAt: c.datetime(),
-  }))
-  .body(`
-    SELECT id AS orderId, amount, created_at AS createdAt
-    FROM orders
-    WHERE user_id = userId AND created_at >= COALESCE(fromDate, '1900-01-01')
-  `);
-```
-
-### Procedure API
-
-```
-Procedure(name: string): ProcedureBuilder
-```
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `description` | `(desc: string) => ProcedureBuilder` | 프로시저 설명 |
-| `database` | `(db: string) => ProcedureBuilder` | 데이터베이스 이름 |
-| `schema` | `(schema: string) => ProcedureBuilder` | 스키마 이름 |
-| `params` | `(fn: (c) => Record) => ProcedureBuilder` | 파라미터 정의 |
-| `returns` | `(fn: (c) => Record) => ProcedureBuilder` | 반환 타입 정의 |
-| `body` | `(sql: string) => ProcedureBuilder` | 프로시저 본문 SQL |
-
-**DbContext 등록:**
-
-```typescript
-const MyDb = defineDbContext({
-  tables: { user: User },
-  procedures: { getUserOrders: GetUserOrders },
-});
-```
-
-MSSQL은 파라미터에 `@` 접두사 필요: `@userId`, `@fromDate`
-
----
-
-## Index
-
-```typescript
-.indexes((i) => [
-  i.index("email").unique(),                     // UNIQUE INDEX
-  i.index("name", "role").orderBy("ASC", "DESC"), // 정렬 방향 지정
-  i.index("createdAt").name("ix_custom_name"),   // 커스텀 이름
-  i.index("code").description("코드 인덱스"),
-])
-```
-
-### IndexBuilder API
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `index` | `(...columns: string[]) => IndexBuilder` | 인덱스 생성 (단일/복합) |
-| `unique` | `() => IndexBuilder` | 유니크 인덱스 설정 |
-| `orderBy` | `(...dirs: ("ASC"\|"DESC")[]) => IndexBuilder` | 컬럼별 정렬 방향 |
-| `name` | `(name: string) => IndexBuilder` | 커스텀 인덱스 이름 |
-| `description` | `(desc: string) => IndexBuilder` | 인덱스 설명 |
-
----
-
-## defineDbContext / createDbContext
-
-### defineDbContext -- 스키마 블루프린트
-
-```typescript
-import { defineDbContext } from "@simplysm/orm-common";
-
-const MyDb = defineDbContext({
-  tables: { user: User, order: Order },
-  views: { userSummary: UserSummary },
-  procedures: { getUserOrders: GetUserOrders },
-  migrations: [
-    {
-      name: "20260105_001_add_phone",
-      up: async (db) => {
-        const c = createColumnFactory();
-        await db.addColumn({ name: "user" }, "phone", c.varchar(20).nullable());
-      },
-    },
-  ],
-});
-```
-
-`_migration` 테이블이 자동으로 포함된다.
-
-### createDbContext -- 런타임 인스턴스 생성
-
-```typescript
-import { createDbContext } from "@simplysm/orm-common";
-
-const db = createDbContext(MyDb, executor, {
-  database: "mydb",
-  schema: "dbo",  // MSSQL/PostgreSQL 선택
-});
-```
-
-```
-createDbContext(
-  def: DbContextDef,
-  executor: DbContextExecutor,
-  opt: { database: string; schema?: string },
-): DbContextInstance
-```
-
-`executor`는 `DbContextExecutor` 인터페이스를 구현해야 한다 (`@simplysm/orm-node`의 `NodeDbContextExecutor` 등).
-
-생성된 인스턴스는 다음을 포함한다:
-- 등록된 테이블/뷰에 대한 `Queryable` 접근자 (예: `db.user()`, `db.order()`)
-- 등록된 프로시저에 대한 `Executable` 접근자 (예: `db.getUserOrders()`)
-- 연결/트랜잭션 관리 메서드
-- DDL 실행 메서드
-- `initialize()` 메서드
-- `_migration()` 시스템 테이블 접근자