# DB Index Suggest

> 쿼리와 실행 계획을 분석해 인덱스 추가·개선 방안을 제안한다

- Skill: `gaebalai-claude-code-kit-ko/db-index-suggest` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/db-index-suggest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/db-index-suggest/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/db-index-suggest

---


당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

## 목적

SQL 쿼리, 슬로우 쿼리 로그, 또는 실행 계획(EXPLAIN 결과)을 분석해  
적절한 인덱스 추가·개선 방안을 제안한다.  

불필요한 인덱스의 제거 후보까지 포함해,  
전체 인덱스 전략을 최적화하는 제안을 제공한다.

## 입력

- SQL 쿼리(단일 또는 복수)
- 슬로우 쿼리 로그 파일
- EXPLAIN / EXPLAIN ANALYZE 출력 결과
- 기존 스키마 정의(테이블 구조 및 기존 인덱스 정보)
- 애플리케이션 코드 내 쿼리(ORM 생성 쿼리 포함)

## 절차

### 1. 쿼리 수집 및 분류

1-1. 제공된 쿼리 또는 파일에서 SQL 문을 추출한다  
1-2. 코드베이스에서 쿼리 패턴을 검색한다 (Repository, DAO, Model 계층 등)  
1-3. ORM이 생성하는 쿼리를 추정한다 (N+1 패턴 포함)  
1-4. 쿼리를 유형별로 분류한다 (SELECT / JOIN / 집계 / 서브쿼리 등)  
1-5. 실행 빈도가 높은 쿼리를 우선 분석 대상으로 지정한다  

### 2. 기존 인덱스 점검

2-1. 스키마 정의에서 기존 인덱스를 목록화한다  
2-2. 기본 키 및 유니크 제약에 따른 암묵적 인덱스를 파악한다  
2-3. 외래 키 컬럼에 인덱스가 존재하는지 확인한다  
2-4. 복합 인덱스의 컬럼 순서 및 선택도(카디널리티)를 평가한다  
2-5. 중복·불필요 인덱스 후보를 식별한다  

### 3. 쿼리별 인덱스 분석

3-1. WHERE 절 조건 컬럼과 선택도를 분석한다  
3-2. JOIN 조건에 사용되는 컬럼의 인덱스 존재 여부를 확인한다  
3-3. ORDER BY / GROUP BY 최적화 가능성을 평가한다  
3-4. EXPLAIN 결과가 있다면 type / key / rows / Extra 항목을 분석한다  
3-5. 커버링 인덱스 적용 가능성을 검토한다  
3-6. 부분 인덱스(조건부 인덱스)의 유효성을 평가한다  

### 4. 인덱스 제안 수립

4-1. 신규 인덱스 추가 제안을 작성한다 (컬럼 순서 근거 포함)  
4-2. 기존 인덱스 개선안을 제시한다 (컬럼 추가 또는 순서 변경)  
4-3. 불필요 인덱스 삭제 후보를 제안한다 (쓰기 비용 절감 목적)  
4-4. 복합 인덱스의 최적 컬럼 순서를 결정한다  
      (등가 조건 → 범위 조건 → 정렬 컬럼 순)  
4-5. 각 제안의 기대 효과를 정성적으로 설명한다  

### 5. 트레이드오프 평가

5-1. 인덱스 추가로 인한 쓰기 성능 영향 평가  
5-2. 스토리지 사용량 증가 추정  
5-3. 인덱스 유지 비용(VACUUM, OPTIMIZE 등) 고려  
5-4. 읽기 성능 개선과 쓰기 성능 저하의 균형 판단  
5-5. 워크로드 특성(읽기 중심 / 쓰기 중심)에 따른 조정  

### 6. 구현 계획 수립

6-1. 인덱스 생성 SQL을 작성한다 (가능하면 CONCURRENTLY 포함)  
6-2. 인덱스 생성 권장 실행 순서를 제시한다  
6-3. 효과 측정을 위한 EXPLAIN 쿼리를 준비한다  
6-4. 인덱스 적용 후 검증 절차를 기술한다  

