From b7c1af0a54a27bc4424f615ee49a85d45a4f3f5f Mon Sep 17 00:00:00 2001 From: YangHao <1169521703@qq.com> Date: Tue, 20 Aug 2024 18:27:53 +0800 Subject: [PATCH 1/2] fix: clean up code to eliminate compilation warnings 1. Assign an initial value of 0 to the 'nSockets_base' variable to prevent the compilation warning 'may be used uninitialized in this function'. 2. Delete the 'blockNum' variable, which is defined but not used in the 'polar_bulk_read_buffer_common' function. 3. Delete the unused function definition 'px_show_scan_unit_size' from the 'guc_px.c' file. The implementation of this function has been removed in the d52e8258 commit. --- src/backend/postmaster/postmaster.c | 2 +- src/backend/storage/buffer/polar_bufmgr.c | 2 -- src/backend/utils/misc/guc_px.c | 1 - 3 files changed, 1 insertion(+), 4 deletions(-) diff --git a/src/backend/postmaster/postmaster.c b/src/backend/postmaster/postmaster.c index da786b0a698..bb71e587ac9 100644 --- a/src/backend/postmaster/postmaster.c +++ b/src/backend/postmaster/postmaster.c @@ -1844,7 +1844,7 @@ static int ServerLoop(void) { fd_set readmask, readmask_base; - int nSockets, nSockets_base; + int nSockets, nSockets_base = 0; time_t last_lockfile_recheck_time, last_touch_time; diff --git a/src/backend/storage/buffer/polar_bufmgr.c b/src/backend/storage/buffer/polar_bufmgr.c index 0b6082c0a87..677af5430cb 100644 --- a/src/backend/storage/buffer/polar_bufmgr.c +++ b/src/backend/storage/buffer/polar_bufmgr.c @@ -1339,8 +1339,6 @@ polar_bulk_read_buffer_common(Relation reln, char relpersistence, ForkNumber for */ for (index = actual_bulk_io_count - 1; index >= 0 ; index--) { - BlockNumber blockNum = firstBlockNum + index; - bufHdr = polar_bulk_io_in_progress_buf[index]; bufBlock = isLocalBuf ? LocalBufHdrGetBlock(bufHdr) : BufHdrGetBlock(bufHdr); diff --git a/src/backend/utils/misc/guc_px.c b/src/backend/utils/misc/guc_px.c index cb261be5187..571ff56cef8 100644 --- a/src/backend/utils/misc/guc_px.c +++ b/src/backend/utils/misc/guc_px.c @@ -284,7 +284,6 @@ int px_wait_lock_timeout = 0; /* POLAR */ static bool px_check_dispatch_log_stats(bool *newval, void **extra, GucSource source); static bool px_check_scan_unit_size(int *newval, void **extra, GucSource source); -static const char* px_show_scan_unit_size(void); static bool px_check_ignore_function(char **newval, void **extra, GucSource source); static void px_assign_ignore_function(const char *newval, void *extra); static int px_guc_array_compare(const void *a, const void *b); From 37be626c8703a1a117fbd329af66af9dc1ffb6af Mon Sep 17 00:00:00 2001 From: mrdrivingduck Date: Fri, 23 Aug 2024 10:06:22 +0800 Subject: [PATCH 2/2] docs: add image link of Alibaba Cloud ACR Currently we have mirror Docker images on ACR other than DockerHub and ghcr. Add links for them. Also, all the Docker images have been tagged to 11, for the preparation of open sourcing PolarDB-PG 15. --- README-CN.md | 9 ++- README.md | 9 ++- docs/.vuepress/configs/navbar/zh.ts | 2 +- docs/.vuepress/configs/sidebar/zh.ts | 2 +- docs/README.md | 28 +++++++-- docs/deploying/db-localfs.md | 74 ++++++++++++++++++++++-- docs/deploying/db-pfs-curve.md | 8 +-- docs/deploying/db-pfs.md | 2 +- docs/deploying/deploy.md | 10 +--- docs/deploying/fs-pfs.md | 26 ++++++++- docs/deploying/introduction.md | 2 +- docs/deploying/quick-start.md | 32 ++++++++-- docs/development/customize-dev-env.md | 4 +- docs/development/dev-on-docker.md | 48 ++++++++++++--- docs/operation/ro-online-promote.md | 26 ++++++++- docs/operation/scale-out.md | 54 +++++++++++++++-- docs/operation/tpch-test.md | 26 ++++++++- docs/zh/README.md | 30 ++++++++-- docs/zh/deploying/db-localfs.md | 74 ++++++++++++++++++++++-- docs/zh/deploying/db-pfs-curve.md | 8 +-- docs/zh/deploying/db-pfs.md | 2 +- docs/zh/deploying/deploy.md | 10 +--- docs/zh/deploying/fs-pfs.md | 26 ++++++++- docs/zh/deploying/introduction.md | 2 +- docs/zh/deploying/quick-start.md | 32 ++++++++-- docs/zh/development/customize-dev-env.md | 4 +- docs/zh/development/dev-on-docker.md | 48 ++++++++++++--- docs/zh/operation/ro-online-promote.md | 26 ++++++++- docs/zh/operation/scale-out.md | 54 +++++++++++++++-- docs/zh/operation/tpch-test.md | 26 ++++++++- docs/zh/theory/arch-overview.md | 4 +- 31 files changed, 583 insertions(+), 125 deletions(-) diff --git a/README-CN.md b/README-CN.md index cad64001995..96424129739 100644 --- a/README-CN.md +++ b/README-CN.md @@ -54,13 +54,12 @@ PolarDB for PostgreSQL 采用了基于 Shared-Storage 的存储计算分离架 ## 快速部署 -如果您已安装 Docker，那么可以从 DockerHub 上拉取 PolarDB for PostgreSQL 的 本地存储实例镜像，创建、运行并进入容器，然后直接使用 PolarDB 实例： +如果您已安装 Docker，那么拉取 PolarDB-PG 的单机实例镜像，创建、运行并进入容器，然后直接使用 PolarDB-PG 实例： ```bash -# 拉取单节点 PolarDB 镜像 -docker pull polardb/polardb_pg_local_instance -# 创建运行并进入容器 -docker run -it --rm polardb/polardb_pg_local_instance psql +# 拉取镜像并运行容器 +docker pull polardb/polardb_pg_local_instance:11 +docker run -it --rm polardb/polardb_pg_local_instance:11 psql # 测试实例可用性 postgres=# SELECT version(); version diff --git a/README.md b/README.md index c22b98222cf..4e4ea631d61 100644 --- a/README.md +++ b/README.md @@ -54,13 +54,12 @@ For more information, see [Architecture](https://apsaradb.github.io/PolarDB-for- ## Quick Start with PolarDB -If you have Docker installed already，then you can pull the instance image of PolarDB for PostgreSQL based on local storage. Create, run and enter the container, and use PolarDB instance directly: +If you have Docker installed already，then you can pull the instance image of PolarDB-PG based on local storage. Create, run and enter the container, and use PolarDB-PG instance directly: ```bash -# pull the instance image from DockerHub -docker pull polardb/polardb_pg_local_instance -# create, run and enter the container -docker run -it --rm polardb/polardb_pg_local_instance psql +# pull the instance image and run the container +docker pull polardb/polardb_pg_local_instance:11 +docker run -it --rm polardb/polardb_pg_local_instance:11 psql # check postgres=# SELECT version(); version diff --git a/docs/.vuepress/configs/navbar/zh.ts b/docs/.vuepress/configs/navbar/zh.ts index da8f85c0ece..8ed793b4404 100644 --- a/docs/.vuepress/configs/navbar/zh.ts +++ b/docs/.vuepress/configs/navbar/zh.ts @@ -24,7 +24,7 @@ export const zh: NavbarConfig = [ ], }, { - text: "部署 PolarDB 数据库", + text: "部署 PolarDB-PG 数据库", children: [ "/zh/deploying/db-localfs.html", "/zh/deploying/db-pfs.html", diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts index a4b286f0514..1726accc0d9 100644 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ b/docs/.vuepress/configs/sidebar/zh.ts @@ -28,7 +28,7 @@ export const zh: SidebarConfig = { ], }, { - text: "部署 PolarDB 数据库", + text: "部署 PolarDB-PG 数据库", children: [ "/zh/deploying/db-localfs.md", "/zh/deploying/db-pfs.md", diff --git a/docs/README.md b/docs/README.md index 3861bc99696..4f81d7b6754 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,11 +11,28 @@ footer: Apache 2.0 Licensed | Copyright © Alibaba Group, Inc. Pull the [local instance image](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags) of PolarDB for PostgreSQL based on local storage. Create and run the container, and try PolarDB-PG instance directly: +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +# pull the instance image and run the container +docker pull polardb/polardb_pg_local_instance:11 +docker run -it --rm polardb/polardb_pg_local_instance:11 psql +# check +postgres=# SELECT version(); + version +-------------------------------- + PostgreSQL 11.9 (POLARDB 11.9) +(1 row) +``` + +::: +::: code-group-item Alibaba Cloud ACR + ```bash:no-line-numbers -# pull the instance image from DockerHub -docker pull polardb/polardb_pg_local_instance -# create and run the container -docker run -it --rm polardb/polardb_pg_local_instance psql +# pull the instance image and run the container +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 +docker run -it --rm registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 psql # check postgres=# SELECT version(); version @@ -24,6 +41,9 @@ postgres=# SELECT version(); (1 row) ``` +::: +:::: +
diff --git a/docs/deploying/db-localfs.md b/docs/deploying/db-localfs.md index cb2b75b518e..09de80073d7 100644 --- a/docs/deploying/db-localfs.md +++ b/docs/deploying/db-localfs.md @@ -14,12 +14,25 @@ minute: 15 ## 拉取镜像 -我们在 DockerHub 上提供了 PolarDB-PG 的 [本地实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，里面已包含启动 PolarDB-PG 本地存储实例的入口脚本。镜像目前支持 `linux/amd64` 和 `linux/arm64` 两种 CPU 架构。 +我们已提供 PolarDB-PG 的 [单机实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，里面已包含启动 PolarDB-PG 单机实例的入口脚本。镜像目前支持 `linux/amd64` 和 `linux/arm64` 两种 CPU 架构。 + +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +docker pull polardb/polardb_pg_local_instance:11 +``` + +::: +::: code-group-item 阿里云 ACR ```bash:no-line-numbers -docker pull polardb/polardb_pg_local_instance +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 ``` +::: +:::: + ## 初始化数据库 新建一个空白目录 `${your_data_dir}` 作为 PolarDB-PG 实例的数据目录。启动容器时，将该目录作为 VOLUME 挂载到容器内，对数据目录进行初始化。在初始化的过程中，可以传入环境变量覆盖默认值： @@ -30,32 +43,83 @@ docker pull polardb/polardb_pg_local_instance 使用如下命令初始化数据库： +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +docker run -it --rm \ + --env POLARDB_PORT=5432 \ + --env POLARDB_USER=u1 \ + --env POLARDB_PASSWORD=your_password \ + -v ${your_data_dir}:/var/polardb \ + polardb/polardb_pg_local_instance:11 \ + echo 'done' +``` + +::: +::: code-group-item 阿里云 ACR + ```bash:no-line-numbers docker run -it --rm \ --env POLARDB_PORT=5432 \ --env POLARDB_USER=u1 \ --env POLARDB_PASSWORD=your_password \ -v ${your_data_dir}:/var/polardb \ - polardb/polardb_pg_local_instance \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 \ echo 'done' ``` +::: +:::: + ## 启动 PolarDB-PG 服务 数据库初始化完毕后，使用 `-d` 参数以后台模式创建容器，启动 PolarDB-PG 服务。通常 PolarDB-PG 的端口需要暴露给外界使用，使用 `-p` 参数将容器内的端口范围暴露到容器外。比如，初始化数据库时使用的是 `5432-5434` 端口，如下命令将会把这三个端口映射到容器外的 `54320-54322` 端口： +:::: code-group +::: code-group-item DockerHub + ```bash:no-line-numbers docker run -d \ -p 54320-54322:5432-5434 \ -v ${your_data_dir}:/var/polardb \ - polardb/polardb_pg_local_instance + polardb/polardb_pg_local_instance:11 ``` +::: +::: code-group-item 阿里云 ACR + +```bash:no-line-numbers +docker run -d \ + -p 54320-54322:5432-5434 \ + -v ${your_data_dir}:/var/polardb \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 +``` + +::: +:::: + 或者也可以直接让容器与宿主机共享网络： +:::: code-group +::: code-group-item DockerHub + ```bash:no-line-numbers docker run -d \ --network=host \ -v ${your_data_dir}:/var/polardb \ - polardb/polardb_pg_local_instance + polardb/polardb_pg_local_instance:11 ``` + +::: +::: code-group-item 阿里云 ACR + +```bash:no-line-numbers +docker run -d \ + --network=host \ + -v ${your_data_dir}:/var/polardb \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 +``` + +::: +:::: diff --git a/docs/deploying/db-pfs-curve.md b/docs/deploying/db-pfs-curve.md index aa6a7668aa7..32e72dccf85 100644 --- a/docs/deploying/db-pfs-curve.md +++ b/docs/deploying/db-pfs-curve.md @@ -14,7 +14,7 @@ minute: 15 ## 源码下载 -在前置文档中，我们已经从 DockerHub 上拉取了 PolarDB 开发镜像，并且进入到了容器中。进入容器后，从 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上下载 PolarDB for PostgreSQL 的源代码，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee 国内镜像](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 +在前置文档中，我们已经从 DockerHub 上拉取了 PolarDB 开发镜像，并且进入到了容器中。进入容器后，从 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上下载 PolarDB for PostgreSQL 的源代码，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 :::: code-group ::: code-group-item GitHub @@ -24,7 +24,7 @@ git clone -b POLARDB_11_STABLE https://github.com/ApsaraDB/PolarDB-for-PostgreSQ ``` ::: -::: code-group-item Gitee 国内镜像 +::: code-group-item Gitee ```bash:no-line-numbers git clone -b POLARDB_11_STABLE https://gitee.com/mirrors/PolarDB-for-PostgreSQL @@ -50,7 +50,7 @@ cd PolarDB-for-PostgreSQL/ ``` ::: warning -上述脚本在编译完成后，会自动部署一个基于 **本地文件系统** 的实例，运行于 `5432` 端口上。 +上述脚本在编译完成后，会自动部署一个基于 **单机文件系统** 的实例，运行于 `5432` 端口上。 手动键入以下命令停止这个实例，以便 **在 PFS 和共享存储上重新部署实例**： @@ -146,7 +146,7 @@ $HOME/tmp_basedir_polardb_pg_1100_bld/bin/psql \ ``` ::: warning -上述脚本在编译完成后，会自动部署一个基于 **本地文件系统** 的实例，运行于 `5432` 端口上。 +上述脚本在编译完成后，会自动部署一个基于 **单机文件系统** 的实例，运行于 `5432` 端口上。 手动键入以下命令停止这个实例，以便 **在 PFS 和共享存储上重新部署实例**： diff --git a/docs/deploying/db-pfs.md b/docs/deploying/db-pfs.md index ac657e18a01..0ec3ac6e35b 100644 --- a/docs/deploying/db-pfs.md +++ b/docs/deploying/db-pfs.md @@ -8,7 +8,7 @@ minute: 15 -本文将指导您在分布式文件系统 PolarDB File System（PFS）上编译部署 PolarDB，适用于已经在共享存储上格式化并挂载 PFS 文件系统的计算节点。 +本文将指导您在分布式文件系统 PolarDB File System（PFS）上编译部署 PolarDB-PG，适用于已经在共享存储上格式化并挂载 PFS 文件系统的计算节点。 [[toc]] diff --git a/docs/deploying/deploy.md b/docs/deploying/deploy.md index e2e6c0f844c..1e46c6040b9 100644 --- a/docs/deploying/deploy.md +++ b/docs/deploying/deploy.md @@ -14,17 +14,11 @@ minute: 10 2. **文件系统层**：由于 PostgreSQL 将数据存储在文件中，因此需要在块存储设备上架设文件系统。根据底层块存储设备的不同，可以选用单机文件系统（如 ext4）或分布式文件系统 [PolarDB File System（PFS）](https://github.com/ApsaraDB/PolarDB-FileSystem)。 3. **数据库层**：PolarDB for PostgreSQL 的编译和部署环境。 -以下表格给出了三个层次排列组合出的的不同实践方式，其中的步骤包含： - -- 存储层：块存储设备的准备 -- 文件系统：PolarDB File System 的编译、挂载 -- 数据库层：PolarDB for PostgreSQL 各集群形态的编译部署 - -我们强烈推荐使用发布在 DockerHub 上的 [PolarDB 开发镜像](https://hub.docker.com/r/polardb/polardb_pg_devel/tags) 来完成实践！开发镜像中已经包含了文件系统层和数据库层所需要安装的所有依赖，无需手动安装。 +以下表格给出了三个层次排列组合出的的不同实践方式： | | 块存储 | 文件系统 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------- | -| [实践 1（极简本地部署）](./db-localfs.md) | 本地 SSD | 本地文件系统（如 ext4） | +| [实践 1（极简本地部署）](./db-localfs.md) | 本地 SSD | 单机文件系统（如 ext4） | | [实践 2（生产环境最佳实践）](./storage-aliyun-essd.md) | 阿里云 ECS + ESSD 云盘 | PFS | | [实践 3（生产环境最佳实践）](./storage-curvebs.md) | [CurveBS](https://opencurve.io/Curve/HOME) 共享存储 | [PFS for Curve](https://github.com/opencurve/PolarDB-FileSystem) | | [实践 4](./storage-ceph.md) | Ceph 共享存储 | PFS | diff --git a/docs/deploying/fs-pfs.md b/docs/deploying/fs-pfs.md index 354d9d1f001..9d7db9fceaf 100644 --- a/docs/deploying/fs-pfs.md +++ b/docs/deploying/fs-pfs.md @@ -14,19 +14,39 @@ PolarDB File System，简称 PFS 或 PolarFS，是由阿里云自主研发的高 ## PFS 编译安装 -推荐使用 [DockerHub](https://hub.docker.com/u/polardb) 上的 PolarDB for PostgreSQL [可执行文件镜像](https://hub.docker.com/r/polardb/polardb_pg_binary/tags)，目前支持 `linux/amd64` 和 `linux/arm64` 两种架构，其中已经包含了编译完毕的 PFS 工具，无需手动编译安装。通过以下命令进入容器即可： +推荐使用 PolarDB-PG 的 [可执行文件镜像](https://hub.docker.com/r/polardb/polardb_pg_binary/tags)，目前支持 `linux/amd64` 和 `linux/arm64` 两种架构，其中已经包含了编译完毕的 PFS 工具，无需手动编译安装。通过以下命令进入容器即可： + +:::: code-group +::: code-group-item DockerHub + +```shell:no-line-numbers +docker pull polardb/polardb_pg_binary:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg \ + --shm-size=512m \ + polardb/polardb_pg_binary:11 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR ```shell:no-line-numbers -docker pull polardb/polardb_pg_binary +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg \ --shm-size=512m \ - polardb/polardb_pg_binary \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 \ bash ``` +::: +:::: + PFS 的手动编译安装方式请参考 PFS 的 [README](https://github.com/ApsaraDB/polardb-file-system/blob/master/Readme-CN.md)，此处不再赘述。 ## 块设备重命名 diff --git a/docs/deploying/introduction.md b/docs/deploying/introduction.md index 08c86095687..8f03ce8d20e 100644 --- a/docs/deploying/introduction.md +++ b/docs/deploying/introduction.md @@ -12,6 +12,6 @@ PolarDB for PostgreSQL 采用了基于 Shared-Storage 的存储计算分离架 ![software-level](../imgs/software-level.png) -为保证所有计算节点能够以相同的可见性视角访问分布式块存储设备，PolarDB 需要使用分布式文件系统 [PolarDB File System（PFS）](https://github.com/ApsaraDB/PolarDB-FileSystem) 来访问块设备，其实现原理可参考发表在 2018 年 VLDB 上的论文[^polarfs-paper]；如果所有计算节点都可以本地访问同一个块存储设备，那么也可以不使用 PFS，直接使用本地的单机文件系统（如 ext4）。这是与 PostgreSQL 的不同点之一。 +为保证所有计算节点能够以相同的可见性视角访问分布式块存储设备，PolarDB-PG 需要使用分布式文件系统 [PolarDB File System（PFS）](https://github.com/ApsaraDB/PolarDB-FileSystem) 来访问块设备，其实现原理可参考发表在 2018 年 VLDB 上的论文[^polarfs-paper]；如果所有计算节点都可以本地访问同一个块存储设备，那么也可以不使用 PFS，直接使用本地的单机文件系统（如 ext4）。这是与 PostgreSQL 的不同点之一。 [^polarfs-paper]: [PolarFS: an ultra-low latency and failure resilient distributed file system for shared storage cloud database](https://www.vldb.org/pvldb/vol11/p1849-cao.pdf) diff --git a/docs/deploying/quick-start.md b/docs/deploying/quick-start.md index b108c2cca70..1efbe7765f0 100644 --- a/docs/deploying/quick-start.md +++ b/docs/deploying/quick-start.md @@ -22,16 +22,33 @@ minute: 5 - CentOS：[在 CentOS 上安装 Docker Engine](https://docs.docker.com/engine/install/centos/) - RHEL：[在 RHEL 上安装 Docker Engine](https://docs.docker.com/engine/install/rhel/) - Fedora：[在 Fedora 上安装 Docker Engine](https://docs.docker.com/engine/install/fedora/) - - macOS（支持 M1 芯片）：[在 Mac 上安装 Docker Desktop](https://docs.docker.com/desktop/mac/install/)，并建议将内存调整为 4GB 以上 + - macOS：[在 Mac 上安装 Docker Desktop](https://docs.docker.com/desktop/mac/install/)，并建议将内存调整为 4GB 以上 - Windows：[在 Windows 上安装 Docker Desktop](https://docs.docker.com/desktop/windows/install/)，并建议将内存调整为 4GB 以上 -从 DockerHub 上拉取 PolarDB for PostgreSQL 的 [本地存储实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，创建并运行容器，然后直接试用 PolarDB-PG： +拉取 PolarDB for PostgreSQL 的 [单机实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，运行容器并试用 PolarDB-PG： + +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +# 拉取镜像并运行容器 +docker pull polardb/polardb_pg_local_instance:11 +docker run -it --rm polardb/polardb_pg_local_instance:11 psql +# 测试可用性 +postgres=# SELECT version(); + version +-------------------------------- + PostgreSQL 11.9 (POLARDB 11.9) +(1 row) +``` + +::: +::: code-group-item 阿里云 ACR ```bash:no-line-numbers -# 拉取 PolarDB-PG 镜像 -docker pull polardb/polardb_pg_local_instance -# 创建并运行容器 -docker run -it --rm polardb/polardb_pg_local_instance psql +# 拉取镜像并运行容器 +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 +docker run -it --rm registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 psql # 测试可用性 postgres=# SELECT version(); version @@ -39,3 +56,6 @@ postgres=# SELECT version(); PostgreSQL 11.9 (POLARDB 11.9) (1 row) ``` + +::: +:::: diff --git a/docs/development/customize-dev-env.md b/docs/development/customize-dev-env.md index d25cf3d305c..680b7158262 100644 --- a/docs/development/customize-dev-env.md +++ b/docs/development/customize-dev-env.md @@ -199,7 +199,7 @@ cd ~ 在 PolarDB for PostgreSQL 源码库根目录的 `deps/` 子目录下，放置了在各个 Linux 发行版上编译安装 PolarDB 和 PFS 需要运行的所有依赖。因此，首先需要克隆 PolarDB 的源码库。 -PolarDB for PostgreSQL 的代码托管于 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee 国内镜像](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 +PolarDB for PostgreSQL 的代码托管于 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 :::: code-group ::: code-group-item GitHub @@ -210,7 +210,7 @@ git clone -b POLARDB_11_STABLE https://github.com/ApsaraDB/PolarDB-for-PostgreSQ ``` ::: -::: code-group-item Gitee 国内镜像 +::: code-group-item Gitee ```bash:no-line-numbers sudo yum install -y git diff --git a/docs/development/dev-on-docker.md b/docs/development/dev-on-docker.md index e044c0e3f97..4587a6dccba 100644 --- a/docs/development/dev-on-docker.md +++ b/docs/development/dev-on-docker.md @@ -6,7 +6,7 @@ ## 在开发机器上下载源代码 -从 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上下载 PolarDB for PostgreSQL 的源代码，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee 国内镜像](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 +从 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上下载 PolarDB for PostgreSQL 的源代码，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 :::: code-group ::: code-group-item GitHub @@ -16,7 +16,7 @@ git clone -b POLARDB_11_STABLE https://github.com/ApsaraDB/PolarDB-for-PostgreSQ ``` ::: -::: code-group-item Gitee 国内镜像 +::: code-group-item Gitee ```bash:no-line-numbers git clone -b POLARDB_11_STABLE https://gitee.com/mirrors/PolarDB-for-PostgreSQL @@ -33,13 +33,25 @@ cd PolarDB-for-PostgreSQL/ ## 拉取开发镜像 -从 DockerHub 上拉取 PolarDB for PostgreSQL 的 [开发镜像](https://hub.docker.com/r/polardb/polardb_pg_devel/tags)。 +拉取 PolarDB-PG 的 [开发镜像](https://hub.docker.com/r/polardb/polardb_pg_devel/tags)。 -```bash -# 拉取 PolarDB 开发镜像 -docker pull polardb/polardb_pg_devel +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +docker pull polardb/polardb_pg_devel:ubuntu24.04 +``` + +::: +::: code-group-item 阿里云 ACR + +```bash:no-line-numbers +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_devel:ubuntu24.04 ``` +::: +:::: + ## 创建并运行容器 此时我们已经在开发机器的源码目录中。从开发镜像上创建一个容器，将当前目录作为一个 volume 挂载到容器中，这样可以： @@ -47,18 +59,36 @@ docker pull polardb/polardb_pg_devel - 在容器内的环境中编译源码 - 在容器外（开发机器上）使用编辑器来查看或修改代码 -```bash +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +docker run -it \ + -v $PWD:/home/postgres/polardb_pg \ + --shm-size=512m --cap-add=SYS_PTRACE --privileged=true \ + --name polardb_pg_devel \ + polardb/polardb_pg_devel:ubuntu24.04 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR + +```bash:no-line-numbers docker run -it \ -v $PWD:/home/postgres/polardb_pg \ --shm-size=512m --cap-add=SYS_PTRACE --privileged=true \ --name polardb_pg_devel \ - polardb/polardb_pg_devel \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_devel:ubuntu24.04 \ bash ``` +::: +:::: + 进入容器后，为容器内用户获取源码目录的权限，然后编译部署 PolarDB-PG 实例。 -```bash +```bash:no-line-numbers # 获取权限并编译部署 cd polardb_pg sudo chmod -R a+wr ./ diff --git a/docs/operation/ro-online-promote.md b/docs/operation/ro-online-promote.md index c74dd48bf50..7e1e5ea181f 100644 --- a/docs/operation/ro-online-promote.md +++ b/docs/operation/ro-online-promote.md @@ -16,19 +16,39 @@ PolarDB for PostgreSQL 是一款存储与计算分离的云原生数据库，所 ## 前置准备 -为方便起见，本示例使用基于本地磁盘的实例来进行演示。拉取如下镜像并启动容器，可以得到一个基于本地磁盘的 HTAP 实例： +为方便起见，本示例使用基于本地磁盘的实例来进行演示。拉取如下镜像并启动容器，可以得到一个单机的 HTAP 实例： + +:::: code-group +::: code-group-item DockerHub + +```shell:no-line-numbers +docker pull polardb/polardb_pg_local_instance:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg_htap \ + --shm-size=512m \ + polardb/polardb_pg_local_instance:11 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR ```shell:no-line-numbers -docker pull polardb/polardb_pg_local_instance +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg_htap \ --shm-size=512m \ - polardb/polardb_pg_local_instance \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 \ bash ``` +::: +:::: + 容器内的 `5432` 至 `5434` 端口分别运行着一个读写节点和两个只读节点。两个只读节点与读写节点共享同一份数据，并通过物理复制保持与读写节点的内存状态同步。 ## 验证只读节点不可写 diff --git a/docs/operation/scale-out.md b/docs/operation/scale-out.md index 6e97259903f..504711ae00a 100644 --- a/docs/operation/scale-out.md +++ b/docs/operation/scale-out.md @@ -14,18 +14,40 @@ PolarDB for PostgreSQL 是一款存储与计算分离的数据库，所有计算 ## 部署读写节点 -首先，在已经搭建完毕的共享存储集群上，初始化并启动第一个计算节点，即读写节点，该节点可以对共享存储进行读写。我们在下面的镜像中提供了已经编译完毕的 PolarDB for PostgreSQL 内核和周边工具的可执行文件： +首先，在已经搭建完毕的共享存储集群上，初始化并启动第一个计算节点，即读写节点，该节点可以对共享存储进行读写。我们在下面的镜像中提供了已经编译完毕的 PolarDB-PG 数据库和工具的可执行文件： + +:::: code-group +::: code-group-item DockerHub + +```shell:no-line-numbers +docker pull polardb/polardb_pg_binary:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg \ + --shm-size=512m \ + polardb/polardb_pg_binary:11 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR ```shell:no-line-numbers -$ docker pull polardb/polardb_pg_binary -$ docker run -it \ +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 +docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg \ --shm-size=512m \ - polardb/polardb_pg_binary \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 \ bash +``` + +::: +:::: +```shell:no-line-numbers $ ls ~/tmp_basedir_polardb_pg_1100_bld/bin/ clusterdb dropuser pg_basebackup pg_dump pg_resetwal pg_test_timing polar-initdb.sh psql createdb ecpg pgbench pg_dumpall pg_restore pg_upgrade polar-replica-initdb.sh reindexdb @@ -129,17 +151,37 @@ $HOME/tmp_basedir_polardb_pg_1100_bld/bin/psql \ 类似地，在用于部署新计算节点的机器上，拉取镜像并启动带有可执行文件的容器： +:::: code-group +::: code-group-item DockerHub + ```shell:no-line-numbers -docker pull polardb/polardb_pg_binary +docker pull polardb/polardb_pg_binary:11 docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg \ --shm-size=512m \ - polardb/polardb_pg_binary \ + polardb/polardb_pg_binary:11 \ bash ``` +::: +::: code-group-item 阿里云 ACR + +```shell:no-line-numbers +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg \ + --shm-size=512m \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 \ + bash +``` + +::: +:::: + ### 确认存储可访问 确保部署只读节点的机器也可以访问到共享存储的块设备： diff --git a/docs/operation/tpch-test.md b/docs/operation/tpch-test.md index 220559da726..07cf0f2d421 100644 --- a/docs/operation/tpch-test.md +++ b/docs/operation/tpch-test.md @@ -20,19 +20,39 @@ minute: 20 ### 部署 PolarDB-PG -使用 Docker 快速拉起一个基于本地存储的 PolarDB for PostgreSQL 集群： +使用 Docker 快速拉起一个单机的 PolarDB for PostgreSQL 集群： + +:::: code-group +::: code-group-item DockerHub + +```shell:no-line-numbers +docker pull polardb/polardb_pg_local_instance:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg_htap \ + --shm-size=512m \ + polardb/polardb_pg_local_instance:11 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR ```shell:no-line-numbers -docker pull polardb/polardb_pg_local_instance +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg_htap \ --shm-size=512m \ - polardb/polardb_pg_local_instance \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 \ bash ``` +::: +:::: + 或者参考 [进阶部署](../deploying/deploy.md) 部署一个基于共享存储的 PolarDB for PostgreSQL 集群。 ### 生成 TPC-H 测试数据集 diff --git a/docs/zh/README.md b/docs/zh/README.md index 0b9dae41464..1587cee575b 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -9,13 +9,30 @@ footer: Apache 2.0 Licensed | Copyright © Alibaba Group, Inc. ### 通过 Docker 快速使用 -从 DockerHub 上拉取 PolarDB for PostgreSQL 的 [本地存储实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，创建并运行容器，然后直接试用 PolarDB-PG： +拉取 PolarDB for PostgreSQL 的 [单机实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，运行容器并试用 PolarDB-PG： + +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +# 拉取镜像并运行容器 +docker pull polardb/polardb_pg_local_instance:11 +docker run -it --rm polardb/polardb_pg_local_instance:11 psql +# 测试可用性 +postgres=# SELECT version(); + version +-------------------------------- + PostgreSQL 11.9 (POLARDB 11.9) +(1 row) +``` + +::: +::: code-group-item 阿里云 ACR ```bash:no-line-numbers -# 拉取 PolarDB-PG 镜像 -docker pull polardb/polardb_pg_local_instance -# 创建并运行容器 -docker run -it --rm polardb/polardb_pg_local_instance psql +# 拉取镜像并运行容器 +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 +docker run -it --rm registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 psql # 测试可用性 postgres=# SELECT version(); version @@ -24,6 +41,9 @@ postgres=# SELECT version(); (1 row) ``` +::: +:::: +
diff --git a/docs/zh/deploying/db-localfs.md b/docs/zh/deploying/db-localfs.md index cb2b75b518e..09de80073d7 100644 --- a/docs/zh/deploying/db-localfs.md +++ b/docs/zh/deploying/db-localfs.md @@ -14,12 +14,25 @@ minute: 15 ## 拉取镜像 -我们在 DockerHub 上提供了 PolarDB-PG 的 [本地实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，里面已包含启动 PolarDB-PG 本地存储实例的入口脚本。镜像目前支持 `linux/amd64` 和 `linux/arm64` 两种 CPU 架构。 +我们已提供 PolarDB-PG 的 [单机实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，里面已包含启动 PolarDB-PG 单机实例的入口脚本。镜像目前支持 `linux/amd64` 和 `linux/arm64` 两种 CPU 架构。 + +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +docker pull polardb/polardb_pg_local_instance:11 +``` + +::: +::: code-group-item 阿里云 ACR ```bash:no-line-numbers -docker pull polardb/polardb_pg_local_instance +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 ``` +::: +:::: + ## 初始化数据库 新建一个空白目录 `${your_data_dir}` 作为 PolarDB-PG 实例的数据目录。启动容器时，将该目录作为 VOLUME 挂载到容器内，对数据目录进行初始化。在初始化的过程中，可以传入环境变量覆盖默认值： @@ -30,32 +43,83 @@ docker pull polardb/polardb_pg_local_instance 使用如下命令初始化数据库： +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +docker run -it --rm \ + --env POLARDB_PORT=5432 \ + --env POLARDB_USER=u1 \ + --env POLARDB_PASSWORD=your_password \ + -v ${your_data_dir}:/var/polardb \ + polardb/polardb_pg_local_instance:11 \ + echo 'done' +``` + +::: +::: code-group-item 阿里云 ACR + ```bash:no-line-numbers docker run -it --rm \ --env POLARDB_PORT=5432 \ --env POLARDB_USER=u1 \ --env POLARDB_PASSWORD=your_password \ -v ${your_data_dir}:/var/polardb \ - polardb/polardb_pg_local_instance \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 \ echo 'done' ``` +::: +:::: + ## 启动 PolarDB-PG 服务 数据库初始化完毕后，使用 `-d` 参数以后台模式创建容器，启动 PolarDB-PG 服务。通常 PolarDB-PG 的端口需要暴露给外界使用，使用 `-p` 参数将容器内的端口范围暴露到容器外。比如，初始化数据库时使用的是 `5432-5434` 端口，如下命令将会把这三个端口映射到容器外的 `54320-54322` 端口： +:::: code-group +::: code-group-item DockerHub + ```bash:no-line-numbers docker run -d \ -p 54320-54322:5432-5434 \ -v ${your_data_dir}:/var/polardb \ - polardb/polardb_pg_local_instance + polardb/polardb_pg_local_instance:11 ``` +::: +::: code-group-item 阿里云 ACR + +```bash:no-line-numbers +docker run -d \ + -p 54320-54322:5432-5434 \ + -v ${your_data_dir}:/var/polardb \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 +``` + +::: +:::: + 或者也可以直接让容器与宿主机共享网络： +:::: code-group +::: code-group-item DockerHub + ```bash:no-line-numbers docker run -d \ --network=host \ -v ${your_data_dir}:/var/polardb \ - polardb/polardb_pg_local_instance + polardb/polardb_pg_local_instance:11 ``` + +::: +::: code-group-item 阿里云 ACR + +```bash:no-line-numbers +docker run -d \ + --network=host \ + -v ${your_data_dir}:/var/polardb \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 +``` + +::: +:::: diff --git a/docs/zh/deploying/db-pfs-curve.md b/docs/zh/deploying/db-pfs-curve.md index aa6a7668aa7..32e72dccf85 100644 --- a/docs/zh/deploying/db-pfs-curve.md +++ b/docs/zh/deploying/db-pfs-curve.md @@ -14,7 +14,7 @@ minute: 15 ## 源码下载 -在前置文档中，我们已经从 DockerHub 上拉取了 PolarDB 开发镜像，并且进入到了容器中。进入容器后，从 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上下载 PolarDB for PostgreSQL 的源代码，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee 国内镜像](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 +在前置文档中，我们已经从 DockerHub 上拉取了 PolarDB 开发镜像，并且进入到了容器中。进入容器后，从 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上下载 PolarDB for PostgreSQL 的源代码，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 :::: code-group ::: code-group-item GitHub @@ -24,7 +24,7 @@ git clone -b POLARDB_11_STABLE https://github.com/ApsaraDB/PolarDB-for-PostgreSQ ``` ::: -::: code-group-item Gitee 国内镜像 +::: code-group-item Gitee ```bash:no-line-numbers git clone -b POLARDB_11_STABLE https://gitee.com/mirrors/PolarDB-for-PostgreSQL @@ -50,7 +50,7 @@ cd PolarDB-for-PostgreSQL/ ``` ::: warning -上述脚本在编译完成后，会自动部署一个基于 **本地文件系统** 的实例，运行于 `5432` 端口上。 +上述脚本在编译完成后，会自动部署一个基于 **单机文件系统** 的实例，运行于 `5432` 端口上。 手动键入以下命令停止这个实例，以便 **在 PFS 和共享存储上重新部署实例**： @@ -146,7 +146,7 @@ $HOME/tmp_basedir_polardb_pg_1100_bld/bin/psql \ ``` ::: warning -上述脚本在编译完成后，会自动部署一个基于 **本地文件系统** 的实例，运行于 `5432` 端口上。 +上述脚本在编译完成后，会自动部署一个基于 **单机文件系统** 的实例，运行于 `5432` 端口上。 手动键入以下命令停止这个实例，以便 **在 PFS 和共享存储上重新部署实例**： diff --git a/docs/zh/deploying/db-pfs.md b/docs/zh/deploying/db-pfs.md index ac657e18a01..0ec3ac6e35b 100644 --- a/docs/zh/deploying/db-pfs.md +++ b/docs/zh/deploying/db-pfs.md @@ -8,7 +8,7 @@ minute: 15 -本文将指导您在分布式文件系统 PolarDB File System（PFS）上编译部署 PolarDB，适用于已经在共享存储上格式化并挂载 PFS 文件系统的计算节点。 +本文将指导您在分布式文件系统 PolarDB File System（PFS）上编译部署 PolarDB-PG，适用于已经在共享存储上格式化并挂载 PFS 文件系统的计算节点。 [[toc]] diff --git a/docs/zh/deploying/deploy.md b/docs/zh/deploying/deploy.md index e2e6c0f844c..1e46c6040b9 100644 --- a/docs/zh/deploying/deploy.md +++ b/docs/zh/deploying/deploy.md @@ -14,17 +14,11 @@ minute: 10 2. **文件系统层**：由于 PostgreSQL 将数据存储在文件中，因此需要在块存储设备上架设文件系统。根据底层块存储设备的不同，可以选用单机文件系统（如 ext4）或分布式文件系统 [PolarDB File System（PFS）](https://github.com/ApsaraDB/PolarDB-FileSystem)。 3. **数据库层**：PolarDB for PostgreSQL 的编译和部署环境。 -以下表格给出了三个层次排列组合出的的不同实践方式，其中的步骤包含： - -- 存储层：块存储设备的准备 -- 文件系统：PolarDB File System 的编译、挂载 -- 数据库层：PolarDB for PostgreSQL 各集群形态的编译部署 - -我们强烈推荐使用发布在 DockerHub 上的 [PolarDB 开发镜像](https://hub.docker.com/r/polardb/polardb_pg_devel/tags) 来完成实践！开发镜像中已经包含了文件系统层和数据库层所需要安装的所有依赖，无需手动安装。 +以下表格给出了三个层次排列组合出的的不同实践方式： | | 块存储 | 文件系统 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------- | -| [实践 1（极简本地部署）](./db-localfs.md) | 本地 SSD | 本地文件系统（如 ext4） | +| [实践 1（极简本地部署）](./db-localfs.md) | 本地 SSD | 单机文件系统（如 ext4） | | [实践 2（生产环境最佳实践）](./storage-aliyun-essd.md) | 阿里云 ECS + ESSD 云盘 | PFS | | [实践 3（生产环境最佳实践）](./storage-curvebs.md) | [CurveBS](https://opencurve.io/Curve/HOME) 共享存储 | [PFS for Curve](https://github.com/opencurve/PolarDB-FileSystem) | | [实践 4](./storage-ceph.md) | Ceph 共享存储 | PFS | diff --git a/docs/zh/deploying/fs-pfs.md b/docs/zh/deploying/fs-pfs.md index 354d9d1f001..9d7db9fceaf 100644 --- a/docs/zh/deploying/fs-pfs.md +++ b/docs/zh/deploying/fs-pfs.md @@ -14,19 +14,39 @@ PolarDB File System，简称 PFS 或 PolarFS，是由阿里云自主研发的高 ## PFS 编译安装 -推荐使用 [DockerHub](https://hub.docker.com/u/polardb) 上的 PolarDB for PostgreSQL [可执行文件镜像](https://hub.docker.com/r/polardb/polardb_pg_binary/tags)，目前支持 `linux/amd64` 和 `linux/arm64` 两种架构，其中已经包含了编译完毕的 PFS 工具，无需手动编译安装。通过以下命令进入容器即可： +推荐使用 PolarDB-PG 的 [可执行文件镜像](https://hub.docker.com/r/polardb/polardb_pg_binary/tags)，目前支持 `linux/amd64` 和 `linux/arm64` 两种架构，其中已经包含了编译完毕的 PFS 工具，无需手动编译安装。通过以下命令进入容器即可： + +:::: code-group +::: code-group-item DockerHub + +```shell:no-line-numbers +docker pull polardb/polardb_pg_binary:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg \ + --shm-size=512m \ + polardb/polardb_pg_binary:11 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR ```shell:no-line-numbers -docker pull polardb/polardb_pg_binary +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg \ --shm-size=512m \ - polardb/polardb_pg_binary \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 \ bash ``` +::: +:::: + PFS 的手动编译安装方式请参考 PFS 的 [README](https://github.com/ApsaraDB/polardb-file-system/blob/master/Readme-CN.md)，此处不再赘述。 ## 块设备重命名 diff --git a/docs/zh/deploying/introduction.md b/docs/zh/deploying/introduction.md index a5d1f563303..e9e6a0bdad1 100644 --- a/docs/zh/deploying/introduction.md +++ b/docs/zh/deploying/introduction.md @@ -12,6 +12,6 @@ PolarDB for PostgreSQL 采用了基于 Shared-Storage 的存储计算分离架 ![software-level](../imgs/software-level.png) -为保证所有计算节点能够以相同的可见性视角访问分布式块存储设备，PolarDB 需要使用分布式文件系统 [PolarDB File System（PFS）](https://github.com/ApsaraDB/PolarDB-FileSystem) 来访问块设备，其实现原理可参考发表在 2018 年 VLDB 上的论文[^polarfs-paper]；如果所有计算节点都可以本地访问同一个块存储设备，那么也可以不使用 PFS，直接使用本地的单机文件系统（如 ext4）。这是与 PostgreSQL 的不同点之一。 +为保证所有计算节点能够以相同的可见性视角访问分布式块存储设备，PolarDB-PG 需要使用分布式文件系统 [PolarDB File System（PFS）](https://github.com/ApsaraDB/PolarDB-FileSystem) 来访问块设备，其实现原理可参考发表在 2018 年 VLDB 上的论文[^polarfs-paper]；如果所有计算节点都可以本地访问同一个块存储设备，那么也可以不使用 PFS，直接使用本地的单机文件系统（如 ext4）。这是与 PostgreSQL 的不同点之一。 [^polarfs-paper]: [PolarFS: an ultra-low latency and failure resilient distributed file system for shared storage cloud database](https://www.vldb.org/pvldb/vol11/p1849-cao.pdf) diff --git a/docs/zh/deploying/quick-start.md b/docs/zh/deploying/quick-start.md index b108c2cca70..1efbe7765f0 100644 --- a/docs/zh/deploying/quick-start.md +++ b/docs/zh/deploying/quick-start.md @@ -22,16 +22,33 @@ minute: 5 - CentOS：[在 CentOS 上安装 Docker Engine](https://docs.docker.com/engine/install/centos/) - RHEL：[在 RHEL 上安装 Docker Engine](https://docs.docker.com/engine/install/rhel/) - Fedora：[在 Fedora 上安装 Docker Engine](https://docs.docker.com/engine/install/fedora/) - - macOS（支持 M1 芯片）：[在 Mac 上安装 Docker Desktop](https://docs.docker.com/desktop/mac/install/)，并建议将内存调整为 4GB 以上 + - macOS：[在 Mac 上安装 Docker Desktop](https://docs.docker.com/desktop/mac/install/)，并建议将内存调整为 4GB 以上 - Windows：[在 Windows 上安装 Docker Desktop](https://docs.docker.com/desktop/windows/install/)，并建议将内存调整为 4GB 以上 -从 DockerHub 上拉取 PolarDB for PostgreSQL 的 [本地存储实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，创建并运行容器，然后直接试用 PolarDB-PG： +拉取 PolarDB for PostgreSQL 的 [单机实例镜像](https://hub.docker.com/r/polardb/polardb_pg_local_instance/tags)，运行容器并试用 PolarDB-PG： + +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +# 拉取镜像并运行容器 +docker pull polardb/polardb_pg_local_instance:11 +docker run -it --rm polardb/polardb_pg_local_instance:11 psql +# 测试可用性 +postgres=# SELECT version(); + version +-------------------------------- + PostgreSQL 11.9 (POLARDB 11.9) +(1 row) +``` + +::: +::: code-group-item 阿里云 ACR ```bash:no-line-numbers -# 拉取 PolarDB-PG 镜像 -docker pull polardb/polardb_pg_local_instance -# 创建并运行容器 -docker run -it --rm polardb/polardb_pg_local_instance psql +# 拉取镜像并运行容器 +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 +docker run -it --rm registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 psql # 测试可用性 postgres=# SELECT version(); version @@ -39,3 +56,6 @@ postgres=# SELECT version(); PostgreSQL 11.9 (POLARDB 11.9) (1 row) ``` + +::: +:::: diff --git a/docs/zh/development/customize-dev-env.md b/docs/zh/development/customize-dev-env.md index d25cf3d305c..680b7158262 100644 --- a/docs/zh/development/customize-dev-env.md +++ b/docs/zh/development/customize-dev-env.md @@ -199,7 +199,7 @@ cd ~ 在 PolarDB for PostgreSQL 源码库根目录的 `deps/` 子目录下，放置了在各个 Linux 发行版上编译安装 PolarDB 和 PFS 需要运行的所有依赖。因此，首先需要克隆 PolarDB 的源码库。 -PolarDB for PostgreSQL 的代码托管于 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee 国内镜像](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 +PolarDB for PostgreSQL 的代码托管于 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 :::: code-group ::: code-group-item GitHub @@ -210,7 +210,7 @@ git clone -b POLARDB_11_STABLE https://github.com/ApsaraDB/PolarDB-for-PostgreSQ ``` ::: -::: code-group-item Gitee 国内镜像 +::: code-group-item Gitee ```bash:no-line-numbers sudo yum install -y git diff --git a/docs/zh/development/dev-on-docker.md b/docs/zh/development/dev-on-docker.md index e044c0e3f97..4587a6dccba 100644 --- a/docs/zh/development/dev-on-docker.md +++ b/docs/zh/development/dev-on-docker.md @@ -6,7 +6,7 @@ ## 在开发机器上下载源代码 -从 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上下载 PolarDB for PostgreSQL 的源代码，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee 国内镜像](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 +从 [GitHub](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL) 上下载 PolarDB for PostgreSQL 的源代码，稳定分支为 `POLARDB_11_STABLE`。如果因网络原因不能稳定访问 GitHub，则可以访问 [Gitee](https://gitee.com/mirrors/PolarDB-for-PostgreSQL)。 :::: code-group ::: code-group-item GitHub @@ -16,7 +16,7 @@ git clone -b POLARDB_11_STABLE https://github.com/ApsaraDB/PolarDB-for-PostgreSQ ``` ::: -::: code-group-item Gitee 国内镜像 +::: code-group-item Gitee ```bash:no-line-numbers git clone -b POLARDB_11_STABLE https://gitee.com/mirrors/PolarDB-for-PostgreSQL @@ -33,13 +33,25 @@ cd PolarDB-for-PostgreSQL/ ## 拉取开发镜像 -从 DockerHub 上拉取 PolarDB for PostgreSQL 的 [开发镜像](https://hub.docker.com/r/polardb/polardb_pg_devel/tags)。 +拉取 PolarDB-PG 的 [开发镜像](https://hub.docker.com/r/polardb/polardb_pg_devel/tags)。 -```bash -# 拉取 PolarDB 开发镜像 -docker pull polardb/polardb_pg_devel +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +docker pull polardb/polardb_pg_devel:ubuntu24.04 +``` + +::: +::: code-group-item 阿里云 ACR + +```bash:no-line-numbers +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_devel:ubuntu24.04 ``` +::: +:::: + ## 创建并运行容器 此时我们已经在开发机器的源码目录中。从开发镜像上创建一个容器，将当前目录作为一个 volume 挂载到容器中，这样可以： @@ -47,18 +59,36 @@ docker pull polardb/polardb_pg_devel - 在容器内的环境中编译源码 - 在容器外（开发机器上）使用编辑器来查看或修改代码 -```bash +:::: code-group +::: code-group-item DockerHub + +```bash:no-line-numbers +docker run -it \ + -v $PWD:/home/postgres/polardb_pg \ + --shm-size=512m --cap-add=SYS_PTRACE --privileged=true \ + --name polardb_pg_devel \ + polardb/polardb_pg_devel:ubuntu24.04 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR + +```bash:no-line-numbers docker run -it \ -v $PWD:/home/postgres/polardb_pg \ --shm-size=512m --cap-add=SYS_PTRACE --privileged=true \ --name polardb_pg_devel \ - polardb/polardb_pg_devel \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_devel:ubuntu24.04 \ bash ``` +::: +:::: + 进入容器后，为容器内用户获取源码目录的权限，然后编译部署 PolarDB-PG 实例。 -```bash +```bash:no-line-numbers # 获取权限并编译部署 cd polardb_pg sudo chmod -R a+wr ./ diff --git a/docs/zh/operation/ro-online-promote.md b/docs/zh/operation/ro-online-promote.md index c74dd48bf50..7e1e5ea181f 100644 --- a/docs/zh/operation/ro-online-promote.md +++ b/docs/zh/operation/ro-online-promote.md @@ -16,19 +16,39 @@ PolarDB for PostgreSQL 是一款存储与计算分离的云原生数据库，所 ## 前置准备 -为方便起见，本示例使用基于本地磁盘的实例来进行演示。拉取如下镜像并启动容器，可以得到一个基于本地磁盘的 HTAP 实例： +为方便起见，本示例使用基于本地磁盘的实例来进行演示。拉取如下镜像并启动容器，可以得到一个单机的 HTAP 实例： + +:::: code-group +::: code-group-item DockerHub + +```shell:no-line-numbers +docker pull polardb/polardb_pg_local_instance:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg_htap \ + --shm-size=512m \ + polardb/polardb_pg_local_instance:11 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR ```shell:no-line-numbers -docker pull polardb/polardb_pg_local_instance +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg_htap \ --shm-size=512m \ - polardb/polardb_pg_local_instance \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 \ bash ``` +::: +:::: + 容器内的 `5432` 至 `5434` 端口分别运行着一个读写节点和两个只读节点。两个只读节点与读写节点共享同一份数据，并通过物理复制保持与读写节点的内存状态同步。 ## 验证只读节点不可写 diff --git a/docs/zh/operation/scale-out.md b/docs/zh/operation/scale-out.md index 6e97259903f..504711ae00a 100644 --- a/docs/zh/operation/scale-out.md +++ b/docs/zh/operation/scale-out.md @@ -14,18 +14,40 @@ PolarDB for PostgreSQL 是一款存储与计算分离的数据库，所有计算 ## 部署读写节点 -首先，在已经搭建完毕的共享存储集群上，初始化并启动第一个计算节点，即读写节点，该节点可以对共享存储进行读写。我们在下面的镜像中提供了已经编译完毕的 PolarDB for PostgreSQL 内核和周边工具的可执行文件： +首先，在已经搭建完毕的共享存储集群上，初始化并启动第一个计算节点，即读写节点，该节点可以对共享存储进行读写。我们在下面的镜像中提供了已经编译完毕的 PolarDB-PG 数据库和工具的可执行文件： + +:::: code-group +::: code-group-item DockerHub + +```shell:no-line-numbers +docker pull polardb/polardb_pg_binary:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg \ + --shm-size=512m \ + polardb/polardb_pg_binary:11 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR ```shell:no-line-numbers -$ docker pull polardb/polardb_pg_binary -$ docker run -it \ +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 +docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg \ --shm-size=512m \ - polardb/polardb_pg_binary \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 \ bash +``` + +::: +:::: +```shell:no-line-numbers $ ls ~/tmp_basedir_polardb_pg_1100_bld/bin/ clusterdb dropuser pg_basebackup pg_dump pg_resetwal pg_test_timing polar-initdb.sh psql createdb ecpg pgbench pg_dumpall pg_restore pg_upgrade polar-replica-initdb.sh reindexdb @@ -129,17 +151,37 @@ $HOME/tmp_basedir_polardb_pg_1100_bld/bin/psql \ 类似地，在用于部署新计算节点的机器上，拉取镜像并启动带有可执行文件的容器： +:::: code-group +::: code-group-item DockerHub + ```shell:no-line-numbers -docker pull polardb/polardb_pg_binary +docker pull polardb/polardb_pg_binary:11 docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg \ --shm-size=512m \ - polardb/polardb_pg_binary \ + polardb/polardb_pg_binary:11 \ bash ``` +::: +::: code-group-item 阿里云 ACR + +```shell:no-line-numbers +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg \ + --shm-size=512m \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_binary:11 \ + bash +``` + +::: +:::: + ### 确认存储可访问 确保部署只读节点的机器也可以访问到共享存储的块设备： diff --git a/docs/zh/operation/tpch-test.md b/docs/zh/operation/tpch-test.md index 220559da726..07cf0f2d421 100644 --- a/docs/zh/operation/tpch-test.md +++ b/docs/zh/operation/tpch-test.md @@ -20,19 +20,39 @@ minute: 20 ### 部署 PolarDB-PG -使用 Docker 快速拉起一个基于本地存储的 PolarDB for PostgreSQL 集群： +使用 Docker 快速拉起一个单机的 PolarDB for PostgreSQL 集群： + +:::: code-group +::: code-group-item DockerHub + +```shell:no-line-numbers +docker pull polardb/polardb_pg_local_instance:11 +docker run -it \ + --cap-add=SYS_PTRACE \ + --privileged=true \ + --name polardb_pg_htap \ + --shm-size=512m \ + polardb/polardb_pg_local_instance:11 \ + bash +``` + +::: +::: code-group-item 阿里云 ACR ```shell:no-line-numbers -docker pull polardb/polardb_pg_local_instance +docker pull registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 docker run -it \ --cap-add=SYS_PTRACE \ --privileged=true \ --name polardb_pg_htap \ --shm-size=512m \ - polardb/polardb_pg_local_instance \ + registry.cn-hangzhou.aliyuncs.com/polardb_pg/polardb_pg_local_instance:11 \ bash ``` +::: +:::: + 或者参考 [进阶部署](../deploying/deploy.md) 部署一个基于共享存储的 PolarDB for PostgreSQL 集群。 ### 生成 TPC-H 测试数据集 diff --git a/docs/zh/theory/arch-overview.md b/docs/zh/theory/arch-overview.md index 24fb09e4c30..00178826048 100644 --- a/docs/zh/theory/arch-overview.md +++ b/docs/zh/theory/arch-overview.md @@ -178,9 +178,9 @@ PolarDB 支持一套 OLTP 场景型的数据在如下两种计算引擎下使用 ![image.png](../imgs/11_issues_of_conventional_streaming_replication.png) -1. 主节点写入 WAL 日志到本地文件系统中。 +1. 主节点写入 WAL 日志到单机文件系统中。 1. WAL Sender 进程读取，并发送。 -1. 只读节点的 WAL Receiver 进程接收写入到本地文件系统中。 +1. 只读节点的 WAL Receiver 进程接收写入到单机文件系统中。 1. 回放进程读取 WAL 日志，读取对应的 Page 到 BufferPool 中，并在内存中回放。 1. 主节点刷脏页到 Shared Storage。