sqlalchemy-mysql-tuning-skill

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? 세션 장기 보유?