@simplysm/orm-node 13.0.0-beta.6

package/src/connections/mysql-db-conn.ts

@@ -0,0 +1,299 @@
+import { randomUUID } from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import type { Connection } from "mysql2/promise";
+import { createConsola } from "consola";
+import {
+  bytesToHex,
+  DateOnly,
+  DateTime,
+  SdError,
+  EventEmitter,
+  strIsNullOrEmpty,
+  Time,
+  Uuid,
+} from "@simplysm/core-common";
+import type { ColumnMeta, DataType, IsolationLevel } from "@simplysm/orm-common";
+import { DB_CONN_DEFAULT_TIMEOUT, DB_CONN_ERRORS, type DbConn, type MysqlDbConnConfig } from "../types/db-conn";
+
+const logger = createConsola().withTag("mysql-db-conn");
+
+/**
+ * MySQL 데이터베이스 연결 클래스
+ *
+ * mysql2/promise 라이브러리를 사용하여 MySQL 연결을 관리합니다.
+ */
+export class MysqlDbConn extends EventEmitter<{ close: void }> implements DbConn {
+  private static readonly _ROOT_USER = "root";
+  private readonly _timeout = DB_CONN_DEFAULT_TIMEOUT;
+
+  private _conn?: Connection;
+  private _connTimeout?: ReturnType<typeof setTimeout>;
+
+  isConnected = false;
+  isOnTransaction = false;
+
+  constructor(
+    private readonly _mysql2: typeof import("mysql2/promise"),
+    readonly config: MysqlDbConnConfig,
+  ) {
+    super();
+  }
+
+  async connect(): Promise<void> {
+    if (this.isConnected) {
+      throw new SdError(DB_CONN_ERRORS.ALREADY_CONNECTED);
+    }
+
+    const conn = await this._mysql2.createConnection({
+      host: this.config.host,
+      port: this.config.port,
+      user: this.config.username,
+      password: this.config.password,
+      // root 사용자는 특정 database에 바인딩되지 않고 연결하여
+      // 모든 데이터베이스에 접근할 수 있도록 함 (관리 작업용)
+      database: this.config.username === MysqlDbConn._ROOT_USER ? undefined : this.config.database,
+      multipleStatements: true,
+      charset: "utf8mb4",
+      infileStreamFactory: (filePath: string) => fs.createReadStream(filePath), // LOAD DATA LOCAL INFILE 지원
+    } as Parameters<typeof this._mysql2.createConnection>[0]);
+
+    conn.on("end", () => {
+      this.emit("close");
+      this._resetState();
+    });
+
+    conn.on("error", (error) => {
+      logger.error("DB 연결 오류", error.message);
+    });
+
+    this._conn = conn;
+    this._startTimeout();
+    this.isConnected = true;
+  }
+
+  async close(): Promise<void> {
+    this._stopTimeout();
+
+    if (this._conn == null || !this.isConnected) {
+      return;
+    }
+
+    await this._conn.end();
+
+    this.emit("close");
+    this._resetState();
+  }
+
+  async beginTransaction(isolationLevel?: IsolationLevel): Promise<void> {
+    const conn = this._assertConnected();
+
+    const level = (isolationLevel ?? this.config.defaultIsolationLevel ?? "READ_UNCOMMITTED").replace(/_/g, " ");
+
+    // 격리 수준을 먼저 설정 (다음 트랜잭션에 적용됨)
+    await conn.query({
+      sql: `SET SESSION TRANSACTION ISOLATION LEVEL ${level}`,
+      timeout: this._timeout,
+    });
+
+    // 그 다음 트랜잭션 시작
+    await conn.beginTransaction();
+
+    this.isOnTransaction = true;
+  }
+
+  async commitTransaction(): Promise<void> {
+    const conn = this._assertConnected();
+    await conn.commit();
+    this.isOnTransaction = false;
+  }
+
+  async rollbackTransaction(): Promise<void> {
+    const conn = this._assertConnected();
+    await conn.rollback();
+    this.isOnTransaction = false;
+  }
+
+  async execute(queries: string[]): Promise<unknown[][]> {
+    const results: unknown[][] = [];
+    for (const query of queries.filter((item) => !strIsNullOrEmpty(item))) {
+      const resultItems = await this.executeParametrized(query);
+      results.push(...resultItems);
+    }
+    return results;
+  }
+
+  async executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]> {
+    const conn = this._assertConnected();
+
+    logger.debug("쿼리 실행", { queryLength: query.length, params });
+
+    try {
+      const [queryResults] = await conn.query({
+        sql: query,
+        timeout: this._timeout,
+        values: params,
+      });
+
+      this._startTimeout();
+
+      // MySQL은 INSERT/UPDATE/DELETE 문에 대해 ResultSetHeader를 반환함
+      // SELECT 결과만 추출하기 위해 ResultSetHeader 객체를 필터링함
+      // ResultSetHeader는 affectedRows, fieldCount 등의 필드를 가지고 있음
+      const result: unknown[] = [];
+      if (queryResults instanceof Array) {
+        for (const queryResult of queryResults.filter(
+          (item: unknown) =>
+            !(typeof item === "object" && item !== null && "affectedRows" in item && "fieldCount" in item),
+        )) {
+          result.push(queryResult);
+        }
+      }
+
+      return [result];
+    } catch (err) {
+      this._startTimeout();
+      const error = err as Error & { sql?: string };
+      throw new SdError(
+        error,
+        "쿼리 수행중 오류발생" + (error.sql != null ? "\n-- query\n" + error.sql.trim() + "\n--" : ""),
+      );
+    }
+  }
+
+  async bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void> {
+    const conn = this._assertConnected();
+
+    if (records.length === 0) return;
+
+    const colNames = Object.keys(columnMetas);
+
+    // 임시 CSV 파일 생성
+    const tmpDir = os.tmpdir();
+    const tmpFile = path.join(tmpDir, `mysql_bulk_${randomUUID()}.csv`);
+
+    try {
+      // CSV 데이터 생성
+      const csvLines: string[] = [];
+      for (const record of records) {
+        const row = colNames.map((colName) => this._escapeForCsv(record[colName], columnMetas[colName].dataType));
+        csvLines.push(row.join("\t"));
+      }
+      const csvContent = csvLines.join("\n");
+
+      // 파일 쓰기
+      await fs.promises.writeFile(tmpFile, csvContent, "utf8");
+
+      // UUID/binary 컬럼은 임시 변수로 읽고 SET 절에서 UNHEX() 변환
+      const binaryColNames = colNames.filter((c) => {
+        const dt = columnMetas[c].dataType.type;
+        return dt === "uuid" || dt === "binary";
+      });
+      const normalCols = colNames.map((c) => {
+        if (binaryColNames.includes(c)) return `@_${c}`;
+        return `\`${c}\``;
+      });
+      const setClauses = binaryColNames.map((c) => `\`${c}\` = UNHEX(@_${c})`);
+
+      // LOAD DATA LOCAL INFILE 실행
+      let query = `LOAD DATA LOCAL INFILE ? INTO TABLE ${tableName} FIELDS TERMINATED BY '\\t' LINES TERMINATED BY '\\n' (${normalCols.join(", ")})`;
+      if (setClauses.length > 0) {
+        query += ` SET ${setClauses.join(", ")}`;
+      }
+
+      await conn.query({ sql: query, timeout: this._timeout, values: [tmpFile] });
+    } finally {
+      // 임시 파일 삭제
+      try {
+        await fs.promises.unlink(tmpFile);
+      } catch {
+        // 삭제 실패 무시
+      }
+    }
+  }
+
+  // ─────────────────────────────────────────────
+  // Private helpers
+  // ─────────────────────────────────────────────
+
+  /**
+   * MySQL LOAD DATA INFILE용 값 이스케이프
+   */
+  private _escapeForCsv(value: unknown, dataType: DataType): string {
+    if (value == null) {
+      return "\\N"; // MySQL NULL 표현
+    }
+
+    switch (dataType.type) {
+      case "int":
+      case "bigint":
+      case "float":
+      case "double":
+      case "decimal":
+        return String(value);
+
+      case "boolean":
+        return (value as boolean) ? "1" : "0";
+
+      case "varchar":
+      case "char":
+      case "text": {
+        const str = value as string;
+        // 탭, 줄바꿈, 백슬래시 이스케이프
+        return str.replace(/\\/g, "\\\\").replace(/\t/g, "\\t").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+      }
+
+      case "datetime":
+        return (value as DateTime).toFormatString("yyyy-MM-dd HH:mm:ss.fff");
+
+      case "date":
+        return (value as DateOnly).toFormatString("yyyy-MM-dd");
+
+      case "time":
+        return (value as Time).toFormatString("HH:mm:ss");
+
+      case "uuid":
+        return (value as Uuid).toString().replace(/-/g, ""); // BINARY(16) 저장용 hex
+
+      case "binary":
+        return bytesToHex(value as Uint8Array);
+
+      default:
+        throw new SdError(`지원하지 않는 DataType: ${JSON.stringify(dataType)}`);
+    }
+  }
+
+  private _assertConnected(): Connection {
+    if (this._conn == null || !this.isConnected) {
+      throw new SdError(DB_CONN_ERRORS.NOT_CONNECTED);
+    }
+    this._startTimeout();
+    return this._conn;
+  }
+
+  private _resetState(): void {
+    this.isConnected = false;
+    this.isOnTransaction = false;
+    this._conn = undefined;
+  }
+
+  private _stopTimeout(): void {
+    if (this._connTimeout != null) {
+      clearTimeout(this._connTimeout);
+    }
+  }
+
+  private _startTimeout(): void {
+    this._stopTimeout();
+    this._connTimeout = setTimeout(() => {
+      this.close().catch((err) => {
+        logger.error("close error", err instanceof Error ? err.message : String(err));
+      });
+    }, this._timeout * 2);
+  }
+}

