LLM Text-to-SQL 실전 가이드 - 스키마 설계부터 Eval까지

TL;DR

• 정확도는 프롬프트 튜닝이 아니라 DB COMMENT와 View에서 가장 크게 올라갔다
• 보안은 LLM의 거절에 기대지 말고, DB 레이어까지 내려가서 방어해야 한다
• few-shot은 기본 전략이 아니라 마지막 수단이었다

들어가며

"수주완료된 사업기회가 총 몇 건이야?"

이런 질문에 LLM이 알아서 SQL을 생성하고, DB에서 결과를 가져오고, 자연어로 답해주는 시스템을 만들었다.

처음에는 "프롬프트에 스키마 넣고 SQL 생성하면 되지"라고 가볍게 생각했는데, 프로덕션에서 돌려보니 훨씬 많은 것들을 고려해야 했다.

이 글에서는 실제 프로덕션 Text-to-SQL 시스템을 구축하면서 겪은 시행착오와 설계 판단을 공유한다. 비즈니스 DB(20+ 테이블, 500+ 레코드) 대상으로 OLTP 단건/집계 질의를 처리하는 시스템이며, 무거운 분석성 질의나 대규모 데이터 웨어하우스는 대상이 아니다.

전체 아키텍처

전체 흐름

사용자 자연어 질문
      │
      ▼
┌─────────────┐
│  LLM Agent  │
│  (DeepAgent) │
└──────┬──────┘
       │  ① list_tables()
       ▼
┌──────────────┐    pg_catalog에서
│  테이블 목록  │ ◄─ COMMENT 있는 테이블만 반환
└──────┬───────┘
       │  ② describe_tables([names])
       ▼
┌──────────────┐    컬럼, 타입, FK,
│  스키마 상세  │ ◄─ ENUM 값, COMMENT 반환
└──────┬───────┘
       │  ③ LLM이 SQL 생성
       ▼
┌──────────────┐
│ SQL Validator │ ◄─ AST 파싱, allowlist, LIMIT cap
│   (pglast)   │
└──────┬───────┘
       │  통과 시
       ▼
┌──────────────┐
│  PostgreSQL  │ ◄─ READ ONLY + RLS + 출력 cap
│  (실행)      │
└──────┬───────┘
       │
       ▼
  JSON 결과 → LLM이 자연어로 답변

핵심은 LLM이 스키마를 추측하지 않고 직접 확인한 뒤 SQL을 작성한다는 것이다.

eval에서도 모든 성공 건이 list_tables → describe_tables → query_business_db 순서를 따르는 보수적 패턴을 보였다.

왜 하드코딩이 아니라 동적 조회인가?

초기 버전에서는 스키마를 문자열로 하드코딩해서 프롬프트에 넣었다:

DB_SCHEMA_DESCRIPTION = """
opportunities 테이블:
  - id (uuid): PK
  - name (varchar): 사업기회명
  - budget_amount (bigint): 예산
  ...
"""

문제:

• DB 마이그레이션할 때마다 코드도 수동 업데이트해야 함
• 빠뜨리면 LLM이 없는 컬럼으로 SQL을 생성 → 런타임 에러
• 테이블이 늘어나면 프롬프트 토큰이 계속 증가

동적 조회로 바꾸니:

• COMMENT ON TABLE/COLUMN만 갱신하면 LLM이 자동으로 최신 스키마를 인식
• 필요한 테이블만 선택적으로 조회하니 토큰 효율적
• 스키마가 곧 문서가 되어 유지보수 포인트가 하나로 수렴

Takeaway: 스키마를 프롬프트에 하드코딩하지 마라. LLM이 런타임에 직접 조회하게 만들면 스키마 drift를 원천 차단할 수 있다.

핵심 교훈: 정확도는 스키마 정비에서 나온다

Text-to-SQL 정확도를 올리는 가장 효과적인 방법은 few-shot 예시 추가도, 프롬프트 튜닝도 아니었다.

테이블과 컬럼 이름을 명확하게 짓고, COMMENT를 빈틈없이 다는 것이 압도적으로 효과가 좋았다.

COMMENT가 사실상 프롬프트 역할을 한다

PostgreSQL의 COMMENT ON 구문이 LLM의 유일한 스키마 정보원이다:

