
SQL을 위한 의미 검사기 — 쿼리 실행 전에 팬아웃 이중 계산, 가산성 위반, 잘못된 조인 키, 정책 위반을 잡아냅니다. BIRD/Spider text-to-SQL 벤치마크에서 실제 버그를 발견했습니다.
AI가 SQL을 작성합니다. sqlsure가 그것이 올바른지 확인합니다.
쿼리는 완벽하게 유효하고, 오류 없이 실행되며, 조용히 틀린 숫자를 반환할 수 있습니다 — 조인으로 인해 매출이 이중 계산되거나, 평균이 합산되거나, 환자 식별자가 노출되는 경우처럼요. 데이터베이스는 이를 잡아내지 못합니다. 린터도 잡아내지 못합니다. 자신의 SQL을 검토하는 LLM도 잡아내지 못합니다.
sqlsure는 잡아냅니다 — 결정론적으로, 0.1 ms 만에, 쿼리가 실행되기 전에.
약속이 아닌 증명: 우리는 모든 text-to-SQL 모델이 평가받는 두 벤치마크의 정답(gold answer)에 대해 sqlsure를 실행했습니다. 전문가가 작성한 2,568개의 쿼리, 45개의 플래그, 오탐 제로 — 여기에는 sqlsure가 겨냥하는 정확한 버그 유형으로 인해 8배나 틀렸음이 증명 가능한 BIRD dev 정답과, 업스트림에 보고되어 이후 수정된 스키마 결함이 포함됩니다 — BIRD의 2026 Mini-Dev 릴리스는 우리가 보고한 바로 그 두 개의 외래 키를 추가했으며, 이제 그 주석은 11개 데이터베이스 모두에서 배포된 데이터베이스와 일치합니다 (검증 방법).
sqlsure는 팀이 이미 선언한 사실에 비추어 SQL을 판정합니다 — dbt unique 테스트는 그레인이 되고, relationships 테스트는 조인 카디널리티가 되며, 한 줄짜리 meta 태그는 무엇을 합산해도 안전한지 표시합니다. 배울 새로운 언어도, 수동으로 유지할 모델도 없습니다. 규칙은 LLM 호출이 아닌 사전 조회입니다: 동일한 입력, 동일한 판정, 매번, 오프라인으로.
모든 거부에는 기계가 실행할 수 있는 fix가 함께 제공되므로 AI 에이전트가 스스로 복구합니다: 초안 → 검사 → 수정 → 검사 → 실행. 우리의 벤치마크에서 수정 사항을 그대로 적용하면 10/10번 통과하는 쿼리가 생성되었습니다.
pip install sqlsure
from sqlsure import SemanticModel, check
violations = check(sql, model) # [] means semantically safe
또는 복제한 후 30초 데모를 실행하세요:
python check.py # 5 wrong queries rejected, 1 approved — with fixes
python -m sqlsure.scan path/to/dbt-repo --report report.md # audit any dbt repo
1. CI 게이트 — PR이 이중 계산될 때 병합을 차단합니다:
python -m sqlsure.cli --model model.json query.sql # exit 1 on violations
2. MCP 서버 — AI 에이전트는 실행 전에 검사를 통과해야 합니다:
claude mcp add sqlsure -- python -m sqlsure.mcp_server --model /abs/path/model.json
도구 참조 및 에이전트 루프 패턴은 docs/MCP.md를 참조하세요.
3. 라이브러리 — 모든 text-to-SQL 제품이나 에이전트 프레임워크 안에 check()를 임베드하세요. 드롭인 방식의 SemanticGate는 Vanna/WrenAI 스타일 생성기를 감싸며, semantic eval metric은 실행 정확도로는 판별할 수 없는 NL2SQL 출력을 평가합니다.
또한 Agent Skill로도 제공됩니다 — 에이전트가 직접 로드하는 단일 SKILL.md이며, 서버 프로세스가 필요 없습니다.
| 규칙 | 심각도 | 탐지 대상 |
|---|---|---|
| FANOUT | error | 일대다 조인 후 가산 측도의 SUM/COUNT |
| CHASM | error | 서로를 배수로 증폭시키는 두 개 이상의 팬아웃 조인 |
| ADDITIVITY | error | 비가산 측도(비율, 평균)의 SUM |
| SEMI_ADDITIVE | error | 스냅샷 차원에 걸쳐 합산된 잔액/인구 조사 |
| JOIN_KEY | error | 선언된 관계와 일치하지 않는 컬럼에 대한 조인 |
| CROSS_JOIN | error | 프레디킷이 없는 조인 |
| WEIGHTED_AVG | warning | 팬아웃으로 인해 조용히 재가중된 AVG |
| UNDECLARED_JOIN | warning | 선언된 관계가 없는 조인 (검증 불가 ≠ 안전) |
| SENSITIVE_COLUMN | policy | 쿼리 출력에 노출된 PHI/PII 컬럼 |
sqlsure가 무언가를 검증할 수 없을 때는 "검증할 수 없음"이라고 말합니다 — 결코 "문제 없어 보임"이라고 하지 않습니다. 정직한 불확실성은 기능입니다.
dbt (현재 지원): manifest.json 또는 schema.yml — 팀이 이미 작성한
테스트가 구성 없이 강제 가능한 시맨틱이 됨
일반 PK/FK 선언 (현재 지원 — 벤치마크 감사를 구동함)
라이브 데이터베이스 자체 (현재 지원): 시맨틱 레이어가 전혀 없나요?
sqlsure.introspect가 카탈로그로부터 규칙집을 구축합니다 — SQLite
PRAGMA 또는 information_schema PK/FK (postgres/mysql). BIRD 자체의
데이터베이스 파일을 인트로스펙션하여 벤치마크의 공개 스키마에서 누락된
외래 키 2개를 복구했습니다 — 업스트림에 보고되어 BIRD의 2026 릴리스에서
수정됨
(bird-bench/mini_dev#37)
from sqlsure.introspect import model_from_sqlite
model = model_from_sqlite("app.db") # PK -> grain, FK -> join edges
수작성 JSON — model.example.json
OSI 및 WrenAI MDL (integrations/에서 동작하는 로더): OSI는
스펙에 공개된 예제에서 시연되었으며,
WrenAI MDL은 WrenAI가 자체적으로
배포한 예제 매니페스트에서 시연되었습니다 — primaryKey → grain, 관계
joinType + condition → 조인 엣지, 큐브 측정값 → 가산성
Cube, Snowflake Semantic Views — 어댑터는 로드맵에 있으며,
엔진은 항상 하나의 SemanticModel만 봅니다
Apache-2.0 · sqlsure.ai
mcp-name: io.github.sqlsure/sqlsure