package/src/connections/postgresql-db-conn.ts

@@ -0,0 +1,254 @@
+import { Readable } from "stream";
+import { createConsola } from "consola";
+import {
+  bytesToHex,
+  DateOnly,
+  DateTime,
+  SdError,
+  EventEmitter,
+  strIsNullOrEmpty,
+  Time,
+  Uuid,
+} from "@simplysm/core-common";
+import type { ColumnMeta, DataType, IsolationLevel } from "@simplysm/orm-common";
+import { DB_CONN_DEFAULT_TIMEOUT, DB_CONN_ERRORS, type DbConn, type PostgresqlDbConnConfig } from "../types/db-conn";
+import type { Client } from "pg";
+import type { CopyStreamQuery } from "pg-copy-streams";
+
+const logger = createConsola().withTag("postgresql-db-conn");
+
+/**
+ * PostgreSQL 데이터베이스 연결 클래스
+ *
+ * pg 라이브러리를 사용하여 PostgreSQL 연결을 관리합니다.
+ */
+export class PostgresqlDbConn extends EventEmitter<{ close: void }> implements DbConn {
+  private readonly _timeout = DB_CONN_DEFAULT_TIMEOUT;
+
+  private _client?: Client;
+  private _connTimeout?: ReturnType<typeof setTimeout>;
+
+  isConnected = false;
+  isOnTransaction = false;
+
+  constructor(
+    private readonly _pg: typeof import("pg"),
+    private readonly _pgCopyFrom: (queryText: string) => CopyStreamQuery,
+    readonly config: PostgresqlDbConnConfig,
+  ) {
+    super();
+  }
+
+  async connect(): Promise<void> {
+    if (this.isConnected) {
+      throw new SdError(DB_CONN_ERRORS.ALREADY_CONNECTED);
+    }
+
+    const client = new this._pg.Client({
+      host: this.config.host,
+      port: this.config.port ?? 5432,
+      user: this.config.username,
+      password: this.config.password,
+      database: this.config.database,
+      connectionTimeoutMillis: this._timeout,
+      query_timeout: this._timeout,
+    });
+
+    client.on("end", () => {
+      this.emit("close");
+      this._resetState();
+    });
+
+    client.on("error", (error) => {
+      logger.error("DB 연결 오류", error.message);
+    });
+
+    await client.connect();
+
+    this._client = client;
+    this._startTimeout();
+    this.isConnected = true;
+  }
+
+  async close(): Promise<void> {
+    this._stopTimeout();
+
+    if (this._client == null || !this.isConnected) {
+      return;
+    }
+
+    await this._client.end();
+
+    this.emit("close");
+    this._resetState();
+  }
+
+  async beginTransaction(isolationLevel?: IsolationLevel): Promise<void> {
+    this._assertConnected();
+
+    const level = (isolationLevel ?? this.config.defaultIsolationLevel ?? "READ_UNCOMMITTED").replace(/_/g, " ");
+
+    await this._client!.query("BEGIN");
+    await this._client!.query(`SET TRANSACTION ISOLATION LEVEL ${level}`);
+
+    this.isOnTransaction = true;
+  }
+
+  async commitTransaction(): Promise<void> {
+    this._assertConnected();
+    await this._client!.query("COMMIT");
+    this.isOnTransaction = false;
+  }
+
+  async rollbackTransaction(): Promise<void> {
+    this._assertConnected();
+    await this._client!.query("ROLLBACK");
+    this.isOnTransaction = false;
+  }
+
+  async execute(queries: string[]): Promise<unknown[][]> {
+    const results: unknown[][] = [];
+    for (const query of queries.filter((item) => !strIsNullOrEmpty(item))) {
+      const resultItems = await this.executeParametrized(query);
+      results.push(...resultItems);
+    }
+    return results;
+  }
+
+  async executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]> {
+    this._assertConnected();
+
+    logger.debug("쿼리 실행", { queryLength: query.length, params });
+
+    try {
+      const result = await this._client!.query(query, params);
+
+      this._startTimeout();
+
+      // PostgreSQL은 단일 결과셋 반환
+      return [result.rows];
+    } catch (err) {
+      this._startTimeout();
+      const error = err instanceof Error ? err : new Error(String(err));
+      throw new SdError(error, "쿼리 수행중 오류발생\n-- query\n" + query.trim() + "\n--");
+    }
+  }
+
+  async bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void> {
+    this._assertConnected();
+
+    if (records.length === 0) return;
+
+    const colNames = Object.keys(columnMetas);
+    const wrappedCols = colNames.map((c) => `"${c}"`).join(", ");
+
+    // COPY FROM STDIN 스트림 생성
+    const copyQuery = `COPY ${tableName} (${wrappedCols}) FROM STDIN WITH (FORMAT csv, NULL '\\N')`;
+    const stream = this._client!.query(this._pgCopyFrom(copyQuery));
+
+    // CSV 데이터 생성
+    const csvLines: string[] = [];
+    for (const record of records) {
+      const row = colNames.map((colName) => this._escapeForCsv(record[colName], columnMetas[colName].dataType));
+      csvLines.push(row.join(","));
+    }
+    const csvContent = csvLines.join("\n") + "\n";
+
+    // 스트림으로 데이터 전송
+    await new Promise<void>((resolve, reject) => {
+      const readable = Readable.from([csvContent]);
+
+      readable.on("error", reject);
+      stream.on("error", reject);
+      stream.on("finish", resolve);
+
+      readable.pipe(stream);
+    });
+  }
+
+  // ─────────────────────────────────────────────
+  // Private helpers
+  // ─────────────────────────────────────────────
+
+  /**
+   * PostgreSQL COPY CSV용 값 이스케이프
+   */
+  private _escapeForCsv(value: unknown, dataType: DataType): string {
+    if (value == null) {
+      return "\\N"; // NULL 표현
+    }
+
+    switch (dataType.type) {
+      case "int":
+      case "bigint":
+      case "float":
+      case "double":
+      case "decimal":
+        return String(value);
+
+      case "boolean":
+        return (value as boolean) ? "true" : "false";
+
+      case "varchar":
+      case "char":
+      case "text": {
+        const str = value as string;
+        // CSV 형식: 쌍따옴표로 감싸고, 내부 쌍따옴표는 두 번
+        if (str.includes('"') || str.includes(",") || str.includes("\n") || str.includes("\r")) {
+          return '"' + str.replace(/"/g, '""') + '"';
+        }
+        return str;
+      }
+
+      case "datetime":
+        return (value as DateTime).toFormatString("yyyy-MM-dd HH:mm:ss.fff");
+
+      case "date":
+        return (value as DateOnly).toFormatString("yyyy-MM-dd");
+
+      case "time":
+        return (value as Time).toFormatString("HH:mm:ss");
+
+      case "uuid":
+        return (value as Uuid).toString();
+
+      case "binary":
+        return '"\\x' + bytesToHex(value as Uint8Array) + '"'; // PostgreSQL bytea hex 형식 (CSV 쌍따옴표로 감쌈)
+
+      default:
+        throw new SdError(`지원하지 않는 DataType: ${JSON.stringify(dataType)}`);
+    }
+  }
+
+  private _assertConnected(): void {
+    if (this._client == null || !this.isConnected) {
+      throw new SdError(DB_CONN_ERRORS.NOT_CONNECTED);
+    }
+    this._startTimeout();
+  }
+
+  private _resetState(): void {
+    this.isConnected = false;
+    this.isOnTransaction = false;
+    this._client = undefined;
+  }
+
+  private _stopTimeout(): void {
+    if (this._connTimeout != null) {
+      clearTimeout(this._connTimeout);
+    }
+  }
+
+  private _startTimeout(): void {
+    this._stopTimeout();
+    this._connTimeout = setTimeout(() => {
+      this.close().catch((err) => {
+        logger.error("close error", err instanceof Error ? err.message : String(err));
+      });
+    }, this._timeout * 2);
+  }
+}

