NL2SQL Tool

NL2SQLTool은 자연어를 SQL 쿼리로 변환하도록 설계된 도구예요.

출처: 문서

본문

개요 (Overview)

이 도구는 자연어를 SQL 쿼리로 변환하는 데 사용됩니다. 에이전트에 전달되면 쿼리를 생성하고 이를 사용해 데이터베이스와 상호작용합니다. 이를 통해 에이전트가 목표에 따라 데이터베이스에 접근해 정보를 가져오고, 그 정보를 사용해 응답·리포트 또는 기타 출력을 생성하는 여러 워크플로가 가능해집니다. 또한 에이전트가 목표에 따라 데이터베이스를 업데이트할 수 있는 능력도 제공합니다.

주의: 기본적으로 도구는 읽기 전용입니다(SELECT/SHOW/DESCRIBE/EXPLAIN만 허용). 쓰기 연산은 allow_dml=True 또는 CREWAI_NL2SQL_ALLOW_DML=true 환경 변수가 필요합니다. 쓰기 접근을 활성화할 때는 가능하면 에이전트가 범위가 제한된 데이터베이스 사용자나 읽기 복제본(read replica)을 사용하도록 하세요.

보안 모델 (Security Model)

NL2SQLTool은 실행 가능한 도구입니다. 모델이 생성한 SQL을 구성된 데이터베이스 연결에 직접 실행합니다. 이는 위험이 배포 선택에 따라 달라진다는 것을 의미합니다:

db_uri에 제공하는 자격 증명이 무엇인지
신뢰할 수 없는 입력이 프롬프트에 영향을 줄 수 있는지
실행 전에 도구 호출 가드레일(guardrails)을 추가하는지

신뢰할 수 없는 입력을 이 도구를 사용하는 에이전트로 라우팅한다면, 고위험 통합으로 취급하세요.

강화 권장 사항 (Hardening Recommendations)

프로덕션에서 다음을 모두 사용하세요:

가능하면 항상 읽기 전용 데이터베이스 사용자 사용
분석/검색 워크로드에는 읽기 복제본 선호
최소 권한 부여(슈퍼유저/관리자 역할, 파일/시스템 수준 기능 없음)
데이터베이스 측 리소스 제한 적용(문장 타임아웃, 잠금 타임아웃, 비용/행 제한)
허용된 쿼리 패턴을 강제하는 before_tool_call 훅 추가
파괴적 문장에 대한 쿼리 로깅과 알림 활성화

읽기 전용 모드 및 DML 설정 (Read-Only Mode & DML Configuration)

NL2SQLTool은 기본적으로 읽기 전용 모드로 동작합니다. 추가 설정 없이 다음 문장 유형만 허용됩니다:

SELECT
SHOW
DESCRIBE
EXPLAIN

쓰기 연산(INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE 등)을 실행하려는 시도는 DML이 명시적으로 활성화되지 않는 한 에러를 발생시킵니다. 세미콜론을 포함한 다중 문장 쿼리(예: SELECT 1; DROP TABLE users)도 인젝션 공격을 방지하기 위해 읽기 전용 모드에서 차단됩니다.

쓰기 연산 활성화 (Enabling Write Operations)

DML(Data Manipulation Language)은 두 가지 방법으로 활성화할 수 있어요:

옵션 1 — 생성자 파라미터:

from crewai_tools import NL2SQLTool

nl2sql = NL2SQLTool(
    db_uri="postgresql://example@localhost:5432/test_db",
    allow_dml=True,
)

옵션 2 — 환경 변수:

CREWAI_NL2SQL_ALLOW_DML=true

from crewai_tools import NL2SQLTool

# DML enabled via environment variable
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

사용 예제 (Usage Examples)

읽기 전용(기본값) — 분석과 리포팅에 안전:

from crewai_tools import NL2SQLTool

# Only SELECT/SHOW/DESCRIBE/EXPLAIN are permitted
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

DML 활성화 — 쓰기 워크로드에 필요:

from crewai_tools import NL2SQLTool

# INSERT, UPDATE, DELETE, DROP, etc. are permitted
nl2sql = NL2SQLTool(
    db_uri="postgresql://example@localhost:5432/test_db",
    allow_dml=True,
)

DML을 활성화하면 에이전트에게 데이터를 수정하거나 삭제할 수 있는 능력이 생깁니다. 사용 사례가 명시적으로 쓰기 접근을 요구할 때만 활성화하고, 데이터베이스 자격 증명이 필요한 최소 권한으로 범위가 제한되어 있는지 확인하세요.

요구 사항 (Requirements)

SqlAlchemy
호환되는 DB 라이브러리 (예: psycopg2, mysql-connector-python)

설치 (Installation)

crewai_tools 패키지를 설치하세요:

pip install 'crewai[tools]'

사용법 (Usage)

NL2SQLTool을 사용하려면 도구에 데이터베이스 URI를 전달해야 합니다. URI는 dialect+driver://username:password@host:port/database 형식이어야 합니다.

from crewai_tools import NL2SQLTool

# psycopg2 was installed to run this example with PostgreSQL
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        allow_delegation=False,
        tools=[nl2sql]
    )

예제 (Example)

첫 번째 태스크 목표는: "각 도시의 월평균·최대·최소 수익을 조회하되, 사용자가 둘 이상인 도시만 포함하세요. 또한 각 도시의 사용자 수를 세고, 월평균 수익 내림차순으로 결과를 정렬하세요" 에이전트는 DB에서 정보를 얻으려고 시도하고, 첫 번째는 틀렸으므로 에이전트가 다시 시도해 올바른 정보를 얻어 다음 에이전트로 전달합니다.

두 번째 태스크 목표는: "데이터를 검토하고 상세 리포트를 만든 뒤, 제공된 데이터를 바탕으로 필드와 함께 데이터베이스에 테이블을 생성하세요. 각 도시의 월평균·최대·최소 수익 정보를 포함하되, 사용자가 둘 이상인 도시만 포함하세요. 또한 각 도시의 사용자 수를 세고, 월평균 수익 내림차순으로 정렬하세요." 이제 흥미진진해집니다. 에이전트는 테이블을 생성할 뿐만 아니라 테이블에 데이터를 삽입하는 SQL 쿼리도 생성합니다. 그리고 마지막에 에이전트는 여전히 데이터베이스에 있었던 내용과 정확히 일치하는 최종 리포트를 반환합니다.

이것은 NL2SQLTool을 사용해 데이터베이스와 상호작용하고 데이터베이스의 데이터를 기반으로 리포트를 생성하는 방법의 간단한 예제입니다. 이 도구는 에이전트의 로직과 데이터베이스와의 상호작용 방식에 무한한 가능성을 제공합니다.

 DB -> Agent -> ... -> Agent -> DB

더 알아보기 (Learn more)

MySQL RAG Search — MySQL 검색 도구 알아보기
Database & Data 도구 개요 — 데이터베이스 도구 전체 살펴보기