🔒 내부용 · 비배포 (포트폴리오에는 일반화 버전만 공개)

라이브러리 컴포넌트 테이블 재설계 — DB 부하 개선 (2026)

데이터파트 라이브러리 테이블 구조 재설계를 새 팀원이 이해할 수 있는 수준의 온보딩 상세

0한눈에

증상: 고객사 환경에서 마스터 DB의 CPU 이상(부하) 관측.
원인: 라이브러리 컴포넌트 테이블의 구조적 문제(타입 오용 + 식별자 정책 부재).
조치: 스키마·인덱스·식별자 정책 재설계로 부하·정합성 동시 개선.

1왜 신중해야 했나

마스터 DB는 하류(복제·고객사 환경)로 전파되는 상류 원천이다. 라이브러리 컴포넌트 테이블은 npm / PyPI / Maven 등 여러 패키지 생태계의 컴포넌트를 한데 담기 때문에, 구조를 잘못 잡으면 부하뿐 아니라 데이터 정합성 문제가 광범위하게 번진다. 증상(CPU 부하)만 보고 인덱스를 더 붙이는 대증 처방은 근본 원인을 가린다.

2진행 순서

마스터 DB CPU 부하 관측 → 원인을 라이브러리 컴포넌트 테이블 구조로 좁힘
varchar 컬럼에 JSON을 저장하던 케이스(예: 라이선스 컬럼)를 전체 테이블 대상 전수조사 — 영향 범위·깨진 데이터 비율 파악
식별자 문제 정리: 서로 다른 패키지가 같은 키로 충돌, 대소문자 차이로 동일 컴포넌트 누락
스키마·인덱스·식별자 정책 재설계 적용 → DB 부하 감소·정합성 개선

JSON을 varchar에 통째로 넣던 컬럼은 조회·가공 비용과 데이터 깨짐의 주범이었다. 타입 정규화와 함께 식별자 정책(충돌·대소문자 normalize)을 함께 잡아야 재발하지 않는다.

3온보딩 포인트

라이브러리 컴포넌트 테이블은 여러 패키지 생태계 공용. 식별자 정책(키 충돌·대소문자)이 정합성의 핵심.
varchar에 JSON 적재 = 안티패턴. 새 컬럼 설계 시 타입을 먼저 정규화.
DB 부하 이슈는 항상 증상 → 구조 원인 추적 → 재설계 순으로 접근. 인덱스 추가는 마지막 수단.

4공개(포트폴리오)와의 차이

공개 버전(human/portfolio/items/library-table-redesign.html)은 내부 테이블명(TB_*)·티켓 ID·고객사명·내부 호스트명을 제거하고, 문제·접근·임팩트 중심으로 일반화했다. 일반 기술 용어(JSON, varchar, npm/PyPI/Maven)는 그대로 유지. 이 내부 문서는 본인 참고/온보딩용.