# PGSimCity - PostgreSQL의 작동 방식을 탐험 가능한 3D 도시로 시각화 > Clean Markdown view of GeekNews topic #31895. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=31895](https://news.hada.io/topic?id=31895) - GeekNews Markdown: [https://news.hada.io/topic/31895.md](https://news.hada.io/topic/31895.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2026-07-28T09:58:03+09:00 - Updated: 2026-07-28T09:58:03+09:00 - Original source: [nikolays.github.io](https://nikolays.github.io/PGSimCity/) - Points: 2 - Comments: 1 ## Topic Body - 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](https://nikolays.github.io/PGSimCity/)는 PostgreSQL 내부 구조를 걸어 다니며 탐색할 수 있는 독립적/비상업적 교육용 시각화 프로젝트임 - 중앙 광장은 `shared_buffers`를 나타내며, 1,024개 페이지 프레임의 높이는 clock-sweep `usage_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 - 발견된 오류와 수정 과정은 커밋 기록에 남아 있음 - 터치 조작은 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_buffers` - `wal_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](https://github.com/NikolayS/PGSimCity/blob/main/LICENSE) 라이선스로 배포됨 - SimCity의 코드/에셋/그림/로고/캐릭터/오디오/게임 콘텐츠를 포함하지 않음 - Electronic Arts 및 PostgreSQL 프로젝트와 제휴/후원/승인 관계가 없는 독립 교육 프로젝트임 ## Comments ### Comment 62499 - Author: neo - Created: 2026-07-28T09:58:04+09:00 - Points: 1 ###### [Hacker News 의견들](https://news.ycombinator.com/item?id=49063754) - 여기서 시도하는 방향은 정말 마음에 들지만, **둘러보기 기능**에는 잡음이 너무 많음. 화면에서 수많은 상자와 요소가 계속 바뀌어 무슨 일이 일어나는지 파악하기 어렵고, 다음 주제로 자동 전환하기보다 사용자가 직접 진행하도록 만들어야 함 한꺼번에 쏟아지는 정보를 수동적으로 보기만 하면 혼란스러움. 기술의 내부 작동을 보여주는 접근 자체는 유용하지만, 데이터와 그래프, 정보 상자를 더하기보다 초점을 좁힐 필요가 있음 - 멋진 **3D 화면의 80%** 를 팝업이 가리고 있음. 잡음을 쉽게 줄이는 기능을 눈에 띄게 제공하고 팝업을 반투명하게 만들면 좋겠음 - 둘러보기에 **TTS**를 추가해볼 만함 - 소프트웨어에 **둘러보기 기능**이 필요하다면 UX를 개선해야 한다는 신호일 수 있음. 새 기능을 알리고 싶어도 사용자는 필요할 때 자연스럽게 발견하게 됨 - 인간 두뇌의 한계는 개발자와 사용자 모두에게 동일함. LLM으로 복잡한 것을 만들 수 있어도 장식적 복잡성인 [그리블]()이 일정 수준을 넘으면 다른 인간이 체험하도록 설계된 것처럼 느껴지지 않음 LLM 없이 만들었다면 개발자 스스로 전체 정신 모형을 머릿속에 담을 수 없어 복잡성을 줄였을 텐데, 사용자 역시 같은 한계를 지님. 애니메이션과 번쩍이는 불빛의 은유를 이해하려 해도 의미가 묻혀버림 새 프로세스가 왜 관을 통과해 건물에 도착하는 사각형이고, 그 뒤 핀볼 스위치가 빨갛게 빛나는지 모르겠음. 무언가를 클릭하면 `"sessions is the victim"`이라는 작은 팝업이 문단과 함께 잠깐 나타났다 사라져 더욱 혼란스러움 교육용이 아닐 수도 있고 내 지식 부족일 가능성도 있지만, 그저 신기한 작품으로 보면 꽤 멋짐 - 처음 화면을 보자마자 질의를 입력하면 **입력 구문 분석부터 결과 반환까지** 전체 흐름을 단계별로 보여주고, 질의와 무관하게 병렬로 상시 실행되는 자율 프로세스도 이해할 수 있으리라 기대했음 시도 자체는 훌륭하지만 어디서 시작해 어디서 끝내야 할지 모르겠음 - `T`를 눌러보면 됨 - 데이터베이스 내부의 **스케줄링**을 이해하려면 예전에는 수많은 아키텍처 다이어그램이 필요했음. PGSimCity는 복잡한 기술 구현 과정을 흥미롭게 표현해 놀라움 오픈 소스인 만큼 같은 발상을 클라우드 컴퓨팅이나 Kubernetes 같은 다른 영역에도 재사용할 수 있어 보임 - Fly.io의 **배포 시스템과 상태 추적**을 Factorio라는 시각적 은유로 설명하는 도구를 늘 만들어보고 싶었음 - **Kubernetes 시각화 도구**를 계속 만들고 싶음. 기존 도구도 있지만 마지막으로 살펴봤을 때는 썩 훌륭해 보이지 않았음 - gdb로 프로그램을 디버깅하며 깊이 집중할 때 머릿속에 그리는 모습과 매우 비슷함. 이런 그래픽으로 **VR 디버깅**을 체험할 수 있다면 코드베이스를 배우는 데 이보다 좋은 방법은 없을 듯함 임의의 코드에서 3D 지도를 생성하면 어느 정도로 좋은 체험을 만들 수 있을지 궁금함 - **48시간도 안 된 바이브 코딩 결과물**이라면 내용이 실제로 정확한지 의문임. 잘못된 결론이나 반지식으로 이어질 위험은 없는지 궁금함 - 완전히 확신할 수는 없지만, 이를 만든 사람은 **Postgres를 매우 잘 아는 편**임 - 여기서 구체적으로 알아내거나 배운 것이 있는지 궁금함. 내게는 잔혹주의풍 장식품처럼 보임 - 요즘 **LLM의 정확도**는 그렇게 나쁘지 않음 - `"Rendering The First Frame..."`가 `"Reticulating Splines..."`가 아니라니 믿기 어려움. UI는 멋짐 - Postgres 내부 구조를 꽤 잘 알지만 오히려 혼란스러웠음. 화면이 너무 분주해 이해하기 어려우며, 최소한 **속도 낮추기 버튼**이 있으면 좋겠음 - 왼쪽 아래에 일시 정지와 속도를 **0.1배까지 조절하는 버튼** 두 개가 있음. 도시의 일부 요소는 클릭해 값을 조절할 수 있고, `transactions/s`에서도 확인했음 - 보기에는 정말 멋짐. 몇 주 전부터 Beam VM을 공장 바닥처럼 돌아다니며 모듈과 함수의 연결 관계, 실행 부하, 불꽃이 튀는 오류를 확인할 수 있는 **Beam용 Doom**을 바이브 코딩하기 시작했음 아직 많이 만들지는 못했지만, VR 헤드셋을 살 명분으로 계속 개발하고 싶음 - AI의 도움으로 만든 것으로 보임. 나도 AI를 활용해 **파국적 망각**을 설명하는 비슷한 바이브 코딩 프로젝트를 진행했음 이제 무언가를 정말 배우고 싶다면 AI의 도움을 언제든 받을 수 있어 만족스러움. 예전에는 좋은 자료를 찾기가 어려웠지만, 이제 병목은 자료가 아니라 개인의 집중력과 주도성으로 옮겨감