- PostgreSQL의 연결/백엔드/공유 메모리/WAL/스토리지/체크포인트/autovacuum/복제를 건물과 구역으로 표현한 3D 교육용 시뮬레이션으로, 각 건물과 애니메이션이 실제 데이터베이스 메커니즘에 대응함
shared_buffers의 clock-sweep 교체, WAL 기록과 플러시, 체크포인트 페이싱, xmin 지평선과 테이블 팽창 등 내부 동작을 느린 시간 척도로 관찰할 수 있도록 수치와 규모를 축소함- 실제 PostgreSQL 코드를 실행하는 에뮬레이터가 아니라 손으로 작성한 모델이며, PostgreSQL 문서와 소스를 기준으로 세 차례 전문 검토와 별도 시각적 감사를 거치고 210개 테스트로 주요 계산과 제한값을 고정함
- 버퍼 부족, 장기 실행 트랜잭션, 체크포인트 폭주,
synchronous_commit=off, 느린 복제 재생 같은 시나리오를 실행해 운영 설정이 지연/팽창/내구성/복제 지연에 미치는 변화를 직접 살펴볼 수 있음 - three.js/TypeScript/Vite로 만든 정적 WebGL2 애플리케이션이며, 향후 실제 WebAssembly PostgreSQL의 쿼리 실행 결과와 계획을 현재의 내부 모델에 연결하는 하이브리드 구조도 가능한 방향으로 검토함
PostgreSQL을 도시로 표현하는 방식
- PGSimCity는 PostgreSQL 내부 구조를 걸어 다니며 탐색할 수 있는 독립적/비상업적 교육용 시각화 프로젝트임
- 중앙 광장은
shared_buffers를 나타내며, 1,024개 페이지 프레임의 높이는 clock-sweepusage_count, 색상은 실제 버퍼 상태를 표현함 - 동쪽의 주황색 구역은 WAL, 광장 아래 굴착지는 데이터 디렉터리, 남쪽 도시는 기본 서버가 전송한 WAL을 조금 늦게 재생하는 대기 서버를 나타냄
- 데이터베이스를 직접 운영해보지 않은 엔지니어가 다음 현상을 이해하도록 설계됨
- 체크포인트가 지연 시간을 급증시키는 이유
- 종료되지 않은 트랜잭션이 테이블 팽창을 지속시키는 방식
synchronous_commit이 커밋 시 어떤 비용을 부과하는지
모델의 정확성과 한계
- PGSimCity는 아직 0.x 단계의 모델이며 PostgreSQL 에뮬레이터가 아님
- PostgreSQL 소스 코드를 실행하지 않음
- 사람이 변화를 볼 수 있도록 수치와 시간 척도를 조정함
- SQL을 파싱하거나 실제 쿼리 결과를 계산하지 않음
- PostgreSQL 동작의 정확성을
postgresql.org/docs와 소스 코드에 대조하는 세 차례 전문 검토를 거쳤으며, 각 발견 사항은 이를 반박하도록 지정된 별도 검토자가 다시 확인함 - 건물 배치/인접 관계/애니메이션이 암묵적으로 만드는 주장도 별도의 감사를 받음
- 210개 테스트가 포함되며 실패한 테스트가 있으면 CI 빌드가 중단됨
- WAL 기반 체크포인트 시작점:
max_wal_size / (1 + checkpoint_completion_target) - 캐시 적중률:
blks_hit / (blks_hit + blks_read) - clock-sweep
usage_count최대값: 5
- WAL 기반 체크포인트 시작점:
- 발견된 오류와 수정 과정은 커밋 기록에 남아 있음
- 터치 조작은 Chrome 모바일 에뮬레이션에서만 검증된 상태임
- 단순화된 동작은 각 구성 요소의 inspector에서 명시함
실제 엔진과 결합할 가능성
- 현재는 clock-sweep가 프레임별로 희생 페이지를 선택하는 과정처럼 PostgreSQL 외부에서 노출되지 않는 내부 단계를 보여주기 위해 직접 작성한 시뮬레이션을 사용함
- PGlite처럼 실제 PostgreSQL을 WebAssembly로 실행하면 쿼리 결과와 실행 계획을 실제 엔진에 맡길 수 있음
- 실제 엔진이 브라우저에서 제공할 수 있는 정보는 catalog,
pg_stat_*뷰,EXPLAIN등 PostgreSQL이 외부로 공개하는 범위에 한정됨 - 실제 실행과 계획이 모델 내부의 움직임을 구동하는 하이브리드 방식도 가능하지만, 확정된 개발 약속이 아닌 향후 방향임
도시의 구역과 구성 요소
- Client sky: 애플리케이션 계층에서 들어오는 연결
- Postmaster: 연결마다 백엔드 프로세스를 생성하지만 사용자 데이터에는 직접 접근하지 않는 감독 프로세스
- Backend row: 16개 백엔드 프로세스이며 조명으로
idle in transaction을 포함한 현재 상태를 표시함 - Shared memory plaza
shared_bufferswal_buffers- ProcArray
- 잠금 테이블
- CLOG
- 버퍼 매핑 테이블
- The excavation: 메모리 영역과 디스크 영역의 경계
- Storage
- 8KiB 페이지로 구성된 heap 파일
- 실제 나무 형태의 B-tree
- TOAST
- FSM
- visibility map
- 운영체제 페이지 캐시
- 디스크
- WAL district: walwriter →
pg_wal세그먼트 → archiver → walsender - Maintenance yard: checkpointer/background writer/autovacuum launcher와 worker
- Standby: walreceiver/WAL을 재생하는 startup 프로세스/두 프로세스 사이의 지연
- Query lab: 선택한 백엔드의 문장을 parse → rewrite → plan → execute 단계로 펼쳐 보여줌
색상과 시각적 의미
- 색상은 장식이 아니라 상태와 메커니즘을 전달함
- WAL: 주황색
- dirty page: 빨간색
- clean page: 파란색
- vacuum: 보라색
- checkpoint: 분홍색
- background writer: 청록색
- replication: 오렌지색
- storage: 초록색
- index: 아쿠아색
- lock: 빨간색
- 구조물은 무광으로, 의미를 가진 요소는 네온으로 표현하며 발광 재질만 bloom 임계값을 넘도록 구성함
직접 실행해볼 시나리오
shared_buffers를 64페이지로 축소usage_count가 무너지고 clock hand가 빠르게 순환함- 제거할 clean page가 부족해지면서 백엔드가 자신의 dirty page를 직접 기록하기 시작함
- Long-running transaction 활성화
- ProcArray의 xmin 지평선이 내려가며 빨간색으로 변함
- autovacuum worker가 계속 순회하지만 정리할 튜플을 제거하지 못함
sessions테이블이 팽창하고 복구되지 않음
- Checkpoint storm 실행
- checkpointer가 가속되고 fsync 단계가 흔들림
- 이후 full-page write가 WAL 구역으로 대량 유입됨
synchronous_commit=off설정- 백엔드가
commit_wait에서 대기하지 않게 됨 - 즉시 응답과 교환한 내구성 조건을 함께 확인할 수 있음
- 백엔드가
- Slow replay 활성화
- 대기 서버의 sent/written/flushed/applied LSN이 서로 벌어짐
- 이 차이는
pg_stat_replication에서 관찰하는 복제 지연에 대응함
G키를 누르면 높이 1.7m의 보행 시점으로 내려가 버퍼와 건물을 눈높이에서 살펴볼 수 있음
탐색과 조작
- 마우스와 터치 조작
- 왼쪽 드래그: 지도를 잡아 움직이듯 이동
- 오른쪽 드래그: 도시 주위를 회전
- 휠: 커서 위치를 기준으로 확대/축소
- 한 손가락: 이동
- 두 손가락: 확대/축소, 회전, 기울기 변경
- 이동 모드
W/A/S/D또는 방향키: 이동Space/E: 상승C/Q: 하강Shift: 빠른 이동Alt: 정밀 이동
- 주요 키
F: 비행/궤도 카메라 전환G: 지상 보행H: 초기 전경으로 복귀T: 도시 전체를 안내하는 14개 장의 투어/또는Ctrl-K: 구성 요소/설정/시나리오 검색?: 키보드 지도와 색상 범례K또는P: 일시 정지/재개,/.: 0.1×~5× 속도 조절1~8: clients/backends/shared buffers/WAL/storage/checkpointer/autovacuum/standby 구역으로 이동
라이선스와 상표
- Apache-2.0 라이선스로 배포됨
- SimCity의 코드/에셋/그림/로고/캐릭터/오디오/게임 콘텐츠를 포함하지 않음
- Electronic Arts 및 PostgreSQL 프로젝트와 제휴/후원/승인 관계가 없는 독립 교육 프로젝트임