English {#english}
MariaDB 10.6 Performance Tuning Plan (my.cnf)
Purpose: Consolidate MariaDB tuning for Frappe/ERPNext. Under Google SRE resource-efficiency principles, only my.cnf options suitable for 8–16GB RAM are listed.
No code generation — parameters, rationale, trade-offs only.
References: saas-db-separation-and-scaling-plan; docker-hub-stack-ansible-deploy-plan §7; cloudflare-orchestration-and-gtape-backup-plan (R2 backup, binlog, PITR).
1. Scope and assumptions
Target: MariaDB 10.6 (LTS, well-tested with Frappe). Memory: 8–16GB DB server; 60–70% of RAM for InnoDB. Workload: Heavy INSERTs and complex JOINs (Frappe).
2–5. Parameters, operations, alignment, summary
- §2.1 Memory: innodb_buffer_pool_size 4G (8GB) / 8–10G (16GB); innodb_buffer_pool_instances 4 (or per-core).
- §2.2 Write/durability: innodb_flush_log_at_trx_commit 2 (performance; up to ~1s loss on power failure — must pair with R2 backup and binlog). innodb_log_file_size 1G; innodb_flush_method O_DIRECT.
- §2.3 Connections: max_connections 500; innodb_thread_concurrency 0; table_open_cache 2000.
- §2.4 Frappe: character-set-server utf8mb4, collation-server utf8mb4_unicode_ci; character-set-client-handshake FALSE.
- §3: With flush_log=2, daily snapshots and binlog to R2 are required. Binlog already in Ansible mariadb_server (log-bin, binlog_format=ROW). Use MySQLTuner for buffer-pool hit rate and connections.
- §4: mariadb_server role: pass params via command or mount my.cnf; add my.cnf.j2 template or defaults.
- §5: Summary: buffer pool 60–70%, instances, flush/log size/O_DIRECT, max_connections, table_open_cache, utf8mb4; flush_log_at_trx_commit=2 only with R2 + binlog.
Full tables (§1–§5) and exact wording are in the Korean section below.
한국어 {#korean}
MariaDB 10.6 성능 최적화 기획서 (my.cnf)
목적: Frappe/ERPNext 성능을 결정하는 MariaDB 튜닝 가이드를 정리한다. 구글 SRE의 자원 효율성 원칙에 따라 8GB~16GB RAM 환경에 적용 가능한 my.cnf 최적화 방안만 추출한다.
코드 생성 없음 — 파라미터·근거·트레이드오프만 정리.
참조:
- saas-db-separation-and-scaling-plan.md (DB 서버 역할)
- docker-hub-stack-ansible-deploy-plan.md (§7 다음 단계)
- cloudflare-orchestration-and-gtape-backup-plan.md (R2 백업·Binlog·PITR)
1. 적용 대상·전제
| 항목 | 내용 |
|---|---|
| 대상 | MariaDB 10.6 (Frappe와 가장 긴밀하게 테스트된 LTS). |
| 메모리 | DB 서버 8GB~16GB RAM 환경. 전체 RAM의 60~70%를 InnoDB에 할당하는 것을 전제로 함. |
| 워크로드 | Frappe 특성상 대량 INSERT와 복잡한 JOIN이 빈번. |
2. 핵심 최적화 파라미터 (my.cnf [mysqld])
효율적인 DB 최적화만 추출한 항목이다. 구현 시 Ansible role에서 my.cnf 템플릿 또는 Docker/컨테이너 command/설정 마운트로 반영한다.
2.1 메모리 (가장 중요)
| 파라미터 | 권장값 | 근거 |
|---|---|---|
| innodb_buffer_pool_size | 4G (8GB RAM 서버) / 8G~10G (16GB RAM) | 전체 RAM의 60~70% 할당. Frappe의 핫 데이터 대부분을 메모리에 유지하여 디스크 I/O 감소. |
| innodb_buffer_pool_instances | 4 (또는 코어 수에 맞춤) | 코어당 1개 권장. 단일 래치 병목 완화. |
2.2 쓰기 성능 및 내구성 (Trade-off)
| 파라미터 | 권장값 | 근거 |
|---|---|---|
| innodb_flush_log_at_trx_commit | 2 | 1: 매 트랜잭션마다 디스크 플러시(완전한 안전, 느림). 2: 커밋 시 OS가 플러시 시점을 결정 — 성능 우선. 전원 장애 시 최대 약 1초 분량 데이터 유실 가능. R2 등 오프사이트 백업·Binlog 파이프라인과 반드시 병행 (GTape 원칙). |
| innodb_log_file_size | 1G | 대용량 쓰기 시 로그 파일 확대로 체크포인트·I/O 완화. |
| innodb_flush_method | O_DIRECT | 버퍼 풀과 OS 캐시 이중 캐싱 방지, 메모리·I/O 효율. |
2.3 연결·동시성
| 파라미터 | 권장값 | 근거 |
|---|---|---|
| max_connections | 500 | 동시 접속 수 상한. Frappe 멀티테넌트·워커 수에 맞게 조정. |
| innodb_thread_concurrency | 0 | OS 스케줄러가 동시성 제어. 기본 권장. |
| table_open_cache | 2000 | 열린 테이블 캐시. JOIN·다중 스키마 환경에서 부족 시 성능 저하 방지. |
2.4 Frappe 특화 (문자 집합)
| 파라미터 | 권장값 | 근거 |
|---|---|---|
| character-set-server | utf8mb4 | 이모지·다국어 안전 저장. |
| collation-server | utf8mb4_unicode_ci | Frappe 기본과 동일. |
| character-set-client-handshake | FALSE | 클라이언트가 다른 문자셋을 보내도 서버 설정(utf8mb4)으로 통일. |
3. 운영 원칙 (Principal Engineer 인사이트)
| 항목 | 내용 |
|---|---|
| flush_log_at_trx_commit = 2 사용 시 | 성능은 올라가나 전원 장애 시 미세한 유실 가능. **Cloudflare R2 기반 일별 스냅샷·Binlog 보관(또는 스트리밍)**이 필수이다. cloudflare-orchestration-and-gtape-backup-plan.md §3.2, §3.3, §3.4 참조. |
| Binlog | 현행 Ansible mariadb_server role은 이미 log-bin, binlog_format=ROW 설정(Phase 2 Replica·PITR 대비). Binlog를 R2에 보관하면 시점 복구(PITR) 가능. |
| 성능 모니터링 | my.cnf 적용 후 MySQLTuner 등으로 실제 부하에서 버퍼 풀 히트율(Hit Rate)·연결 수를 주기 점검 권장. |
4. 현재 시스템과의 정합성
| 현행 | 반영 방안 |
|---|---|
| mariadb_server role | MariaDB 컨테이너 기동 시 command로 위 파라미터 전달하거나, my.cnf 파일을 볼륨으로 마운트. 현재는 --log-bin, --binlog-format 등만 command로 전달 중. |
| 구현 시 | role에 my.cnf.j2 템플릿 추가 또는 defaults에 변수(innodb_buffer_pool_size 등) 정의 후 컨테이너에 설정 주입. |
5. 요약
- 8GB~16GB RAM 기준 InnoDB 버퍼 풀 60~70%, buffer_pool_instances, flush 로그·로그 파일 크기·O_DIRECT, max_connections·table_open_cache, utf8mb4 등 효율적인 DB 최적화만 정리함.
- innodb_flush_log_at_trx_commit = 2는 성능 우선 선택이며, **R2 백업·Binlog 보관(또는 스트리밍)**과 반드시 병행한다.