@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/orm-common/types/query-def.md

@@ -0,0 +1,224 @@
+# QueryDef
+
+SQL AST 정의 타입 모음. `Queryable`이 내부적으로 생성하며, `QueryBuilderBase.build(def)`에 전달되어 SQL 문자열로 변환된다.
+
+## `QueryDef`
+
+모든 쿼리 정의의 유니온 타입.
+
+```typescript
+export type QueryDef =
+  | SelectQueryDef
+  | InsertQueryDef
+  | InsertIfNotExistsQueryDef
+  | InsertIntoQueryDef
+  | UpdateQueryDef
+  | DeleteQueryDef
+  | UpsertQueryDef
+  | SwitchFkQueryDef
+  | CreateTableQueryDef
+  | DropTableQueryDef
+  | RenameTableQueryDef
+  | TruncateQueryDef
+  | AddColumnQueryDef
+  | DropColumnQueryDef
+  | ModifyColumnQueryDef
+  | RenameColumnQueryDef
+  | AddPrimaryKeyQueryDef
+  | DropPrimaryKeyQueryDef
+  | AddForeignKeyQueryDef
+  | DropForeignKeyQueryDef
+  | AddIndexQueryDef
+  | DropIndexQueryDef
+  | CreateViewQueryDef
+  | DropViewQueryDef
+  | CreateProcQueryDef
+  | DropProcQueryDef
+  | ExecProcQueryDef
+  | ClearSchemaQueryDef
+  | SchemaExistsQueryDef;
+```
+
+## `QueryDefObjectName`
+
+DB 객체 이름 (테이블, 뷰, 프로시저 등).
+
+```typescript
+export interface QueryDefObjectName {
+  database?: string;
+  schema?: string;
+  name: string;
+}
+```
+
+DBMS별 네임스페이스 처리:
+- MySQL: `database.name` (schema 무시)
+- MSSQL: `database.schema.name` (schema 기본값 dbo)
+- PostgreSQL: `schema.name` (database는 연결용)
+
+## DML 쿼리 정의
+
+### `SelectQueryDef`
+
+```typescript
+export interface SelectQueryDef {
+  type: "select";
+  from?: QueryDefObjectName | SelectQueryDef | SelectQueryDef[] | string;
+  as: string;
+  select?: Record<string, Expr>;
+  distinct?: boolean;
+  top?: number;
+  lock?: boolean;
+  where?: WhereExpr[];
+  joins?: SelectQueryDefJoin[];
+  orderBy?: [Expr, ("ASC" | "DESC")?][];
+  limit?: [number, number];
+  groupBy?: Expr[];
+  having?: WhereExpr[];
+  with?: { name: string; base: SelectQueryDef; recursive: SelectQueryDef };
+}
+```
+
+### `SelectQueryDefJoin`
+
+```typescript
+export interface SelectQueryDefJoin extends SelectQueryDef {
+  isSingle?: boolean;
+}
+```
+
+### `InsertQueryDef`
+
+```typescript
+export interface InsertQueryDef {
+  type: "insert";
+  table: QueryDefObjectName;
+  records: Record<string, ColumnPrimitive>[];
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+### `InsertIfNotExistsQueryDef`
+
+```typescript
+export interface InsertIfNotExistsQueryDef {
+  type: "insertIfNotExists";
+  table: QueryDefObjectName;
+  record: Record<string, ColumnPrimitive>;
+  existsSelectQuery: SelectQueryDef;
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+### `InsertIntoQueryDef`
+
+```typescript
+export interface InsertIntoQueryDef {
+  type: "insertInto";
+  table: QueryDefObjectName;
+  recordsSelectQuery: SelectQueryDef;
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+### `UpdateQueryDef`
+
+```typescript
+export interface UpdateQueryDef {
+  type: "update";
+  table: QueryDefObjectName;
+  as: string;
+  record: Record<string, Expr>;
+  top?: number;
+  where?: WhereExpr[];
+  joins?: SelectQueryDefJoin[];
+  limit?: [number, number];
+  output?: CudOutputDef;
+}
+```
+
+### `DeleteQueryDef`
+
+```typescript
+export interface DeleteQueryDef {
+  type: "delete";
+  table: QueryDefObjectName;
+  as: string;
+  top?: number;
+  where?: WhereExpr[];
+  joins?: SelectQueryDefJoin[];
+  limit?: [number, number];
+  output?: CudOutputDef;
+}
+```
+
+### `UpsertQueryDef`
+
+```typescript
+export interface UpsertQueryDef {
+  type: "upsert";
+  table: QueryDefObjectName;
+  existsSelectQuery: SelectQueryDef;
+  insertRecord: Record<string, Expr>;
+  updateRecord: Record<string, Expr>;
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+## `CudOutputDef`
+
+INSERT/UPDATE/DELETE 후 반환값 정의 (OUTPUT 절).
+
+```typescript
+export interface CudOutputDef {
+  columns: string[];
+  pkColNames: string[];
+  aiColName?: string;
+}
+```
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `columns` | `string[]` | 반환할 컬럼 이름 배열 |
+| `pkColNames` | `string[]` | PK 컬럼 이름 배열 |
+| `aiColName` | `string \| undefined` | AUTO_INCREMENT 컬럼 이름 |
+
+## DDL 쿼리 정의
+
+| 인터페이스 | `type` 값 | 설명 |
+|------------|-----------|------|
+| `CreateTableQueryDef` | `"createTable"` | CREATE TABLE |
+| `DropTableQueryDef` | `"dropTable"` | DROP TABLE |
+| `RenameTableQueryDef` | `"renameTable"` | RENAME TABLE |
+| `TruncateQueryDef` | `"truncate"` | TRUNCATE TABLE |
+| `AddColumnQueryDef` | `"addColumn"` | ADD COLUMN |
+| `DropColumnQueryDef` | `"dropColumn"` | DROP COLUMN |
+| `ModifyColumnQueryDef` | `"modifyColumn"` | MODIFY/ALTER COLUMN |
+| `RenameColumnQueryDef` | `"renameColumn"` | RENAME COLUMN |
+| `AddPrimaryKeyQueryDef` | `"addPrimaryKey"` | ADD PRIMARY KEY |
+| `DropPrimaryKeyQueryDef` | `"dropPrimaryKey"` | DROP PRIMARY KEY |
+| `AddForeignKeyQueryDef` | `"addForeignKey"` | ADD FOREIGN KEY |
+| `DropForeignKeyQueryDef` | `"dropForeignKey"` | DROP FOREIGN KEY |
+| `AddIndexQueryDef` | `"addIndex"` | ADD INDEX |
+| `DropIndexQueryDef` | `"dropIndex"` | DROP INDEX |
+| `CreateViewQueryDef` | `"createView"` | CREATE VIEW |
+| `DropViewQueryDef` | `"dropView"` | DROP VIEW |
+| `CreateProcQueryDef` | `"createProc"` | CREATE PROCEDURE |
+| `DropProcQueryDef` | `"dropProc"` | DROP PROCEDURE |
+| `ExecProcQueryDef` | `"execProc"` | EXEC PROCEDURE |
+| `ClearSchemaQueryDef` | `"clearSchema"` | 스키마 내 모든 객체 제거 |
+| `SchemaExistsQueryDef` | `"schemaExists"` | 스키마 존재 여부 확인 |
+| `SwitchFkQueryDef` | `"switchFk"` | FK 제약조건 활성화/비활성화 |
+
+## `DDL_TYPES` / `DdlType`
+
+DDL 타입 문자열 목록 및 유니온 타입. `DbContext.executeDefs()` 내부에서 트랜잭션 중 DDL 실행 차단에 사용된다.
+
+```typescript
+export const DDL_TYPES: readonly string[];
+export type DdlType = typeof DDL_TYPES[number];
+```

package/claude/references/sd-simplysm-v14/orm-node/README.md

@@ -0,0 +1,65 @@
+# @simplysm/orm-node
+
+> Node.js 환경에서 MSSQL, MySQL, PostgreSQL에 대한 저수준 DB 연결 및 ORM 실행자를 제공한다.
+> `@simplysm/orm-common`의 `DbContext`와 함께 사용하며, 네이티브 드라이버(tedious, mysql2, pg)를 선택적 peerDependency로 지연 로딩한다.
+
+## Installation
+
+```bash
+npm install @simplysm/orm-node
+```
+
+Peer dependencies (사용하는 DBMS에 따라 선택적 설치):
+
+```bash
+# MySQL
+npm install mysql2
+
+# PostgreSQL
+npm install pg pg-copy-streams
+
+# MSSQL
+npm install tedious
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| DbContext로 ORM 쿼리 실행 | [createOrm](./core/create-orm.md) |
+| 저수준 SQL 직접 실행 | [createDbConn](./core/create-db-conn.md) |
+| 연결 설정 구성 | [DbConnConfig](./types/db-conn-config.md) |
+| 특정 DBMS의 bulk insert 동작 확인 | [MssqlDbConn](./connections/mssql-db-conn.md), [MysqlDbConn](./connections/mysql-db-conn.md), [PostgresqlDbConn](./connections/postgresql-db-conn.md) |
+| DbConn 인터페이스 확인 | [DbConn](./types/db-conn.md) |
+
+## API Overview
+
+### Types
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`DbConn`](./types/db-conn.md) | interface | DbConn 구현체의 공통 인터페이스를 확인할 때 |
+| [`DbConnConfig`](./types/db-conn-config.md) | type | DB 연결 설정을 구성할 때. `dialect` 필드로 DBMS를 결정한다 |
+| [`DB_CONN_CONNECT_TIMEOUT`](./types/db-conn-constants.md) | const | 타임아웃 상수나 오류 메시지 상수를 참조할 때 |
+| [`getDialectFromConfig`](./types/get-dialect-from-config.md) | function | `DbConnConfig`에서 정규화된 `Dialect`를 추출할 때 (`"mssql-azure"` → `"mssql"`) |
+
+### Connections
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`MssqlDbConn`](./connections/mssql-db-conn.md) | class | MSSQL/Azure SQL에 저수준으로 연결할 때 (tedious 사용) |
+| [`MysqlDbConn`](./connections/mysql-db-conn.md) | class | MySQL에 저수준으로 연결할 때 (mysql2/promise 사용) |
+| [`PostgresqlDbConn`](./connections/postgresql-db-conn.md) | class | PostgreSQL에 저수준으로 연결할 때 (pg + pg-copy-streams 사용) |
+
+### Core
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`createDbConn`](./core/create-db-conn.md) | function | dialect 기반으로 DbConn 인스턴스를 자동 생성할 때 |
+| [`NodeDbContextExecutor`](./core/node-db-context-executor.md) | class | DbContext 내부에서 사용하는 실행자. 직접 사용할 일은 거의 없다 |
+| [`createOrm`](./core/create-orm.md) | function | DbContext 서브클래스와 연결 설정으로 트랜잭션 관리 ORM 인스턴스를 만들 때 |
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 브라우저/클라이언트에서 DB 접근 → `@simplysm/service-client`로 서버를 경유한다.
+- ORM 쿼리빌더·스키마 정의만 필요 → `@simplysm/orm-common`을 직접 사용한다.

package/claude/references/sd-simplysm-v14/orm-node/connections/mssql-db-conn.md

@@ -0,0 +1,85 @@
+# `MssqlDbConn`
+
+tedious 라이브러리를 사용하여 MSSQL/Azure SQL 연결을 관리하는 클래스.
+
+## When to use
+
+- ✅ 테스트 코드에서 MSSQL 연결을 직접 생성하여 네이티브 라이브러리를 주입할 때.
+- ❌ 일반적으로 직접 생성하지 않는다. [`createDbConn()`](../core/create-db-conn.md)이 dialect에 따라 자동 생성한다.
+
+## Signature
+
+```typescript
+class MssqlDbConn extends EventEmitter<{ close: void }> implements DbConn {
+  isConnected: boolean;
+  isInTransaction: boolean;
+  readonly config: MssqlDbConnConfig;
+
+  constructor(
+    tedious: typeof import("tedious"),
+    config: MssqlDbConnConfig,
+  );
+
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
+  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
+  bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `isConnected` | property | `boolean` | 연결 여부 |
+| `isInTransaction` | property | `boolean` | 트랜잭션 진행 여부 |
+| `config` | property | `MssqlDbConnConfig` | 연결 설정 |
+| `connect()` | method | `Promise<void>` | DB 연결을 수립한다. `dialect === "mssql-azure"`인 경우 `encrypt: true`로 연결한다. 연결 성공 시 유휴 타임아웃 타이머(`DB_CONN_DEFAULT_TIMEOUT * 2`)를 시작한다 |
+| `close()` | method | `Promise<void>` | 진행 중인 요청을 취소(`cancel()`)하고 30초 내에 완료될 때까지 대기한 뒤 연결을 종료한다 |
+| `beginTransaction(isolationLevel?)` | method | `Promise<void>` | 트랜잭션을 시작한다 |
+| `commitTransaction()` | method | `Promise<void>` | 트랜잭션을 커밋한다 |
+| `rollbackTransaction()` | method | `Promise<void>` | 트랜잭션을 롤백한다 |
+| `execute(queries)` | method | `Promise<Record<string, unknown>[][]>` | SQL 쿼리 배열을 순차 실행한다 |
+| `executeParametrized(query, params?)` | method | `Promise<Record<string, unknown>[][]>` | 파라미터화된 쿼리를 실행한다. 파라미터가 있으면 `execSql()`, 없으면 `execSqlBatch()`를 사용한다. 쿼리 오류 시 오류 발생 줄을 `==> ` 접두사로 표시하여 에러 메시지에 포함한다 |
+| `bulkInsert(tableName, columnMetas, records)` | method | `Promise<void>` | tedious `BulkLoad` API를 사용하여 대량 삽입한다 |
+
+일반적으로 직접 생성하지 않고 [`createDbConn()`](../core/create-db-conn.md)을 통해 인스턴스를 얻는다. 직접 생성은 테스트 코드에서 네이티브 라이브러리를 주입할 때 사용한다.
+
+생성자에서 tedious 라이브러리 모듈을 첫 번째 인수로 직접 주입받는다. `createDbConn()`이 동적 import 후 전달한다.
+
+## `bulkInsert()` 값 변환 규칙
+
+| 값 타입 | 변환 방식 |
+|---------|-----------|
+| `Uuid` | `toString()` |
+| `Uint8Array` | `Buffer.from(val)` (tedious 라이브러리 요구사항으로 인한 예외적 허용) |
+| `DateTime` / `DateOnly` | `.date` (native Date 객체) |
+| `Time` | `"HH:mm:ss"` 포맷 문자열 |
+
+## Usage
+
+```typescript
+import { MssqlDbConn } from "@simplysm/orm-node";
+
+const tedious = await import("tedious");
+const conn = new MssqlDbConn(tedious, {
+  dialect: "mssql",
+  host: "localhost",
+  port: 1433,
+  username: "sa",
+  password: "password",
+  database: "mydb",
+});
+
+await conn.connect();
+const results = await conn.execute(["SELECT 1 AS val"]);
+await conn.close();
+```

package/claude/references/sd-simplysm-v14/orm-node/connections/mysql-db-conn.md

@@ -0,0 +1,83 @@
+# `MysqlDbConn`
+
+mysql2/promise 라이브러리를 사용하여 MySQL 연결을 관리하는 클래스.
+
+## When to use
+
+- ✅ 테스트 코드에서 MySQL 연결을 직접 생성하여 네이티브 라이브러리를 주입할 때.
+- ❌ 일반적으로 직접 생성하지 않는다. [`createDbConn()`](../core/create-db-conn.md)이 dialect에 따라 자동 생성한다.
+
+## Signature
+
+```typescript
+class MysqlDbConn extends EventEmitter<{ close: void }> implements DbConn {
+  isConnected: boolean;
+  isInTransaction: boolean;
+  readonly config: MysqlDbConnConfig;
+
+  constructor(
+    mysql2: typeof import("mysql2/promise"),
+    config: MysqlDbConnConfig,
+  );
+
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
+  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
+  bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `isConnected` | property | `boolean` | 연결 여부 |
+| `isInTransaction` | property | `boolean` | 트랜잭션 진행 여부 |
+| `config` | property | `MysqlDbConnConfig` | 연결 설정 |
+| `connect()` | method | `Promise<void>` | DB 연결을 수립한다. `multipleStatements: true`, `charset: "utf8mb4"`로 연결한다 |
+| `close()` | method | `Promise<void>` | DB 연결을 종료한다 |
+| `beginTransaction(isolationLevel?)` | method | `Promise<void>` | `SET SESSION TRANSACTION ISOLATION LEVEL {level}` 후 `BEGIN`을 실행한다. MySQL은 트랜잭션 시작 전에 격리 수준을 설정해야 한다 |
+| `commitTransaction()` | method | `Promise<void>` | 트랜잭션을 커밋한다 |
+| `rollbackTransaction()` | method | `Promise<void>` | 트랜잭션을 롤백한다 |
+| `execute(queries)` | method | `Promise<Record<string, unknown>[][]>` | SQL 쿼리 배열을 순차 실행한다 |
+| `executeParametrized(query, params?)` | method | `Promise<Record<string, unknown>[][]>` | 파라미터화된 쿼리를 실행한다. 결과 형식에 따라 처리: single SELECT → flat 배열, single INSERT/UPDATE/DELETE → 빈 결과 집합, multi-statement → 각 statement의 결과를 별도 결과 집합으로 분리 |
+| `bulkInsert(tableName, columnMetas, records)` | method | `Promise<void>` | `LOAD DATA LOCAL INFILE`을 사용하여 대량 삽입한다 |
+
+일반적으로 직접 생성하지 않고 [`createDbConn()`](../core/create-db-conn.md)을 통해 인스턴스를 얻는다. 직접 생성은 테스트 코드에서 네이티브 라이브러리를 주입할 때 사용한다.
+
+생성자에서 mysql2/promise 라이브러리 모듈을 첫 번째 인수로 직접 주입받는다.
+
+## `bulkInsert()` 처리 흐름
+
+1. `os.tmpdir()`에 UUID 기반 임시 CSV 파일 생성 (TAB 구분)
+2. UUID/binary 컬럼은 hex 문자열로 기록, `SET` 절에서 `UNHEX()` 변환
+3. `LOAD DATA LOCAL INFILE` 실행
+4. `finally` 블록에서 임시 파일 삭제
+
+## Usage
+
+```typescript
+import { MysqlDbConn } from "@simplysm/orm-node";
+
+const mysql2 = await import("mysql2/promise");
+const conn = new MysqlDbConn(mysql2, {
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "testdb",
+});
+
+await conn.connect();
+const results = await conn.execute(["SELECT 1 AS val"]);
+await conn.close();
+```

package/claude/references/sd-simplysm-v14/orm-node/connections/postgresql-db-conn.md

@@ -0,0 +1,86 @@
+# `PostgresqlDbConn`
+
+pg + pg-copy-streams 라이브러리를 사용하여 PostgreSQL 연결을 관리하는 클래스.
+
+## When to use
+
+- ✅ 테스트 코드에서 PostgreSQL 연결을 직접 생성하여 네이티브 라이브러리를 주입할 때.
+- ❌ 일반적으로 직접 생성하지 않는다. [`createDbConn()`](../core/create-db-conn.md)이 dialect에 따라 자동 생성한다.
+
+## Signature
+
+```typescript
+class PostgresqlDbConn extends EventEmitter<{ close: void }> implements DbConn {
+  isConnected: boolean;
+  isInTransaction: boolean;
+  readonly config: PostgresqlDbConnConfig;
+
+  constructor(
+    pg: typeof import("pg"),
+    pgCopyStreams: typeof import("pg-copy-streams"),
+    config: PostgresqlDbConnConfig,
+  );
+
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
+  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
+  bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `isConnected` | property | `boolean` | 연결 여부 |
+| `isInTransaction` | property | `boolean` | 트랜잭션 진행 여부 |
+| `config` | property | `PostgresqlDbConnConfig` | 연결 설정 |
+| `connect()` | method | `Promise<void>` | DB 연결을 수립한다. 기본 포트는 `5432`. `connectionTimeoutMillis: DB_CONN_CONNECT_TIMEOUT`, `query_timeout: DB_CONN_DEFAULT_TIMEOUT`으로 연결한다 |
+| `close()` | method | `Promise<void>` | DB 연결을 종료한다 |
+| `beginTransaction(isolationLevel?)` | method | `Promise<void>` | `BEGIN` 후 `SET TRANSACTION ISOLATION LEVEL {level}`을 실행한다 |
+| `commitTransaction()` | method | `Promise<void>` | `COMMIT`을 실행한다 |
+| `rollbackTransaction()` | method | `Promise<void>` | `ROLLBACK`을 실행한다 |
+| `execute(queries)` | method | `Promise<Record<string, unknown>[][]>` | SQL 쿼리 배열을 순차 실행한다 |
+| `executeParametrized(query, params?)` | method | `Promise<Record<string, unknown>[][]>` | 파라미터화된 쿼리를 실행한다. PostgreSQL은 단일 결과 집합을 반환하므로 `[result.rows]`로 래핑하여 반환한다 |
+| `bulkInsert(tableName, columnMetas, records)` | method | `Promise<void>` | `COPY FROM STDIN`(CSV 형식)을 사용하여 대량 삽입한다 |
+
+일반적으로 직접 생성하지 않고 [`createDbConn()`](../core/create-db-conn.md)을 통해 인스턴스를 얻는다. 직접 생성은 테스트 코드에서 네이티브 라이브러리를 주입할 때 사용한다.
+
+생성자에서 pg와 pg-copy-streams 라이브러리 모듈을 첫 번째, 두 번째 인수로 직접 주입받는다.
+
+## `bulkInsert()` 처리 방식
+
+`pg-copy-streams`의 `from()` 함수로 스트림을 생성하고, `Readable.from(csvContent)`를 파이프한다.
+
+binary 컬럼 값 변환:
+- `binary` 타입: PostgreSQL bytea hex 형식 (`\x{hex}`, CSV 큰따옴표로 감쌈)
+- `uuid` 타입: `toString()` 그대로
+
+## Usage
+
+```typescript
+import { PostgresqlDbConn } from "@simplysm/orm-node";
+
+const pg = await import("pg");
+const pgCopyStreams = await import("pg-copy-streams");
+const conn = new PostgresqlDbConn(pg, pgCopyStreams, {
+  dialect: "postgresql",
+  host: "localhost",
+  port: 5432,
+  username: "postgres",
+  password: "password",
+  database: "testdb",
+});
+
+await conn.connect();
+const results = await conn.execute(["SELECT 1 AS val"]);
+await conn.close();
+```

package/claude/references/sd-simplysm-v14/orm-node/core/create-db-conn.md

@@ -0,0 +1,62 @@
+# `createDbConn`
+
+dialect 기반 DbConn 팩토리. 네이티브 드라이버를 지연 로딩하여 DbConn 인스턴스를 생성한다.
+
+## When to use
+
+- ✅ ORM 없이 생 SQL을 직접 실행할 때.
+- ✅ 트랜잭션·연결 생명주기를 직접 제어할 때.
+- ❌ DbContext 기반 ORM 쿼리를 실행할 때 → [`createOrm`](./create-orm.md)이 내부적으로 연결을 관리한다.
+
+## Signature
+
+```typescript
+async function createDbConn(config: DbConnConfig): Promise<DbConn>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `config` | `DbConnConfig` | 데이터베이스 연결 설정. `dialect` 필드로 구현체를 결정한다 |
+
+## Returns
+
+`Promise<DbConn>` — 아직 연결되지 않은 상태의 DbConn 인스턴스. `connect()`를 별도로 호출해야 한다.
+
+`config.dialect`에 따라 적절한 DbConn 구현체를 생성한다:
+
+| dialect | 반환 타입 | 로드하는 패키지 |
+|---------|-----------|----------------|
+| `"mysql"` | [`MysqlDbConn`](../connections/mysql-db-conn.md) | `mysql2/promise` |
+| `"postgresql"` | [`PostgresqlDbConn`](../connections/postgresql-db-conn.md) | `pg`, `pg-copy-streams` |
+| `"mssql"` / `"mssql-azure"` | [`MssqlDbConn`](../connections/mssql-db-conn.md) | `tedious` |
+
+네이티브 드라이버 패키지는 최초 호출 시에만 동적 import로 로드하고 모듈 수준 캐시에 보관한다. 이후 호출에서는 캐시된 모듈을 재사용한다.
+
+## Usage
+
+```typescript
+import { createDbConn } from "@simplysm/orm-node";
+
+const conn = await createDbConn({
+  dialect: "postgresql",
+  host: "localhost",
+  port: 5432,
+  username: "postgres",
+  password: "password",
+  database: "mydb",
+});
+
+await conn.connect();
+
+try {
+  await conn.beginTransaction();
+  await conn.execute(["INSERT INTO users (name) VALUES ('Alice')"]);
+  await conn.commitTransaction();
+} catch {
+  await conn.rollbackTransaction();
+} finally {
+  await conn.close();
+}
+```