쿼리 계획 시각화 도우미

PostgreSQL 확장의 쿼리 계획 시각화 도우미를 사용하여 편집기를 종료하지 않고 PostgreSQL EXPLAIN 출력을 검사합니다. 쿼리 편집기 또는 PostgreSQL 쿼리 결과 패널에서 계획을 생성하거나 편집기에서 기존 JSON 또는 TEXT 계획 출력을 열 수 있습니다. 시각화 도우미는 Visual Studio Code커서에서 동일한 방식으로 실행됩니다.

필수 조건

  • PostgreSQL 확장 이 설치되었습니다.
  • 쿼리 편집기 또는 PostgreSQL 쿼리 결과 패널에서 라이브 계획을 생성하려는 경우 PostgreSQL 서버에 대한 활성 연결입니다.
  • AI 지원 분석을 원하는 경우 선택적 AI 도우미: Visual Studio Code GitHub Copilot 설치하거나 커서에서 기본 제공 AI를 사용합니다.
  • 데이터베이스에 연결하지 않고 저장된 계획을 가져오려는 경우 선택적 EXPLAIN 출력이 편집기에서 이미 열려 있습니다.

플랜을 여는 방법 선택

워크플로와 일치하는 진입점을 사용합니다.

  • 쿼리 편집기: 편집기 도구 모음에서 쿼리 계획 시각화(PostgreSQL) 를 선택합니다. 텍스트를 먼저 선택하지 않으면 확장에서 현재 편집기 콘텐츠를 사용합니다.
  • PostgreSQL 쿼리 결과 패널: 쿼리를 실행한 다음 PostgreSQL 쿼리 결과 패널 도구 모음에서 쿼리 계획 시각화 를 선택하여 결과 집합을 생성한 쿼리를 검사합니다.
  • 가져온 실행 계획: PostgreSQL 실행 계획 출력이 포함된 편집기 탭을 연 다음 명령 팔레트에서 PGSQL: 편집기에서 쿼리 계획 시각화를 실행합니다.

라이브 쿼리에서 계획 생성

  1. 쿼리 편집기에서 검사할 SQL 파일을 엽니다.
  2. 대상 데이터베이스에 연결합니다.
  3. 분석할 문을 선택합니다. 선택 영역을 비워 두면 확장에서 현재 편집기 콘텐츠를 사용합니다.
  4. 편집기 도구 모음에서 쿼리 계획 시각화(PostgreSQL) 를 선택합니다. 먼저 쿼리를 실행한 다음 PostgreSQL 쿼리 결과 패널에서 쿼리 계획 시각화를 선택할 수도 있습니다.
  5. 쿼리 계획 구성에서 원하는 형식과 옵션을 선택한 다음 Enter 키를 누릅니다.
  6. 시각화 도우미에서 계획을 검토합니다.

쿼리 계획 옵션 구성

쿼리 계획 구성 선택기를 사용하면 출력 형식과 EXPLAIN 실행할 옵션을 선택할 수 있습니다.

Option 변경 내용
JSON 시각적 보기에서 가장 잘 작동하는 구조화된 계획 출력을 반환합니다.
TEXT PostgreSQL의 일반 텍스트 EXPLAIN 출력을 반환하고 원본 뷰에서 해당 원본을 유지합니다.
분석 쿼리를 실행하고 실제 런타임 통계를 포함합니다.
버퍼 버퍼 사용 통계를 추가합니다. 자동으로 선택하면 ANALYZE가 활성화됩니다.
타이밍 실제 타이밍 데이터를 추가합니다. 자동으로 선택하면 ANALYZE가 활성화됩니다.
WAL WAL 사용 통계를 추가합니다. 자동으로 선택하면 ANALYZE가 활성화됩니다.
자세한 정보 표시 스키마 및 열 정보와 같은 추가 출력 세부 정보를 추가합니다.
비용 예상 시작 및 총 비용 값을 포함합니다.
설정 기본값과 다른 Planner 설정을 포함합니다.

Caution

