sonamu 0.8.2 → 0.8.4

package/src/bin/cli.ts

@@ -964,6 +964,7 @@ async function skills_sync() {
     await skills_sync_to(path.join(os.homedir(), ".claude"), sourceSkillsDir, sourceClaudeMd, {
       useSymlink: false,
       copyProjectTemplates: false,
+      isGlobal: true,
     });
     console.log(chalk.cyan(`\n  Global sync complete → ~/.claude/skills/sonamu/`));
     console.log(chalk.dim(`  These skills are available in all Claude Code sessions.`));
@@ -994,6 +995,7 @@ async function skills_sync_to(
     useSymlink: boolean;
     copyProjectTemplates: boolean;
     sourceBase?: string;
+    isGlobal?: boolean;
   },
 ) {
   const targetSkillsDir = path.join(claudeDir, "skills", "sonamu");
@@ -1050,7 +1052,11 @@ async function skills_sync_to(
   if (await exists(sourceClaudeMd)) {
     try {
       const targetClaudeMd = path.join(claudeDir, "CLAUDE.md");
-      const sourceContent = await readFile(sourceClaudeMd, "utf-8");
+      const rawContent = await readFile(sourceClaudeMd, "utf-8");
+      // 글로벌 모드에서는 상대 경로를 절대 경로로 변환합니다
+      const sourceContent = options.isGlobal
+        ? rawContent.replaceAll(".claude/skills/sonamu/", "~/.claude/skills/sonamu/")
+        : rawContent;
 
       if (await exists(targetClaudeMd)) {
         const targetContent = await readFile(targetClaudeMd, "utf-8");

package/src/skills/sonamu/SKILL.md

@@ -249,7 +249,7 @@ confirmed → cancelled (환자/의사 취소, 24시간 전까지만)
 
 | Skill | 파일 | 용도 |
 |-------|------|------|
-| **전체 워크플로우** | `workflow.md` | **엔티티 설계 → 테스트 완료 5단계 가이드** |
+| **전체 워크플로우** | `workflow.md` | **엔티티 설계 → Frontend 개발 7단계 가이드** |
 | 프로젝트 생성 | `create-sonamu.md` | create-sonamu CLI 옵션 |
 | 프로젝트 초기화 | `project-init.md` | 프로젝트 생성 여부 확인, 대화 흐름 |
 | 프로젝트 설정 | `config.md` | .env, sonamu.config.ts 설정 |
@@ -276,7 +276,7 @@ confirmed → cancelled (환자/의사 취소, 24시간 전까지만)
 
 | 작업 | 참고 Skill |
 |------|-----------|
-| **처음부터 전체 시스템 개발** | **workflow.md (5단계 마스터 가이드)** |
+| **처음부터 전체 시스템 개발** | **workflow.md (7단계 마스터 가이드)** |
 | 프로젝트 생성 | create-sonamu, project-init |
 | 프로젝트 설정 | config |
 | Sonamu 로컬 개발 설정 | config |

package/src/skills/sonamu/fixture-cli.md

@@ -93,7 +93,7 @@ pnpm sonamu fixture gen --include User --count 10 --save-to none
 - `--exclude <entities>`: --all과 함께 사용, 제외할 Entity
 - `--count <number>`: 각 Entity별 생성 개수 (기본값: 5)
 - `--save-to <target>`: 저장 방식 - `db` | `file` | `file:name.json` | `none`
-- `--use-llm`: fixtureHint 기반 LLM 생성 활성화 (ANTHROPIC_API_KEY 필요)
+- `--use-llm`: cone.note 기반 LLM 생성 활성화 (ANTHROPIC_API_KEY 필요)
 - `--no-cache`: LLM 캐시 비활성화 (기본값: 캐시 ON)
 
 ---
@@ -428,39 +428,39 @@ Entity JSON에 `cone` 메타데이터를 추가하면 fixture 생성을 더욱
 }
 ```
 
-### fixtureHint - LLM 연동 트리거
+### note - 설명 및 LLM 연동 트리거
 
 ```json
 {
   "name": "phone",
   "type": "string",
   "cone": {
-    "fixtureHint": "010-XXXX-XXXX 형식의 한국 전화번호"
+    "note": "010-XXXX-XXXX 형식의 한국 전화번호"
   }
 }
 ```
 
 **동작 방식**:
-- `--use-llm` 없을 때: 개발자 참고용 주석 역할만 함
-- `--use-llm` 있을 때: Claude API를 호출하여 hint 기반의 실제 값 생성
+- `--use-llm` 없을 때: 개발자/LLM 참고용 설명 역할만 함 (cone-generator가 읽어 메타데이터 생성 시 활용)
+- `--use-llm` 있을 때: fixture gen이 Claude API를 호출하여 note 내용 기반의 실제 값 생성
 
 **용도**:
 - 단순 faker.js로 표현하기 어려운 맥락있는 텍스트 (자기소개, 설명문 등)
-- 개발자에게 생성 패턴 설명
+- 개발자에게 필드의 의미와 생성 패턴 설명
 - 길이 제한 없음 (짧은 패턴 또는 긴 설명 모두 가능)
 
 ---
 
 ### LLM 기반 데이터 생성
 
-`--use-llm` 플래그를 사용하면 `fixtureHint`가 Claude API 호출 트리거로 작동합니다.
+`--use-llm` 플래그를 사용하면 `cone.note`가 Claude API 호출 트리거로 작동합니다.
 
 #### 우선순위 체인
 
 ```
 1. override 값 (generate() 호출 시 전달)
 2. fixtureGenerator (faker.js 표현식)
-3. fixtureHint + LLM  ← --use-llm 플래그 시 활성화
+3. cone.note + LLM  ← --use-llm 플래그 시 활성화
 4. fixtureDefault (고정 기본값)
 5. 타입별 기본값 (자동 생성)
 ```
@@ -489,21 +489,23 @@ export default defineConfig({
 
 #### 캐싱 동작
 
-- 동일한 `entity:field:hint` 조합은 LLM을 재호출하지 않음
-- 같은 FixtureGenerator 인스턴스 내에서만 유효 (인메모리)
-- `--no-cache`로 비활성화 가능
+- `useLLM=true` 시 하나의 row에서 LLM 대상 필드 전체를 **단일 LLM 호출**로 생성 (필드별 개별 호출 아님)
+- 단일 호출 덕분에 `name`, `name_en`, `name_cn`, `email` 등 연관 필드 간 일관성이 자동으로 보장됨
+- 생성된 결과는 `rowKey:fieldName` 키로 인메모리 캐시에 저장되어, 같은 row 내 다음 필드 처리 시 즉시 반환
+- 캐시는 같은 FixtureGenerator 인스턴스 내에서만 유효
+- `--no-cache`로 캐시 비활성화 가능 (단, row 단위 생성 방식 자체는 유지됨)
 
 #### Fallback 동작
 
 - API 키 없음 → fixtureDefault 또는 타입 기본값으로 fallback (에러 없음)
 - LLM 호출 실패 → 동일하게 fallback (콘솔 경고만 출력)
 
-#### fixtureHint vs fixtureGenerator 선택 기준
+#### note vs fixtureGenerator 선택 기준
 
 | 상황 | 추천 |
 |------|------|
 | 이메일, 이름, 숫자 등 단순한 값 | `fixtureGenerator` (faker.js) |
-| 자기소개, 설명문 등 맥락있는 텍스트 | `fixtureHint` (LLM) |
+| 자기소개, 설명문 등 맥락있는 텍스트 | `cone.note` + `--use-llm` (LLM) |
 | 특정 값 목록에서 선택 | `fixtureGenerator` (arrayElement) |
 
 ---

package/src/skills/sonamu/testing.md

@@ -40,8 +40,8 @@ export async function createTestUser(params?: Partial<UserSaveParams>): Promise<
     name: "Test User",
     ...params,
   };
-  const saved = await UserModel.save(user);
-  return saved.id;
+  const [id] = await UserModel.save([user]);
+  return id;
 }
 
 // User with dependencies (의존성 체인)
@@ -61,8 +61,8 @@ export async function createTestPost(
     content: "Test content",
     ...params,
   };
-  const saved = await PostModel.save(post);
-  return saved.id;
+  const [id] = await PostModel.save([post]);
+  return id;
 }
 
 // Post with dependencies
@@ -84,8 +84,8 @@ export async function createTestComment(
     content: "Test comment",
     ...params,
   };
-  const saved = await CommentModel.save(comment);
-  return saved.id;
+  const [id] = await CommentModel.save([comment]);
+  return id;
 }
 
 // Comment with dependencies
@@ -228,11 +228,12 @@ describe("PostModel", () => {
     test("게시글 수정", async () => {
       const { postId } = await createTestPostWithDeps();
       
-      const updated = await PostModel.save({
+      await PostModel.save([{
         id: postId,
         title: "Updated Title",
-      });
+      }]);
       
+      const updated = await PostModel.findById("A", postId);
       expect(updated.title).toBe("Updated Title");
     });
   });
@@ -2240,8 +2241,8 @@ findById 결과를 수정 후 다시 save할 때 relation을 FK로 변환해야
 ```typescript
 // api/src/testing/test-helpers.ts
 
-// Task Subset D → SaveParams 변환
-export function taskToSaveParams(task: TaskSubsetD): TaskSaveParams {
+// Task Subset A → SaveParams 변환
+export function taskToSaveParams(task: TaskSubsetA): TaskSaveParams {
   const {
     program,
     project,
@@ -2289,13 +2290,13 @@ import { createTestTaskWithDeps, taskToSaveParams } from "../../testing/test-hel
 test("Update - 과제 정보 수정", async () => {
   const { taskId } = await createTestTaskWithDeps();
 
-  const task = await TaskModel.findById("D", taskId);
+  const task = await TaskModel.findById("A", taskId);
   await TaskModel.save([{
     ...taskToSaveParams(task),
     title: "수정된 제목",
   }]);
 
-  const updated = await TaskModel.findById("D", taskId);
+  const updated = await TaskModel.findById("A", taskId);
   expect(updated.title).toBe("수정된 제목");
 });
 ```

package/src/skills/sonamu/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: sonamu-workflow
-description: Sonamu 전체 개발 워크플로우. 엔티티 설계부터 Frontend 개발까지 7단계 가이드. Use when starting a new feature or system from scratch.
+description: Sonamu 전체 개발 워크플로우. 엔티티 설계부터 Frontend 개발까지 7단계(PHASE 1~7) 가이드. Use when starting a new feature or system from scratch.
 ---
 
 # Sonamu 전체 개발 워크플로우

package/src/testing/fixture-generator.ts

@@ -38,6 +38,7 @@ export class FixtureGenerator {
   private locale: Locale;
   private mappings: FakerMappings;
   private llmCache: Map<string, unknown> = new Map();
+  private entityCache: Map<string, Entity> = new Map();
   private options: FixtureGeneratorOptions;
 
   constructor(
@@ -69,9 +70,18 @@ export class FixtureGenerator {
     overrides: Record<string, unknown> = {},
     context: GeneratorContext = this.createContext(),
   ): Promise<Record<string, unknown>> {
-    const entity = this.entityManager.get(entityName);
+    // Entity 캐싱: 테스트에서 entity cone 수정이 반영되도록 보장
+    let entity = this.entityCache.get(entityName);
+    if (!entity) {
+      entity = this.entityManager.get(entityName);
+      this.entityCache.set(entityName, entity);
+    }
+
     const tempId = `${entityName}#temp#${Date.now()}`; // 임시 ID
 
+    // LLM row 단위 생성을 위한 고유 키 (같은 row의 필드들이 동일한 rowKey를 공유)
+    const rowKey = this.options.useLLM ? `${entityName}#row#${Date.now()}` : undefined;
+
     // 각 prop별 값 생성
     const fixture: Record<string, unknown> = {};
 
@@ -81,6 +91,11 @@ export class FixtureGenerator {
         continue;
       }
 
+      // DB sequence로 관리되는 PK는 생성하지 않음 (DB가 자동 할당)
+      if (prop.name === "id" && "cone" in prop && prop.cone?.fixtureStrategy === "sequence") {
+        continue;
+      }
+
       // override가 있으면 사용
       if (prop.name in overrides) {
         fixture[prop.name] = overrides[prop.name];
@@ -118,7 +133,7 @@ export class FixtureGenerator {
       // 2.5. cone.note + LLM 사용
       if (cone?.note && this.options.useLLM) {
         try {
-          fixture[prop.name] = await this.generateWithLLM(cone.note, prop, entity);
+          fixture[prop.name] = await this.generateWithLLM(cone.note, prop, entity, rowKey);
           continue;
         } catch (error) {
           console.warn(
@@ -724,6 +739,69 @@ export class FixtureGenerator {
     fixtureHint: string,
     prop: EntityProp,
     entity: Entity,
+    rowKey?: string,
+  ): Promise<unknown> {
+    // rowKey가 있으면 row 단위 생성 전략 사용
+    if (rowKey) {
+      const rowCacheKey = `${rowKey}:${prop.name}`;
+
+      // 이미 이 row에 대한 LLM 호출이 완료된 경우 캐시에서 바로 반환
+      if (this.llmCache.has(rowCacheKey)) {
+        return this.llmCache.get(rowCacheKey);
+      }
+
+      // 새 row: LLM 대상 prop 전체를 한 번에 생성
+      const llmProps = entity.props.filter((p) => {
+        if (isRelationProp(p)) return false;
+        if (p.cone?.fixtureGenerator) return false;
+        if (p.name === "id" && p.cone?.fixtureStrategy === "sequence") return false;
+        return !!p.cone?.note;
+      });
+
+      // llmProps가 비어있으면 단일 필드 방식으로 fallback
+      if (llmProps.length === 0) {
+        !isTest() &&
+          console.log(
+            `[FixtureGenerator] llmProps is empty for ${entity.id}.${prop.name}, using single field fallback`,
+          );
+        return this.generateSingleWithLLM(fixtureHint, prop, entity);
+      }
+
+      const apiKey = this.getApiKey();
+      const { createAnthropic } = await import("@ai-sdk/anthropic");
+      const { generateText } = await import("ai");
+
+      const { text } = await generateText({
+        model: createAnthropic({ apiKey })(this.options.llmModel || "claude-sonnet-4-5"),
+        prompt: this.buildRowLLMPrompt(llmProps, entity),
+      });
+
+      // 응답을 파싱하여 각 필드에 대한 결과를 캐시에 저장
+      const rowResult = this.parseRowLLMResponse(text, llmProps);
+      for (const [fieldName, value] of Object.entries(rowResult)) {
+        this.llmCache.set(`${rowKey}:${fieldName}`, value);
+      }
+
+      // 요청한 필드의 값 반환 (없으면 단일 필드 fallback)
+      if (this.llmCache.has(rowCacheKey)) {
+        return this.llmCache.get(rowCacheKey);
+      }
+
+      // 만약 row 응답에 이 필드가 누락된 경우 단일 필드 fallback
+      return this.generateSingleWithLLM(fixtureHint, prop, entity);
+    }
+
+    // rowKey가 없으면 기존 단일 필드 방식
+    return this.generateSingleWithLLM(fixtureHint, prop, entity);
+  }
+
+  /**
+   * 단일 필드를 LLM으로 생성합니다 (rowKey 없을 때 fallback용)
+   */
+  private async generateSingleWithLLM(
+    fixtureHint: string,
+    prop: EntityProp,
+    entity: Entity,
   ): Promise<unknown> {
     const cacheKey = `${entity.id}:${prop.name}:${fixtureHint}`;
     if (this.options.enableLLMCache && this.llmCache.has(cacheKey)) {
@@ -747,6 +825,78 @@ export class FixtureGenerator {
     return value;
   }
 
+  /**
+   * row 전체를 한 번에 생성하는 LLM 프롬프트를 만듭니다.
+   */
+  private buildRowLLMPrompt(props: EntityProp[], entity: Entity): string {
+    const locale = this.options.locale || "ko";
+    const language = locale === "ko" ? "Korean" : locale === "ja" ? "Japanese" : "English";
+
+    const fieldDescriptions = props
+      .map((p) => {
+        let desc = `- ${p.name} (${p.type}): ${p.cone?.note ?? ""}`;
+        if (
+          (p.type === "enum" || p.type === "enum[]") &&
+          "id" in p &&
+          p.id &&
+          entity.enumLabels?.[p.id]
+        ) {
+          const values = Object.keys(entity.enumLabels[p.id]).join(", ");
+          desc += ` [allowed values: ${values}]`;
+        }
+        return desc;
+      })
+      .join("\n");
+
+    const outputShape = props.map((p) => `  "${p.name}": <${p.type}>`).join(",\n");
+
+    return `Generate test fixture data for the ${entity.id} entity. All fields must be coherent and consistent with each other.
+
+Entity: ${entity.id}
+Locale: ${locale} (use ${language} for text fields)
+
+Fields to generate:
+${fieldDescriptions}
+
+Rules:
+- All fields in a single row must be logically consistent (e.g. name/name_en/name_cn should represent the same person)
+- Return ONLY valid JSON, no markdown or explanation
+- Dates in ISO 8601 format
+- Use ${language} for text unless field description says otherwise
+
+Return exactly this JSON shape:
+{
+${outputShape}
+}`;
+  }
+
+  /**
+   * row LLM 응답을 파싱하여 필드별 값으로 변환합니다.
+   */
+  private parseRowLLMResponse(text: string, props: EntityProp[]): Record<string, unknown> {
+    const jsonText = text
+      .trim()
+      .replace(/^```json\s*/i, "")
+      .replace(/```\s*$/, "")
+      .trim();
+
+    let parsed: Record<string, unknown>;
+    try {
+      parsed = JSON.parse(jsonText);
+    } catch {
+      !isTest() && console.warn("[FixtureGenerator] Failed to parse row LLM response:", text);
+      return {};
+    }
+
+    const result: Record<string, unknown> = {};
+    for (const prop of props) {
+      if (prop.name in parsed) {
+        result[prop.name] = this.parseLLMResponse(String(parsed[prop.name] ?? ""), prop.type);
+      }
+    }
+    return result;
+  }
+
   private buildLLMPrompt(hint: string, prop: EntityProp, entity: Entity): string {
     const locale = this.options.locale || "ko";
     const language = locale === "ko" ? "Korean" : locale === "ja" ? "Japanese" : "English";

package/src/testing/fixture-manager.ts

@@ -155,8 +155,13 @@ export class FixtureManagerClass {
         const idProp = entity.props.find((p) => p.name === "id");
         const idType = idProp?.type;
 
-        // integer나 bigInteger가 아닌 경우 sequence reset을 스킵합니다 (text, uuid 등)
-        if (!idType || (idType !== "integer" && idType !== "bigInteger")) {
+        // integer/bigInteger이거나, string이지만 fixtureStrategy=sequence인 경우에만 리셋합니다
+        const usesSequence =
+          idType === "integer" ||
+          idType === "bigInteger" ||
+          idProp?.cone?.fixtureStrategy === "sequence";
+
+        if (!usesSequence) {
           !isTest() &&
             console.log(
               `Skipping sequence reset for ${tableName} (id type: ${idType || "unknown"})`,
@@ -165,11 +170,12 @@ export class FixtureManagerClass {
         }
 
         // PostgreSQL 시퀀스를 현재 테이블의 MAX(id)로 리셋합니다.
-        // 세 번째 인자를 생략하면 기본값 true가 적용되어, 다음 INSERT 시 MAX(id)+1부터 시작합니다.
+        // string 타입의 경우 숫자 캐스팅이 필요합니다.
+        const maxExpr = idType === "string" ? "MAX(id::bigint)" : "MAX(id)";
         await testDb.raw(`
           SELECT setval(
             pg_get_serial_sequence('public.${tableName}', 'id'),
-            COALESCE((SELECT MAX(id) FROM ${tableName}), 1)
+            COALESCE((SELECT ${maxExpr} FROM ${tableName}), 1)
           )
         `);
       }
@@ -619,8 +625,13 @@ export class FixtureManagerClass {
               const idProp = entity.props.find((p) => p.name === "id");
               const idType = idProp?.type;
 
-              // integer나 bigInteger가 아닌 경우 sequence reset을 스킵합니다
-              if (!idType || (idType !== "integer" && idType !== "bigInteger")) {
+              // integer/bigInteger이거나, string이지만 fixtureStrategy=sequence인 경우에만 리셋합니다
+              const usesSequence =
+                idType === "integer" ||
+                idType === "bigInteger" ||
+                idProp?.cone?.fixtureStrategy === "sequence";
+
+              if (!usesSequence) {
                 !isTest() &&
                   console.log(
                     chalk.gray(
@@ -631,13 +642,25 @@ export class FixtureManagerClass {
               }
             }
 
-            // 테이블의 최대 ID 조회
-            const maxIdResult = await trx(tableName).max("id as max_id").first();
+            // 테이블의 최대 ID 조회 (string 타입은 숫자 캐스팅 필요)
+            const entity2 = EntityManager.getAllEntities().find(
+              (e) => e.table === tableName || e.id.toLowerCase() === tableName,
+            );
+            const idType2 = entity2?.props.find((p) => p.name === "id")?.type;
+            const maxIdResult =
+              idType2 === "string"
+                ? await trx
+                    .raw(`SELECT MAX(id::bigint) as max_id FROM "${tableName}"`)
+                    .then((r) => r.rows[0])
+                : await trx(tableName).max("id as max_id").first();
             const maxId = maxIdResult?.max_id;
 
             if (maxId !== null && maxId !== undefined) {
-              // 시퀀스를 최대 ID로 설정
-              await trx.raw(`SELECT setval('${tableName}_id_seq', ?)`, [maxId]);
+              // 시퀀스명을 pg_get_serial_sequence로 안전하게 조회
+              await trx.raw(`SELECT setval(pg_get_serial_sequence(?, 'id'), ?)`, [
+                tableName,
+                maxId,
+              ]);
               !isTest() && console.log(chalk.green(`Reset sequence for ${tableName}: ${maxId}`));
             }
           } catch (_err) {

package/src/types/types.ts

@@ -30,6 +30,7 @@ export type Cone = {
   // Fixture 생성 관련
   fixtureGenerator?: string; // Faker.js 코드 또는 커스텀 함수
   fixtureDefault?: unknown; // 기본값
+  fixtureStrategy?: "sequence"; // string 타입이지만 DB sequence로 관리되는 PK (better-auth 등)
 
   // 참조 데이터 관련
   dataSource?: {
@@ -1051,6 +1052,7 @@ const ConeSchema = z
     tags: z.array(z.string()).optional(),
     fixtureGenerator: z.string().optional(),
     fixtureDefault: z.unknown().optional(),
+    fixtureStrategy: z.literal("sequence").optional(),
     dataSource: z
       .object({
         strategy: z.enum(["sample", "ids", "query", "file", "recent", "random"]),

package/src/ui/api.ts

@@ -1204,13 +1204,13 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
       }>("/api/sonamu/fixture/generate", async (request, reply) => {
         const { entity, count = 1, overrides, targetDb = "fixture" } = request.body;
 
-        try {
-          // 타겟 DB 설정 가져오기
-          const dbConfig = targetDb === "fixture" ? Sonamu.dbConfig.fixture : Sonamu.dbConfig.test;
+        // 타겟 DB 설정 가져오기
+        const dbConfig = targetDb === "fixture" ? Sonamu.dbConfig.fixture : Sonamu.dbConfig.test;
 
-          // Knex 인스턴스 생성
-          const db = createKnexInstance(dbConfig);
+        // Knex 인스턴스 생성
+        const db = createKnexInstance(dbConfig);
 
+        try {
           // FixtureGenerator 생성
           const generator = new FixtureGenerator(db, db, targetDb, EntityManager);
 
@@ -1223,9 +1223,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             },
           ]);
 
-          // Knex 연결 종료
-          await db.destroy();
-
           return {
             success: true,
             entity,
@@ -1239,6 +1236,8 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             success: false,
             error: error instanceof Error ? error.message : String(error),
           };
+        } finally {
+          await db.destroy();
         }
       });
 
@@ -1255,13 +1254,13 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
       }>("/api/sonamu/fixture/explore", async (request, reply) => {
         const { entity, strategy, limit = 10, where } = request.body;
 
-        try {
-          // Fixture DB 설정 가져오기
-          const fixtureDbConfig = Sonamu.dbConfig.fixture;
+        // Fixture DB 설정 가져오기
+        const fixtureDbConfig = Sonamu.dbConfig.fixture;
 
-          // Knex 인스턴스 생성
-          const fixtureDb = createKnexInstance(fixtureDbConfig);
+        // Knex 인스턴스 생성
+        const fixtureDb = createKnexInstance(fixtureDbConfig);
 
+        try {
           // DataExplorer 생성
           const explorer = new DataExplorer(fixtureDb, EntityManager);
 
@@ -1271,9 +1270,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             where,
           });
 
-          // Knex 연결 종료
-          await fixtureDb.destroy();
-
           return {
             success: true,
             entity,
@@ -1287,6 +1283,8 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             success: false,
             error: error instanceof Error ? error.message : String(error),
           };
+        } finally {
+          await fixtureDb.destroy();
         }
       });
 
@@ -1311,13 +1309,13 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           maxDepth = 2,
         } = request.body;
 
-        try {
-          // Source DB (production/development) - 읽기 전용
-          const sourceDb = DB.getDB("r");
+        // Source DB (production/development) - 읽기 전용
+        const sourceDb = DB.getDB("r");
 
-          // Target DB (fixture)
-          const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
+        // Target DB (fixture)
+        const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
 
+        try {
           // FixtureGenerator 생성
           const generator = new FixtureGenerator(sourceDb, fixtureDb, "fixture", EntityManager);
 
@@ -1329,9 +1327,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             maxDepth,
           });
 
-          // Knex 연결 종료 (sourceDb는 Sonamu가 관리하므로 destroy하지 않음)
-          await fixtureDb.destroy();
-
           return {
             success: true,
             entity,
@@ -1345,6 +1340,9 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             success: false,
             error: error instanceof Error ? error.message : String(error),
           };
+        } finally {
+          // sourceDb는 Sonamu가 관리하므로 destroy하지 않음
+          await fixtureDb.destroy();
         }
       });
 
@@ -1359,10 +1357,10 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
       }>("/api/sonamu/fixture/clean", async (request, reply) => {
         const { entities } = request.body;
 
-        try {
-          // Fixture DB 연결
-          const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
+        // Fixture DB 연결
+        const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
 
+        try {
           // 삭제할 Entity 목록 결정
           const targetEntities =
             entities && entities.length > 0 ? entities : EntityManager.getAllIds();
@@ -1379,9 +1377,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             `TRUNCATE TABLE ${tableNames.map((t) => `"${t}"`).join(", ")} RESTART IDENTITY CASCADE`,
           );
 
-          // Knex 연결 종료
-          await fixtureDb.destroy();
-
           return {
             success: true,
             cleaned: tableNames,
@@ -1393,6 +1388,8 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             success: false,
             error: error instanceof Error ? error.message : String(error),
           };
+        } finally {
+          await fixtureDb.destroy();
         }
       });