---
name: sqlalchemy-mysql-tuning-skill
description: SQLAlchemy + MySQL 성능 튜닝 스킬. SQLAlchemy(Python) 환경에서 MySQL 쿼리가 느린 경우, N+1 문제 해결, EXPLAIN 분석, 인덱스 설계, Eager Loading 전략, 배치 처리, 커넥션 풀 관리 등 모든 SQLAlchemy+MySQL 성능 관련 작업에 사용한다. "N+1 쿼리가 발생해요", "SQLAlchemy 쿼리가 느려요", "joinedload vs selectinload", "bulk_insert_mappings 사용법", "커넥션 풀 설정", "세션 관리" 등의 요청에 이 스킬을 사용할 것.
---

# SQLAlchemy MySQL 성능 튜닝 스킬

## 개요

이 스킬은 SQLAlchemy (Python) 환경에서 MySQL 쿼리 성능 문제를 진단하고 해결하는 데 필요한 레퍼런스를 제공한다. 사용자의 요청에 따라 아래 레퍼런스 파일 중 필요한 것만 선택적으로 읽어서 활용한다.

## 레퍼런스 파일 구조

| 파일 | 내용 | 이런 경우 읽을 것 |
|------|------|-------------------|
| `reference/01-explain-logging.md` | SQL 로깅 및 EXPLAIN 실행 | 실행계획 확인, echo 설정, 슬로우쿼리 이벤트 리스너 |
| `reference/02-index.md` | 모델 인덱스 선언 및 커버링 인덱스 | Index 클래스, __table_args__, 컬럼 제한 조회 |
| `reference/03-n-plus-one.md` | N+1 문제 해결 | joinedload, selectinload, subqueryload, 컬럼 지정 로드 |
| `reference/04-query-patterns.md` | 실전 쿼리 튜닝 패턴 | 좌변 가공 방지, 형변환 방지, 서브쿼리→JOIN, Keyset 페이징, 대량 DML, 세션 관리 |
| `reference/05-orm-pitfalls.md` | SQLAlchemy 특유 주의사항 | lazy="select" 기본값, pool_recycle, expire_on_commit |
| `reference/06-checklist.md` | 튜닝 체크리스트 | 종합 진단, 전체 점검 |

## 사용 흐름

1. 사용자의 요청을 파악한다
2. 관련된 레퍼런스 파일을 `view` 도구로 읽는다 (여러 파일이 필요하면 복수 로드)
3. 레퍼런스의 내용을 바탕으로 구체적인 진단과 해결책을 제시한다

## 핵심 원칙

- **echo=True로 SQL 확인**: 개발 시 항상 실행 쿼리를 확인한다
- **N+1을 항상 경계**: joinedload/selectinload로 명시적 로딩
- **필요 컬럼만 select**: `select(Model)` 대신 `select(Model.col1, Model.col2)`
- **커넥션 풀 관리**: pool_recycle, pool_pre_ping 설정 필수
- **세션을 짧게**: `with` 문으로 세션 범위를 최소화

## 빠른 진단 가이드

사용자가 "SQLAlchemy 쿼리가 느려요" 라고 말하면, 이 순서로 진단한다:

```
1. SQL 로깅 켜기 → 01-explain-logging.md
   - echo=True로 실제 쿼리 확인
   - 이벤트 리스너로 슬로우 쿼리 감지

2. N+1 문제인가? → 03-n-plus-one.md
   - lazy="select" 기본값 확인
   - joinedload / selectinload 적용

3. 인덱스 문제인가? → 02-index.md
   - Index 선언 확인
   - 커버링 인덱스 / 컬럼 제한 조회

4. 쿼리 패턴 문제인가? → 04-query-patterns.md
   - 좌변 함수? 형변환? OFFSET 페이징?

5. SQLAlchemy 특유 함정인가? → 05-orm-pitfalls.md
   - pool_recycle? expire_on_commit? 세션 장기 보유?
```