1,000개 테이블을 AI가 이해하게 만드는 법: DB 스키마 문서화 시스템

윤동균

들어가며

"이 데이터는 어느 테이블에 있어요?"

데이터 분석가, PM, 개발자 모두가 이 질문을 합니다. 테이블이 10개일 때는 머릿속에 답이 있지만, 1,000개가 넘으면 누구도 전체를 파악하지 못합니다.

이 글은 6개 데이터베이스, 1,000+ 테이블의 스키마를 체계적으로 문서화하고, AI 어시스턴트가 자연어 질문만으로 올바른 SQL을 생성할 수 있게 만든 시스템 설계 경험입니다.

이 시스템이 해결하는 문제
• 개발자: "이 컬럼이 어떤 의미지? JOIN 조건은?"
• 분석가: "주간 트렌드를 보려면 어떤 테이블을 써야 하지?"
• PM: "이 수치를 뽑아주세요" → 매번 개발자에게 의뢰
→ 자연어 질문 → 자동 SQL 생성 → 결과 해석으로 해결

왜 기존 방법으로는 안 되는가

기존 접근 방식의 한계

방법	문제점
위키에 테이블 목록 정리	금방 낙후됨. 실제 스키마와 문서가 불일치
ERD 도구 (DataGrip 등)	1,000개 테이블 ERD는 읽을 수 없음
구두 전달 / 슬랙 질문	지식이 특정 사람에게 집중. 퇴사하면 사라짐
INFORMATION_SCHEMA 직접 조회	테이블은 찾을 수 있지만 "비즈니스 의미"를 모름

핵심 문제는 테이블의 "기술적 구조"와 "비즈니스 의미"가 분리되어 있다는 것입니다. Orders 테이블이 있다는 건 INFORMATION_SCHEMA로 알 수 있지만, "이 테이블에서 is_canceled = 0 필터를 꼭 걸어야 한다"는 건 사람의 머릿속에만 있습니다.

시스템 전체 구조

이 시스템은 4개 계층으로 구성됩니다.

graph TB subgraph USER["사용자 인터페이스"] U1["자연어 질문\n'최근 2주간 트렌드는?'"] end subgraph AI["AI 쿼리 파이프라인 (7단계)"] direction TB A0["Phase 0: 캐시 조회"] A1["Phase 1: 질문 분석"] A2["Phase 2: 스키마 탐색"] A3["Phase 3: SQL 생성"] A4["Phase 4: SQL 실행"] A5["Phase 5: 결과 분석"] A6["Phase 6: 캐시 저장"] A0 --> A1 --> A2 --> A3 --> A4 --> A5 --> A6 end subgraph DOCS["문서화 계층"] direction LR D1["가이드 파일\n(도메인별 네비게이션)"] D2["스키마 파일\n(테이블/컬럼 상세)"] D3["SQL 컨벤션\n(안전 규칙)"] end subgraph SAFETY["안전 계층"] direction LR S1["SQL Safety Hook\n(DML 차단)"] S2["읽기 전용 설정"] S3["대형 테이블 경고"] end USER --> AI AI --> DOCS AI --> SAFETY style USER fill:#3b82f6,stroke:#2563eb,color:#fff style AI fill:#f59e0b,stroke:#d97706,color:#fff style DOCS fill:#10b981,stroke:#059669,color:#fff style SAFETY fill:#ef4444,stroke:#dc2626,color:#fff

1계층: 스키마 문서화 — "AI가 읽을 수 있는 형태로"

도메인 기반 분류

1,000개 테이블을 알파벳순으로 나열하면 아무도 읽지 않습니다. 대신 비즈니스 도메인별로 그룹화했습니다.

graph LR subgraph DB["데이터베이스 (6개)"] direction TB DB1["메인 DB\n~714 테이블"] DB2["스토어 DB\n~166 테이블"] DB3["분석 DB\n~80 테이블"] DB4["리워드 DB\n~34 테이블"] DB5["인증 DB\n~10 테이블"] DB6["사용자 DB\n~10 테이블"] end subgraph DOMAIN["도메인 분류 (예: 메인 DB)"] direction TB DM1["캠페인"] DM2["결제/정산"] DM3["사용자"] DM4["쿠폰/프로모션"] DM5["커뮤니케이션"] DM6["콘텐츠"] DM7["레거시"] end DB1 --> DOMAIN style DB fill:#f8fafc,stroke:#3b82f6,stroke-width:2px style DOMAIN fill:#f8fafc,stroke:#10b981,stroke-width:2px

2단계 문서 구조: 가이드 + 스키마

문서를 가이드 파일과 스키마 파일로 분리한 것이 핵심 설계입니다.