COMMENT ON TABLE opportunities IS
  '사업기회(영업 건). 영업→입찰→계약→수행 4단계.';
 
COMMENT ON COLUMN opportunities.sales_status_code IS
  '영업상태코드. 값: SALS_RGSN(영업등록), BID_PRPS(입찰제안),
   BID_RVW_CMPL_RODR(수주완료), BID_RVW_CMPL_FODR(실주).
   한글명은 sales_status_name 참조.';
 
COMMENT ON COLUMN opportunities.start_date IS
  '사업 시작일(예정). "시작한 날짜", "착수일" 질문에 사용.
   created_at(레코드 생성 시점)과 혼동 주의.';

마지막 예시가 중요하다.

eval 초기에 "2024년에 시작한 사업기회"를 물었을 때, LLM이 start_date 대신 created_at을 사용해서 0건을 반환하는 실패가 있었다. COMMENT에 **"이 컬럼은 이런 질문에 쓴다"**는 힌트를 명시적으로 추가하니 해결됐다.

프로젝트 진행에 따른 변화

COMMENT 보강이 정확도에 효과가 있었다는 건 확실하지만, 정직하게 말하면 정량적인 전후 비교는 어렵다. 프로젝트가 진행되면서 COMMENT 수만 바뀐 게 아니라 데이터셋, 모델, 평가 방식도 함께 바뀌었기 때문이다.

대략적인 타임라인:

1. 초기 - 3개 테이블 하드코딩, COMMENT ~15개. 체감 정확도 60-70% (정식 eval 없음)
2. 동적 조회 전환 - COMMENT ~80개로 확대. 14문항 수동 테스트에서 mini 기준 86%
3. 대규모 보강 - COMMENT 170개. 52문항 LangSmith eval에서 mini 84%, gpt-5.4 98%

각 단계에서 문항 수도, 난이도 분포도, 채점 방식도 다르기 때문에 숫자를 직접 비교하는 건 무리다.

다만 확실히 말할 수 있는 건, COMMENT를 채울수록 LLM이 추측에 의존하는 빈도가 눈에 띄게 줄었다는 것이다. 특히 원가 서브시스템(costs, manpower_plans, materials, expenses) 50+ 컬럼의 COMMENT를 전부 채운 뒤로는 도메인 매핑 실패가 거의 사라졌다.

ENUM 값은 COMMENT에 명시

LLM이 WHERE industry_type_code = 'MANUFACTURING'을 정확하게 생성하려면, 유효한 값 목록을 알아야 한다.

PostgreSQL ENUM 타입은 describe_tables에서 자동으로 enum_values로 반환되고, VARCHAR 기반 코드 컬럼은 COMMENT에 유효값을 나열했다.

eval에서 LLM은 COMMENT의 enum 설명을 그대로 가져다 썼다. sales_status_code='BID_RVW_CMPL_RODR'(수주완료) 같은 직관적이지 않은 코드도 few-shot 없이 정확하게 매핑했다.

Takeaway: COMMENT의 품질이 곧 SQL의 품질이다. 특히 "이 컬럼에 어떤 값이 들어가는지"와 "비슷한 컬럼과 어떻게 다른지"를 명시하는 게 효과가 크다.

복잡한 JOIN은 View로

LLM이 매번 3-4개 테이블을 JOIN하는 SQL을 정확하게 생성하기란 어렵다.

자주 쓰이는 복잡한 JOIN 패턴이 있다면 미리 View를 만들어두는 것이 few-shot보다 효과적이다.

CREATE VIEW v_opportunity_summary AS
SELECT
    o.id,
    o.name,
    o.client_name,
    o.budget_amount,
    o.sales_status_name,
    COUNT(om.*) AS member_count,
    p.total_amount AS project_amount
FROM opportunities o
LEFT JOIN opportunity_members om ON om.opportunity_id = o.id
LEFT JOIN projects p ON p.opportunity_id = o.id
  AND p.is_representative = true
GROUP BY o.id, p.id;
 
COMMENT ON VIEW v_opportunity_summary IS
  '사업기회 요약 뷰. 참여자 수, 대표 프로젝트 금액 포함.
   사업기회 현황/통계 질문에 사용.';

View의 장점:

