오픈 소스 서버리스 Postgres 데이터베이스 플랫폼 Neon

Neon은 오픈 소스 서버리스 Postgres 데이터베이스 플랫폼입니다. Neon은 스토리지(Storage)와 컴퓨트(Compute)를 분리하며, 데이터를 노드 클러스터 전체에 재배포함으로써 PostgreSQL 스토리지 계층을 대체합니다.

Neon Free Tier를 사용하여 서버리스 Postgres 인스턴스를 생성해 보세요. 그 다음 선호하는 Postgres 클라이언트(psql, dbeaver 등)로 연결하거나 온라인 SQL 에디터를 사용할 수 있습니다. 연결 방법은 'Connect from any application'을 참조하십시오.

또는 프로젝트를 로컬에서 컴파일하여 실행할 수 있습니다.

Neon 설치는 컴퓨트 노드(Compute nodes)와 Neon 스토리지 엔진(Neon storage engine)으로 구성됩니다. 컴퓨트 노드는 Neon 스토리지 엔진에 의해 지원되는 상태 비저장(Stateless) PostgreSQL 노드입니다.

Neon 스토리지 엔진은 두 가지 주요 구성 요소로 이루어져 있습니다:

• Pageserver: 컴퓨트 노드를 위한 확장 가능한 스토리지 백엔드(Storage backend).
• Safekeepers: Safekeepers는 중복성을 갖춘 WAL(Write Ahead Log) 서비스를 형성하며, 컴퓨트 노드로부터 WAL을 수신하고, Pageserver에 의해 처리되어 클라우드 스토리지에 업로드될 때까지 이를 내구적으로 저장합니다.

자세한 내용은 SUMMARY.md에 있는 개발자 문서를 참조하십시오.

Neon은 다음 지침을 따라 소규모 실험 및 코드 변경 테스트를 위해 워크스테이션에서 실행할 수 있습니다.

• 빌드 의존성(Build dependencies) 및 기타 적용 가능한 패키지 설치

• Ubuntu 또는 Debian의 경우, 다음 패키지 세트면 코드를 빌드하기에 충분합니다:

apt install build-essential libtool libreadline-dev zlib1g-dev flex bison libseccomp-dev \
libssl-dev clang pkg-config libpq-dev cmake postgresql-client protobuf-compiler \
libprotobuf-dev libcurl4-openssl-dev openssl python3-poetry lsof libicu-dev

• Fedora의 경우, 다음 패키지들이 필요합니다:

dnf install flex bison readline-devel zlib-devel openssl-devel \
libseccomp-devel perl clang cmake postgresql postgresql-contrib protobuf-compiler \
protobuf-devel libcurl-devel openssl poetry lsof libicu-devel libpq-devel python3-devel \
...

• Arch 기반 시스템의 경우, 다음 패키지들이 필요합니다:

pacman -S base-devel readline zlib libseccomp openssl clang \
postgresql-libs cmake postgresql protobuf curl lsof

Neon을 빌드하려면 protoc (protobuf-compiler) 3.15 이상의 버전이 필요합니다.

사용 중인 배포판에서 더 낮은 버전을 제공하는 경우, 여기에서 최신 버전을 설치할 수 있습니다.

# https://www.rust-lang.org/tools/install 의 권장 방식
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• XCode 및 의존성 설치

xcode-select --install
brew install protobuf openssl flex bison icu4c pkg-config m4
# neon_local에서 ed25519 키 생성을 위해 필요한 openssl을 PATH에 추가
...

m4가 누락되었다는 오류가 발생하는 경우,

수동으로 설치해야 할 수도 있습니다:

brew install m4
brew link --force m4

# https://www.rust-lang.org/tools/install 의 권장 방식
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• PostgreSQL 클라이언트 설치

# https://stackoverflow.com/questions/44654216/correct-way-to-install-psql-without-full-postgres-on-macos 에서 가져옴
brew install libpq
brew link --force libpq