문서 유형	역할	예시 내용
가이드 파일	도메인 전체 지도, SQL 컨벤션, 주의사항	"결제 관련 데이터는 01~04번 파일 참조. 반드시 취소 필터 적용"
스키마 파일	테이블별 상세 (컬럼, 타입, 관계, JOIN 조건)	테이블 인덱스, 행 수, 최종 업데이트, 외래키 관계
빈 테이블 목록	미사용 테이블 별도 분류	"Rows=0인 테이블은 레거시이므로 무시"

이 분리가 중요한 이유: AI가 질문을 받으면 먼저 가이드를 읽어 어떤 도메인인지 파악하고, 그 다음 해당 스키마 파일만 로드합니다. 1,000개 테이블 전체를 읽지 않아도 됩니다.

왜 마크다운인가?
스키마 문서를 마크다운으로 작성한 이유는 AI가 가장 잘 이해하는 포맷이기 때문입니다. JSON이나 YAML보다 마크다운 테이블이 LLM의 컨텍스트 윈도우를 효율적으로 사용합니다. 또한 사람도 GitHub에서 바로 읽을 수 있어 유지보수가 쉽습니다.

2계층: AI 쿼리 파이프라인 — "질문하면 답이 나오는"

자연어 질문이 SQL 결과로 변환되는 7단계 파이프라인을 설계했습니다.

Phase 0: 캐시 조회

동일하거나 유사한 질문이 이전에 처리되었는지 확인합니다. 캐시에 있으면 날짜 파라미터만 교체하여 즉시 재사용합니다.

Phase 1: 질문 분석

자연어에서 엔티티(무엇을), 조건(어떤 기간/상태로), **메트릭(무엇을 측정)**을 추출하고, 6개 데이터베이스 중 어디를 조회해야 하는지 결정합니다.

Phase 2: 스키마 탐색

가이드 파일 → 도메인 파일 → 테이블 상세 순으로 점진적으로 탐색합니다. 필요한 테이블의 컬럼명, JOIN 조건, 필수 필터를 수집합니다.

Phase 3: SQL 생성 + 사용자 확인

SQL을 생성하되 실행 전에 사용자에게 보여줍니다. 이것이 안전장치입니다. 사용자가 확인해야만 다음 단계로 진행합니다.

Phase 4: SQL 실행

MCP(Model Context Protocol)를 통해 MySQL에 직접 쿼리합니다. 오류 발생 시 최대 3회 자동 재시도하며, 오류 메시지를 분석하여 SQL을 수정합니다.

Phase 5: 결과 분석

원시 데이터를 마크다운 테이블로 포맷하고, 비즈니스 관점의 해석을 추가합니다. "전주 대비 12% 증가" 같은 인사이트를 자동 생성합니다. 후속 질문도 제안합니다.

Phase 6: 캐시 저장

성공한 쿼리를 날짜, 질문, SQL, 결과 요약과 함께 캐시에 저장합니다. 다음에 유사 질문이 오면 Phase 0에서 재활용됩니다.

3계층: 안전 시스템 — "절대 데이터를 변경하지 않는"

프로덕션 데이터베이스에 AI가 접근하는 만큼, 다중 방어 계층이 필수입니다.

graph TD Q["SQL 쿼리"] --> H{"Hook 검증"} H -->|SELECT| P{"MCP 서버 검증"} H -->|INSERT/UPDATE/DELETE| B["차단"] P -->|읽기 허용| E["실행"] P -->|쓰기 시도| B E --> W{"대형 테이블?"} W -->|예| L["LIMIT 경고"] W -->|아니오| R["결과 반환"] L --> R style B fill:#ef4444,stroke:#dc2626,color:#fff style E fill:#10b981,stroke:#059669,color:#fff style L fill:#f59e0b,stroke:#d97706,color:#fff

3단계 방어

계층	역할	동작
1. SQL Safety Hook	쿼리 실행 전 Python 스크립트 검증	DML 감지 → 즉시 차단 (exit code 2)
2. MCP 서버 설정	데이터베이스 연결 수준 제한	INSERT/UPDATE/DELETE 연산 비활성화
3. SQL 컨벤션 규칙	AI에게 안전한 패턴 교육	소프트 삭제 필터, LIMIT 필수, 타임아웃 설정

대형 테이블 보호

수천만 행이 있는 테이블에 WHERE 없이 SELECT하면 DB 서버가 멈출 수 있습니다. 이를 방지하기 위해 행 수가 100만 이상인 테이블 목록을 관리하고, 해당 테이블 조회 시 LIMIT 없으면 경고를 발생시킵니다.