EXPLAIN ANALYZE 는 쿼리를 실행합니다. 문이 INSERT, UPDATE, DELETE, 또는 TRUNCATE와 같이 데이터를 수정하는 경우, 확장 프로그램은 계속 진행하기 전에 확인 메시지를 표시합니다.

편집기에서 저장된 계획 열기

  1. JSON 또는 TEXT 형식의 PostgreSQL EXPLAIN 출력이 포함된 편집기 탭을 엽니다.
  2. 명령 팔레트를 엽니다(Ctrl+Shift+P).
  3. PGSQL 실행: 편집기에서 쿼리 계획 시각화
  4. 시각화 도우미에서 가져온 계획을 검토합니다.

이 워크플로에는 활성 데이터베이스 연결이 필요하지 않습니다. 이 명령은 현재 편집기 내용을 읽으므로, 복사한 계획 출력 결과, 저장된 .json 또는 .txt 파일, 또는 스크래치 편집기에 붙여 넣은 계획 텍스트와 함께 사용할 수 있습니다.

보기 간 전환

도구 모음의 뷰 선택기를 사용하여 트리 뷰, Icicle 뷰, 테이블 뷰 및 원본 뷰 간에 이동합니다.

트리 구조 보기

트리 뷰 는 기본적으로 열립니다. 실행 계획의 노드별 다이어그램을 원하는 경우 사용합니다.

  • 확대/축소 컨트롤을 사용하여 확대하거나 축소하고, 보기를 재설정하거나 도면을 창에 맞출 수 있습니다.
  • 옵션 패널을 사용하여 비용이 많이 들거나 비정상적인 노드를 강조 표시하는 레이아웃 방향과 색 메트릭을 변경할 수 있습니다.
  • 노드를 선택하여 세부 정보 패널을 엽니다.
  • 노드를 마우스 오른쪽 단추로 클릭하여 다른 보기로 이동하거나 AI 도우미를 사용하여 해당 노드를 분석합니다.

표 보기

여러 노드를 한 번에 정렬, 검색 및 비교하려는 경우 테이블 뷰 를 사용합니다.

  • 계획은 접고 펼칠 수 있는 트리가 아니라 정렬 가능한 테이블의 평면 구조로 표시됩니다.
  • 검색 상자는 테이블 뷰에만 나타납니다.
  • 검색은 노드 유형, 관계 이름, 인덱스 이름, 별칭, 필터 텍스트 및 하위 계획 이름과 일치합니다.
  • 미리 설정된 선택기를 사용하여 성능, 예측값, 효율성 또는 I/O에 집중하거나 표시되는 메트릭 열을 사용자 지정합니다.

Icicle 보기

비용, 시간 또는 버퍼 사용량이 집중된 위치에 대한 전체 너비 시각적 요약을 원하는 경우 Icicle View 를 사용합니다.

  • Icicle View는 Tree View 내의 패널이 아니라 별도의 보기입니다.
  • 옵션 패널을 사용하여 사전 설정을 전환하고, 너비 메트릭을 변경하고, 색 메트릭을 변경하고, 지원되는 자체 범위와 전체 범위 간에 전환할 수 있습니다.
  • 블록 위로 마우스를 가져가서 메트릭을 검사하거나 블록을 마우스 오른쪽 단추로 클릭하여 세부 정보를 열거나 다른 보기로 이동합니다.

원본 뷰

원래 계획 출력을 원하는 경우 원본 뷰 를 사용합니다.

  • 트리 모드와 텍스트 모드 간에 전환할 옵션을 선택합니다.
  • 패널은 가져온 소스 또는 생성된 원본이 JSON인지 텍스트인지를 보여줍니다.
  • 모두 확장 및 모두 축소 는 원본 보기 가 활성화된 동안에만 도구 모음에 나타납니다.
  • 텍스트 모드에서 계획은 읽기 전용 편집기에서 열립니다. 트리 모드에서는 구문 분석된 구조를 접고 펼 수 있는 트리로 확인할 수 있습니다.

언제든지 계획 복사 를 선택하여 현재 계획 원본을 클립보드에 복사합니다. JSON 계획은 서식이 지정된 형식으로 복사되고 TEXT 계획은 원래 원본으로 복사됩니다.