package/src/db-conn-factory.ts

@@ -0,0 +1,114 @@
+import type { Pool } from "generic-pool";
+import { createPool } from "generic-pool";
+import type { DbConn, DbConnConfig } from "./types/db-conn";
+import { PooledDbConn } from "./pooled-db-conn";
+import { MysqlDbConn } from "./connections/mysql-db-conn";
+import { MssqlDbConn } from "./connections/mssql-db-conn";
+import { PostgresqlDbConn } from "./connections/postgresql-db-conn";
+
+/**
+ * DB 연결 팩토리
+ *
+ * 데이터베이스 연결 인스턴스를 생성하고 풀링을 관리한다.
+ * MSSQL, MySQL, PostgreSQL을 지원한다.
+ */
+export class DbConnFactory {
+  // 설정별 커넥션 풀 캐싱
+  private static readonly _poolMap = new Map<string, Pool<DbConn>>();
+
+  /**
+   * DB 연결 생성
+   *
+   * 커넥션 풀에서 연결을 획득하여 반환한다.
+   * 풀이 없는 경우 새로 생성한다.
+   *
+   * @param config - 데이터베이스 연결 설정
+   * @returns 풀링된 DB 연결 객체
+   */
+  static create(config: DbConnConfig): Promise<DbConn> {
+    // 1. 풀 가져오기 (없으면 생성)
+    const pool = this._getOrCreatePool(config);
+
+    // 2. 래퍼 객체 반환
+    return Promise.resolve(new PooledDbConn(pool, config));
+  }
+
+  private static _getOrCreatePool(config: DbConnConfig): Pool<DbConn> {
+    // 객체를 키로 쓰기 위해 문자열 변환 (중첩 객체도 정렬하여 동일 설정의 일관된 키 보장)
+    const configKey = JSON.stringify(config, (_, value: unknown) =>
+      value != null && typeof value === "object" && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)))
+        : value,
+    );
+
+    if (!this._poolMap.has(configKey)) {
+      const pool = createPool<DbConn>(
+        {
+          create: async () => {
+            const conn = await this._createRawConnection(config);
+            await conn.connect();
+            return conn;
+          },
+          destroy: async (conn) => {
+            await conn.close(); // 풀에서 제거될 때 실제 연결 종료
+          },
+          validate: (conn) => {
+            // 획득 시 연결 상태 확인 (끊겨있으면 Pool이 폐기하고 새로 만듦)
+            return Promise.resolve(conn.isConnected);
+          },
+        },
+        {
+          min: config.pool?.min ?? 1,
+          max: config.pool?.max ?? 10,
+          acquireTimeoutMillis: config.pool?.acquireTimeoutMillis ?? 30000,
+          idleTimeoutMillis: config.pool?.idleTimeoutMillis ?? 30000,
+          testOnBorrow: true, // [중요] 빌려줄 때 validate 실행 여부
+        },
+      );
+
+      this._poolMap.set(configKey, pool);
+    }
+
+    return this._poolMap.get(configKey)!;
+  }
+
+  private static async _createRawConnection(config: DbConnConfig): Promise<DbConn> {
+    if (config.dialect === "mysql") {
+      const mysql = await this._ensureModule("mysql");
+      return new MysqlDbConn(mysql, config);
+    } else if (config.dialect === "postgresql") {
+      const pg = await this._ensureModule("pg");
+      const pgCopyStreams = await this._ensureModule("pgCopyStreams");
+      return new PostgresqlDbConn(pg, pgCopyStreams.from, config);
+    } else {
+      // mssql, mssql-azure
+      const tedious = await this._ensureModule("tedious");
+      return new MssqlDbConn(tedious, config);
+    }
+  }
+
+  // 지연 로딩 모듈 캐시
+  private static readonly _modules: {
+    tedious?: typeof import("tedious");
+    mysql?: typeof import("mysql2/promise");
+    pg?: typeof import("pg");
+    pgCopyStreams?: typeof import("pg-copy-streams");
+  } = {};
+
+  private static async _ensureModule<K extends keyof typeof this._modules>(
+    name: K,
+  ): Promise<NonNullable<(typeof this._modules)[K]>> {
+    if (this._modules[name] == null) {
+      if (name === "mysql") {
+        this._modules.mysql = await import("mysql2/promise");
+      } else if (name === "pg") {
+        this._modules.pg = await import("pg");
+      } else if (name === "pgCopyStreams") {
+        this._modules.pgCopyStreams = await import("pg-copy-streams");
+      } else {
+        this._modules.tedious = await import("tedious");
+      }
+    }
+    return this._modules[name]!;
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// Types
+export * from "./types/db-conn";
+
+// Connections
+export * from "./connections/mssql-db-conn";
+export * from "./connections/mysql-db-conn";
+export * from "./connections/postgresql-db-conn";
+
+// Core
+export * from "./db-conn-factory";
+export * from "./node-db-context-executor";
+export * from "./pooled-db-conn";
+export * from "./sd-orm";