@simplysm/orm-common 13.0.100 → 14.0.4

package/src/query-builder/postgresql/postgresql-query-builder.ts

@@ -38,25 +38,25 @@ import { PostgresqlExprRenderer } from "./postgresql-expr-renderer";
 /**
  * PostgreSQL QueryBuilder
  *
- * PostgreSQL specifics:
- * - OUTPUT: uses RETURNING clause (native support)
- * - TRUNCATE: RESTART IDENTITY option required
- * - UPSERT: CTE approach (INSERT ... ON CONFLICT only supports single unique constraint)
- * - AUTO_INCREMENT: GENERATED BY DEFAULT AS IDENTITY (allows explicit value assignment)
- * - Separate index generation needed when adding FK (unlike MySQL)
+ * PostgreSQL 고유 사항:
+ * - OUTPUT: RETURNING 절 사용 (네이티브 지원)
+ * - TRUNCATE: RESTART IDENTITY 옵션 필요
+ * - UPSERT: CTE 방식 (INSERT ... ON CONFLICT는 단일 유니크 제약조건만 지원)
+ * - AUTO_INCREMENT: GENERATED BY DEFAULT AS IDENTITY (명시적 값 할당 가능)
+ * - FK 추가 시 별도 인덱스 생성 필요 (MySQL과 다름)
  */
 export class PostgresqlQueryBuilder extends QueryBuilderBase {
   protected expr = new PostgresqlExprRenderer((def) => this.select(def).sql);
 
   //#region ========== Utilities ==========
 
-  /** Render table name (PostgreSQL: database is handled by connection, uses schema.table only) */
+  /** 테이블명 렌더링 (PostgreSQL: database는 연결에서 처리, schema.table만 사용) */
   protected tableName(obj: QueryDefObjectName): string {
     const schema = obj.schema ?? "public";
     return `${this.expr.wrap(schema)}.${this.expr.wrap(obj.name)}`;
   }
 
-  /** Render LIMIT...OFFSET clause */
+  /** LIMIT...OFFSET 절 렌더링 */
   protected renderLimit(limit: [number, number] | undefined, top: number | undefined): string {
     if (limit != null) {
       const [offset, count] = limit;
@@ -71,15 +71,15 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   protected renderJoin(join: SelectQueryDefJoin): string {
     const alias = this.expr.wrap(join.as);
 
-    // Detect if LATERAL JOIN is needed
+    // LATERAL JOIN이 필요한지 감지
     if (this.needsLateral(join)) {
-      // If from is an array (UNION ALL), use renderFrom(join.from),
-      // otherwise (orderBy, top, select, etc.) use renderFrom(join) to generate subquery
+      // from이 배열(UNION ALL)이면 renderFrom(join.from) 사용,
+      // 그 외(orderBy, top, select 등)이면 renderFrom(join)으로 서브쿼리 생성
       const from = Array.isArray(join.from) ? this.renderFrom(join.from) : this.renderFrom(join);
       return ` LEFT OUTER JOIN LATERAL ${from} AS ${alias} ON TRUE`;
     }
 
-    // Normal JOIN
+    // 일반 JOIN
     const from = this.renderFrom(join.from);
     const where =
       join.where != null && join.where.length > 0
@@ -140,7 +140,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     // LIMIT
     sql += this.renderLimit(def.limit, def.top);
 
-    // LOCK (FOR UPDATE at end)
+    // LOCK (끝에 FOR UPDATE 추가)
     if (def.lock) {
       sql += " FOR UPDATE";
     }
@@ -156,7 +156,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const table = this.tableName(def.table);
 
     if (def.records.length === 0) {
-      throw new Error("INSERT requires at least one record.");
+      throw new Error("INSERT에는 최소 1개의 레코드가 필요합니다.");
     }
 
     const columns = Object.keys(def.records[0]);
@@ -169,14 +169,14 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `INSERT INTO ${table} (${colList})`;
 
-    // GENERATED BY DEFAULT AS IDENTITY, so no additional clause needed for explicit value insertion
-    // overrideIdentity parameter is kept for MSSQL (SET IDENTITY_INSERT) compatibility, but
-    // PostgreSQL's GENERATED BY DEFAULT automatically allows explicit values
-    // (note: OVERRIDING SYSTEM VALUE would be needed if GENERATED ALWAYS was used)
+    // GENERATED BY DEFAULT AS IDENTITY이므로 명시적 값 삽입에 추가 구문 불필요
+    // overrideIdentity 파라미터는 MSSQL (SET IDENTITY_INSERT) 호환성을 위해 유지하지만
+    // PostgreSQL의 GENERATED BY DEFAULT는 자동으로 명시적 값을 허용
+    // (참고: GENERATED ALWAYS를 사용했다면 OVERRIDING SYSTEM VALUE가 필요)
 
     sql += ` VALUES ${valuesList.join(", ")}`;
 
-    // RETURNING (PostgreSQL native support)
+    // RETURNING (PostgreSQL 네이티브 지원)
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => this.expr.wrap(c)).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -192,7 +192,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const colList = columns.map((c) => this.expr.wrap(c)).join(", ");
     const values = columns.map((c) => this.expr.escapeValue(def.record[c])).join(", ");
 
-    // Render existsSelectQuery as SELECT 1 AS _
+    // existsSelectQuery를 SELECT 1 AS _로 렌더링
     const existsQuerySql = this.select({
       ...def.existsSelectQuery,
       select: { _: { type: "value", value: 1 } },
@@ -200,7 +200,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `INSERT INTO ${table} (${colList}) SELECT ${values} WHERE NOT EXISTS (${existsQuerySql})`;
 
-    // RETURNING
+    // RETURNING 절
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => this.expr.wrap(c)).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -213,7 +213,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const table = this.tableName(def.table);
     const selectSql = this.select(def.recordsSelectQuery).sql;
 
-    // Extract columns from INSERT INTO SELECT
+    // INSERT INTO SELECT에서 column 추출
     const selectDef = def.recordsSelectQuery;
     const colList =
       selectDef.select != null
@@ -224,7 +224,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `INSERT INTO ${table} (${colList}) ${selectSql}`;
 
-    // RETURNING
+    // RETURNING 절
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => this.expr.wrap(c)).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -248,7 +248,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `UPDATE ${table} AS ${alias} SET ${setParts.join(", ")}`;
 
-    // PostgreSQL: JOINs are handled via FROM clause
+    // PostgreSQL: JOIN은 FROM 절로 처리
     if (def.joins != null && def.joins.length > 0) {
       const joinTables = def.joins.map((j) => {
         const from = this.renderFrom(j.from);
@@ -256,7 +256,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       });
       sql += ` FROM ${joinTables.join(", ")}`;
 
-      // Add JOIN ON conditions to WHERE
+      // JOIN ON 조건을 WHERE에 추가
       const joinConditions = def.joins
         .filter((j) => j.where != null && j.where.length > 0)
         .map((j) => this.expr.renderWhere(j.where!));
@@ -273,7 +273,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       sql += this.renderWhere(def.where);
     }
 
-    // RETURNING
+    // RETURNING 절
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => `${alias}.${this.expr.wrap(c)}`).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -292,7 +292,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `DELETE FROM ${table} AS ${alias}`;
 
-    // PostgreSQL: JOINs are handled via USING clause
+    // PostgreSQL: JOIN은 USING 절로 처리
     if (def.joins != null && def.joins.length > 0) {
       const joinTables = def.joins.map((j) => {
         const from = this.renderFrom(j.from);
@@ -300,7 +300,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       });
       sql += ` USING ${joinTables.join(", ")}`;
 
-      // Add JOIN ON conditions to WHERE
+      // JOIN ON 조건을 WHERE에 추가
       const joinConditions = def.joins
         .filter((j) => j.where != null && j.where.length > 0)
         .map((j) => this.expr.renderWhere(j.where!));
@@ -317,7 +317,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       sql += this.renderWhere(def.where);
     }
 
-    // RETURNING (PostgreSQL: also supported for DELETE)
+    // RETURNING (PostgreSQL: DELETE에서도 지원)
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => this.expr.wrap(c)).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -331,31 +331,31 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   //#region ========== DML - UPSERT ==========
 
   protected upsert(def: UpsertQueryDef): QueryBuildResult {
-    // PostgreSQL: CTE approach (uses CTE for generality since ON CONFLICT only supports single unique constraint)
+    // PostgreSQL: CTE 방식 (ON CONFLICT는 단일 유니크 제약조건만 지원하므로 범용성을 위해 CTE 사용)
     const table = this.tableName(def.table);
     const alias = this.expr.wrap(def.existsSelectQuery.as);
 
-    // UPDATE SET part
+    // UPDATE SET 부분
     const updateSetParts = Object.entries(def.updateRecord).map(
       ([col, e]) => `${this.expr.wrap(col)} = ${this.expr.render(e)}`,
     );
 
-    // INSERT part
+    // INSERT 부분
     const insertColumns = Object.keys(def.insertRecord);
     const insertColList = insertColumns.map((c) => this.expr.wrap(c)).join(", ");
     const insertValues = insertColumns.map((c) => this.expr.render(def.insertRecord[c])).join(", ");
 
-    // WHERE condition
+    // WHERE 조건
     const whereCondition =
       def.existsSelectQuery.where != null && def.existsSelectQuery.where.length > 0
         ? this.expr.renderWhere(def.existsSelectQuery.where)
         : "TRUE";
 
-    // OUTPUT column
+    // OUTPUT column 정의
     const outputCols =
       def.output != null ? def.output.columns.map((c) => this.expr.wrap(c)).join(", ") : "*";
 
-    // CTE-based UPSERT
+    // CTE 기반 UPSERT
     let sql = `WITH matched AS (\n`;
     sql += `  SELECT ${alias}.* FROM ${table} AS ${alias} WHERE ${whereCondition}\n`;
     sql += `),\n`;
@@ -385,7 +385,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const colDefs = def.columns.map((col) => {
       let colSql = `${this.expr.wrap(col.name)} ${this.expr.renderDataType(col.dataType)}`;
 
-      // nullable: true → NULL, else → NOT NULL
+      // nullable: true → NULL, 아니면 → NOT NULL
       if (col.nullable === true) {
         colSql += " NULL";
       } else {
@@ -403,7 +403,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       return colSql;
     });
 
-    // Primary Key with CONSTRAINT name
+    // CONSTRAINT 이름이 포함된 Primary Key
     if (def.primaryKey != null && def.primaryKey.length > 0) {
       const pkCols = def.primaryKey.map((c) => this.expr.wrap(c)).join(", ");
       const pkName = this.expr.wrap(`PK_${def.table.name}`);
@@ -424,7 +424,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   }
 
   protected truncate(def: TruncateQueryDef): QueryBuildResult {
-    // PostgreSQL: reset sequence with RESTART IDENTITY
+    // PostgreSQL: RESTART IDENTITY로 시퀀스 초기화
     return { sql: `TRUNCATE TABLE ${this.tableName(def.table)} RESTART IDENTITY` };
   }
 
@@ -466,22 +466,22 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const table = this.tableName(def.table);
     const col = def.column;
 
-    // PostgreSQL: ALTER COLUMN requires multiple ALTER statements
+    // PostgreSQL: ALTER COLUMN은 여러 ALTER 문이 필요
     const parts: string[] = [];
 
-    // Change TYPE
+    // TYPE 변경
     parts.push(
       `ALTER COLUMN ${this.expr.wrap(col.name)} TYPE ${this.expr.renderDataType(col.dataType)}`,
     );
 
-    // Change NULL constraint
+    // NULL 제약조건 변경
     if (col.nullable === false) {
       parts.push(`ALTER COLUMN ${this.expr.wrap(col.name)} SET NOT NULL`);
     } else {
       parts.push(`ALTER COLUMN ${this.expr.wrap(col.name)} DROP NOT NULL`);
     }
 
-    // Change DEFAULT
+    // DEFAULT 변경
     if (col.default !== undefined) {
       parts.push(
         `ALTER COLUMN ${this.expr.wrap(col.name)} SET DEFAULT ${this.expr.escapeValue(col.default)}`,
@@ -526,7 +526,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `ALTER TABLE ${table} ADD CONSTRAINT ${this.expr.wrap(fk.name)} FOREIGN KEY (${fkCols}) REFERENCES ${targetTable} (${targetCols})`;
 
-    // PostgreSQL: separate index generation needed for FK
+    // PostgreSQL: FK에 대한 별도 인덱스 생성 필요
     const idxName = `IDX_${def.table.name}_${fk.name.replace(/^FK_/, "")}`;
     sql += `;\nCREATE INDEX ${this.expr.wrap(idxName)} ON ${table} (${fkCols});`;
 
@@ -548,7 +548,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   }
 
   protected dropIndex(def: DropIndexQueryDef): QueryBuildResult {
-    // PostgreSQL: indexes are unique at schema level so table name is not needed, but schema must be specified
+    // PostgreSQL: 인덱스는 스키마 수준에서 고유하므로 테이블명은 불필요하지만 스키마 지정 필요
     const schema = def.table.schema ?? "public";
     return { sql: `DROP INDEX ${this.expr.wrap(schema)}.${this.expr.wrap(def.index)}` };
   }
@@ -570,7 +570,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   protected createProc(def: CreateProcQueryDef): QueryBuildResult {
     const proc = this.tableName(def.procedure);
 
-    // Process params
+    // 파라미터 처리
     const paramList =
       def.params
         ?.map((p) => {
@@ -582,7 +582,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
         })
         .join(", ") ?? "";
 
-    // Process returns
+    // 반환 타입 처리
     let returnClause = "VOID";
     if (def.returns && def.returns.length > 0) {
       const returnFields = def.returns
@@ -625,9 +625,9 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
   protected clearSchema(def: ClearSchemaQueryDef): QueryBuildResult {
     const schemaName = def.schema ?? "public";
-    // SQL injection prevention: schema name validation
+    // SQL 인젝션 방지: schema 이름 유효성 검사
     if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schemaName)) {
-      throw new Error(`Invalid schema name: ${schemaName}`);
+      throw new Error(`잘못된 schema 이름: ${schemaName}`);
     }
     const schema = this.expr.escapeString(schemaName);
     return {
@@ -636,7 +636,7 @@ DO $$
 DECLARE
   r RECORD;
 BEGIN
-  -- Drop FK constraints
+  -- FK 제약조건 삭제
   FOR r IN (SELECT conname, conrelid::regclass AS tablename
             FROM pg_constraint
             WHERE contype = 'f' AND connamespace = '${schema}'::regnamespace)
@@ -644,19 +644,19 @@ BEGIN
     EXECUTE 'ALTER TABLE ' || r.tablename || ' DROP CONSTRAINT ' || quote_ident(r.conname);
   END LOOP;
 
-  -- Drop tables
+  -- 테이블 삭제
   FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = '${schema}')
   LOOP
     EXECUTE 'DROP TABLE IF EXISTS ' || quote_ident(r.tablename) || ' CASCADE';
   END LOOP;
 
-  -- Drop views
+  -- 뷰 삭제
   FOR r IN (SELECT viewname FROM pg_views WHERE schemaname = '${schema}')
   LOOP
     EXECUTE 'DROP VIEW IF EXISTS ' || quote_ident(r.viewname) || ' CASCADE';
   END LOOP;
 
-  -- Drop functions
+  -- 함수 삭제
   FOR r IN (SELECT proname, pg_get_function_identity_arguments(oid) AS args
             FROM pg_proc WHERE pronamespace = '${schema}'::regnamespace)
   LOOP
@@ -675,10 +675,10 @@ END $$`,
   protected switchFk(def: SwitchFkQueryDef): QueryBuildResult {
     const table = this.tableName(def.table);
     if (def.enabled) {
-      // PostgreSQL: enable all FK triggers on the table
+      // PostgreSQL: 테이블의 모든 FK 트리거 활성화
       return { sql: `ALTER TABLE ${table} ENABLE TRIGGER ALL` };
     }
-    // PostgreSQL: disable all FK triggers on the table
+    // PostgreSQL: 테이블의 모든 FK 트리거 비활성화
     return { sql: `ALTER TABLE ${table} DISABLE TRIGGER ALL` };
   }
 

package/src/query-builder/query-builder.ts

@@ -5,7 +5,7 @@ import { MysqlQueryBuilder } from "./mysql/mysql-query-builder";
 import { PostgresqlQueryBuilder } from "./postgresql/postgresql-query-builder";
 
 /**
- * Generate a QueryBuilder instance matching the given Dialect
+ * 주어진 Dialect에 맞는 QueryBuilder 인스턴스 생성
  */
 export function createQueryBuilder(dialect: Dialect): QueryBuilderBase {
   switch (dialect) {