실행 계획 노드 확인

트리 뷰, 테이블 뷰 또는 Icicle 보기에서 노드를 선택하여 세부 정보 패널을 엽니다.

  • 일반적으로 노드 유형, 주요 메트릭 및 계획별 분석 세부 정보를 보여 줍니다.
  • 계획에 버퍼 데이터가 포함되면 I/O가 나타납니다.
  • 노드가 필터, 조인 조건 또는 유사한 조건자를 노출할 때 조건이 나타납니다.

이 패널을 사용하여 예상 작업과 실제 작업을 비교하고, 버퍼가 많은 노드를 검사하고, 계획을 구동하는 조건자를 확인합니다.

AI 도우미를 사용하여 계획 분석

확장에서 현재 계획을 컨텍스트로 사용하여 분석 채팅을 열려면 AI 도우미를 사용합니다.

전체 계획 분석

  1. 시각화 도우미에서 계획을 엽니다.
  2. Copilot 사용하여 분석(또는 커서에서 AI를 사용하여 분석)을 선택합니다.
  3. 분석에 SQL 쿼리 텍스트를 포함할지 여부를 선택합니다.
  4. 에이전트 모드에서 열리는 새 채팅 세션을 검토합니다.

계획이 PGSQL에서 제공된 경우: 편집기에서 쿼리 계획 시각화 및 유용한 SQL 텍스트가 아직 없는 경우 확장은 AI가 더 나은 컨텍스트를 되도록 먼저 쿼리를 입력하라는 메시지를 표시할 수 있습니다.

하나의 노드 분석

  1. 검사할 노드를 마우스 오른쪽 단추로 클릭합니다.
  2. Copilot 사용하여 이 노드 분석을 선택합니다(또는 커서에서 AI를 사용하여 이 노드 분석).
  3. 노드별 분석을 위해 새 에이전트 모드 채팅 세션을 검토합니다.

SQL 텍스트 포함 여부 제어

이 설정은 pgsql.copilot.autoAttachQuery AI 분석을 시작하면 확장에서 SQL 텍스트를 처리하는 방법을 제어합니다.

  • 매번 SQL을 포함할지 여부를 묻습니다.
  • 메시지를 표시하지 않고 항상 SQL 포함
  • SQL 포함 안 함

프롬프트에서 SQL을 포함하거나 제외하도록 선택하면 확장에서 향후 세션에 대한 선택 사항을 기억하도록 제공할 수도 있습니다.

에이전트 모드에서 쿼리 계획 도구 사용

시각화 도구는 현재 계획을 캐시하고 pgsql_query_plan 도구를 통해, 또는 지원되는 호스트에서는 이에 상응하는 MCP를 통해 해당 계획을 AI 도우미에 제공합니다. 이 도구는 다음 작업을 지원합니다.

조치 다음 용도로 사용
get_summary 세부 정보를 자세히 알아보기 전에 계획 전체 요약을 가져옵니다.
get_node ID별로 하나의 노드를 검사합니다.
get_subtree 노드를 하위 항목과 함께 검사합니다.
list_nodes 형식 또는 최소 비용별로 노드를 찾습니다.

시각화 도우미 대신 활성 쿼리에서 AI를 시작하려면 편집기의 AI 쿼리 작업 하위 메뉴에서 쿼리 성능 분석을 사용합니다. 계획을 직접 검사한 다음 정확한 계획을 AI에 전달하려는 경우 시각화 도우미를 사용합니다.

성능 분석을 위한 팁

  • 문을 실행해도 안전한 경우 ANALYZE 를 사용합니다. 예측만으로도 잘못된 행 개수 가정을 숨길 수 있습니다.
  • 예상 행 수와 실제 행 수를 비교하여 부실 통계를 발견하거나 선택성 문제를 필터링합니다.
  • 계획이 크고 검색 또는 병렬 메트릭 비교가 필요한 경우 테이블 뷰 로 전환합니다.
  • 팀 동료와의 문제, 코드 검토 또는 토론에 대한 원시 계획이 필요한 경우 원본 뷰 로 전환합니다.

관련 콘텐츠

  • Last updated on