## 출력 형식

```markdown
# 인덱스 제안: [대상 테이블 / 쿼리 요약]

## 분석 요약
| 항목 | 내용 |
|------|------|
| 분석 쿼리 수 | N건 |
| 기존 인덱스 수 | N개 |
| 신규 추가 제안 | N개 |
| 개선 제안 | N개 |
| 삭제 제안 | N개 |

## 기존 인덱스 목록
| 테이블 | 인덱스명 | 컬럼 | 유형 | 평가 |
|--------|----------|-------|------|------|
| `table_name` | `idx_name` | `col1, col2` | BTREE | 유효 / 중복 / 미사용 |

## 신규 인덱스 제안

### 제안 1: [테이블].[인덱스명]
- **대상 쿼리**: `SELECT ... WHERE col1 = ? AND col2 > ?`
- **제안 인덱스**: `(col1, col2)` — 등가 조건을 선두에 배치
- **근거**: col1 필터링 후 col2 범위 스캔 최적화
- **기대 효과**: 풀 테이블 스캔 → 인덱스 범위 스캔 전환
- **쓰기 영향**: INSERT/UPDATE 시 인덱스 갱신 비용 소폭 증가

```sql
-- 인덱스 생성 제안
CREATE INDEX CONCURRENTLY idx_table_col1_col2
  ON table_name (col1, col2);
```

### 제안 2: [커버링 인덱스]
- **대상 쿼리**: `SELECT col1, col2 FROM table WHERE col3 = ?`
- **제안 인덱스**: `(col3) INCLUDE (col1, col2)`
- **근거**: 테이블 접근 없이 인덱스만으로 응답 가능
- **기대 효과**: 랜덤 I/O 대폭 감소

```sql
CREATE INDEX CONCURRENTLY idx_table_covering
  ON table_name (col3) INCLUDE (col1, col2);
```

## 삭제 후보 인덱스
| 인덱스명           | 사유                          | 기대 효과              |
| -------------- | --------------------------- | ------------------ |
| `idx_old_name` | `idx_new_name`에 포함되는 중복 인덱스 | 쓰기 성능 개선 및 스토리지 절감 |

## 트레이드오프 분석
| 제안  | 읽기 개선 | 쓰기 영향 | 스토리지 증가 | 권장도    |
| --- | ----- | ----- | ------- | ------ |
| 제안1 | 높음    | 낮음    | 약 N MB  | 강력 권장  |
| 제안2 | 중간    | 중간    | 약 N MB  | 조건부 권장 |

## 효과 측정 쿼리
```sql
-- 적용 전/후 실행 계획 비교
EXPLAIN ANALYZE SELECT ... ;
```

## 구현 순서
1. 가장 효과가 높은 인덱스부터 생성
2. 의존 관계가 있는 경우 그 순서를 명시
```

## 안전 주의사항

- **실제 SQL을 실행하지 말 것** — 본 기능은 분석 및 제안 전용이다  
- **운영 데이터베이스에 접속하지 말 것**
- 인덱스 생성 SQL은 제안으로만 작성한다  
- 가능한 경우 `CONCURRENTLY` 옵션 사용을 권장한다 (락 최소화 목적)  
- 대용량 테이블에 대한 인덱스 추가는 점검 시간에 수행할 것을 권장한다  
- 삭제 제안 인덱스는 반드시 쿼리 로그 사용 이력 확인을 전제로 한다  
- 데이터베이스 엔진(MySQL / PostgreSQL / SQLite 등)에 따른 문법 차이를 고려한다  

## 종료 조건

- 모든 대상 쿼리가 분석되었다  
- 기존 인덱스 평가가 완료되었다  
- 각 제안에 근거와 기대 효과가 포함되었다  
- 읽기/쓰기 트레이드오프가 평가되었다  
- 인덱스 생성 SQL이 제시되었다 (실행은 하지 않음)  
- 효과 측정을 위한 EXPLAIN 쿼리가 준비되었다