sqlsure

AI가 SQL을 작성합니다. sqlsure는 그것이 올바른지 확인합니다.

쿼리는 완벽하게 유효하고, 오류 없이 실행되며, 조인으로 인해 수익이 두 번 계산되거나, 평균이 합산되거나, 환자 식별자가 노출되는 등 조용히 잘못된 숫자를 반환할 수 있습니다. 데이터베이스는 이를 잡아내지 못합니다. 린터도 잡아내지 못합니다. 자신의 SQL을 검토하는 LLM도 잡아내지 못합니다.

sqlsure는 쿼리가 실행되기 전에 결정론적으로 0.1ms 만에 이를 잡아냅니다.

증명이지 약속이 아닙니다: 우리는 sqlsure를 모든 텍스트-SQL 모델이 평가되는 두 벤치마크의 정답에 대해 실행했습니다. 2,568개의 전문가 작성 쿼리, 45개의 플래그, 0개의 오탐 — 여기에는 sqlsure가 목표로 하는 정확한 버그 클래스로 인해 8배나 잘못된 것으로 증명 가능한 BIRD dev 정답과 상류에 제출된 스키마 결함이 포함됩니다.

작동 방식

sqlsure는 팀이 이미 선언한 사실에 대해 SQL을 판단합니다. dbt unique 테스트는 그레인이 되고, relationships 테스트는 조인 카디널리티가 되며, 한 줄의 meta 태그는 합계에 안전한 항목을 표시합니다. 배울 새로운 언어도, 수동으로 유지 관리할 모델도 없습니다. 규칙은 LLM 호출이 아닌 사전 조회입니다: 동일한 입력, 동일한 판결, 항상, 오프라인에서.

모든 거부에는 머신이 실행 가능한 fix가 포함되어 있어 AI 에이전트가 스스로 수정합니다: 초안 → 확인 → 수정 → 확인 → 실행. 우리의 벤치마크에서 수정 사항을 그대로 적용했을 때 10/10번의 경우 통과 쿼리가 생성되었습니다.

빠른 시작

pip install sqlsure

from sqlsure import SemanticModel, check
violations = check(sql, model)   # []는 의미적으로 안전함을 의미

또는 클론하여 30초 데모를 실행하세요:

python check.py                   # 5개의 잘못된 쿼리 거부, 1개 승인 — 수정 사항 포함
python -m sqlsure.scan path/to/dbt-repo --report report.md   # 모든 dbt 저장소 감사

세 가지 진입점, 하나의 엔진

1. CI 게이트 — PR이 이중 계산할 때 병합을 차단합니다:

python -m sqlsure.cli --model model.json query.sql   # 위반 시 종료 코드 1

2. MCP 서버 — AI 에이전트가 실행 전 검사를 통과해야 합니다:

claude mcp add sqlsure -- python -m sqlsure.mcp_server --model /abs/path/model.json

도구 참조 및 에이전트 루프 패턴은 docs/MCP.md를 참조하세요.

3. 라이브러리 — check()를 모든 텍스트-SQL 제품 또는 에이전트 프레임워크에 내장하세요. 드롭인 SemanticGate는 Vanna/WrenAI 스타일 생성기를 래핑하고, 의미적 평가 지표는 실행 정확도가 보지 못하는 NL2SQL 출력을 채점합니다.

또한 Agent Skill로 사용 가능 — 에이전트가 직접 로드하는 단일 SKILL.md; 서버 프로세스가 필요 없습니다.

규칙 (v0.1)

sqlsure가 무언가를 검증할 수 없을 때는 "확인할 수 없음"이라고 말합니다 — "괜찮아 보임"이 아닙니다. 정직한 불확실성은 기능입니다.

신뢰 속성

• 결정론적 — 동일한 SQL + 동일한 규칙집 = 항상 동일한 판결; 규칙은 사전 조회이며, 한 줄씩 감사 가능
• 오프라인 — 네트워크 호출 없음; SQL이 기계를 떠나지 않음
• 데이터 접근 없음 — 쿼리 텍스트를 구문 분석; 데이터베이스에 연결하지 않음
• 원격 측정 없음 — 절대 수집되지 않음 (SECURITY.md)
• 공급망 — 릴리스는 공개 CI 실행이 있는 태그된 커밋에서 PyPI Trusted Publishing (OIDC)을 통해서만 제공; 두 개의 런타임 종속성

규칙집의 출처

• dbt (현재 작동): manifest.json 또는 schema.yml — 팀이 이미 작성한 테스트가 구성 없이 집행 가능한 의미론이 됩니다

• 일반 PK/FK 선언 (현재 작동 — 벤치마크 감사에 사용됨)

• 실제 데이터베이스 자체 (현재 작동): 의미론 계층이 전혀 없나요? sqlsure.introspect가 카탈로그에서 규칙집을 구축합니다 — SQLite PRAGMA 또는 information_schema PK/FK (postgres/mysql). BIRD의 자체 데이터베이스 파일을 분석하여 벤치마크의 게시된 스키마에서 누락된 2개의 외래 키를 복구했습니다 (bird-bench/mini_dev#37)

  root@kitploit:~

  from sqlsure.introspect import model_from_sqlite
  model = model_from_sqlite("app.db")   # PK -> 그레인, FK -> 조인 가장자리
  

• 수동 작성 JSON — model.example.json

• OSI 및 WrenAI MDL (integrations/에 작동 중인 로더 있음): OSI는 사양의 게시된 예제에서 시연됨; WrenAI MDL은 WrenAI의 자체 제공 예제 매니페스트에서 시연됨 — primaryKey → 그레인, 관계 joinType + condition → 조인 가장자리, 큐브 측정값 → 가산성

검증 대상

• 16/16 규칙 테스트, 100% 재현율 / 0% 위양성 쌍을 이루는 벤치마크에서 (docs/METRICS.md)
• 실제 프로덕션 저장소 (Mattermost의 웨어하우스, Fivetran 패키지, dbt의 jaffle shop) — docs/TEST-REPORTS.md
• Spider + BIRD 골드 쿼리 — 위의 무잡음 외부 감사

더 알아보기

• docs/EVIDENCE.md — 당신을 위해 하는 일, 모든 주장이 재실행 가능한 측정과 연결됨
• docs/ARCHITECTURE.md — 물리적 작동 방식, ELI5 → 전문가 수준, 실제 중간 출력 포함
• docs/FOR-DUMMIES.md — 모든 개념을 기초부터
• docs/INTEGRATIONS.md — GitHub Action, pre-commit, MCP, Snowflake UDF / Cortex Agent 도구, 쿼리 기록 감사
• docs/MCP.md — MCP 서버 문서
• CONTRIBUTING.md — 규칙 및 로더 추가

Apache-2.0 · sqlsure.ai

mcp-name: io.github.sqlsure/sqlsure