# neon-lab

Neon 저장 엔진(pageserver, safekeeper, storage_broker)과 compute를 Docker Compose로 올려
branch(timeline) 동작을 직접 확인하는 학습용 구성입니다.
upstream [neondatabase/neon](https://github.com/neondatabase/neon)의 `docker-compose/` 예제(Apache-2.0)를 바탕으로
PostgreSQL 기본 버전을 17로 바꾸고, branch용 compute와 도우미 스크립트를 추가했습니다.

해설과 실측 기록은 https://dbalog.dev/neon/local-lab/ 에 있습니다.

## 준비물

- Docker와 Compose (`docker compose` 또는 `docker-compose`)
- `jq`, `curl`, `python3` (도우미 스크립트가 사용)
- 디스크 여유 15 GB 이상 (이미지 약 9 GB)

호스트에 `psql`은 없어도 됩니다. `scripts/psql.sh`가 compute 컨테이너 안의 `psql`을 실행합니다.

## 빠른 시작

```bash
docker compose build compute1        # compute 이미지에 curl, jq, nc 설치
docker compose up -d                 # 컨테이너 8개 기동
./scripts/psql.sh compute1 -c "select version();"
./scripts/status.sh                  # tenant 와 timeline 트리

./scripts/branch.sh feature-a                      # 현재 시점에서 branch 생성
docker compose --profile branch up -d compute2     # branch 에 붙는 compute (포트 55434)
./scripts/psql.sh compute2 -c "show neon.timeline_id;"

./scripts/branch.sh rescue --at-lsn 0/D902000      # 과거 LSN 에서 branch 생성 (PITR)
```

정리는 `docker compose --profile branch down -v`입니다. `-v`를 빼면 MinIO 볼륨이 남아
다음 기동 때 이전 tenant를 다시 attach하려 시도합니다.

## 구성

| 서비스 | 역할 | 호스트 포트 |
|---|---|---|
| minio | S3 호환 object storage | 9000, 9001 |
| storage_broker | safekeeper 와 pageserver 사이 상태 전파 | 50051 |
| pageserver | page 재구성, layer 저장, 관리 API | 9898, 6400 |
| safekeeper1~3 | WAL quorum 저장 | 7676~7678 |
| compute1 | main timeline 의 PostgreSQL | 55433, 3080 |
| compute2 | branch timeline 의 PostgreSQL (profile `branch`) | 55434, 3081 |

`scripts/branch.sh`가 `.env`에 `TENANT_ID`, `TIMELINE_ID`, `BRANCH_TIMELINE_ID`를 기록하고
compose가 그 값을 compute에 전달합니다. `.env`와 `.branches`는 실행 중 생기는 파일입니다.

## 주의

upstream README는 이 compose 구성이 "이미지 테스트용이며 사용 가능한 시스템을 배포하려는 목적이 아니다"라고 밝힙니다.
control plane과 storage controller가 없고 pageserver 인증도 꺼져 있습니다. 학습과 실험에만 사용하고
접속 정보(`cloud_admin`/`cloud_admin`, MinIO `minio`/`password`)를 외부 인터페이스에 노출하지 않습니다.