7.1 용어집
Neon 문서와 소스 저장소의 docs/glossary.md, 그리고 이 노트에서 다룬 대안 기술의 용어를 정리했습니다. 정의는 공식 문서와 소스 저장소 문서의 범위 안에서만 작성했습니다. 문서에 없는 수치는 넣지 않았습니다. 같은 단어가 PostgreSQL과 Neon 저장소 계층에서 다른 뜻으로 쓰이는 경우(checkpoint, basebackup, timeline)는 항목을 나눴습니다.
구성 요소
| 용어 | 정의 | 관련 장 |
|---|---|---|
| tenant | Neon 저장소에서 고객 하나에 해당하는 단위. WAL redo, timeline, layer를 tenant별로 독립적으로 관리한다. pageserver 하나가 여러 tenant를 서비스한다 | 2.3, 3.1 |
| timeline | 페이지 변경을 받아들이고 get_page_at_lsn(), get_rel_size() 요청을 처리하는 내부 단위. 사용자에게는 branch라는 이름으로 노출된다. PostgreSQL의 WAL timeline과는 무관하다 | 2.4 |
| branch | 특정 LSN에서 만든 copy-on-write 복제. 내부적으로는 ancestor를 가진 timeline이다. 부모 layer는 공유하고, 분기 이후 변경은 자식의 in-memory layer를 거쳐 delta layer로 기록된다. compaction 과정에서 자식의 image layer도 생성된다 | 2.4, 3.2 |
| compute node, endpoint | 데이터를 pageserver에 저장하는 stateless PostgreSQL 프로세스. 저장소 코드에서는 compute node, Neon CLI와 콘솔에서는 endpoint라고 부른다 | 2.1 |
| pageserver | Neon 저장소 엔진. repository, WAL receiver, page service, WAL redo로 구성된다 | 2.3 |
| page service | compute의 GetPage@LSN 요청을 받아 repository에서 페이지를 반환하는 pageserver 내부 서비스 | 2.3 |
| safekeeper | WAL 서비스에 참여하는 노드 하나. 여러 safekeeper가 quorum을 이룬다 | 2.2 |
| WAL service | safekeeper 전체를 묶어 WAL을 영구적으로 보관하는 서비스 | 2.2 |
| storage broker | WAL 서비스와 pageserver 사이를 조정하는 컴포넌트. docker-compose 예제에서는 50051 포트에서 실행된다 | 3.1 |
| storage controller | 여러 pageserver에 tenant를 배치하고 실행 중인 compute를 재구성하는 컴포넌트. docker-compose 예제에는 없다. pageserver.toml이 control_plane_emergency_mode=true로 동작한다 | 3.6 |
| WAL proposer, WAL acceptor | Paxos 용어. compute 안에서 실행되는 background worker가 proposer이고, safekeeper가 acceptor다 | 2.2 |
| WAL receiver | safekeeper에 PostgreSQL 물리 스트리밍 복제 프로토콜로 접속해 WAL을 받는 pageserver 내부 컴포넌트. 레코드를 해석해 repository에 저장한다. timeline마다 하나씩 있다 | 2.3 |
| WAL redo process | pageserver 안에서 --wal-redo 모드로 실행되는 PostgreSQL. 이전 page image에 WAL 레코드를 적용해 새 page image를 만든다 | 2.3, 2.6 |
| proxy | PostgreSQL 프로토콜 프록시. 외부 서비스로 인증을 확인하고 control plane API를 호출한다. neon 이미지에 포함되지만 docker-compose 예제에서는 사용하지 않는다 | 3.6 |
| Neon Local | Neon 클라우드 프로젝트에 프록시로 연결되는 Docker 이미지. 기본 동작은 컨테이너 시작 시 임시 branch를 만들고 종료 시 삭제하는 것이다. BRANCH_ID로 기존 branch에 연결하거나 DELETE_BRANCH=false로 branch를 유지하는 모드도 있다. 어느 모드든 오프라인으로는 동작하지 않는다 | 3.5 |
LSN
LSN은 WAL 안의 바이트 위치를 나타내는 64비트 정수입니다. 0/16B5A50처럼 슬래시로 나눈 16진수 두 개로 표기합니다. PostgreSQL, safekeeper, pageserver는 서로 다른 이름의 LSN을 추적합니다. 따라서 로그와 API 응답을 읽을 때 어느 계층의 값인지 먼저 확인합니다.
| 용어 | 계층 | 정의 |
|---|---|---|
pg_current_wal_flush_lsn() | PostgreSQL | compute가 flush한 WAL 위치. backpressure 계산의 기준 |
| CommitLSN | safekeeper | quorum의 safekeeper가 확인한 WAL 위치. 이 위치까지를 commit된 것으로 본다 |
| RestartLSN | safekeeper | 모든 safekeeper가 확인한 위치. 이 위치 이전의 WAL은 잘라낼 수 있다 |
| FlushLSN | safekeeper | 해당 safekeeper가 로컬 디스크에 persist한 위치 |
| VCL (Volume Complete LSN) | safekeeper | 이전 모든 레코드의 가용성을 보장하는 가장 큰 LSN. 복구 시 quorum의 max(FlushLSN)으로 정한다 |
last_record_lsn | pageserver | 마지막으로 처리한 WAL 레코드의 끝 |
disk_consistent_lsn | pageserver | 로컬 디스크에 flush와 fsync를 마친 LSN |
remote_consistent_lsn | pageserver | 원격 스토리지(S3)에 동기화되어 pageserver 장애에도 보존되는 LSN |
ancestor_lsn | pageserver | branch가 부모에서 분기한 LSN. 이 값 이하의 페이지는 부모 timeline에서 읽는다 |
Layer와 저장 구조
| 용어 | 정의 | 관련 장 |
|---|---|---|
| layer | 특정 key 범위와 LSN 범위 안의 page version을 재구성하는 데 필요한 데이터. in-memory layer와 on-disk layer가 있다 | 2.3 |
| in-memory layer | 들어오는 WAL을 받아 최근 page version을 빠르게 제공하는 layer. 열린(open) 상태에서 WAL을 받는다. 닫힌(frozen) 뒤에는 delta layer 파일로 flush된다 | 2.3 |
| layer file | 불변(immutable) on-disk layer. image 파일과 delta 파일 두 종류가 있다 | 2.3 |
| image layer | 특정 LSN 시점의 key 범위 스냅샷. image layer에 없는 key는 그 LSN에 존재하지 않는 것으로 본다 | 2.3 |
| delta layer | key 범위와 LSN 범위 안의 WAL 레코드 또는 page image 모음. 수정되지 않은 key는 들어 있지 않다 | 2.3 |
| L0, L1 | 전체 key 범위를 덮는 delta 파일은 L0이고, key 범위 일부만 덮는 파일은 L1이다. 파일명의 key 범위로만 구분하며 읽기 경로에서는 둘을 구분하지 않는다 | 2.3 |
| layer map | timeline에 어떤 layer가 있는지 추적하는 자료구조. ancestor를 인식해 현재 timeline에 없는 데이터는 부모에서 읽는다 | 2.4 |
| compaction | L0 파일 여러 개를 key 범위에 따라 재분할해 L1 파일로 만드는 백그라운드 작업 | 2.3 |
| garbage collection (GC) | 어느 timeline에도 더는 필요하지 않은 오래된 layer를 제거하는 작업 | 2.3 |
| GC horizon | GC가 보존해야 하는 byte 기준 LSN 범위. 저장소 문서의 기본값(DEFAULT_GC_HORIZON)은 64MB이다. 클라우드 서비스의 history window는 시간 기준 pitr_interval에 대응하며 이 byte 기준 horizon과는 별개 cutoff다 | 2.4, 6.1 |
| checkpoint (PostgreSQL) | WAL 상의 한 지점이면서, 그 지점까지 수정된 shared buffer의 dirty page를 데이터 파일로 flush하는 작업. checkpoint record는 WAL에서 그 지점을 표시하는 레코드다 | 2.1 |
| checkpoint (layered repository) | pageserver가 in-memory layer를 새 delta layer 파일로 써 내는 작업. checkpoint_distance(open layer에 쌓인 WAL 바이트)와 checkpoint_timeout(기본 10분) 두 조건 중 먼저 충족되는 쪽이 이 작업을 유발한다. PostgreSQL checkpoint와 이름만 같다 | 2.3 |
| basebackup | compute를 부팅하는 데 필요한 control 파일, 설정, SLRU를 담은 tarball. pageserver가 만든다. PostgreSQL의 pg_basebackup과 무관하다 | 2.1 |
| repository | 같은 initdb에서 분기된 여러 timeline과 WAL redo 서비스를 담는 단위. tenant 하나에 repository 하나가 대응한다 | 2.3 |
| page, GetPage@LSN | PostgreSQL의 기본 저장 단위인 페이지와 compute가 pageserver에 특정 LSN 시점의 페이지를 요청하는 프로토콜 | 2.1 |
| SLRU | pg_xact(clog), pg_multixact 같은 비relation 메타데이터. relation 페이지와 달리 basebackup에 포함된다 | 2.1 |
크기, 캐시, 흐름 제어
| 용어 | 정의 | 관련 장 |
|---|---|---|
| logical size | timeline 안에 있는 모든 PostgreSQL 데이터베이스의 relation 크기 합계. 1GB 데이터베이스에서 branch를 만들면 두 timeline 모두 logical size가 1GB다 | 3.4, 6.1 |
| physical size | timeline의 layer 파일이 실제로 차지하는 크기. 새 branch는 부모 layer를 공유하므로 0에 가깝게 시작한다. 다만 이후 증가분은 WAL 변경량과 그대로 일치하지 않고 image layer 생성과 compaction의 영향을 받는다. 클라우드 서비스의 과금 저장량은 또 다른 값이며, 자식 branch가 restore window를 벗어나면 부모와 공유가 끊겨 root branch 수준으로 과금된다(가격 문서 기준) | 3.4 |
| LFC (Local File Cache) | compute의 로컬 NVMe에 두는 페이지 캐시. shared_buffers 다음 단계의 캐시이다. autoscaling은 이를 대상으로 working set 크기를 추정한다. compute RAM의 최대 75%까지 사용한다 | 2.5 |
| CU (Compute Unit) | compute 크기 단위. 가격 문서는 1 CU를 약 4GB RAM과 그에 대응하는 CPU, SSD 묶음으로 설명하며 vCPU 수를 숫자로 명시하지 않는다. 플랜별 범위는 0.25 CU에서 56 CU까지다 | 2.5, 6.1 |
| backpressure | compute 또는 WAL 서비스가 pageserver보다 너무 앞서가지 않도록 쓰기 backend를 차단하는 장치. max_replication_write_lag, max_replication_flush_lag, max_replication_apply_lag로 조정한다 | 6.2 |
| scale to zero | 유휴 상태가 일정 시간 지속되면 compute를 중지하는 기능. Free와 Launch 플랜의 기본값은 5분이다 | 2.5 |
| read replica | 같은 branch의 저장소를 읽는 read-only compute. 데이터 복사 없이 pageserver에서 직접 읽는다 | 2.5 |
Branch 기능
| 용어 | 정의 | 관련 장 |
|---|---|---|
| history window | 변경 이력을 보존하는 범위. Free 플랜은 최대 6시간 또는 데이터 변경 1GB 중 먼저 도달하는 쪽이고, Launch 플랜은 최대 7일, Scale 플랜은 최대 30일이다. instant restore, 과거 시점 branch, snapshot이 도달하는 범위를 정한다 | 4.4, 6.1 |
| instant restore | branch를 history window 안의 임의 시점으로 되돌리는 기능. CLI에서는 neon branches restore다 | 4.4 |
| reset from parent | 자식 branch를 부모의 최신 상태와 다시 맞추는 기능. CLI에서는 neon branches reset --parent다 | 4.4 |
| schema-only branch | 스키마만 복제하고 데이터는 복제하지 않는 branch. 부모 관계가 없는 독립 root branch이므로 reset from parent를 사용할 수 없다 | 4.5 |
| root branch | 부모가 없는 branch. 프로젝트의 main과 schema-only branch가 여기에 해당한다. 플랜별로 개수 제한이 있다 | 4.5 |
| protected branch | 삭제와 일부 변경이 제한된 branch. production 데이터가 있는 branch에 지정한다 | 4.1 |
| default branch | 프로젝트의 기본 branch. CLI에서 neon branches set-default로 변경한다 | 4.1 |
| branch expiration | branch에 삭제 시각을 지정하는 기능. CI나 임시 환경에 사용한다. CLI에서는 --expires-at과 neon branches set-expiration이다 | 4.2 |
| snapshot | branch의 특정 시점 백업. 문서 기준으로 부모가 없는 root branch에서만 생성한다. CLI neon snapshots로 만들고 expires_at으로 보존 기한을 정한다. 저장량은 history와 별도로 $0.09/GB-month가 과금된다 | 4.4, 4.6 |
| schema diff | 두 branch 또는 같은 branch의 두 시점 사이의 스키마 차이. CLI neon branches schema-diff | 4.3 |
대안 기술 용어
| 용어 | 정의 | 관련 장 |
|---|---|---|
| copy-on-write | 공유 데이터를 쓰기 시점에만 복사하는 방식. Neon과 Aurora는 페이지 수준, Xata는 블록 수준, ZFS는 파일시스템 수준, Dolt는 트리 노드 수준에서 구현한다 | 1.2 |
| thin clone | 물리 복사 없이 copy-on-write로 만든 데이터베이스 복제. ZFS, LVM, DBLab 문서에서 사용하는 용어다 | 5.1, 5.2 |
| ZFS snapshot, clone | snapshot은 dataset의 읽기 전용 시점 복사이고, clone은 snapshot에서 만든 쓰기 가능한 dataset이다. clone은 snapshot과 블록을 공유한다 | 5.1 |
| DBLab branch, commit | DBLab Engine 4.0부터 제공하는 Git 방식의 명령. commit은 clone의 현재 상태로 새 snapshot을 만든다. branch는 snapshot 계보를 이름으로 묶는다 | 5.2 |
| physical mode, logical mode | DBLab의 데이터 소스 방식. physical은 pg_basebackup, WAL-G, pgBackRest로 받아 지속해서 갱신한다. logical은 dump와 restore로 주기적으로 새로 받는다 | 5.2 |
| Prolly tree | 내용 주소(content-addressed) 방식의 B-tree 변형. Dolt가 branch 사이의 구조 공유와 빠른 diff에 사용한다 | 5.3 |
| deploy request | PlanetScale에서 branch의 스키마 변경을 production으로 보내는 검토 절차. Vitess 기반 MySQL에서 제공한다. PlanetScale Postgres는 지원하지 않는다 | 1.3 |
| Aurora clone | Aurora 스토리지 볼륨의 copy-on-write protocol로 만든 클러스터. copy-on-write 클론은 15개까지이며, 그 이후에는 full copy가 된다 | 1.2, 6.5 |
| Fluid Storage fork | Tiger Cloud의 copy-on-write fork. --now, --last-snapshot, --to-timestamp 중 하나로 시점을 정한다 | 1.3 |
| lakebase | Databricks가 정의한 OLTP 데이터베이스 유형. storage와 compute를 분리한다. 저장소의 source of truth를 object storage에 두며 branching을 제공한다. Neon의 아키텍처가 Lakebase Postgres의 기반이다 | 1.3, 6.3 |