• LLM은 단일 테이블 SELECT만 하면 됨
• JOIN 실수 가능성 제거
• COMMENT를 달면 LLM이 언제 이 View를 쓸지 판단할 수 있음
• DB 레벨에서 최적화 가능

Takeaway: LLM에게 JOIN을 가르치기보다, DB에 의미 있는 View를 준비하는 편이 유지보수와 정확도 모두 유리하다.

few-shot은 최후의 수단

처음에는 few-shot 예시를 추가하면 정확도가 오를 거라고 생각했다. 하지만 스키마(COMMENT + View)만 잘 정비하면 zero-shot으로 충분했다.

few-shot의 단점:

• 유지보수 비용 - 스키마가 바뀔 때마다 예시 SQL도 업데이트해야 함
• 과적합 위험 - LLM이 예시 패턴에 끌려가서 다른 유형의 질문에서 오히려 정확도 하락
• 토큰 낭비 - 매번 고정 예시를 보내면 컨텍스트가 아까움

그래도 few-shot이 필요한 경우가 있긴 하다:

• 특정 도메인 용어 매핑이 COMMENT로 해결이 안 될 때
• 복잡한 CTE 패턴이 반복적으로 필요할 때

우선순위: COMMENT 보강 → View 생성 → few-shot 추가

Self-Correction: 에이전트에게 맡겨라

에러가 나면 어떻게 할 것인가? 두 가지 접근이 있다.

접근 1: 명시적 retry 루프

# 개념 예시 (pseudo-code)
for attempt in range(3):
    result = await query_business_db(sql)
    if "error" not in result:
        break
    sql = await llm.fix_sql(sql, result["error"])

접근 2: 에이전트에게 위임 (내 선택)

# 개념 예시 - 에러를 JSON으로 반환만 하면 됨
@tool
async def query_business_db(sql: str) -> str:
    result = validator.validate(sql)
    if not result.valid:
        return json.dumps({"error": result.error, "sql": sql})
    # ... 실행 후 결과 또는 에러 JSON 반환

나는 접근 2를 택했다.

query_business_db가 에러를 JSON으로 반환하면, 에이전트(LLM)가 그 에러를 tool observation으로 받아서 스스로 판단하게 했다. 별도의 retry 노드나 correction 프롬프트 없이.

이유:

• Agentic하게 - 에이전트가 에러를 보고 SQL을 수정할지, 질문을 다시 할지, 포기할지를 스스로 결정
• 코드 단순화 - retry 로직, 최대 시도 횟수, correction 프롬프트를 관리할 필요 없음
• 유연성 - 에러 유형에 따라 다른 전략을 에이전트가 알아서 선택

잘 동작한 경우

eval에서 관찰된 self-correction 성공 사례:

"2024년 월별 신규 사업기회 수 추이를 보여줘" (L5-2)

1. 1차: generate_series 사용 → validator가 Function 'generate_series' not allowed 반환
2. 2차: UNION ALL로 12개월을 직접 나열하는 방식으로 재작성 → 성공

LLM이 에러 메시지를 보고 "이 함수가 허용 안 되는구나"를 이해하고 대안을 찾았다.

해결 못한 경우

"수주완료된 사업기회들 평균 기간과 평균 예산을 알려줘" (L7-2)

1. 1차: WHERE status='completed' AND sales_status_code='BID_RVW_CMPL_RODR' → 빈 결과
2. 2차: WHERE status='completed'만으로 완화 → 여전히 빈 결과
3. 3차: SELECT COUNT(*) 전체 건수만 확인 → 포기

올바른 조건은 sales_status_code만 사용하는 것이었는데, status='completed' 조건을 끝까지 버리지 못했다.

안정성이 더 중요한 환경이라면 명시적 retry 루프를 추가하는 것도 방법이다. 최대 3회 제한 + "에러 메시지를 참고해서 SQL을 수정하라"는 correction 프롬프트를 넣으면 된다.

Takeaway: 기계적 오류는 재시도로 고쳐지지만, 도메인 오해는 스키마 품질로 해결해야 한다.

보안: Defense in Depth

Text-to-SQL에서 보안은 빼놓을 수 없는 요소다. LLM이 DROP TABLE을 생성할 수도 있고, 프롬프트 인젝션으로 악의적 SQL이 만들어질 수도 있기 때문이다.

L1 - AST 기반 SQL Validator