이 프로젝트는 테스트를 위한 CI(지속적 통합) 및 로컬 빌드 시 빌드에 사용되는 버전을 정의하기 위해 rust 툴체인 (toolchain) 파일을 사용합니다.

이 파일은 rustup에 의해 자동으로 인식되며,

파일에 고정된 툴체인 버전을 (설치되어 있지 않은 경우) 설치하고 사용합니다.

다른 툴체인으로 빌드하고자 하는 rustup 사용자는 rustup override 명령을 사용하여 프로젝트 디렉토리에 특정 툴체인을 설정할 수 있습니다.

rustup을 사용하지 않는 사용자는 파일로부터 동일한 툴체인을 자동으로 가져오지 못할 가능성이 높으므로, 자신의 툴체인이 파일에 명시된 버전과 일치하는지 수동으로 확인할 책임이 있습니다. 최신 rustc 버전은 문제없이 작동할 가능성이 높지만, 프로젝트나 크레이트 (crates)에서 사용하는 새로운 기능으로 인해 이전 버전은 지원되지 않을 수 있습니다.

• neon 및 패치된 postgres 빌드

# 참고: neon 소스 경로에는 공백이 포함될 수 없습니다.
git clone --recursive https://github.com/neondatabase/neon.git
cd neon
...

• Neon 및 패치된 Postgres 빌드

# 참고: neon 소스 경로에는 공백이 포함될 수 없습니다.
git clone --recursive https://github.com/neondatabase/neon.git
cd neon
...

psql 클라이언트를 실행하려면 postgresql-client 패키지를 설치하거나, PATH와 LD_LIBRARY_PATH를 각각 pg_install/bin 및 pg_install/lib를 포함하도록 수정하십시오.

통합 테스트(integration tests) 또는 Python 스크립트를 실행하려면 (코드를 반드시 사용할 필요는 없음), Python (3.11 이상)을 설치하고 프로젝트 디렉토리에서 ./scripts/pysync를 사용하여 python3 패키지를 설치하십시오 (poetry>=1.8 필요).

• pageserver 및 그 위의 postgres 시작 (레포지토리 루트에서 호출해야 함):

# 바이너리 및 데이터에 대한 적절한 경로와 함께 .neon에 레포지토리 생성
# 나중에는 패키지 설치 스크립트의 책임이 됩니다.
> cargo neon init
...

• 이제 postgres에 연결하여 쿼리를 실행할 수 있습니다:

> psql -p 55432 -h 127.0.0.1 -U cloud_admin postgres
postgres=# CREATE TABLE t(key int primary key, value text);
CREATE TABLE
...

• 그리고 브랜치를 생성하고 그 위에서 postgres를 실행합니다:

# migration_check라는 이름의 브랜치 생성
> cargo neon timeline branch --branch-name migration_check
Created timeline 'b3b863fa45fa9e57e615f9f2d944e601' at Lsn 0/16F9A00 for tenant: 9ef87a5bf0d92544f6fafeeb3239695c. Ancestor timeline: 'main'
...

• 이후에 테스트를 실행하려면 (아래 참조), 방금 시작한 모든 실행 중인 pageserver, safekeeper 및 postgres 인스턴스를 중지해야 합니다. 한 번의 명령으로 모두 종료할 수 있습니다:

> cargo neon stop

더 고급 사용법은 Local Development Control Plane (neon_local)에서 확인할 수 있습니다.

초기 테넌트(tenant) 설정 중에 오류가 발생하면, 모든 것을 중지(cargo neon stop)하고 .neon 디렉토리를 삭제하는 것이 가장 좋습니다. 그런 다음 문제를 해결하고 설정을 다시 시작하십시오.

우리는 Github Workflows에서 테스트를 실행하기 위해 cargo-nextest를 사용합니다. 일부 크레이트(crates)는 더 이상 일반적인 cargo test 실행을 지원하지 않으므로, cargo nextest run을 권장합니다.