프로덕션 DB에 AI를 연결할 때의 원칙
1. 읽기 전용은 설정이 아닌 인프라로 강제 — 설정 파일 하나가 아닌 Hook + MCP + 권한의 다중 방어
2. 사용자 확인 단계 필수 — AI가 생성한 SQL을 실행 전에 반드시 검토
3. 대형 테이블은 별도 관리 — 행 수 기반 경고 시스템으로 실수 방지

4계층: 캐시 시스템 — "같은 질문을 두 번 하지 않는"

반복되는 질문 패턴(주간 리포트, 월간 트렌드 등)을 캐시하여 재사용합니다.

캐시 구조

각 캐시 항목에는 날짜, 질문, 대상 DB, 태그, SQL, 결과 요약이 포함됩니다. 핵심은 SQL의 날짜 파라미터를 교체 가능하게 설계한 것입니다.

예를 들어 "최근 2주간 트렌드"라는 질문이 캐시에 있으면, 날짜만 현재 기준으로 교체하여 즉시 실행할 수 있습니다.

캐시의 또 다른 가치: 지식 자산

캐시 파일은 단순한 성능 최적화가 아닙니다. "조직이 데이터에 대해 어떤 질문을 하는가"의 기록이자, 새 팀원이 도메인을 이해하는 데 쓸 수 있는 학습 자료입니다.

이 접근 방식의 장점

역할별 가치

역할	기존	개선 후
데이터 분석가	매번 개발자에게 스키마 문의	가이드 → 스키마 → 자체 SQL 작성
PM	"이 수치 뽑아주세요" 의뢰	자연어로 직접 질문, 결과 + 해석 자동
개발자	슬랙으로 스키마 설명 반복	문서 링크 공유로 해결
신규 입사자	3~6개월 도메인 파악	가이드 파일로 1~2주 내 주요 도메인 이해

직접 구축하려면: 핵심 설계 원칙

이 시스템을 다른 조직에 적용할 때 참고할 원칙입니다.

1. 도메인 기반 분류는 자동화할 수 없다

테이블 목록은 INFORMATION_SCHEMA에서 자동 추출할 수 있지만, 어떤 테이블이 어떤 비즈니스 도메인에 속하는지는 사람이 결정해야 합니다. 이 분류 작업이 가장 시간이 오래 걸리지만, 한 번 하면 장기적으로 가장 큰 가치를 제공합니다.

2. 가이드와 스키마를 분리하라

가이드(도메인 지도)와 스키마(테이블 상세)를 한 파일에 넣으면 AI의 컨텍스트 윈도우를 낭비합니다. 먼저 가이드로 방향을 잡고, 필요한 스키마만 로드하는 2단계 탐색이 효율적입니다.

3. 안전은 반복하라

프로덕션 DB에 AI를 연결할 때는 "한 계층이 뚫려도 다음 계층이 막는" 다중 방어를 구축하세요. Hook, MCP 설정, DB 권한을 모두 조합하면 실수로 데이터를 변경할 확률을 0에 가깝게 만들 수 있습니다.

4. 캐시는 성능이 아닌 지식이다

캐시를 단순히 "빠르게 하려고" 만들지 마세요. 조직의 데이터 질문 패턴이 축적되는 지식 자산으로 설계하면, 신규 인원 교육, 반복 리포트 자동화, 데이터 거버넌스에 활용할 수 있습니다.

시작이 반이다
1,000개 테이블을 한 번에 문서화할 필요는 없습니다. 가장 많이 질문받는 도메인 3\~5개부터 시작하세요. 가이드 파일 1개 + 스키마 파일 5\~10개면 충분합니다. 사용하면서 점진적으로 확장하면 됩니다.

마치며

대규모 데이터베이스를 다루는 조직이라면 이런 질문에 익숙할 것입니다:

"그 데이터 어느 테이블에 있어요?"
"JOIN 조건이 뭐예요?"
"이 컬럼에 소프트 삭제 필터를 걸어야 하나요?"

이 시스템은 이런 질문들을 문서로 답하고, AI가 자동으로 처리할 수 있게 만듭니다.

핵심 교훈 세 가지:

문서화의 가치는 "사람이 읽는 것"이 아니라 "AI가 활용하는 것"으로 바뀌고 있습니다. 마크다운으로 잘 정리된 스키마 문서는 AI 어시스턴트의 정확도를 극적으로 높입니다.
안전은 설정이 아닌 아키텍처입니다. 프로덕션 DB에 AI를 연결하려면, 읽기 전용을 "설정 한 줄"이 아닌 "다중 계층"으로 강제해야 합니다.
반복되는 질문은 시스템의 신호입니다. 같은 질문이 반복되면, 그것은 문서화가 필요하다는 신호입니다. 캐시 시스템은 이 신호를 포착하여 조직의 지식 자산으로 전환합니다.