royashbrook/sql-spider

sql-spider은(는) 무엇을 하나요?

SQL 데이터베이스의 결정론적 의존성 그래프를 구축하고 시드 객체로부터 닫힐(closed) 때까지 스파이더링합니다. 즉, 하나의 연결 요소, 고아(orphan) 없음, 가상의 가장자리(phantom edge) 없음을 의미합니다. 그래프 엔진은 순수하고 오프라인으로 작동합니다. SQL 텍스트를 AST로 파싱하고 트리에서 직접 의존성을 읽어내므로, 동일한 입력은 항상 동일한 그래프를 생성하며 휴리스틱이나 라이브 연결이 필요하지 않습니다.

이 스킬이 존재하는 이유: sql-spider는 데이터베이스에 연결하지 않습니다. 읽기 전용 쿼리를 내보내고 CSV 결과를 수집합니다. 따라서 당신, 에이전트가 데이터베이스 어댑터 역할을 합니다. 내보낸 각 쿼리를 데이터베이스에 도달할 수 있는 방법(직접 연결이 아닌 읽기 전용 작업을 통해서만 도달 가능한 데이터베이스를 매핑하기 위해 구축된 방식)으로 실행하고 결과를 다시 공급하여 루프를 구동합니다. 이것이 바로 이 도구가 안전하게 사용될 수 있는 이유입니다.

사용 시기

• "이 데이터베이스 매핑" / "이 저장 프로시저/테이블/뷰의 의존성 그래프를 구축해 줘."
• "Orders를 참조하는 것은 무엇인가요?" / "proc_x가 실제로 접촉하는 것은 무엇인가요?"
• "이 테이블 주변의 전체 폐쇄(closure)를 찾아줘": 더 이상 매달린 것이 없을 때까지 모든 전이적 의존성.
• "데이터베이스에 직접 연결할 수 없습니다. 쿼리를 내보내면 제가 실행하겠습니다." 또는 "DBA에게 보내주세요."
• 레거시 스키마를 문서화/이해할 때 (아무도 무엇이 무엇에 의존하는지 모르는 경우).

사용하지 말아야 할 경우: 애플리케이션 SQL 작성, 데이터나 스키마 변경(이 스킬은 읽기 전용입니다. 가드레일 참조), 데이터베이스 변경이 필요한 모든 경우.

작동 방식 (계약)

엔진은 방언에 구애받지 않습니다. 방언별 단계는 .sql을 의존성 *사실(facts)*로 파싱하는 것뿐입니다(단일 메서드 IDialectExtractor 뒤에 위치). 다른 모든 것은 방언 중립적입니다: 그래프 어셈블리, 프론티어, 스파이더 루프, 연결 요소 폐쇄 감사, 계보(lineage), viz.

루프는 방언이나 데이터베이스에 관계없이 항상 동일한 형태입니다:

1. seed / round 출력 디렉터리에 읽기 전용 .sql 쿼리 파일을 내보냅니다.
2. 당신이 해당 쿼리를 데이터베이스에 대해 실행하고(어댑터 단계) 각 결과를 CSV로 저장합니다.
3. absorb CSⅤ를 .sql로 코퍼스(corpus)에 다시 접습니다.
4. round 다시 추출하고, 그래프 + HTML 시각화를 작성하며, 다음 풀(pull) 쿼리를 준비하거나 폐쇄를 보고합니다.
5. 프론티어가 비어 있고 그래프가 하나의 연결 요소가 될 때까지 반복합니다.

먼저: 실행만 하지 말고 설치하세요 (일회성)

이 파일을 원시로 가져왔거나(fetch .../SKILL.md를 붙여넣고 따르는 경우) 스킬 디렉터리에 없는 체크아웃에서 가져온 경우, 사용하기 전에 설치하고, 리포지토리를 스킬 디렉터리에 클론한 다음 설치된 복사본에서 계속하십시오:

git clone https://github.com/royashbrook/sql-spider ~/.claude/skills/sql-spider   # Claude Code
# 다른 하니스: 스킬이 자동으로 발견되는 위치에 클론하십시오.

그런 다음 사용자에게 설치했다고 알리십시오. 차이는 중요합니다: 현재 위치에서 실행(또는 원시 가져오기)은 오늘 작동하고 내일은 잊혀집니다. 설치하면 모든 미래 세션이 스스로 이 기능을 발견합니다. "이 도구 사용"은 설치를 포함하는 것으로 취급하십시오.

graphify 페어링(6단계)에도 동일한 규칙이 적용됩니다: graphify 설치는 두 가지 명령입니다(바이너리의 경우 uv tool install graphifyy, 그런 다음 graphify의 자체 스킬을 등록하기 위해 graphify install --platform <your harness>). 바이너리만 설치하는 경우가 가장 흔한 실수입니다. 둘 다 수행하십시오.

