Merge pull request #499 from ApsaraDB/POLARDB_11_DEV

merge: 20240407

.github/workflows/docs-format-check.yml

@@ -21,27 +21,21 @@ jobs:
           # fetch all commits to get last updated time or other git log info
           fetch-depth: 0
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          # choose pnpm version to use
+          version: 8
+          # install deps with pnpm
+          run_install: true
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           # choose node.js version to use
-          node-version: "16"
-
-      # cache node_modules
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        id: yarn-cache
-        with:
-          path: |
-            **/node_modules
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-
-      # install dependencies if the cache did not hit
-      - name: Install dependencies
-        if: steps.yarn-cache.outputs.cache-hit != 'true'
-        run: yarn --frozen-lockfile
+          node-version: 20
+          # cache deps for pnpm
+          cache: pnpm
 
       - name: Prettier check
-        run: npx prettier --check docs/
+        run: pnpm prettier:check

.github/workflows/docs.yml

@@ -21,31 +21,25 @@ jobs:
           # fetch all commits to get last updated time or other git log info
           fetch-depth: 0
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          # choose pnpm version to use
+          version: 8
+          # install deps with pnpm
+          run_install: true
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           # choose node.js version to use
-          node-version: "16"
-
-      # cache node_modules
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        id: yarn-cache
-        with:
-          path: |
-            **/node_modules
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-
-      # install dependencies if the cache did not hit
-      - name: Install dependencies
-        if: steps.yarn-cache.outputs.cache-hit != 'true'
-        run: yarn --frozen-lockfile
+          node-version: 20
+          # cache deps for pnpm
+          cache: pnpm
 
       # run build script
       - name: Build VuePress site
-        run: yarn docs:build
+        run: pnpm docs:build
 
       # please check out the docs of the workflow for more details
       # @see https://github.com/crazy-max/ghaction-github-pages

README-CN.md

@@ -29,14 +29,14 @@
 PolarDB for PostgreSQL（下文简称为 PolarDB）是一款阿里云自主研发的云原生数据库产品，100% 兼容 PostgreSQL，采用基于 Shared-Storage 的存储计算分离架构，具有极致弹性、毫秒级延迟、HTAP 的能力。
 
 1. 极致弹性：存储与计算能力均可独立地横向扩展。
-   - 当计算能力不够时，可以单独扩展计算集群，数据无需复制。
-   - 当存储容量或 I/O 不够时，可以单独扩展存储集群，而不中断业务。
+   - 当计算能力不够时，可以单独扩展计算集群，数据无需复制
+   - 当存储容量或 I/O 不够时，可以单独扩展存储集群，而不中断业务
 2. 毫秒级延迟：
-   - WAL 日志存储在共享存储上，RW 到所有 RO 之间仅复制 WAL 的元数据。
-   - 独创的 _LogIndex_ 技术，实现了 Lazy 回放和 Parallel 回放，理论上最大程度地缩小了 RW 和 RO 节点间的延迟。
+   - WAL 日志存储在共享存储上，RW 到所有 RO 之间仅复制 WAL 日志的元数据
+   - 独创的 _LogIndex_ 技术，实现了 Lazy 回放和 Parallel 回放，最大程度地缩小了 RW 和 RO 节点间的延迟
 3. HTAP 能力：基于 Shared-Storage 的分布式并行执行框架，加速在 OLTP 场景下的 OLAP 查询。一套 OLTP 型的数据，可支持 2 套计算引擎：
-   - 单机执行引擎：处理高并发的 TP 型负载。
-   - 分布式执行引擎：处理大查询的 AP 型负载。
+   - 单机执行引擎：处理高并发的 TP 型负载
+   - 分布式执行引擎：处理大查询的 AP 型负载
 
 PolarDB 还支持时空、GIS、图像、向量、搜索、图谱等多模创新特性，应对企业对数据处理日新月异的需求。
 
@@ -46,13 +46,13 @@ PolarDB 还支持时空、GIS、图像、向量、搜索、图谱等多模创新
 
 ## 产品架构
 
