refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,248 @@
|
||||
---
|
||||
id: db-vacuum-autovacuum
|
||||
title: Vacuum / Autovacuum — Bloat / Wraparound 방지
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [database, postgres, vacuum, vibe-coding]
|
||||
tech_stack: { language: "Postgres", applicable_to: ["Backend"] }
|
||||
applied_in: []
|
||||
aliases: [VACUUM, autovacuum, bloat, dead tuple, transaction wraparound, freeze]
|
||||
---
|
||||
|
||||
# Vacuum / Autovacuum
|
||||
|
||||
> Postgres MVCC = UPDATE/DELETE 가 dead tuple 생성. **VACUUM 이 정리**. Autovacuum 자동 — 그러나 큰 테이블 / write 많을 때 manual 필요. Bloat / wraparound 위험.
|
||||
|
||||
## 📖 핵심 개념
|
||||
- Dead tuple: 삭제 / 업데이트 된 row.
|
||||
- Bloat: dead tuple 누적 → 테이블 거대.
|
||||
- VACUUM: dead tuple 마킹 + 재사용.
|
||||
- VACUUM FULL: 테이블 rewrite (lock).
|
||||
- ANALYZE: 통계 업데이트.
|
||||
|
||||
## 💻 코드 패턴
|
||||
|
||||
### Autovacuum 기본
|
||||
```
|
||||
default 활성. 각 테이블 별:
|
||||
- 50 row + 20% 변경 → autovacuum
|
||||
- 50 row + 10% 변경 → autoanalyze
|
||||
```
|
||||
|
||||
### 큰 테이블 = autovacuum 안 따라옴
|
||||
```
|
||||
1억 row × 20% = 2천만 → autovacuum 한 번에 큰 cost
|
||||
→ 자주 작게 하라.
|
||||
```
|
||||
|
||||
```sql
|
||||
ALTER TABLE orders SET (
|
||||
autovacuum_vacuum_scale_factor = 0.05, -- 5% 마다 (default 20%)
|
||||
autovacuum_analyze_scale_factor = 0.02,
|
||||
autovacuum_vacuum_cost_limit = 2000, -- I/O cost limit ↑
|
||||
);
|
||||
```
|
||||
|
||||
### 수동 VACUUM
|
||||
```sql
|
||||
VACUUM (ANALYZE, VERBOSE) orders;
|
||||
-- Bloat 정리 + 통계 + log
|
||||
|
||||
-- Concurrent (lock 적음)
|
||||
VACUUM (ANALYZE) orders; -- 이미 concurrent default
|
||||
|
||||
-- Full (lock 큼 — 잘 안 씀)
|
||||
VACUUM FULL orders; -- 테이블 lock + rewrite
|
||||
```
|
||||
|
||||
### Bloat 측정
|
||||
```sql
|
||||
SELECT
|
||||
schemaname, relname,
|
||||
n_live_tup, n_dead_tup,
|
||||
round(100.0 * n_dead_tup / nullif(n_live_tup + n_dead_tup, 0), 2) AS dead_pct,
|
||||
last_vacuum, last_autovacuum
|
||||
FROM pg_stat_user_tables
|
||||
ORDER BY n_dead_tup DESC LIMIT 20;
|
||||
```
|
||||
|
||||
→ dead_pct > 20% = vacuum 필요.
|
||||
|
||||
### pgstattuple (정확한 bloat)
|
||||
```sql
|
||||
CREATE EXTENSION pgstattuple;
|
||||
SELECT * FROM pgstattuple('orders');
|
||||
-- tuple_count, dead_tuple_count, free_space
|
||||
```
|
||||
|
||||
### Index bloat
|
||||
```sql
|
||||
CREATE EXTENSION pgstattuple;
|
||||
SELECT * FROM pgstatindex('orders_pkey');
|
||||
-- index_size, leaf_fragmentation
|
||||
```
|
||||
|
||||
→ Index bloat → REINDEX.
|
||||
|
||||
### REINDEX (CONCURRENTLY)
|
||||
```sql
|
||||
REINDEX INDEX CONCURRENTLY orders_pkey;
|
||||
-- lock 없이 새 인덱스 빌드 + swap
|
||||
```
|
||||
|
||||
### pg_repack (extension)
|
||||
```bash
|
||||
pg_repack -d mydb -t orders
|
||||
# Online table rewrite — bloat 제거 lock 없이
|
||||
```
|
||||
|
||||
→ VACUUM FULL 의 zero-downtime 대안.
|
||||
|
||||
### Transaction wraparound (위험)
|
||||
```
|
||||
Postgres = 32-bit transaction ID. 2B → wrap.
|
||||
→ 모든 row 의 xmin 이 frozen 안 되면 — DB freeze.
|
||||
|
||||
Autovacuum 자동 freeze. but very busy DB 일 때 추적 필요.
|
||||
```
|
||||
|
||||
```sql
|
||||
-- 가장 오래된 frozen 까지의 거리
|
||||
SELECT
|
||||
datname,
|
||||
age(datfrozenxid) AS xid_age,
|
||||
2147483647 - age(datfrozenxid) AS remaining
|
||||
FROM pg_database
|
||||
ORDER BY age(datfrozenxid) DESC;
|
||||
```
|
||||
|
||||
→ 200M+ = 주의. 1.5B = 위험. 2B = freeze.
|
||||
|
||||
```sql
|
||||
-- 명시 freeze
|
||||
VACUUM FREEZE orders;
|
||||
```
|
||||
|
||||
### Long-running transaction = autovacuum 차단
|
||||
```sql
|
||||
-- 오래된 transaction
|
||||
SELECT pid, usename, query, state, age(NOW(), query_start) AS age
|
||||
FROM pg_stat_activity
|
||||
WHERE state != 'idle'
|
||||
ORDER BY query_start;
|
||||
```
|
||||
|
||||
→ 30분+ = 의심. 2시간+ = autovacuum 차단.
|
||||
|
||||
```ts
|
||||
// App 에서 transaction 짧게
|
||||
async function work() {
|
||||
await db.transaction(async (tx) => {
|
||||
// ❌ 안 — fetch 외부 API
|
||||
// const data = await fetch(...);
|
||||
|
||||
// 짧게 — write 만
|
||||
await tx.insert(...);
|
||||
});
|
||||
// 외부 호출 후 commit
|
||||
}
|
||||
```
|
||||
|
||||
### Maintenance window
|
||||
```sql
|
||||
-- Off-peak 시간 더 적극 vacuum
|
||||
ALTER TABLE big_table SET (
|
||||
autovacuum_vacuum_cost_delay = 0 -- 빠르게
|
||||
);
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```sql
|
||||
-- Autovacuum 진행
|
||||
SELECT pid, datname, query, query_start
|
||||
FROM pg_stat_activity
|
||||
WHERE query LIKE 'autovacuum:%';
|
||||
|
||||
-- 횟수
|
||||
SELECT relname, n_tup_ins, n_tup_upd, n_tup_del,
|
||||
autovacuum_count, autoanalyze_count,
|
||||
last_autovacuum, last_autoanalyze
|
||||
FROM pg_stat_user_tables
|
||||
ORDER BY n_tup_upd + n_tup_del DESC LIMIT 20;
|
||||
```
|
||||
|
||||
### Tunables
|
||||
```
|
||||
autovacuum_max_workers = 3 -- worker 수
|
||||
autovacuum_naptime = 1min -- check 주기
|
||||
maintenance_work_mem = 256MB -- vacuum 메모리
|
||||
|
||||
# 큰 cluster:
|
||||
autovacuum_max_workers = 6
|
||||
maintenance_work_mem = 2GB
|
||||
```
|
||||
|
||||
### HOT update (no index update)
|
||||
```sql
|
||||
-- Index 컬럼 안 변경 + page 안 free space 있음 → HOT update
|
||||
-- → bloat 적음 + 빠름
|
||||
```
|
||||
|
||||
```sql
|
||||
-- 측정
|
||||
SELECT relname, n_tup_upd, n_tup_hot_upd,
|
||||
round(100.0 * n_tup_hot_upd / nullif(n_tup_upd, 0), 2) AS hot_pct
|
||||
FROM pg_stat_user_tables ORDER BY n_tup_upd DESC LIMIT 20;
|
||||
```
|
||||
|
||||
→ hot_pct 높음 = 좋음.
|
||||
|
||||
```sql
|
||||
-- Fillfactor (page 안 free space 남기기)
|
||||
ALTER TABLE orders SET (fillfactor = 80); -- 20% 비움
|
||||
```
|
||||
|
||||
### Alarm
|
||||
```yaml
|
||||
- alert: HighDeadTuples
|
||||
expr: pg_stat_user_tables_n_dead_tup / pg_stat_user_tables_n_live_tup > 0.3
|
||||
for: 1h
|
||||
|
||||
- alert: TransactionWraparound
|
||||
expr: pg_database_xid_age > 1500000000
|
||||
for: 10m
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
| 상황 | 액션 |
|
||||
|---|---|
|
||||
| Dead pct > 20% | Manual VACUUM |
|
||||
| Bloat 큼 | pg_repack |
|
||||
| Index bloat | REINDEX CONCURRENTLY |
|
||||
| Wraparound 임박 | VACUUM FREEZE |
|
||||
| Long transaction | App fix — short tx |
|
||||
| 큰 write 테이블 | scale_factor 낮게 |
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **VACUUM FULL prod**: lock — table 못 사용. pg_repack.
|
||||
- **Autovacuum 끄기**: bloat 폭발.
|
||||
- **Long transaction (30분+)**: autovacuum 차단.
|
||||
- **모든 table 같은 setting**: 큰 vs 작은 다름.
|
||||
- **Wraparound 모니터링 X**: freeze 위험.
|
||||
- **REINDEX 직접 prod**: lock. CONCURRENTLY.
|
||||
- **Fillfactor 100% prod**: HOT update X — bloat.
|
||||
|
||||
## 🤖 LLM 활용 힌트
|
||||
- 큰 table = scale_factor 낮게 + cost limit 높게.
|
||||
- Long transaction = 적.
|
||||
- pg_repack 가 zero-downtime maintenance.
|
||||
- Wraparound + bloat alarm 항상.
|
||||
|
||||
## 🔗 관련 문서
|
||||
- [[DB_Postgres_EXPLAIN]]
|
||||
- [[DB_Query_Optimization]]
|
||||
- [[DB_Lock_Analysis]]
|
||||
Reference in New Issue
Block a user