PostgreSQL 내부를 3D 도시로 걷는 PGSimCity

PostgreSQL 내부를 3D 도시로 걷는 PGSimCity

IT & AI 뉴스 썸네일

PostgreSQL 서버 안에서 벌어지는 일을 도시의 움직임으로 볼 수 있는 프로젝트가 나왔어요. PGSimCity는 연결부터 버퍼 교체, WAL 기록, 체크포인트, autovacuum, 복제까지 눈에 보이는 건물과 애니메이션으로 바꿔 보여줘요. 1

핵심 요약

구분	핵심	왜 볼 만한가요
교육 방식	PostgreSQL 내부 구조를 탐험 가능한 3D 도시로 표현해요	문서의 추상적인 개념을 공간과 움직임으로 연결할 수 있어요
관찰 대상	shared_buffers, WAL, 체크포인트, vacuum, 복제 지연을 느린 속도로 보여줘요	설정 하나가 지연과 테이블 팽창에 미치는 영향을 비교하기 쉬워요
정확성 범위	실제 PostgreSQL을 실행하지 않는 수작업 시뮬레이션이에요	210개 테스트와 검토 기록이 있지만 운영 수치를 재현하는 도구는 아니에요
구현 방식	three.js, TypeScript, Vite로 만든 정적 WebGL2 앱이에요	설치 없이 브라우저에서 열고 소스 코드도 확인할 수 있어요

1. 데이터베이스 문서를 도시의 움직임으로 바꿨어요

PostgreSQL의 내부 구조는 문서만 읽으면 각 요소가 어떻게 이어지는지 잡기 어려워요. `shared_buffers`, WAL, 체크포인트, vacuum을 따로 이해해도 한 번의 쿼리가 이 경로를 어떻게 통과하는지는 머릿속에서 다시 조립해야 해요. PGSimCity는 이 관계를 도시 배치로 바꿨어요. 중앙 광장은 공유 버퍼, 동쪽 구역은 WAL, 지하 굴착지는 스토리지, 남쪽 도시는 대기 서버를 나타내요. 2

공유 버퍼 광장에는 1,024개 페이지 프레임이 놓여 있어요. 프레임 높이는 clock-sweep의 `usage_count`와 연결되고, 색은 clean page와 dirty page 같은 상태를 구분해요. 백엔드 프로세스가 페이지를 읽고 수정하면 버퍼와 WAL 구역의 움직임이 함께 달라져요. PostgreSQL의 부품 목록을 외우는 대신 데이터가 이동하는 순서를 따라갈 수 있는 셈이에요.

728x90

직접 바꿔 볼 설정도 구체적이에요. 버퍼를 64페이지로 줄이면 캐시 적중률이 떨어지고 스토리지 읽기가 늘어나는 과정을 볼 수 있어요. 장기 실행 트랜잭션을 켜면 `xmin` 지평선이 고정돼 dead tuple 정리가 늦어져요. 체크포인트 폭주, 느린 복제 재생, `synchronous_commit=off`도 별도 시나리오로 제공해요. 숫자를 읽는 데서 끝나지 않고 설정 변경 전후의 움직임을 비교할 수 있어요.

시뮬레이션의 한계는 분명해요

PGSimCity는 PostgreSQL 바이너리나 실제 쿼리 엔진을 실행하는 에뮬레이터가 아니에요. 교육을 위해 규모와 시간을 줄인 수작업 모델이에요. 실제 서버의 처리량이나 장애 시간을 예측하는 벤치마크로 쓰면 안 돼요.

프로젝트는 단순화한 모델이 엉뚱한 설명으로 굳어지는 문제도 다뤘어요. PostgreSQL 문서와 소스를 기준으로 세 차례 기술 검토를 거쳤고, 건물의 위치와 애니메이션이 만드는 시각적 주장도 따로 점검했어요. 주요 계산과 제한값은 210개 테스트로 고정했어요. 그래도 현재 버전은 0.x 단계예요. 학습용 지도와 운영 환경의 관측 도구를 구분해서 봐야 해요. 3

브라우저에서 바로 살펴볼 수 있어요

앱은 three.js, TypeScript, Vite로 만들었고 WebGL2를 지원하는 브라우저에서 실행돼요. 별도 서버나 데이터베이스 연결이 필요 없는 정적 애플리케이션이에요. Guided Tour로 주요 구역을 순서대로 보거나, 시나리오를 고른 뒤 재생 속도를 0.1배까지 낮출 수 있어요. Source 링크에서는 구현과 테스트도 확인할 수 있어요.

향후 실제 PostgreSQL을 WebAssembly로 실행하는 PGlite 같은 엔진과 결합할 여지도 언급돼요. 실제 엔진이 쿼리 결과와 실행 계획을 맡고, 지금의 모델이 내부 움직임을 설명하는 방식이에요. 다만 확정된 개발 일정은 아니에요. 현재 프로젝트의 가치는 실제 실행 재현보다 PostgreSQL 내부 개념 사이의 관계를 한 화면에서 익히는 데 있어요.

왜 중요한가요

데이터베이스 장애를 다룰 때 `shared_buffers`나 autovacuum 설정값만 외우면 원인과 결과를 연결하기 어려워요. PGSimCity에서는 버퍼 압박이 스토리지 읽기로 이어지고, 긴 트랜잭션이 vacuum을 막아 테이블 팽창을 키우는 흐름을 같은 공간에서 볼 수 있어요. 입문자는 용어 사이의 관계를 익힐 수 있고, 경험이 있는 개발자는 팀 교육 때 공통 그림으로 활용할 수 있어요. 2

가장 유용한 사용법은 시나리오 하나를 고른 뒤 PostgreSQL 공식 문서와 함께 비교하는 거예요. 도시의 애니메이션으로 흐름을 먼저 확인하고, WAL이나 MVCC의 세부 규칙은 문서와 소스에서 다시 검증하면 좋아요. 시각화는 복잡한 시스템을 이해하는 출발점이에요. 운영 판단과 성능 튜닝은 실제 서버의 통계, 로그, 실행 계획을 근거로 해야 해요.

참고 자료

1. PGSimCity - PostgreSQL의 작동 방식을 탐험 가능한 3D 도시로 시각화 — GeekNews
2. PGSimCity · How PostgreSQL Works, in 3D — PGSimCity
3. NikolayS/PGSimCity — GitHub