대신 cargo install cargo-nextest를 사용하여 cargo-nextest를 설치할 수 있습니다.

의존성(dependencies)이 여기에 설명된 대로 설치되었는지 확인하십시오.

git clone --recursive https://github.com/neondatabase/neon.git
CARGO_BUILD_FLAGS="--features=testing" make
./scripts/pytest

기본적으로 이 명령은 디버그(debug) 모드와 릴리스(release) 모드 모두를 실행하며, 지원되는 모든 Postgres 버전을 실행합니다. 로컬에서 테스트할 때는 다음과 같이 하나의 조합 세트만 실행하는 것이 편리합니다:

DEFAULT_PG_VERSION=17 BUILD_TYPE=release ./scripts/pytest

이 저장소의 소프트웨어를 위해 플레임그래프(flamegraphs)가 필요할 수도 있습니다. flamegraph-rs 또는 오리지널 flamegraph.pl을 사용할 수 있습니다. 선택은 여러분의 몫입니다!

중요

lld 또는 mold를 사용하는 경우, --no-rosegment 링커(linker) 인자가 필요합니다. 이는 이 저장소에 국한된 것이 아니라 Rust / lld / mold의 일반적인 사항입니다. 자세한 지침은 이 PR을 참조하십시오.

빌드 아티팩트(artifacts)로부터 소스 트리(source tree)를 정리하려면 소스 디렉토리에서 make clean을 실행하십시오.

빌드 및 구성(configure) 단계의 모든 아티팩트를 제거하려면 make distclean을 실행하십시오. 또한 target 디렉토리의 cargo 바이너리와 .neon 디렉토리의 데이터베이스를 삭제하는 것도 고려하십시오. .neon 디렉토리를 삭제하면 그 안의 모든 데이터를 포함한 데이터베이스가 삭제된다는 점에 유의하십시오. 경고했습니다!

docs: 사용 가능한 모든 마크다운(markdown) 문서에 대한 최상위 개요를 포함합니다.

• sourcetree.md: 소스 트리 레이아웃의 개요를 포함합니다.

브라우저에서 rustdoc 문서를 보려면 cargo doc --no-deps --open을 실행해 보십시오. 일부 소스 디렉토리의 README 파일과 rustdoc 스타일의 문서 주석(documentation comments)도 참조하십시오.

기타 리소스:

• SELECT 'Hello, World': Nikita Shamgunov의 하이 레벨 아키텍처(high level architecture)에 관한 블로그 포스트
• Architecture decisions in Neon: Heikki Linnakangas의 블로그 포스트
• Neon: Serverless PostgreSQL!: CMU Database Group 세미나 시리즈에서 Heikki Linnakangas가 발표한 스토리지 시스템(storage system)에 관한 프레젠테이션

Neon은 PostgreSQL 내부 구조(internals)와 매우 밀접한 관계가 있기 때문에 수많은 특정 용어들이 사용됩니다. 이는 특정 철자법에도 동일하게 적용됩니다. 예를 들어, 우리는 1024 * 1024 바이트를 나타내기 위해 MB를 사용합니다. 기술적으로는 MiB가 더 정확하겠지만, 이는 PostgreSQL 코드 및 관련 문서에서 사용하는 방식과 일치하지 않기 때문입니다.

이러한 측면에 대해 더 익숙해지려면 다음을 참조하십시오:

• Neon 용어 사전 (glossary)

• PostgreSQL 용어 사전 (glossary)

• 기타 PostgreSQL 문서 및 출처 (Neon 포크(fork) 소스 코드는 여기서 찾을 수 있습니다)

• 프로젝트 코드 스타일(code style)과 관례(practices)에 대해 알아보려면 CONTRIBUTING.md를 읽어보십시오.

• 소스 트리 레이아웃(source tree layout)에 익숙해지려면 sourcetree.md를 사용하십시오.

• PostgreSQL 내부 구조(internals)에 대해 더 자세히 알아보려면 http://www.interdb.jp/pg/index.html 을 확인하십시오.