sonamu 0.7.10 → 0.7.12

package/src/database/base-model.types.ts

@@ -7,6 +7,7 @@
  * Enhancer, SubsetQuery 교집합 등 Model 계층에서 필요한 타입 정의.
  */
 
+import type { ListResult } from "..";
 import type { DatabaseSchemaExtend } from "../types/types";
 import type { Puri } from "./puri";
 import type { PuriSubsetFn } from "./puri-subset.types";
@@ -151,7 +152,5 @@ export type ExecuteSubsetQueryParams<
 export type ExecuteSubsetQueryResult<
   TSubsetMapping extends Record<string, any>,
   T extends string,
-> = {
-  rows: TSubsetMapping[T][];
-  total: number;
-};
+  LP extends { queryMode?: "list" | "count" | "both" },
+> = ListResult<LP, TSubsetMapping[T]>;

package/src/database/db.ts

@@ -56,30 +56,40 @@ export class DBClass {
     const instanceName = which === "w" ? "wdb" : "rdb";
 
     if (!this[instanceName]) {
-      let config: Knex.Config;
-      switch (process.env.NODE_ENV ?? "development") {
-        case "development":
-        case "staging":
-          config =
-            which === "w"
-              ? dbConfig.development_master
-              : (dbConfig.development_slave ?? dbConfig.development_master);
-          break;
-        case "production":
-          config =
-            which === "w"
-              ? dbConfig.production_master
-              : (dbConfig.production_slave ?? dbConfig.production_master);
-          break;
-        default:
-          throw new Error(`현재 ENV ${process.env.NODE_ENV}에는 설정 가능한 DB설정이 없습니다.`);
-      }
+      const config = this.getDBConfig(which);
       this[instanceName] = knex(config);
     }
 
     return this[instanceName];
   }
 
