프로젝트 소개

dsh-sql은 DSH(DeepSeek Harness)용 데이터베이스 플러그인으로, 에이전트가 데이터베이스에 연결하고 조작할 수 있게 해줍니다. 연결 관리, 읽기 전용 쿼리, 쓰기 작업, 구조 탐색, 통계 개요, 상태 자가 점검을 포괄하는 6개 도구를 제공합니다. 도구 목록: - sql_list: 구성된 연결을 나열하고 연결성 테스트를 수행합니다. - sql_query: 읽기 전용 쿼리로, SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH를 지원하며 키워드 화이트리스트를 사용하고 다중 문장을 거부합니다. - sql_exec: 쓰기 작업 및 DDL로, 다중 문장 스크립트를 실행할 수 있으며 readOnly 스위치와 승인 게이트의 제약을 받습니다. - sql_schema: 테이블 목록을 나열하거나 지정된 테이블 구조를 확인하며, 테이블 이름은 식별자 화이트리스트 검증을 거칩니다. - sql_stats: 테이블 수, 행 수, 데이터베이스 크기 개요를 제공하며, 쿼리 실패는 서로 격리됩니다. - sql_health: 연결별로 활성 상태를 확인하고 보안 구성을 점검하며, 비밀번호는 표시하지 않습니다. 엔진 및 연결: SQLite는 Node 22.13+에 내장된 node:sqlite를 사용해 의존성이 없고, MySQL은 mysql2 연결 풀을, PostgreSQL은 pg 연결 풀을 사용합니다. 구성에서 여러 명명된 연결을 선언할 수 있으며, 각각 엔진과 연결 매개변수를 지정합니다. 구성이 제공되지 않으면 기본적으로 :memory: SQLite 연결이 제공되지만, 구성이 존재하고 형식이 유효하지 않으면 로딩을 중단하고 오류를 보고하며 메모리 데이터베이스로 조용히 폴백하지 않습니다. 보안 설계: - 어휘 수준 읽기 전용 보호: sql_query는 문자열과 주석을 먼저 제거한 후 검증하며, 데이터 수정 CTE(WITH…DELETE/UPDATE), SELECT INTO, FOR UPDATE/FOR SHARE, PRAGMA 할당 및 다중 문장을 거부합니다. - 쓰기 승인 게이트: sql_exec는 기본적으로 승인 팝업을 띄우며, headless 환경에서 승인 채널이 없으면 실행을 거부합니다. - readOnly 모드: 쓰기 작업을 전체적으로 비활성화할 수 있어 프로덕션 데이터베이스에 적합합니다. - 스트리밍 행 수 제한: SQLite 반복자, MySQL Readable, PostgreSQL Query 행 이벤트는 최대 maxRows+1행만 수집하고, 초과 시 truncated로 표시합니다. MySQL과 PostgreSQL은 상한에 도달하면 해당 쿼리의 전용 연결을 닫고, 미달 시 연결 풀에 반환하여 전체 결과가 메모리에 상주하지 않도록 합니다. - 취소 가능한 실행: 쿼리와 쓰기 작업은 Harness의 exec.signal을 준수하며, 취소 시 대기를 중단하고 작업 중인 MySQL/PostgreSQL 전용 연결을 파괴합니다. - 큰 정수 무손실: bigint는 JavaScript 안전 정수 범위 내에서는 number로 출력하고, 범위를 초과하면 십진수 문자열로 출력하여 정밀도 손실을 조용히 방지합니다. - 식별자 검증: 테이블 이름은 문자, 숫자, 밑줄만 허용하여 스키마 주입을 방지합니다. - 키는 구성에 저장하지 않음: 비밀번호는 DSH_SQL_PASSWORD_<연결 이름> 환경 변수를 통해 제공할 수 있습니다. 구성 항목에는 maxRows(쿼리 반환 행 수 상한, 1-10000), queryTimeoutMs(단일 쿼리 타임아웃, 기본 60초), execTimeoutMs(단일 쓰기 작업 타임아웃, 기본 120초), readOnly 및 writeApproval이 포함됩니다. 설치 방법은 dsh plugin --profile web add dsh-sql이며, 제거 후에는 Web 서비스를 재시작해야 합니다. 프로젝트는 MIT 라이선스를 사용하며, 개발 시 pnpm install과 pnpm test(빌드 및 전체 테스트 스위트, 실제 SQLite 통합 포함)를 사용합니다. README는 공식 @deepseek-ai/dsh@0.1.5-rc.1 및 Node 24.16.0에서 검증되었으며, cordis.patch.yml과 dsh.bundle.patch 조합 패키지 모델을 채택합니다.