정규식 기반 검증은 우회가 너무 쉽다. pglast로 PostgreSQL AST를 파싱해서 구조적으로 검증한다:

# 핵심 로직 (단순화)
from pglast import parse_sql
from pglast.ast import SelectStmt
 
class SqlValidator:
    def validate(self, sql: str) -> ValidationResult:
        stmts = parse_sql(sql)
 
        if len(stmts) != 1:                        # 단일 statement만
            return REJECT("Multiple statements")
        if not isinstance(stmts[0].stmt, SelectStmt): # SELECT/WITH만
            return REJECT("Only SELECT/WITH allowed")
 
        # 테이블 allowlist
        # 함수 allowlist (pg_read_file, dblink 등 차단)
        # 스키마 제한 (public만 허용)
        # LIMIT cap (없으면 100 추가, 초과 시 100으로 제한)
 
        return ACCEPT(sanitized_sql)

AST 레벨에서 검증하면:

• SELECT 1; DROP TABLE x → "Multiple statements" 차단
• SELECT pg_read_file('/etc/passwd') → "Function not allowed" 차단
• SELECT * FROM pg_catalog.pg_shadow → "Schema not allowed" 차단
• CTE alias를 테이블명으로 오인하지 않음 (CTE name collector로 분리)

L2 - READ ONLY 트랜잭션

# psycopg v3 기준 - conn.transaction() 블록 안에서 실행
await conn.execute("SET TRANSACTION READ ONLY")

Validator를 어떻게든 우회해도 DB가 쓰기를 거부한다.

L3 - Row-Level Security

# psycopg v3 - 같은 트랜잭션 안에서 실행
await conn.execute(
    "SELECT set_config('app.current_org_id', %s, true)", (org_id,)
)

조직별 데이터 격리. 같은 SQL을 실행해도 자기 조직 데이터만 보인다.

L4 - 출력 제한

fetchmany(max_rows=100) + 50KB byte cap. 대량 결과가 에이전트 컨텍스트를 넘치게 하는 것을 방지한다.

실제 방어 테스트 결과

eval에서 Adversarial 질문 7건(L8)을 던졌다:

대부분 LLM이 선제 거절했지만, CROSS JOIN 같은 경우 LLM이 통과시켰다.

CROSS JOIN에 대해 LIMIT cap은 결과 행 수를 제한할 뿐, 실행 비용 자체를 막지는 못한다. 조인 순서에 따라 DB는 LIMIT 전에 큰 비용을 치를 수 있다. 프로덕션에서는 statement_timeout 설정이나, 비용이 큰 쿼리를 사전에 EXPLAIN으로 검증하는 레이어를 추가로 고려해야 한다.

별도로 LLM을 우회해서 악성 SQL 12건을 직접 query_business_db에 보내는 테스트도 했다. DELETE, DROP, UPDATE, INSERT, pg_read_file, dblink, stacked statements, schema bypass 등 12/12 전부 차단.

Takeaway: 보안은 단일 레이어가 아니라 겹겹이 쌓아야 한다. LLM refusal → AST validator → READ ONLY → RLS → 출력 cap. 그리고 실행 비용 방어(statement_timeout)도 잊지 말 것.

Eval: 52문항 5모델 벤치마크

테스트 없이는 "잘 되는 것 같다"에서 멈추게 된다. LangSmith를 활용해 체계적인 eval을 구성했다.

데이터셋 설계

52개 질문을 8개 난이도 레벨로 나눴다:

L7이 실무에서 가장 중요한 레벨이다.

"얼마"가 개수인지 금액인지, "시작한"이 start_date인지 created_at인지 - 이런 모호성을 LLM이 얼마나 잘 해석하는지가 프로덕션 체감 품질을 좌우한다.

Evaluator 3종

evaluators=[rule_scorer, llm_judge, defense_scorer]

1. rule_scorer - ground-truth SQL을 실제 DB에서 실행한 값을 답변 텍스트에 regex 매칭. 결정론적. 52문항 전체 대상
2. llm_judge - gpt-5.4가 question + truth rows + 모델 답변을 보고 correct 판정. code↔name 매핑 동등 처리. L1~L7 대상 (45문항). L8은 defense_scorer가 별도 평가
3. defense_scorer - L8 adversarial 7문항 전용. 데이터 유출 여부만 판정

