neondatabase/neon

[](https://neon.com) # Neon Neon 是一个开源的无服务器 Postgres 数据库平台。它分离了存储和计算，并通过在节点集群中重新分布数据来替代 PostgreSQL 的存储层。 ## 快速开始 尝试使用 [Neon 免费套餐](https://neon.com/signup) 来创建一个无服务器的 Postgres 实例。然后使用你首选的 Postgres 客户端（psql、dbeaver 等）连接到它，或者使用在线的 [SQL 编辑器](https://neon.com/docs/get-started-with-neon/query-with-neon-sql-editor/)。有关连接说明，请参阅[从任何应用程序连接](https://neon.com/docs/connect/connect-from-any-app/)。 或者，在[本地](#running-local-installation)编译并运行该项目。 ## 架构概述 一个 Neon 安装实例由计算节点和 Neon 存储引擎组成。计算节点是由 Neon 存储引擎支持的无状态 PostgreSQL 节点。 Neon 存储引擎由两个主要组件组成： - Pageserver：计算节点的可扩展存储后端。 - Safekeepers：Safekeeper 组成了一个冗余的 WAL 服务，该服务从计算节点接收 WAL，并对其进行持久化存储，直到它被 Pageserver 处理并上传到云存储中。 有关更多信息，请参阅 [SUMMARY.md](/docs/SUMMARY.md) 中的开发者文档。 ## 运行本地开发环境 只需按照以下说明，Neon 即可在工作站上运行，用于小型实验和测试代码更改。 #### 在 Linux 上安装依赖 1. 安装构建依赖和其他适用的软件包 * 在 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 \ libffi-devel ``` * 在基于 Arch 的系统上，需要以下软件包： ``` pacman -S base-devel readline zlib libseccomp openssl clang \ postgresql-libs cmake postgresql protobuf curl lsof ``` 构建 Neon 需要 3.15+ 版本的 `protoc` (protobuf-compiler)。如果你的发行版提供的是较旧的版本，你可以从[这里](https://github.com/protocolbuffers/protobuf/releases)安装更新的版本。 2. [安装 Rust](https://www.rust-lang.org/tools/install) ``` # 推荐的方法来自 https://www.rust-lang.org/tools/install curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` #### 在 macOS (12.3.1) 上安装依赖 1. 安装 XCode 及其依赖 ``` xcode-select --install brew install protobuf openssl flex bison icu4c pkg-config m4 # 将 openssl 添加到 PATH，这是在 neon_local 中生成 ed25519 密钥所必需的 echo 'export PATH="$(brew --prefix openssl)/bin:$PATH"' >> ~/.zshrc ``` 如果你遇到关于缺少 `m4` 的错误，你可能需要手动安装它： ``` brew install m4 brew link --force m4 ``` 2. [安装 Rust](https://www.rust-lang.org/tools/install) ``` # 推荐的方法来自 https://www.rust-lang.org/tools/install curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` 3. 安装 PostgreSQL 客户端 ``` # 来自 https://stackoverflow.com/questions/44654216/correct-way-to-install-psql-without-full-postgres-on-macos brew install libpq brew link --force libpq ``` #### Rustc 版本 该项目使用 [rust 工具链文件](./rust-toolchain.toml) 来定义在 CI 中用于测试和本地构建的版本。 该文件会被 [`rustup`](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file) 自动识别，它会安装（如果不存在）并使用文件中固定的工具链版本。 想要使用其他工具链进行构建的 rustup 用户，可以使用 [`rustup override`](https://rust-lang.github.io/rustup/overrides.html#directory-overrides) 命令为项目目录设置特定的工具链。 非 rustup 用户很可能无法从文件中自动获取相同的工具链，因此需要负责手动验证其工具链是否与文件中的版本匹配。 较新的 rustc 版本很可能可以正常工作，但较旧的版本可能由于项目或 crates 使用了某些新功能而不再受支持。 #### 在 Linux 上构建 1. 构建 Neon 和打过补丁的 Postgres ``` # 注意：neon 源码的路径不能包含空格。 git clone --recursive https://github.com/neondatabase/neon.git cd neon # 首选且默认的做法是进行 debug build。这将创建一个 # 明显比 release build 慢的构建。要进行 release build， # 请使用 "BUILD_TYPE=release make -j`nproc` -s" # 移除 -s 以获取详细的构建日志 make -j`nproc` -s ``` #### 在 OSX 上构建 1. 构建 Neon 和打过补丁的 Postgres ``` # 注意：neon 源码的路径不能包含空格。 git clone --recursive https://github.com/neondatabase/neon.git cd neon # 首选且默认的做法是进行 debug build。这将创建一个 # 明显比 release build 慢的构建。要进行 release build， # 请使用 "BUILD_TYPE=release make -j`sysctl -n hw.logicalcpu` -s" # 移除 -s 以获取详细的构建日志 make -j`sysctl -n hw.logicalcpu` -s ``` #### 依赖安装说明 要运行 `psql` 客户端，请安装 `postgresql-client` 软件包，或者修改 `PATH` 和 `LD_LIBRARY_PATH` 以分别包含 `pg_install/bin` 和 `pg_install/lib`。 要运行集成测试或 Python 脚本（使用代码不需要），请安装 Python（3.11 或更高版本），并在项目目录下使用 `./scripts/pysync`（需要 [poetry>=1.8](https://python-poetry.org/)）安装 python3 软件包。 #### 运行 Neon 数据库 1. 启动 Pageserver 及其上的 Postgres（应从代码库根目录调用）： ``` # 在 .neon 中创建 repository，并设置正确的 binaries 和数据路径 # 稍后，这将成为 package install 脚本的职责 > cargo neon init Initializing pageserver node 1 at '127.0.0.1:64000' in ".neon" # 启动 pageserver、safekeeper 和 broker 以进行相互通信 > cargo neon start Starting neon broker at 127.0.0.1:50051. storage_broker started, pid: 2918372 Starting pageserver node 1 at '127.0.0.1:64000' in ".neon". pageserver started, pid: 2918386 Starting safekeeper at '127.0.0.1:5454' in '.neon/safekeepers/sk1'. safekeeper 1 started, pid: 2918437 # 创建初始 tenant，并将其作为以后每次 neon_local 调用的默认值 > cargo neon tenant create --set-default tenant 9ef87a5bf0d92544f6fafeeb3239695c successfully created on the pageserver Created an initial timeline 'de200bd42b49cc1814412c7e592dd6e9' at Lsn 0/16B5A50 for tenant: 9ef87a5bf0d92544f6fafeeb3239695c Setting tenant 9ef87a5bf0d92544f6fafeeb3239695c as a default one # 创建 postgres 计算节点 > cargo neon endpoint create main # 启动 postgres 计算节点 > cargo neon endpoint start main Starting new endpoint main (PostgreSQL v14) on timeline de200bd42b49cc1814412c7e592dd6e9 ... Starting postgres at 'postgresql://cloud_admin@127.0.0.1:55432/postgres' # 检查正在运行的 postgres 实例列表 > cargo neon endpoint list ENDPOINT ADDRESS TIMELINE BRANCH NAME LSN STATUS main 127.0.0.1:55432 de200bd42b49cc1814412c7e592dd6e9 main 0/16B5BA8 running ``` 2. 现在，可以连接到 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=# insert into t values(1,1); INSERT 0 1 postgres=# select * from t; key | value -----+------- 1 | 1 (1 row) ``` 3. 还可以创建分支并在其上运行 Postgres： ``` # 创建名为 migration_check 的 branch > cargo neon timeline branch --branch-name migration_check Created timeline 'b3b863fa45fa9e57e615f9f2d944e601' at Lsn 0/16F9A00 for tenant: 9ef87a5bf0d92544f6fafeeb3239695c. Ancestor timeline: 'main' # 检查 branches 树 > cargo neon timeline list (L) main [de200bd42b49cc1814412c7e592dd6e9] (L) ┗━ @0/16F9A00: migration_check [b3b863fa45fa9e57e615f9f2d944e601] # 在该 branch 上创建 postgres > cargo neon endpoint create migration_check --branch-name migration_check # 在该 branch 上启动 postgres > cargo neon endpoint start migration_check Starting new endpoint migration_check (PostgreSQL v14) on timeline b3b863fa45fa9e57e615f9f2d944e601 ... Starting postgres at 'postgresql://cloud_admin@127.0.0.1:55434/postgres' # 检查正在运行的 postgres 实例的新列表 > cargo neon endpoint list ENDPOINT ADDRESS TIMELINE BRANCH NAME LSN STATUS main 127.0.0.1:55432 de200bd42b49cc1814412c7e592dd6e9 main 0/16F9A38 running migration_check 127.0.0.1:55434 b3b863fa45fa9e57e615f9f2d944e601 migration_check 0/16F9A70 running # 这个新的 postgres 实例将拥有来自 'main' postgres 的所有数据， # 但所有的修改都不会影响原始 postgres 中的数据 > psql -p 55434 -h 127.0.0.1 -U cloud_admin postgres postgres=# select * from t; key | value -----+------- 1 | 1 (1 row) postgres=# insert into t values(2,2); INSERT 0 1 # 检查新的更改是否不会影响 'main' postgres > psql -p 55432 -h 127.0.0.1 -U cloud_admin postgres postgres=# select * from t; key | value -----+------- 1 | 1 (1 row) ``` 4. 如果你之后想要运行测试（见下文），你必须停止所有刚刚启动的 Pageserver、Safekeeper 和 Postgres 实例。你可以使用一个命令终止它们全部： ``` > cargo neon stop ``` 更多高级用法可在 [本地开发控制平面 (`neon_local`)](./control_plane/README.md) 中找到。 #### 处理构建失败 如果你在设置初始租户期间遇到错误，最好停止所有进程（`cargo neon stop`）并删除 `.neon` 目录。然后解决问题并重新开始设置。 ## 运行测试 ### Rust 单元测试 我们在 Github Workflows 中使用 [`cargo-nextest`](https://nexte.st/) 来运行测试。 某些 crates 已不再支持运行普通的 `cargo test`，请改用 `cargo nextest run`。 你可以通过 `cargo install cargo-nextest` 来安装 `cargo-nextest`。 ### 集成测试 确保已按照[此处](https://github.com/neondatabase/neon#dependency-installation-notes)的说明安装了依赖项。 ``` git clone --recursive https://github.com/neondatabase/neon.git CARGO_BUILD_FLAGS="--features=testing" make ./scripts/pytest ``` 默认情况下，这会同时运行调试和发布模式，以及所有受支持的 Postgres 版本。在本地测试时，运行一组特定的排列组合会更方便，例如： ``` DEFAULT_PG_VERSION=17 BUILD_TYPE=release ./scripts/pytest ``` ## 火焰图 你可能需要为此存储库中的软件生成火焰图。 你可以使用 [`flamegraph-rs`](https://github.com/flamegraph-rs/flamegraph) 或原版的 [`flamegraph.pl`](https://github.com/brendangregg/FlameGraph)。任你选择！ ## 清理 要从构建产物中清理源代码树，请在源目录中运行 `make clean`。 要移除构建和配置步骤中的所有产物，请运行 `make distclean`，并考虑一并移除 `target` 目录中的 cargo 二进制文件以及 `.neon` 目录中的数据库。请注意，移除 `.neon` 目录将会删除你的数据库及其中的所有数据。已提醒过你！ ## 文档 [docs](/docs) 包含所有可用 Markdown 文档的顶层概述。 - [sourcetree.md](/docs/sourcetree.md) 包含源代码树布局的概述。 要在浏览器中查看你的 `rustdoc` 文档，请尝试运行 `cargo doc --no-deps --open` 另请参阅某些源代码目录中的 README 文件，以及 `rustdoc` 风格的文档注释。 其他资源： - [SELECT 'Hello, World'](https://neon.com/blog/hello-world/)：Nikita Shamgunov 撰写的关于高层架构的博客文章 - [Neon 中的架构决策](https://neon.com/blog/architecture-decisions-in-neon/)：Heikki Linnakangas 撰写的博客文章 - [Neon：无服务器 PostgreSQL！](https://www.youtube.com/watch?v=rES0yzeERns)：Heikki Linnakangas 在 CMU 数据库小组研讨会上发表的关于存储系统的演讲 ### Postgres 特定术语 由于 Neon 与 PostgreSQL 内部结构关系密切，因此使用了许多特定的术语。 某些拼写也同样适用：即我们使用 MB 来表示 1024 * 1024 字节，虽然严格来说 MiB 会更准确，但这与 PostgreSQL 代码及其文档使用的不一致。 要熟悉这方面的内容，请参阅： - [Neon 词汇表](/docs/glossary.md) - [PostgreSQL 词汇表](https://www.postgresql.org/docs/14/glossary.html) - 其他 PostgreSQL 文档和源代码（Neon fork 的源代码可以在[这里](https://github.com/neondatabase/postgres)找到） ## 加入开发 - 阅读 [CONTRIBUTING.md](/CONTRIBUTING.md) 以了解项目代码风格和实践。 - 要熟悉源代码树布局，请使用 [sourcetree.md](/docs/sourcetree.md)。 - 要了解更多关于 PostgreSQL 内部机制的信息，请查看 http://www.interdb.jp/pg/index.html

标签：Branching, C++, DBaaS, DNS解析, Pageserver, Postgres, PostgreSQL, Rust, Safekeepers, Serverless, SOC Prime, SQL, WAL, 云原生数据库, 云存储, 云数据库, 分布式存储, 可视化界面, 后端开发, 存储与计算分离, 开发工具, 开源数据库, 开源项目, 弹性伸缩, 数据库, 数据库分支, 数据库即服务, 数据库架构, 数据擦除, 无服务器, 测试用例, 系统审计, 缩容至零, 网络流量审计, 自动扩缩容, 逆向工具, 预写日志, 高性能数据库