postgres-performance

Postgres Performance

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Sahip Agent

database-optimizer — ORM N+1 için backend-reviewer'a delege.

Ne Zaman Kullanılır

• Endpoint p99 yüksek
• DB CPU/IO satüre
• Migration prod'a girmeden önce
• Yeni feature query plan kontrolü

Workflow

1. Tanı
   • pg_stat_statements top: total_exec_time, calls, mean_exec_time
   • pg_stat_activity: active query, wait_event
   • pg_locks join pg_stat_activity -> blocker tespit
   • pg_stat_user_indexes: idx_scan = 0 olanlar (kullanılmayan index)
   • pg_stat_user_tables: seq_scan vs idx_scan oranı
2. Plan oku
   • EXPLAIN (ANALYZE, BUFFERS, VERBOSE) <query>
   • Seq scan büyük tabloda? Filter selectivity?
   • Sort: external merge -> work_mem yetmedi
   • Nested loop high outer rows -> bad join order
   • Hash join build/probe row mismatch
3. Optimize
   • Index: B-tree, partial, expression, GIN/GiST text/jsonb
   • Rewrite: keyset pagination, EXISTS vs IN, LATERAL, window fn
   • Statistics: ANALYZE <table> veya default_statistics_target
   • Config: work_mem session-level, shared_buffers
4. Migration güvenliği
   • CREATE INDEX CONCURRENTLY (lock değil)
   • ALTER TABLE ADD COLUMN NULL + backfill batch + SET NOT NULL
   • Lock bekleme: lock_timeout set + retry

Checklist

• pg_stat_statements aktif
• Yavaş query log threshold (log_min_duration_statement)
• EXPLAIN ANALYZE plan kanıtı
• Index gerçekten kullanılıyor mu (pg_stat_user_indexes)
• N+1 ORM tarafında (eager load)
• Connection pool size + idle timeout
• Replica lag (read split varsa)
• VACUUM/ANALYZE schedule

Antipattern

• SELECT * prod kod
• WHERE LOWER(col) = $1 index'siz
• Big OFFSET (10k+) pagination
• Function in WHERE (WHERE date_trunc('day', x) = ...) — expression index yoksa
• IN (subquery) çok büyük sub -> JOIN tercih
• Migration'da ALTER TABLE ADD COLUMN NOT NULL DEFAULT ... büyük tabloda (lock tüm tablo, eski PG'de rewrite)
• App user superuser

Örnek Agent Davranışı

User: /orders endpoint p99 1.2s
Agent:
1. pg_stat_statements top 5 -> ORDER BY mean_exec_time
2. SELECT ... FROM orders JOIN users ON ... WHERE u.email = $1
3. EXPLAIN ANALYZE -> Seq Scan on users (2.1M rows)
4. \d users -> email kolonunda index yok
5. Çözüm: CREATE INDEX CONCURRENTLY ix_users_email ON users (email);
6. Build süresi ~30s tahmin, lock yok
7. Onay, çalıştır, query yeniden ölç -> 12ms

Çıktı Formatı

# Postgres Perf: <query/feature>

## Plan Özeti
## Bottleneck
## Önerilen index/rewrite
## Beklenen kazanım
## Risk