PGSimCity - PostgreSQL의 작동 방식을 탐험 가능한 3D 도시로 시각화

 (nikolays.github.io)
1P by GN⁺ | ★ favorite | 댓글 1개
  • 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-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 라이선스로 배포됨
  • SimCity의 코드/에셋/그림/로고/캐릭터/오디오/게임 콘텐츠를 포함하지 않음
  • Electronic Arts 및 PostgreSQL 프로젝트와 제휴/후원/승인 관계가 없는 독립 교육 프로젝트임

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • 여기서 시도하는 방향은 정말 마음에 들지만, 둘러보기 기능에는 잡음이 너무 많음. 화면에서 수많은 상자와 요소가 계속 바뀌어 무슨 일이 일어나는지 파악하기 어렵고, 다음 주제로 자동 전환하기보다 사용자가 직접 진행하도록 만들어야 함
    한꺼번에 쏟아지는 정보를 수동적으로 보기만 하면 혼란스러움. 기술의 내부 작동을 보여주는 접근 자체는 유용하지만, 데이터와 그래프, 정보 상자를 더하기보다 초점을 좁힐 필요가 있음

    • 멋진 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의 도움을 언제든 받을 수 있어 만족스러움. 예전에는 좋은 자료를 찾기가 어려웠지만, 이제 병목은 자료가 아니라 개인의 집중력과 주도성으로 옮겨감

답변달기