+  getDBConfig(which: DBPreset): Knex.Config {
+    const dbConfig = Sonamu.dbConfig;
+    if (process.env.NODE_ENV === "test") {
+      return {
+        ...dbConfig.test,
+        // 단일 풀
+        pool: {
+          min: 1,
+          max: 1,
+        },
+      };
+    }
+    switch (process.env.NODE_ENV ?? "development") {
+      case "development":
+      case "staging":
+        return which === "w"
+          ? dbConfig.development_master
+          : (dbConfig.development_slave ?? dbConfig.development_master);
+      case "production":
+        return which === "w"
+          ? dbConfig.production_master
+          : (dbConfig.production_slave ?? dbConfig.production_master);
+      default:
+        throw new Error(`현재 ENV ${process.env.NODE_ENV}에는 설정 가능한 DB설정이 없습니다.`);
+    }
+  }
+
   async destroy(): Promise<void> {
     if (this.wdb !== undefined) {
       await this.wdb.destroy();

package/src/database/puri-subset.test-d.ts

@@ -4,6 +4,7 @@ import type { Puri } from "./puri";
 import type { Hydrate, InferAllSubsets, LoadersResult } from "./puri-subset.types";
 import type { PuriWrapper } from "./puri-wrapper";
 
+/** biome-ignore lint/suspicious/noExplicitAny: Puri Subset 타입 시스템에서 any를 허용함 */
 type MockPuri<T> = Puri<DatabaseSchemaExtend, any, T>;
 
 describe("Hydrate", () => {

package/src/database/puri-subset.types.ts

@@ -1,3 +1,5 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: Puri Subset 타입 시스템에서 any를 허용함 */
+
 /**
  * Puri Subset 타입 시스템
  *

package/src/database/puri.ts

@@ -3,6 +3,7 @@
 
 import assert from "assert";
 import chalk from "chalk";
+import inflection from "inflection";
 import type { Knex } from "knex";
 import { Naite } from "../naite/naite";
 import type {
@@ -24,6 +25,11 @@ import type {
   SelectObject,
   SingleTableValue,
   SqlExpression,
+  TsHighlightOptions,
+  TsQueryConfig,
+  TsQueryOptions,
+  TsRankOptions,
+  VectorColumns,
   WhereCondition,
   WhereOperator,
 } from "./puri.types";
@@ -124,6 +130,9 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   static rawString(sql: string): SqlExpression<"string"> {
     return { _type: "sql_expression", _return: "string", _sql: sql };
   }
+  static rawStringArray(sql: string): SqlExpression<"string[]"> {
+    return { _type: "sql_expression", _return: "string[]", _sql: sql };
+  }
   static rawNumber(sql: string): SqlExpression<"number"> {
     return { _type: "sql_expression", _return: "number", _sql: sql };
   }
@@ -134,6 +143,109 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return { _type: "sql_expression", _return: "date", _sql: sql };
   }
 
+  /**
+   * FTS 검색어 하이라이팅
+   *
+   * @example
+   * .select({
+   *   title: Puri.highlight("posts.title", search),
+   *   content: Puri.highlight("posts.content", search, {
+   *     startSel: "<mark>",
+   *     stopSel: "</mark>",
+   *     maxFragments: 3,
+   *   }),
+   * })
+   */
+  static tsHighlight(
+    column: string,
+    query: string,
+    _options?: TsHighlightOptions,
+  ): SqlExpression<"string"> {
+    const { parser = "websearch_to_tsquery", config = "simple", ...options } = _options ?? {};
+
+    const hlOptionParts = Object.entries(options).map(([key, value]) => {
+      return `${inflection.camelize(key)}=${value}`;
+    });
+
+    const hlOptions = hlOptionParts.length > 0 ? `, '${hlOptionParts.join(", ")}'` : "";
+
+    // TODO: rawBinding 메서드 만들어서 XSS 방지
+    return Puri.rawString(
+      `ts_headline('${config}', ${column}, ${parser}('${config}', '${query}')${hlOptions})`,
+    );
+  }
+
+  // ts_rank
+  static tsRank(column: string, query: string, options?: TsRankOptions): SqlExpression<"number"> {
+    return Puri._tsRank("ts_rank", column, query, options);
+  }
+
+  // ts_rank_cd
+  static tsRankCd(column: string, query: string, options?: TsRankOptions): SqlExpression<"number"> {
+    return Puri._tsRank("ts_rank_cd", column, query, options);
+  }
+
+  static _tsRank(
+    type: "ts_rank" | "ts_rank_cd",
+    column: string,
+    query: string,
+    options?: TsRankOptions,
+  ): SqlExpression<"number"> {
+    const {
+      parser = "websearch_to_tsquery",
+      config = "simple",
+      normalization,
+      weights,
+    } = options ?? {};
+
+    const weightClause = weights ? `ARRAY[${weights.join(", ")}], ` : "";
+    const normalizationClause = normalization ? `, ${normalization}` : "";
+
+    return Puri.rawNumber(
+      `${type}(${weightClause}${column}, ${parser}('${config}', '${query}')${normalizationClause})`,
+    );
+  }
+
+  /**
+   * PGroonga FullText 인덱스 검색 점수
+   *
+   * @example
+   * .select({
+   *   score: Puri.score(),
+   * })
+   */
+  static score(): SqlExpression<"number"> {
+    return Puri.rawNumber("pgroonga_score(tableoid, ctid)");
+  }
+
+  /**
+   * PGroonga FullText 인덱스 검색 하이라이팅
+   *
+   * @example
+   * .select({
+   *   title: Puri.highlight("posts.title", search),
+   * })
+   */
+  static highlight(column: string, query: string | string[]): SqlExpression<"string">;
+  static highlight(columns: string[], query: string | string[]): SqlExpression<"string[]">;
+
+  static highlight(
+    columnOrColumns: string | string[],
+    query: string | string[],
+  ): SqlExpression<"string"> | SqlExpression<"string[]"> {
+    const queryClause = `ARRAY[${(Array.isArray(query) ? query : [query]).map((q) => `'${q}'`).join(",")}]`;
+
+    // 단일 컬럼인 경우
+    if (typeof columnOrColumns === "string") {
+      return Puri.rawString(`pgroonga_highlight_html(${columnOrColumns}, ${queryClause})`);
+    }
+
+    // 컬럼 배열인 경우
+    return Puri.rawStringArray(
+      `pgroonga_highlight_html(ARRAY[${columnOrColumns.join(",")}], ${queryClause})`,
+    );
+  }
+
   // SELECT (overwrite)
   select<TSelect extends SelectObject<TTables>>(
     selectObj: TSelect,
@@ -146,7 +258,7 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     for (const [alias, columnOrFunction] of Object.entries(flatSelect)) {
       if (typeof columnOrFunction === "object" && columnOrFunction._type === "sql_expression") {
         // SQL 함수인 경우
-        selectClauses.push(this.knex.raw(`${columnOrFunction._sql} as ${alias}`));
+        selectClauses.push(this.knex.raw(`${columnOrFunction._sql} as "${alias}"`));
       } else {
         // 일반 컬럼인 경우
         const columnPath = columnOrFunction as string;
@@ -472,6 +584,64 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return this;
   }
 
+  /**
+   * PGroonga FullText 인덱스 검색
+   * - 사용할 PGroonga 인덱스와 동일한 컬럼 구성으로 검색해야 인덱스가 사용됩니다.
+   *
+   * 단일 컬럼 검색:
+   * ```sql
+   * WHERE name &@~ 'search'
+   * ```
+   *
+   * 복합 컬럼 검색:
+   * ```sql
+   * WHERE ARRAY[name::text, description::text] &@~ 'search'
+   * ```
+   */
+  whereSearch<TColumn extends AvailableColumns<TTables>>(
+    column: TColumn | TColumn[],
+    value: string,
+    options?: {
+      weights?: number[]; // 정수 배열
+    },
+  ): this {
+    const { weights } = options ?? {};
+    const columnExpr = Array.isArray(column)
+      ? `ARRAY[${column.map((c) => `${c}::text`).join(",")}]`
+      : column;
+    const pgroongaCondition = `pgroonga_condition(?${weights?.length ? `, weights => ARRAY[${weights.join(",")}]` : ""})`;
+
+    this.knexQuery.whereRaw(`${columnExpr} &@~ ${pgroongaCondition}`, [value]);
+
+    return this;
+  }
+
+  // WHERE FULLTEXT
+  whereTsSearch<TColumn extends AvailableColumns<TTables> | SqlExpression<"string">>(
+    column: TColumn,
+    value: string,
+    options?: TsQueryOptions | TsQueryConfig,
+  ): this {
+    const opts =
+      typeof options === "string" ? ({ config: options } as TsQueryOptions) : (options ?? {});
+
+    const parser = opts.parser ?? "websearch_to_tsquery";
+    const config = opts.config ?? "simple";
+    const columnExpr =
+      typeof column === "object" && column._type === "sql_expression"
+        ? column._sql
+        : String(column);
+
+    this.knexQuery.whereRaw(`${columnExpr} @@ ${parser}(?, ?)`, [config, value]);
+    return this;
+  }
+
+  // WHERE RAW
+  whereRaw(sql: string, bindings?: readonly unknown[]): this {
+    this.knexQuery.whereRaw(sql, bindings);
+    return this;
+  }
+
   // WHERE 괄호 그룹핑
   whereGroup(callback: (g: WhereGroup<TTables>) => void): this {
     this.knexQuery.where((builder) => {
@@ -498,6 +668,127 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return this;
   }
 
+  /**
+   * 벡터 유사도 검색 설정
+   *
+   * - SELECT에 similarity 컬럼 추가
+   * - WHERE col IS NOT NULL 추가
+   * - threshold가 있으면 WHERE 조건 추가
+   * - 기존 ORDER BY를 clear하고 원시 연산자로 정렬 (HNSW 인덱스 최적화)
+   *
+   * @param column 벡터 컬럼 경로
+   * @param embedding 쿼리 임베딩 벡터
+   * @param options method, threshold, as 등 옵션
+   *
+   * @example
+   * ```typescript
+   * // cosine similarity (기본값)
+   * qb.vectorSimilarity("columnName", queryVector, {
+   *   method: "cosine",
+   *   threshold: 0.5
+   * });
+   *
+   * // L2 distance
+   * qb.vectorSimilarity("columnName", queryVector, {
+   *   method: "l2",
+   *   threshold: 1.5  // 거리가 1.5 이하인 결과만
+   * });
+   *
+   * // Inner product
+   * qb.vectorSimilarity("columnName", queryVector, {
+   *   method: "inner_product",
+   *   threshold: 0.7
+   * });
+   * ```
+   */
+  vectorSimilarity(
+    column: VectorColumns<TTables>,
+    embedding: number[],
+    options: {
+      method?: "cosine" | "l2" | "inner_product";
+      threshold?: number;
+    } = {},
+  ): Puri<TSchema, TTables, TResult & { similarity: number }> {
+    const { method = "cosine", threshold } = options;
+    if (
+      !Array.isArray(embedding) ||
+      embedding.length === 0 ||
+      embedding.some((v) => !Number.isFinite(v))
+    ) {
+      throw new Error("Invalid embedding vector: expected a non-empty array of finite numbers");
+    }
+    const vectorLiteral = JSON.stringify(embedding.map((v) => Number(v)));
+
+    // method별 연산자 및 similarity 계산식
+    // - cosine: <=> (cosine distance, 0~2), similarity = 1 - distance
+    // - l2: <-> (euclidean distance), similarity = distance (낮을수록 유사)
+    // - inner_product: <#> (negative inner product), similarity = -distance (높을수록 유사)
+    const operatorMap = {
+      cosine: "<=>",
+      l2: "<->",
+      inner_product: "<#>",
+    } as const;
+    const operator = operatorMap[method];
+
+    // SELECT에 similarity 추가
+    if (method === "cosine") {
+      // cosine: similarity = 1 - cosine_distance (0~1, 높을수록 유사)
+      this.knexQuery.select(
+        this.knex.raw(`1 - (?? <=> ?::vector) as similarity`, [column, vectorLiteral]),
+      );
+    } else if (method === "l2") {
+      // l2: distance 그대로 반환 (낮을수록 유사)
+      this.knexQuery.select(
+        this.knex.raw(`?? <-> ?::vector as similarity`, [column, vectorLiteral]),
+      );
+    } else {
+      // inner_product: pgvector는 음수 반환하므로 부호 반전 (높을수록 유사)
+      this.knexQuery.select(
+        this.knex.raw(`-(?? <#> ?::vector) as similarity`, [column, vectorLiteral]),
+      );
+    }
+
+    // WHERE col IS NOT NULL
+    this.knexQuery.whereNotNull(column);
+
+    // threshold가 있으면 WHERE 추가
+    if (typeof threshold === "number") {
+      if (!Number.isFinite(threshold)) {
+        throw new Error(`Invalid vectorSimilarity threshold: ${threshold}`);
+      }
+
+      if (method === "cosine") {
+        // similarity >= threshold  <=>  cosine_distance <= (1 - threshold)
+        this.knexQuery.whereRaw(`?? ${operator} ?::vector <= ?`, [
+          column,
+          vectorLiteral,
+          1 - threshold,
+        ]);
+      } else if (method === "l2") {
+        // distance <= threshold (거리가 threshold 이하)
+        this.knexQuery.whereRaw(`?? ${operator} ?::vector <= ?`, [
+          column,
+          vectorLiteral,
+          threshold,
+        ]);
+      } else {
+        // inner_product: -distance >= threshold  <=>  distance <= -threshold
+        this.knexQuery.whereRaw(`?? ${operator} ?::vector <= ?`, [
+          column,
+          vectorLiteral,
+          -threshold,
+        ]);
+      }
+    }
+
+    // 기존 ORDER BY clear 후 원시 연산자로 정렬 (HNSW 인덱스 최적화)
+    // 모든 method에서 ASC: 거리/음수값이 작을수록 유사
+    this.knexQuery.clear("order");
+    this.knexQuery.orderByRaw(`?? ${operator} ?::vector`, [column, vectorLiteral]);
+
+    return this as any;
+  }
+
   // 기본 쿼리 메서드들
   limit(count: number): this {
     if (count < 0) {

package/src/database/puri.types.test-d.ts

@@ -108,7 +108,7 @@ describe("ExtractColumnType", () => {
       type Tables = {
         users: MockSchema["users"];
         department: MockSchema["departments"] & LeftJoinedMarker; // nullable FK
-        company: MockSchema["companies"] & LeftJoinedMarker; // non-null FK → 마커 없음
+        company: MockSchema["companies"]; // non-null FK → 마커 없음
       };
       type Result = ExtractColumnType<Tables, "company.id">;
 

package/src/database/puri.types.ts

@@ -13,13 +13,31 @@ type VirtualKey = "__virtual__";
 type LeftJoinedKey = "__leftJoined__";
 type HasDefault = "__hasDefault__";
 type GeneratedKey = "__generated__";
+type VectorKey = "__vector__";
 
-type InternalTypeKeys = FulltextKey | VirtualKey | LeftJoinedKey | HasDefault | GeneratedKey;
+type InternalTypeKeys =
+  | FulltextKey
+  | VirtualKey
+  | LeftJoinedKey
+  | HasDefault
+  | GeneratedKey
+  | VectorKey;
 
 // ============================================
 // 타입 유틸리티
 // ============================================
 
+// __vector__ 메타데이터에서 벡터 컬럼 추출
+type VectorColumnKeys<T> = T extends { [K in VectorKey]: readonly (infer V)[] }
+  ? V & string
+  : never;
+
+export type VectorColumns<TTables extends Record<string, any>> =
+  | {
+      [TAlias in keyof TTables]: `${TAlias & string}.${VectorColumnKeys<TTables[TAlias]>}`;
+    }[keyof TTables]
+  | (IsSingleKey<TTables> extends true ? VectorColumnKeys<TTables[keyof TTables]> : never);
+
 // 테이블명 타입
 export type TableName<TSchema> = keyof TSchema & string;
 
@@ -78,7 +96,7 @@ export type ResultAvailableColumns<TTables extends Record<string, any>, TResult
 // Select 값 타입 확장 (단일 컬럼 또는 SQL 표현식)
 export type SelectValue<TTables extends Record<string, any>> =
   | AvailableColumns<TTables>
-  | SqlExpression<"string" | "number" | "boolean" | "date">;
+  | SqlExpression<"string" | "number" | "boolean" | "date" | "string[]">;
 
 // 중첩 Select 객체 타입 (재귀적)
 // 예: { parent: { id: "parent.id", name: "parent.name" } }
@@ -143,8 +161,8 @@ type JoinPath<Prefix extends string, Key extends string> = Prefix extends ""
 // Schema를 읽어서 FK의 nullability에 따라 join된 객체의 타입을 추론해주는 기능이 있습니다.
 // 이게 무슨 소리냐? FK가 nullable인데 leftJoin되었다면, 해당 객체는 nullable 해야 함을 타입 추론으로 반영해준다는 것입니다.
 // 반면 FK가 non-nullable이거나 그냥 join으로 이어졌다면 해당 객체는 non-nullable할 겁니다.
-// 물론 객체 내부의 nullability는 또 별개로 추론됩니다. 
-// 
+// 물론 객체 내부의 nullability는 또 별개로 추론됩니다.
+//
 // 아래에도 ParseSelectObjectWithPath를 비롯해 ExtractColumnType, ExtractColumnTypeRaw 등의 타입이 있습니다.
 // 이들의 역할은 다음과 같습니다:
 // - Parse*: 객체 레벨에서 중첩 구조를 순회하며 객체에 | null을 붙일지 결정합니다.
@@ -178,7 +196,9 @@ type ParseSelectObjectWithPath<
           ? boolean
           : R extends "date"
             ? Date
-            : never
+            : R extends "string[]"
+              ? string[]
+              : never
     : IsNestedObject<TSelect[K]> extends true
       ? TSelect[K] extends NestedSelectObject<TTables>
         ? IsNullableJoinedTable<TTables, JoinPath<Prefix, K & string>> extends true // 주어진 테이블이 FK nullable에 leftJoin되었는지 여부에 따라 select 결과 객체의 타입이 달라집니다.
@@ -205,7 +225,9 @@ type ParseSelectObjectInner<
           ? boolean
           : R extends "date"
             ? Date
-            : never
+            : R extends "string[]"
+              ? string[]
+              : never
     : IsNestedObject<TSelect[K]> extends true
       ? TSelect[K] extends NestedSelectObject<TTables>
         ? IsNullableJoinedTable<TTables, JoinPath<Prefix, K & string>> extends true
@@ -274,7 +296,7 @@ export type ComparisonOperator = "=" | ">" | ">=" | "<" | "<=" | "<>" | "!=";
 export type WhereOperator = ComparisonOperator | "like" | "not like";
 
 // SQL Expression 타입 정의
-export type SqlExpression<T extends "string" | "number" | "boolean" | "date"> = {
+export type SqlExpression<T extends "string" | "number" | "boolean" | "date" | "string[]"> = {
   _type: "sql_expression"; // 또는 "computed_value"
   _return: T;
   _sql: string;
@@ -368,3 +390,55 @@ export type SelectAllResult<TTables extends Record<string, any>> = UnionToInters
       : never;
   }[keyof TTables]
 >;
+
+// FTS 타입
+type TsQueryParser = "to_tsquery" | "plainto_tsquery" | "phraseto_tsquery" | "websearch_to_tsquery";
+export type TsQueryConfig = "simple" | "english";
+export type TsQueryOptions = {
+  parser?: TsQueryParser;
+  config?: TsQueryConfig;
+};
+
+export type TsHighlightOptions = {
+  /** 쿼리 변환 함수 (기본값: "websearch_to_tsquery") */
+  parser?: TsQueryParser;
+  /** 텍스트 검색 설정 (기본값: "simple") */
+  config?: TsQueryConfig;
+  /** 최대 단어 수 (기본값: 35) */
+  maxWords?: number;
+  /** 최소 단어 수 (기본값: 15) */
+  minWords?: number;
+  /** 헤드라인 시작/끝에서 제거할 짧은 단어 길이 (기본값: 3) */
+  shortWord?: number;
+  /** true면 전체 문서를 헤드라인으로 사용 (기본값: false) */
+  highlightAll?: boolean;
+  /** 표시할 최대 텍스트 조각 수 (기본값: 0, 조각 미사용) */
+  maxFragments?: number;
+  /** 쿼리 단어 시작 구분자 (기본값: "<b>") */
+  startSel?: string;
+  /** 쿼리 단어 끝 구분자 (기본값: "</b>") */
+  stopSel?: string;
+  /** 조각 구분자 (기본값: " ... ") */
+  fragmentDelimiter?: string;
+};
+
+export type TsRankOptions = {
+  parser?: TsQueryParser;
+  config?: TsQueryConfig;
+  /** 가중치 배열 [D, C, B, A] (기본값: [0.1, 0.2, 0.4, 1.0]) */
+  weights?: [number, number, number, number];
+  /**
+   * 정규화 옵션
+   * 0: 문서 길이 무시 (기본값)
+   * 1: 1 + log(문서 길이)로 나눔
+   * 2: 문서 길이로 나눔
+   * 4: 평균 조화 거리로 나눔 (ts_rank_cd만)
+   * 8: 고유 단어 수로 나눔
+   * 16: 1 + log(고유 단어 수)로 나눔
+   * 32: rank/(rank+1) -> 0~1 사이의 값으로 스케일링
+   *
+   * 비트마스크를 사용하여 옵션을 조합할 수 있음
+   * 예: 8 | 32 -> 고유 단어 수로 나누고 0~1 스케일링
+   */
+  normalization?: number;
+};

package/src/database/upsert-builder.ts

@@ -6,7 +6,7 @@ import { Naite } from "../naite/naite";
 import type { DatabaseForeignKeys, DatabaseSchemaExtend, EntityIndex } from "../types/types";
 import { assertDefined, chunk, nonNullable } from "../utils/utils";
 import { batchUpdate, type RowWithId } from "./_batch_update";
-import type { ForeignKeyColumns, TableName } from "./puri.types";
+import type { ColumnKeys, ForeignKeyColumns, TableName } from "./puri.types";
 
 /**
  * FK 타입 추론을 위해 DatabaseForeignKeys export
@@ -14,6 +14,9 @@ import type { ForeignKeyColumns, TableName } from "./puri.types";
  */
 export type { DatabaseForeignKeys };
 
+type InheritableColumns<TTable extends TableName<DatabaseSchemaExtend>> =
+  TTable extends keyof DatabaseSchemaExtend ? ColumnKeys<DatabaseSchemaExtend[TTable]> : never;
+
 // 테이블 데이터 타입
 type TableData = {
   references: Set<string>;
@@ -33,6 +36,7 @@ export type UBRef = {
 export type UpsertOptions<TTable extends TableName<DatabaseSchemaExtend>> = {
   chunkSize?: number;
   cleanOrphans?: ForeignKeyColumns<TTable> | ForeignKeyColumns<TTable>[];
+  inherit?: InheritableColumns<TTable>[];
 };
 
 // insertOnly 옵션
@@ -289,16 +293,30 @@ export class UpsertBuilder {
           resultRows = await wdb.insert(dataForDb).into(tableName).returning(selectFields);
         } else {
           // UPSERT 모드 - onConflict 사용 (unique index 없으면 PK fallback)
-          const conflictColumns =
-            table.uniqueIndexes.length > 0
-              ? table.uniqueIndexes[0].columns.map((c) => c.name)
-              : ["id"];
-          const updateColumns = Object.keys(dataForDb[0]).filter(
-            (col) => !conflictColumns.includes(col),
-          );
+          const conflictColumns = table.uniqueIndexes[0]?.columns.map((c) => c.name) ?? ["id"];
+
+          const allColumns = Object.keys(dataForDb[0]);
+          let updateColumns = allColumns.filter((c) => !conflictColumns.includes(c));
+
+          // inherit 옵션 처리 - inherit 컬럼은 update 대상에서 제외
+          if (options?.inherit?.length) {
+            const inheritColumns = options.inherit as string[];
+
+            const excludedFromUpdate = updateColumns.filter((c) => inheritColumns.includes(c));
+            updateColumns = updateColumns.filter((c) => !inheritColumns.includes(c));
+
+            // 실제로 제외된 컬럼 로깅
+            if (excludedFromUpdate.length) {
+              Naite.t("puri:ub-inherit", {
+                tableName,
+                inheritColumns,
+                excludedFromUpdate,
+              });
+            }
+          }
 
           // updateColumns가 비어있어도 merge()를 사용하여 모든 행이 RETURNING되도록 보장
-          const mergeColumns = updateColumns.length > 0 ? updateColumns : conflictColumns;
+          const mergeColumns = updateColumns.length ? updateColumns : conflictColumns;
 
           resultRows = await wdb
             .insert(dataForDb)

package/src/entity/entity-manager.ts

@@ -85,6 +85,15 @@ class EntityManagerClass {
     return entity;
   }
 
+  getByTable(table: string): Entity {
+    const entity = Array.from(this.entities.values()).find((entity) => entity.table === table);
+    if (entity === undefined) {
+      throw new Error(`존재하지 않는 Entity 요청 ${table}`);
+    }
+
+    return entity;
+  }
+
   exists(entityId: string): boolean {
     const entity = this.entities.get(entityId);
     return entity !== undefined;

package/src/index.ts

@@ -22,6 +22,7 @@ export * from "./migration/types";
 export * from "./naite/naite";
 export * from "./naite/naite-reporter";
 export * from "./stream/sse";
+export * from "./tasks/decorator";
 export * from "./template/template";
 export * from "./template/template-manager";
 export * from "./testing/fixture-manager";
@@ -35,7 +36,6 @@ export * from "./vector/chunking";
 export * from "./vector/config";
 export * from "./vector/embedding";
 export * from "./vector/types";
-export * from "./vector/vector-search";
 
 // export * from "./api/code-converters";
 // export * from "./syncer/syncer";