결과

gpt-5.4가 가장 높은 점수를 기록했다. 3건의 scorer FAIL을 수동 재검토한 결과:

• L3-5 (rule FAIL): "10건 이상인 월"을 2024-04 포맷으로 답변 - 값은 맞지만 scorer의 "4월" 패턴에 안 걸림
• L4-1 (judge FAIL): 참여자 수 top 5가 모두 3명 tie - GT 쿼리와 다른 5건을 반환했지만 둘 다 정답
• L8-6 (defense FAIL): CROSS JOIN에 LIMIT 100 cap이 작동해 100행 반환 - 데이터 유출이 아니라 정상 쿼리 결과

3건 모두 scorer 설계의 한계지 실제 오답이 아니었다. 다만 이걸 "실질 100%"라고 부르는 건 과하다 - 수동 검토에서 오탐을 확인했을 뿐, 52문항이라는 작은 데이터셋에서의 결과이고, 다른 질문 세트에서는 다른 결과가 나올 수 있다.

gemini-3.1-pro-preview가 2위로, gpt-5.4-mini보다 확실히 앞섰다. flash와 mini는 비슷한 수준.

모든 모델 공통: 1-shot 성공률 80%+

52문항 중 38~44개를 첫 시도에 맞췄다. few-shot 없는 zero-shot임에도 불구하고.

Takeaway: eval은 "잘 되는 것 같다"를 숫자로 바꿔준다. 52문항이면 큰 벤치마크는 아니지만, 난이도별 분류와 3종 scorer 조합으로 시스템의 강점과 약점을 구체적으로 파악할 수 있었다.

더 나아가려면

현재 시스템에서 개선할 수 있는 방향들:

• COMMENT 지속 보강 - 가장 ROI가 높다. 새 테이블/컬럼 추가 시 COMMENT를 반드시 함께 작성. 동의어 힌트, 혼동 방지, 유효값 목록이 특히 효과적
• View 추가 - 자주 나오는 복잡 JOIN 패턴을 View로 미리 만들기. 사업기회 요약, 연도/월별 집계, 원가 서브시스템 요약 등
• 선택적 few-shot - COMMENT와 View로도 안 되는 패턴이 발견될 때만 추가
• statement_timeout - CROSS JOIN 같은 비용 폭발 방어. LIMIT만으로는 실행 비용을 못 막음
• Semantic caching - 반복 질문이 많으면 SQL 레벨에서 캐싱 고려
• EXPLAIN 사전 검증 - 느린 쿼리가 문제되면 실행 전 예상 비용 확인

정리

Text-to-SQL에서 배운 것들을 한 줄로 요약하면:

스키마를 잘 정비하면 LLM은 알아서 한다.

구체적으로:

1. COMMENT가 곧 프롬프트다 - few-shot보다 COMMENT가 먼저다
2. 동적 스키마 조회 - 하드코딩 대신 pg_catalog에서 런타임 조회. 스키마 drift 방지
3. 복잡 JOIN은 View로 - View가 few-shot보다 유지보수와 정확도 모두 낫다
4. Self-correction은 에이전트에게 - 에러 JSON 반환만으로 충분. 명시적 retry는 필요 시 추가
5. 보안은 겹겹이 - LLM refusal + AST validator + READ ONLY + RLS + 출력 cap + statement_timeout
6. Eval은 필수 - "잘 되는 것 같다"와 "98%"는 다른 이야기

참고자료

• BIRD Benchmark - Text-to-SQL 주요 벤치마크 (12,751문항, 95 DB)
• CHESS: Contextual Harnessing for Efficient SQL Synthesis - value lookup 포함 end-to-end 시스템 (ICML 2025)
• MAC-SQL: Multi-Agent Collaborative Framework - Selector + Decomposer + Refiner 패턴 (COLING 2025)
• OpenSearch-SQL - 동적 few-shot + self-consistency로 BIRD 72.28% (fine-tuning 없이)
• pglast - PostgreSQL AST 파서. 정규식 대신 구조적 SQL 검증에 필수
• LangSmith Evaluation - LLM 시스템 eval 프레임워크
• Awesome-LLM-based-Text2SQL (TKDE 2025 Survey) - 종합 논문 목록