0단계: 한 번 빌드하기 (최초 사용 시 빌드)

이 스킬은 .NET 소스 코드를 제공하며 바이너리는 제공하지 않습니다. 첫 번째 호출 시 빌드됩니다. 이후 호출은 빌드를 재사용합니다. .NET 10 SDK가 필요합니다(dotnet --version; 없으면 설치: macOS의 경우 brew install dotnet, 다른 경우는 배포판 패키지, 또는 https://dot.net 참조).

SKILL_DIR을 이 파일이 포함된 디렉터리의 절대 경로로 설정한 다음 하나의 명령을 정의하십시오:

SKILL_DIR="<이 스킬 디렉터리의 절대 경로>"
spider() { dotnet run -c Release --project "$SKILL_DIR" -- "$@"; }

첫 번째 spider ... 호출은 컴파일됩니다(몇 초 소요, ScriptDom + SqlParserCS 복원). 이후 모든 호출은 빠릅니다. 실제 데이터베이스를 다루기 전에 번들된 예제로 정상 작동을 확인하십시오:

spider extract "$SKILL_DIR/examples/northwind"   # -> 36개 노드, 66개 간선, "하나의 구성 요소, 고아 없음"
spider viz "$SKILL_DIR/examples/northwind/graph.json" && open "$SKILL_DIR/examples/northwind/graph.html"

OK: 단일 연결 구성 요소, 고아 없음이 출력되면 도구가 작동하는 것입니다.

1단계: 어댑터 선택 (데이터베이스에 어떻게 도달할 것인가?)

sql-spider는 쿼리를 내보냅니다. 이를 실행할 무언가가 필요합니다. 시드(seeding) 전에 당신이 어떤 역할을 할지 결정하십시오(전체 레시피는 references/adapters.md에 있음):

• 연결된 SQL 도구 / MCP: 쿼리를 실행하고 행을 반환하는 도구가 있습니다. 내보낸 각 .sql을 실행하고 행을 CSV로 작성합니다. 가장 빠름. 에이전트가 DB에 도달할 수 있을 때 가장 좋음.
• 읽기 전용 쿼리 브리지: .sql 파일을 넣으면 데이터베이스에 대해 실행되고 CSV가 반환되는 작업/스킬입니다(원래 설정인 읽기 액세스 권한이 있는 CI 작업). 내보낸 각 쿼리를 이를 통해 전달하고 CSV를 수집합니다.
• 사용자가 실행: 데이터베이스에 전혀 도달할 수 없습니다. 각 쿼리를 출력하고 사용자가 자신의 클라이언트(SSMS, sqlcmd 등)에서 실행한 다음 CSV를 다시 붙여넣습니다. 가장 느리지만 어디서나 작동하며 잠긴 프로덕션 데이터베이스에 대한 올바른 방법입니다(사용자 또는 DBA가 배치로 실행).

어떤 방식이든 계약은 동일합니다: 내보낸 .sql 입력, CSV 출력. 하나를 선택하고 전체 실행 동안 유지하십시오.

2단계: 작업 디렉터리 설정

스킬 리포지토리를 깨끗하게 유지하기 위해 스킬 디렉터리 외부에서 작업하십시오. 사용자의 프로젝트(또는 임시 디렉터리)에서:

mkdir -p work/corpus work/stage && cd work

corpus/는 누적되는 .sql을 보관합니다(현재까지의 모델). stage/는 이번 라운드의 쿼리와 CSⅤ가 저장되는 곳입니다.

3단계: 루트 객체에서 시드하기

사용자가 관심 있는 루트, 중앙 테이블 또는 프로시저를 선택하십시오. 그것으로부터 콜드 스타트:

spider seed Orders stage/           # 읽기 전용 풀 쿼리를 stage/에 작성

seed는 루트 자체의 정의, 스키마(테이블인 경우), 그리고 그것을 참조하는 모든 것을 가져오는 쿼리를 내보냅니다. 해당 쿼리를 어댑터(1단계)를 통해 실행하고 각 결과를 stage/에 CSV로 저장한 다음 접습니다:

spider absorb stage/*.csv --corpus corpus/

4단계: 폐쇄를 위한 라운드 (한 번에 하나의 검토 가능한 라운드)

spider round corpus/

각 라운드: corpus/를 corpus/graph.json으로 다시 추출하고, corpus/graph.html을 작성하며(열어서 검토), 폐쇄를 보고하거나 다음 풀 쿼리를 corpus/_next/에 준비합니다. 프론티어가 남아 있으면:

# 어댑터를 통해 corpus/_next/*.sql을 실행하고 CSV를 corpus/_next/에 저장한 후:
spider absorb corpus/_next/*.csv --corpus corpus/
spider round corpus/      # 다시

프론티어는 각 라운드마다 줄어듭니다. 기본적으로 한 번에 하나의 라운드를 수행하여 사람이 시각화를 열고 계속 가져올지 결정할 수 있도록 합니다. 특히 프로덕션 환경에서 중요합니다. round가 프론티어가 비었다고 보고할 때까지 계속하십시오.

5단계: 폐쇄

프론티어가 비어 있고 그래프가 하나의 연결 요소이며 고아가 없으면 완료입니다. 폐쇄 감사는 게이트 역할을 합니다. extract는 그래프가 아직 폐쇄되지 않는 한 0이 아닌 종료 코드를 반환하므로 CI에 연결할 수 있습니다.

범위 참고: 노드 ID는 데이터베이스 범위의 베어 네임(스키마 접두사는 생략됨)이므로, 하나의 스파이더 실행은 ONE 데이터베이스를 매핑합니다. 사용자의 질문이 스키마 또는 데이터베이스에 걸쳐 있는 경우, 범위별로 한 번씩 루프를 실행하고, 첫 번째 폐쇄 그래프의 경계 간선(외부를 가리키는 참조)을 다음 스캔의 시드로 사용한 다음, 노드 ID를 기준으로 결과 graph.json 파일을 병합합니다(graphify merge-graphs 또는 작은 json 유니온). 이 전체 시퀀스를 직접 구동할 수 있습니다. 새로운 도구가 필요하지 않습니다.

모든 객체가 간선으로 폐쇄되는 것은 아니며 괜찮습니다: 진정으로 독립적인 객체(앱 전용 함수, 데이터베이스 외부에서만 참조되는 버전/아카이브 테이블)는 오류가 아닌 이유와 함께 보고됩니다. 정직한 불변 조건은 "추출 누락으로 인한 고아 없음"입니다: 노드가 격리된 경우 감사는 그것이 가져올 실제 격차인지 아니면 진정한 독립체인지 알려줍니다.

6단계: 보기 및 (선택 사항) graphify에 전달

이미 뷰어가 있으며 설치가 필요하지 않습니다: spider viz <graph.json>은 자체 포함된 대화형 HTML(힘 기반, 드래그 가능, 종류별 색상)을 작성합니다. 모든 브라우저에서 엽니다. 대부분의 사용 사례에서는 이것으로 충분합니다.

graphify가 설치된 경우, 폐쇄된 그래프를 전달할 것을 제안하십시오. graphify(https://github.com/safishamsi/graphify)는 그래프를 커뮤니티 탐지 및 query / path / explain을 갖춘 쿼리 가능한 지식 그래프로 변환합니다. 에이전트로서 사용 가능한지 확인하고(PATH에 graphify 명령, graphify 스킬, 또는 프로젝트에 기존 graphify-out/ 디렉터리), 있으면 사용자에게 graphify 뷰도 내보낼지 물어보십시오. 설치되어 있지 않으면 설치를 제안하고, 사용자가 동의하면 두 부분 모두 바이너리와 스킬을 설치하십시오(uv tool install graphifyy, 그런 다음 graphify install --platform <your harness>). 두 번째 명령은 graphify가 향후 세션에서 검색 가능하도록 만듭니다. 바이너리만 설치하는 것이 가장 흔한 실수입니다.

--graphify를 사용하고, 네이티브 graph.json을 graphify에 복사하지 마십시오. 네이티브 그래프는 방향성 멀티그래프입니다. raw한 상태로 graphify에 전달하면 충분히 읽히지 않습니다. --graphify 플래그는 별도의 graphify 형식 파일을 작성하고 네이티브 graph.json은 그대로 둡니다:

spider extract corpus/ --graphify     # 네이티브 graph.json과 graphify-out/graph.json을 작성
graphify cluster-only corpus/          # 클러스터링 + 보고   (또는 /graphify 사용)

알아두면 좋은 두 가지 사항으로, 실제 실행에서 배운 것들입니다:

• 관계 어휘(기본적으로 우리 것을 유지). 프로젝션은 기본적으로 sql-spider 자체 관계를 유지합니다(fk / references / writes / calls / join_key). graphify는 이를 잘 수용하며, 읽기와 쓰기 분할은 "이 테이블을 실제로 업데이트하는 것은 무엇인가"에 대한 가장 유용한 신호입니다. --graphify-standard를 추가하면 graphify의 축복된 열거형(references / calls / shares_data_with)으로 축소되며, 여러 데이터베이스를 병합하고 하나의 균일한 어휘를 원할 때 유용합니다.
• 테이블 사용 방법 묻기. query X 대신 graphify explain X를 사용하십시오. 참조되는 테이블은 싱크(간선이 안쪽을 가리킴)이므로, query(바깥쪽 이동)는 테이블 자체만 반환하는 반면, explain은 질문에 답하는 인바운드 간선을 보여줍니다.
• 커뮤니티 이름 지정. 클러스터링은 자리 표시자 레이블(예: "Community 7")을 생성하며, 이름 없는 50개 이상의 클러스터가 있는 그래프는 전달받는 사람이 읽을 수 없습니다. 거의 항상 구성원, 지배적인 테이블 이름 접두사, 허브 객체, 클러스터의 프로시저가 실제로 수행하는 작업(청구, 발송, 급여 등급, 감사)에서 실제 이름을 유추할 수 있습니다. cluster-only 후 각 커뮤니티의 구성원 목록을 읽고 짧은 도메인 기반 레이블로 이름을 바꾸십시오(graphify의 graph.json / 보고서에서 커뮤니티 레이블 편집). 10분의 이름 지정은 소유자가 탐색할 수 있는 그래프와 당신만이 탐색할 수 있는 그래프의 차이를 만듭니다. 제안하십시오. 인간은 동의할 것입니다.

우리의 사용에서 우리는 청구 하위 시스템을 폐쇄 그래프에 매핑하고 "이것에 의존하는 것은 무엇인가"에 대한 답변을 그래프에서 직접 얻었으며, 그래프가 가리키는 하나의 프로시저만 열었습니다. graphify의 자체 문서는 지식 그래프가 제공하는 나머지 이점을 다룹니다. graphify가 설치되지 않은 경우 이 모든 것을 건너뛰십시오. viz는 이미 그래프를 보여주며, sql-spider의 작업은 폐쇄되면 완료됩니다.

가드레일

• 항상 읽기 전용. 내보내는 모든 쿼리는 no-lock/deadlock-victim/set nocount on 안전 프리앰블이 있는 select입니다. 절대 쓰기로 편집하지 마십시오. 이 스킬을 통해 insert / update / delete / merge / DDL을 절대 실행하지 마십시오. 읽기 이외의 것을 구성하는 경우 잘못된 도구를 사용하는 것입니다.
• 프로덕션 환경에서는 속도를 조절하십시오. 프로덕션 데이터베이스에 쿼리 홍수를 자동으로 발사하지 마십시오. 한 번에 하나의 검토 가능한 라운드를 실행하거나, 준비된 쿼리를 사용자/DBA에게 배치로 실행하도록 전달하십시오. 자동 루핑(round가 폐쇄될 때까지)은 어댑터가 안전하게 무인 실행될 수 있고 데이터베이스 소유자가 동의한 경우에만 적절합니다.
• 그래프가 본문보다 안전한 산출물입니다. 의존성 그래프(객체 이름 + 간선)는 지속 가능한 출력입니다. corpus/에 있는 가져온 프로시저 본문은 대상 조직의 내부 로직입니다. 해당 코퍼스를 비공개로 취급하십시오. 그래프를 게시하고 본문은 게시하지 마십시오.

하위 명령어

명령어	하는 일
extract <corpus-dir> [graph.json] [frontier.json] [--dialect tsql|sqlite] [--graphify[=out.json]] [--graphify-standard]	*.sql을 의존성 그래프 + 프론티어 + 감사로 파싱; --graphify는 graphify 형식 그래프도 작성(--graphify-standard는 graphify의 축복된 관계 어휘 사용)
seed <root-object> <outdir>	빈 코퍼스에서 하나의 루트에 대한 콜드 스타트 풀 쿼리
generate <frontier.json> <outdir>	현재 프론티어에 대한 순방향 풀 쿼리
reverse <referencers.csv> <outdir> [--roots a b]	루트를 참조하는 객체의 모듈 정의 가져오기(한 역방향 수준)
absorb <csv...> --corpus <dir>	가져온 CSV를 .sql로 코퍼스에 다시 접기
viz <graph.json> [out.html]	그래프를 하나의 독립형 대화형 HTML 파일로 렌더링
round <corpus-dir> [--dialect ...]	하나의 검토 가능한 스파이더 패스: 추출 → 그래프 + 시각화 → 다음 쿼리 준비(또는 폐쇄 보고)

round는 루프 드라이버입니다. 다른 명령어는 그것이 구성하는 조각들입니다(콜드 스타트를 위해 seed와 함께 직접 호출하거나 generate / reverse로 수동 패스를 위해 호출).

방언

--dialect tsql(기본값)은 Microsoft ScriptDom(완전한 T-SQL 충실도)으로 파싱합니다. --dialect sqlite는 SqlParserCS로 파싱합니다(MySQL/Postgres 등도 포함). 방언을 추가하는 것은 Extractor.Pick에 등록된 IDialectExtractor를 구현하는 하나의 작은 클래스입니다. 엔진은 변경되지 않습니다. 전체 설계와 작업된 Northwind 예제는 README.md를 참조하십시오.