-PolarDB 采用了基于 Shared-Storage 的存储计算分离架构。数据库由传统的 Share-Nothing 架构，转变成了 Shared-Storage 架构。由原来的 N 份计算 + N 份存储，转变成了 N 份计算 + 1 份存储。虽然共享存储上数据是一份，但是数据在各节点内存中的状态是不同的，需要通过内存状态的同步来维护数据的一致性；同时主节点在刷脏时也需要做协调，避免只读节点读取到超前的 **“未来页面”**，也要避免只读节点读取到过时的没有在内存中被正确回放的 **“过去页面”**。为了解决该问题，PolarDB 创造性地设计了 _LogIndex_ 数据结构来维护页面的回放历史，该结构能够实现主节点与只读节点之间的同步。
+PolarDB for PostgreSQL 采用了基于 Shared-Storage 的存储计算分离架构。数据库由传统的 Share-Nothing 架构，转变成了 Shared-Storage 架构。由原来的 N 份计算 + N 份存储，转变成了 N 份计算 + 1 份存储。虽然共享存储上数据是一份，但是数据在各节点内存中的状态是不同的，需要通过内存状态的同步来维护数据的一致性；同时主节点在刷脏时也需要做协调，避免只读节点读取到超前的 **“未来页面”**，也要避免只读节点读取到过时的没有在内存中被正确回放的 **“过去页面”**。为了解决该问题，PolarDB 创造性地设计了 _LogIndex_ 数据结构来维护页面的回放历史，该结构能够实现主节点与只读节点之间的同步。
 
 在存储计算分离后，I/O 单路延迟变大的同时，I/O 的吞吐也变大了。在处理分析型查询时，仅使用单个只读节点无法发挥出存储侧的大 I/O 带宽优势，也无法利用其他只读节点的 CPU、内存和 I/O 资源。为了解决该问题，PolarDB 研发了基于 Shared-Storage 的并行执行引擎，能够在 SQL 级别上弹性利用任意数目的 CPU 来加速分析查询，支持 HTAP 的混合负载场景。
 
 详情请查阅 [产品架构](https://apsaradb.github.io/PolarDB-for-PostgreSQL/zh/theory/arch-overview.html)。
 
-## 快速入门
+## 快速部署
 
 如果您已安装 Docker，那么可以从 DockerHub 上拉取 PolarDB for PostgreSQL 的 本地存储实例镜像，创建、运行并进入容器，然后直接使用 PolarDB 实例：
 
@@ -69,7 +69,11 @@ postgres=# SELECT version();
 (1 row)
 ```
 
-对于更多进阶部署方式，请移步在线文档中的 [进阶部署](https://apsaradb.github.io/PolarDB-for-PostgreSQL/zh/deploying/deploy.html)。在部署前，我们建议您先了解一下 PolarDB for PostgreSQL 的 [架构简介](https://apsaradb.github.io/PolarDB-for-PostgreSQL/zh/deploying/introduction.html)。
+对于更多进阶部署方式，请移步在线文档中的 [进阶部署](https://apsaradb.github.io/PolarDB-for-PostgreSQL/zh/deploying/deploy.html)。在部署前，了解 PolarDB for PostgreSQL 的 [架构简介](https://apsaradb.github.io/PolarDB-for-PostgreSQL/zh/deploying/introduction.html) 能够深化对每个步骤的理解。
+
+## 开发
+
+参考 [开发指南](https://apsaradb.github.io/PolarDB-for-PostgreSQL/zh/development/dev-on-docker.html) 进行源码编译和开发。
 
 ## 文档
 
@@ -79,7 +83,7 @@ postgres=# SELECT version();
 
 ## 参与贡献
 
-我们诚挚欢迎社区参与 PolarDB 的贡献，无论是代码还是文档。
+我们诚挚欢迎社区参与 PolarDB for PostgreSQL 的贡献，无论是代码还是文档。
 
 以下是贡献者列表（由 [contrib.rocks](https://contrib.rocks) 支持）：
 

README.md

@@ -46,7 +46,7 @@ The `POLARDB_11_STABLE` is the stable branch based on PostgreSQL 11.9, which sup
 
 ## Architecture and Roadmap
 
-PolarDB uses a shared-storage-based architecture in which computing is decoupled from storage. The conventional shared-nothing architecture is changed to the shared-storage architecture. N copies of data in the compute cluster and N copies of data in the storage cluster are changed to N copies of data in the compute cluster and one copy of data in the storage cluster. The shared storage stores one copy of data, but the data states in memory are different. The WAL logs must be synchronized from the primary node to read-only nodes to ensure data consistency. In addition, when the primary node flushes dirty pages, it must be controlled to prevent the read-only nodes from reading future pages. Meanwhile, the read-only nodes must be prevented from reading the outdated pages that are not correctly replayed in memory. To resolve this issue, PolarDB provides the index structure _LogIndex_ to maintain the page replay history. LogIndex can be used to synchronize data from the primary node to read-only nodes.
+PolarDB for PostgreSQL uses a shared-storage-based architecture in which computing is decoupled from storage. The conventional shared-nothing architecture is changed to the shared-storage architecture. N copies of data in the compute cluster and N copies of data in the storage cluster are changed to N copies of data in the compute cluster and one copy of data in the storage cluster. The shared storage stores one copy of data, but the data states in memory are different. The WAL logs must be synchronized from the primary node to read-only nodes to ensure data consistency. In addition, when the primary node flushes dirty pages, it must be controlled to prevent the read-only nodes from reading future pages. Meanwhile, the read-only nodes must be prevented from reading the outdated pages that are not correctly replayed in memory. To resolve this issue, PolarDB provides the index structure _LogIndex_ to maintain the page replay history. LogIndex can be used to synchronize data from the primary node to read-only nodes.
 
 After computing is decoupled from storage, the I/O latency and throughput increase. When a single read-only node is used to process analytical queries, the CPUs, memory, and I/O of other read-only nodes and the large storage I/O bandwidth cannot be fully utilized. To resolve this issue, PolarDB provides the shared-storage-based MPP engine. The engine can use CPUs to accelerate analytical queries at SQL level and support a mix of OLAP workloads and OLTP workloads for HTAP.
 
@@ -71,6 +71,10 @@ postgres=# SELECT version();
 
 For more advanced deployment way, please refer to [Advanced Deployment](https://apsaradb.github.io/PolarDB-for-PostgreSQL/deploying/deploy.html). Before your deployment, we recommand to figure out the [architecture](https://apsaradb.github.io/PolarDB-for-PostgreSQL/deploying/introduction.html) of PolarDB for PostgreSQL.
 
+## Development
+
+Please refer to [Development Guide](https://apsaradb.github.io/PolarDB-for-PostgreSQL/development/dev-on-docker.html) to compile and development PolarDB for PostgreSQL.
+
 ## Documentation
 
 Please refer to [Online Documentation Website](https://apsaradb.github.io/PolarDB-for-PostgreSQL/) to see the whole documentations.
@@ -79,7 +83,7 @@ If you want to explore or develop documentation locally, see [Document Contribut
 
 ## Contributing
 
-You are welcome to make contributions to PolarDB, no matter code or documentation.
+You are welcome to make contributions to PolarDB for PostgreSQL, no matter code or documentation.
 
 Here are the contributors:
 

docs/.vuepress/components/ArticleInfo.vue

@@ -11,7 +11,7 @@ const { frontmatter } = toRefs(props);
 </script>
 
 <style>
-.line {
+.info_line {
   display: flex;
   flex-direction: row;
   align-items: center;
@@ -28,8 +28,8 @@ const { frontmatter } = toRefs(props);
 </style>
 
 <template>
-  <div class="line">
-    <div v-if="frontmatter.author" class="line container">
+  <div class="info_line">
+    <div v-if="frontmatter.author" class="info_line container">
       <svg
         t="1658821554263"
         class="icon"
@@ -48,7 +48,7 @@ const { frontmatter } = toRefs(props);
       </svg>
       <p class="text">{{ frontmatter.author }}</p>
     </div>
-    <div v-if="frontmatter.date" class="line container">
+    <div v-if="frontmatter.date" class="info_line container">
       <svg
         t="1658821678607"
         class="icon"
@@ -72,7 +72,7 @@ const { frontmatter } = toRefs(props);
       </svg>
       <p class="text">{{ frontmatter.date }}</p>
     </div>
-    <div v-if="frontmatter.minute" class="line container">
+    <div v-if="frontmatter.minute" class="info_line container">
       <svg
         t="1658821512864"
         class="icon"

docs/.vuepress/config.ts

@@ -1,14 +1,17 @@
-import { defineUserConfig } from "@vuepress/cli";
+import { defineUserConfig } from "vuepress";
+import { path } from "vuepress/utils";
 import { defaultTheme } from "@vuepress/theme-default";
 import { docsearchPlugin } from "@vuepress/plugin-docsearch";
 import { mdEnhancePlugin } from "vuepress-plugin-md-enhance";
 import { registerComponentsPlugin } from "@vuepress/plugin-register-components";
 import { navbar, sidebar } from "./configs";
-import { path } from "@vuepress/utils";
+import { viteBundler } from "@vuepress/bundler-vite";
 
 export default defineUserConfig({
   base: "/PolarDB-for-PostgreSQL/",
 
+  bundler: viteBundler(),
+
   head: [
     ["link", { rel: "icon", href: "/PolarDB-for-PostgreSQL/favicon.ico" }],
   ],

docs/.vuepress/configs/navbar/en.ts

@@ -84,32 +84,18 @@ export const en: NavbarConfig = [
     text: "Dev",
     link: "/development/",
     children: [
-      {
-        text: "Development on Docker",
-        link: "/development/dev-on-docker.html",
-      },
-      {
-        text: "Customize Development Environment",
-        link: "/development/customize-dev-env.html",
-      },
+      "/development/dev-on-docker.html",
+      "/development/customize-dev-env.html",
     ],
   },
   {
     text: "Contributing",
     link: "/contributing/",
     children: [
-      {
-        text: "Contributing Docs",
-        link: "/contributing/contributing-polardb-docs.html",
-      },
-      {
-        text: "Contributing Code",
-        link: "/contributing/contributing-polardb-kernel.html",
-      },
-      {
-        text: "Coding Style",
-        link: "/contributing/coding-style.html",
-      },
+      "/contributing/contributing-polardb-docs.html",
+      "/contributing/contributing-polardb-kernel.html",
+      "/contributing/coding-style.html",
+      "/contributing/trouble-issuing.html",
     ],
   },
 ];

docs/.vuepress/configs/navbar/zh.ts

@@ -121,18 +121,10 @@ export const zh: NavbarConfig = [
     text: "参与社区",
     link: "/zh/contributing/",
     children: [
-      {
-        text: "贡献文档",
-        link: "/zh/contributing/contributing-polardb-docs.html",
-      },
-      {
-        text: "贡献代码",
-        link: "/zh/contributing/contributing-polardb-kernel.html",
-      },
-      {
-        text: "编码风格",
-        link: "/zh/contributing/coding-style.html",
-      },
+      "/zh/contributing/contributing-polardb-docs.html",
+      "/zh/contributing/contributing-polardb-kernel.html",
+      "/zh/contributing/coding-style.html",
+      "/zh/contributing/trouble-issuing.md",
     ],
   },
 ];

docs/.vuepress/configs/sidebar/en.ts

@@ -102,6 +102,7 @@ export const en: SidebarConfig = {
         "/contributing/contributing-polardb-kernel.md",
         "/contributing/contributing-polardb-docs.md",
         "/contributing/coding-style.md",
+        "/contributing/trouble-issuing.md",
       ],
     },
   ],

docs/.vuepress/configs/sidebar/zh.ts

@@ -175,6 +175,7 @@ export const zh: SidebarConfig = {
         "/zh/contributing/contributing-polardb-kernel.md",
         "/zh/contributing/contributing-polardb-docs.md",
         "/zh/contributing/coding-style.md",
+        "/zh/contributing/trouble-issuing.md",
       ],
     },
   ],

docs/contributing/trouble-issuing.md

@@ -0,0 +1,38 @@
+# 问题报告
+
+如果在运行 PolarDB for PostgreSQL 的过程中出现问题，请提供数据库的日志与机器的配置信息以方便定位问题。
+
+通过 `polar_stat_env` 插件可以轻松获取数据库所在主机的硬件配置：
+
+```sql:no-line-numbers
+=> CREATE EXTENSION polar_stat_env;
+=> SELECT polar_stat_env();
+                           polar_stat_env
+--------------------------------------------------------------------
+ {                                                                 +
+   "CPU": {                                                        +
+     "Architecture": "x86_64",                                     +
+     "Model Name": "Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz",+
+     "CPU Cores": "8",                                             +
+     "CPU Thread Per Cores": "2",                                  +
+     "CPU Core Per Socket": "4",                                   +
+     "NUMA Nodes": "1",                                            +
+     "L1d cache": "192 KiB (4 instances)",                         +
+     "L1i cache": "128 KiB (4 instances)",                         +
+     "L2 cache": "5 MiB (4 instances)",                            +
+     "L3 cache": "48 MiB (1 instance)"                             +
+   },                                                              +
+   "Memory": {                                                     +
+     "Memory Total (GB)": "14",                                    +
+     "HugePage Size (MB)": "2",                                    +
+     "HugePage Total Size (GB)": "0"                               +
+   },                                                              +
+   "OS Params": {                                                  +
+     "OS": "5.10.134-16.1.al8.x86_64",                             +
+     "Swappiness(1-100)": "0",                                     +
+     "Vfs Cache Pressure(0-1000)": "100",                          +
+     "Min Free KBytes(KB)": "67584"                                +
+   }                                                               +
+ }
+(1 row)
+```

docs/zh/contributing/trouble-issuing.md

@@ -0,0 +1,38 @@
+# 问题报告
+
+如果在运行 PolarDB for PostgreSQL 的过程中出现问题，请提供数据库的日志与机器的配置信息以方便定位问题。
+
+通过 `polar_stat_env` 插件可以轻松获取数据库所在主机的硬件配置：
+
+```sql:no-line-numbers
+=> CREATE EXTENSION polar_stat_env;
+=> SELECT polar_stat_env();
+                           polar_stat_env
+--------------------------------------------------------------------
+ {                                                                 +
+   "CPU": {                                                        +
+     "Architecture": "x86_64",                                     +
+     "Model Name": "Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz",+
+     "CPU Cores": "8",                                             +
+     "CPU Thread Per Cores": "2",                                  +
+     "CPU Core Per Socket": "4",                                   +
+     "NUMA Nodes": "1",                                            +
+     "L1d cache": "192 KiB (4 instances)",                         +
+     "L1i cache": "128 KiB (4 instances)",                         +
+     "L2 cache": "5 MiB (4 instances)",                            +
+     "L3 cache": "48 MiB (1 instance)"                             +
+   },                                                              +
+   "Memory": {                                                     +
+     "Memory Total (GB)": "14",                                    +
+     "HugePage Size (MB)": "2",                                    +
+     "HugePage Total Size (GB)": "0"                               +
+   },                                                              +
+   "OS Params": {                                                  +
+     "OS": "5.10.134-16.1.al8.x86_64",                             +
+     "Swappiness(1-100)": "0",                                     +
+     "Vfs Cache Pressure(0-1000)": "100",                          +
+     "Min Free KBytes(KB)": "67584"                                +
+   }                                                               +
+ }
+(1 row)
+```