# openGauss通信协议
　客户端可以通过两种 "子协议" 来发送请求，分别是 `simple query` 和 `extened query`。使用 `simple query` 时，客户端发送字符串文本请求，后端收到后立即处理并返回结果（gsql）；使用 `extened query` 时，发送请求的过程被分为若干步骤，通常包括 Parse，Bind ， Execute和Sync。本文主要关注 `extened query`。
 
## 一、消息格式
　　客户端和服务端所有通信都通过消息流进行。消息的第一个字节标识消息类型，随后四个字节标识消息内容的长度（该长度包括这四个字节本身），具体的消息内容由消息类型决定。

![](https://blog.lc044.love/static/img/972f04fedcb2afc606c674868bc982e1.image.webp)

　　openGauss 目前支持如下客户端消息类型：

```c++
switch (qtype) {
        case 'a': /* Not reach : Trigger shipped to DN */
        case 'A': /* AC WLM */
        case 'b': /* Barrier */
        case 'B': /* bind */
        case 'c': /* copy done */
        case 'C': /* close */
        case 'D': /* describe */
        case 'd': /* copy data */
        case 'e': /* Thread ID */
        case 'E': /* execute */
        case 'f': /* copy fail */
        case 'F': /* fastpath function call */
        case 'g': /* GXID */
        case 'G': /* PGXCBucketMap and PGXCNodeId */
        case 'h': /* hybrid message query */
        case 'H': /* flush */
        case 'i': /* Instrumentation */
        case 'I': /* Push, Pop schema name */
        case 'j': /* Check gtm mode */
        case 'J': /* Trace ID */
        case 'k': /* Global session ID */
        case 'K': /* client conn driver net_time */
        case 'l': /* get and handle csn for csnminsync */
        case 'L': /* Link gc_fdw */
        case 'M': /* Command ID */
        case 'n': /* Committing */
        case 'N': /* Commit csn */
        case 'o': /* role name */
        case 'O': /* to reset openGauss thread in pooler stateless reuse mode */
        case 'p': /* Process Pid */
        case 'P': /* parse */
        case 'q': /* Query ID */
        case 'Q': /* simple query */
        case 'r': /* Plan ID with sync */
        case 'R': /* Reply collect info */
        case 's': /* Snapshot */
        case 'S': /* sync */
        case 't': /* Timestamp */
        case 'T': /* consistency point */
        case 'u': /* AUTONOMOUS_TRANSACTION simple query */
        case 'U': /* batch bind-execute */
        case 'V': /* client conn driver support trace info*/
        case 'W': /* WLM Control Group */
        case 'w': /* dynamic WLM */
        case 'x': /* imcs populate query */
        case 'X': /* terminate */
        case 'y': /* sequence from cn 2 dn */
        case 'Y': /* plan with params */
        case 'z': /* PBE for DDL */
        case 'Z': /* simple plan  */
        default:
            break;
}
```

　　服务端收到如上消息的处理流程可以参考 [PostgresMain](https://github.com/postgres/postgres/blob/bf68b79e50e3359accc85c94fa23cc03abb9350a/src/backend/tcop/postgres.c#L4277)。服务端发送给客户端的消息有如下类型（不完全）：

```java
switch (c) {
          case 'K': //receive dbTime
          case 'A': // Asynchronous Notify
          case '1': // Parse Complete (response to Parse)
          case 't': // ParameterDescription
          case '2': // Bind Complete (response to Bind)
          case '3': // Close Complete (response to Close)
          case 'n': // No Data (response to Describe)
          case 's':  // Portal Suspended (end of Execute)
          case 'C':  // Command Status (end of Execute)
          case 'D': // Data Transfer (ongoing Execute response)
          case 'E': // Error Response (response to pretty much everything; backend then skips until Sync)
          case 'I':  // Empty Query (end of Execute)
          case 'N': // Notice Response
          case 'S': // Parameter Status
          case 'Z': // Ready For Query (eventual response to Sync)
          case 'G': // CopyInResponse
          case 'H': // CopyOutResponse
          case 'c': // CopyDone
          case 'd': // CopyData
          default:
            throw new IOException("Unexpected packet type: " + c);
}
```

　　客户端处理如上服务端消息的流程可以参考 PostgreSQL libqp 的实现 [pqParseInput3](https://github.com/postgres/postgres/blob/c9d29775195922136c09cc980bb1b7091bf3d859/src/interfaces/libpq/fe-protocol3.c#L63)。

　　openGauss 通信协议包括两个阶段： `startup` 阶段和常规 `normal` 阶段。 `startup` 阶段，客户端尝试创建连接并发送授权信息，如果一切正常，服务端会反馈状态信息，连接成功创建，随后进入 `normal` 阶段。 `normal` 阶段，客户端发送请求至服务端，服务端执行命令并将结果返回给客户端。客户端请求结束后，可以主动发送消息断开连接。

　　`normal` 阶段，客户端可以通过两种 "子协议" 来发送请求，分别是 `simple query` 和 `extened query`。使用 `simple query` 时，客户端发送字符串文本请求，后端收到后立即处理并返回结果（gsql）；使用 `extened query` 时，发送请求的过程被分为若干步骤，通常包括 Parse，Bind ， Execute和Sync。

## 二、**Extended Query 处理流程**
　　在 openGauss 中，**Extended Query（扩展查询，JDBC默认协议）**  是一种通过多个步骤拆分 SQL 执行过程的协议，主要用于参数化查询，能有效避免 SQL 注入、提升重复执行效率。**Extended Query** 不允许在一个请求中包含多条 SQL 命令，否则会报语法错误 **（** Extended Query模式下**JDBC会自动拆分一条语句的多个SQL）** 。Extended Query 协议通常包括 5 个步骤，分别是 Parse，Bind，Describe（可选），Execute 和 Sync。以下分别介绍各个阶段的处理流程。


![](https://blog.lc044.love/static/img/8d23abc8e2cb8fc345b650af5caea21e.image.webp)

### 2.1. Parse（解析）：生成语法树
+ **作用**：客户端发送不带参数的 SQL 模板（如`SELECT * FROM users WHERE id = $1`），服务端收到该消息后，调用 `exec_parse_message` 函数进行处理，进行语法分析、语义分析和重写，同时会创建一个 Plan Cache 的结构，用于缓存后续的执行计划。![](https://blog.lc044.love/static/img/374335e5ca95978cf7fb24998256ef5b.image.webp)
+ **关键操作**：
    - 检查 SQL 语法是否正确（如关键字拼写、语句结构）。
    - 验证表、列等对象是否存在（语义校验）。
    - 生成解析树，存储在服务器的内存中，并返回一个**Parse Complete**消息（包含解析树的标识，如`Portal`或`Statement` ID）。
+ **示例**：客户端发送`Parse("SELECT * FROM users WHERE id = $1")`，服务器返回解析成功的确认。


### 2.2. Bind（绑定）：关联参数与执行计划
+ **作用**：客户端发送参数值（如`$1 = 123`），服务器将参数与解析树绑定，生成**执行计划**（Execution Plan）。openGauss 收到该消息后，调用 `exec_bind_message` 函数进行处理。为之前保存的 Prepared Statement 创建执行计划并将其保存在 Plan Cache 中，创建一个 `Portal` 用于后续执行。

> 在 openGauss 内核中，Portal 是对查询执行状态的一种抽象，该结构贯穿执行器运行的始终。
>


![](https://blog.lc044.love/static/img/b1071543ff660a21bb7818bcee366078.image.webp)

+ **关键操作**：
    - 校验参数类型是否与表字段匹配（如`id`是整数，`$1`不能是字符串）。
    - 基于参数值和数据库统计信息（如索引分布），优化器生成最优执行计划（如选择索引扫描还是全表扫描）。
    - 生成一个**Portal**（可理解为 “执行上下文”），包含绑定后的执行计划，返回`Bind Complete`消息。
+ **示例**：客户端发送`Bind(参数: [123])`，服务器将`123`与`$1`绑定，生成针对`id=123`的执行计划。

### 2.3. Execute（执行）：执行查询并返回结果
+ **作用**：客户端触发执行已绑定的 Portal，服务器执行执行计划，返回结果。`Execute` 消息中可以指定返回的行数，若行数为 0，表示返回所有行。

![](https://blog.lc044.love/static/img/a4ac10ef0d479f546b0db9c2dce70c53.image.webp)

+ **关键操作**：
    - 按照执行计划执行数据操作（如查询、插入、更新）。
    - 若为查询语句，将结果集分批返回给客户端（可通过`Fetch`控制返回行数）。
    - 若为写操作（如`INSERT`），执行事务日志记录和数据页更新。
+ **示例**：客户端发送`Execute(Portal ID)`，服务端收到消息后，执行 `Bind` 阶段创建的 Portal，执行结果通过 `DataRow` 消息返回给客户端，执行完成后发送 `CommandComplete`消息。![](https://blog.lc044.love/static/img/eabdbf92439790ba803eb73d486b32f8.image.webp)msg示例：INSERT 0 1

### 2.4. Sync（同步）：结束当前查询流程
+ **作用**：客户端发送`Sync`消息，服务器清理本次查询的资源，结束当前会话的查询流程。
+ **关键操作**：
    - 释放 Portal 占用的内存资源（解析树、执行计划等）。
    - 向客户端返回`ReadyForQuery`消息，表明当前会话处于 “就绪状态”，可接收新的查询。
+ **示例**：客户端发送`Sync`，服务器清理资源，等待下一次查询请求。

### 2.5. 批量管线与 Sync
　　对于一次执行的多条SQL语句，JDBC会自动将语句拆分成多个单独的SQL语句，每条SQL语句都独立执行Parse/Bind/Describe/Execute流程

```java
String sql = "INSERT INTO users (name, age) VALUES ('Alice', 30);select * from users where age=?;select * from users;select * from users;select * from users;select * from users;";
PreparedStatement pstmt = conn.prepareStatement(sql);
pstmt.setInt(1, 30); 
pstmt.execute();
```

![](https://blog.lc044.love/static/img/594959d0e43911a5328a1e042779f1bf.image.webp)

+ 为了减少往返延迟，JDBC 驱动通常将多条语句的 Parse/Bind/Describe/Execute 消息依次**排队发送**（pipelining），而不是一次一收一发，如果数据量小的话仅需一次RTT即可完成通信。
+ 当所有语句对应的 Execute 都发出后，客户端发送一个 **Sync** 消息，表示“这一批所有命令都发完了，请一次性返回结果，最后给我一个 ReadyForQuery”。
+ **服务器 → 客户端**
    - 按照收到的命令顺序依次返回 ParseComplete、BindComplete、RowDescription（若有）、DataRow、CommandComplete……
    - 在最后，返回 **ReadyForQuery**，表示事务状态可查（空闲/活动/回滚），客户端可开始下一次交互。

　　‍



openGauss通信协议

## 1 内容及目的

openGauss-jdbc调试方法，便于快速搭建调试环境

## 2 配置环境过程

操作系统：openEuler22.03 X86

前提要求：

- 有可用的openGauss数据库

## 3 实践过程

### 3.1 安装依赖

软件及环境依赖要求如下：

| 软件及环境要求     | 推荐版本   |
| -------------------- | ------------ |
| maven              | 3.6.1      |
| java               | 1.8        |
| Git Bash (Windows) | 无推荐版本 |

```bash
sudo dnf update
sudo dnf install -y java-1.8.0-openjdk-devel
# 安装完成后，可通过以下命令验证是否安装成功：
java -version
```

#### 安装 Maven 3.6.1

1. 访问[Maven 官方下载页面](https://maven.apache.org/download.cgi)
2. 在页面中找到 “Maven 3 archives”，点击进入，找到 3.6.1 版本并下载对应的压缩包，推荐下载`.tar.gz`格式的文件。
3. 在 openEuler 系统中创建一个文件夹用于存放 Maven 安装包，例如：

    ```bash
    mkdir ~/maven
    cd ~/maven
    tar -zxvf apache-maven-3.6.1-bin.tar.gz
    ```

4. 配置环境变量，编辑`~/.bachrc`文件：

    ```bash
    nano ~/.bachrc
    ```
    
    在文件末尾添加以下内容：

    ```bash
    export MAVEN_HOME=/a-dev/maven/apache-maven-3.6.1
    export PATH=$MAVEN_HOME/bin:$PATH
    ```
   
    保存并退出编辑，然后执行`source ~/.bashrc`使配置生效。

5.  验证安装，执行命令：

    ```bash
    mvn -v
    ```

若显示 Maven 版本信息，则表示安装成功。

### 3.2 安装vscode插件

在vscode插件市场里安装以下插件，注意如果是调试代码在服务器上，则必须在**服务器**上的vscode安装该扩展（图中LOCAL-INSTALLED中的是本地vscode安装的插件，SSH：IP-INSTALLED中显示的是服务器中安装的插件，黄色按钮表示可以将插件安装到服务器上）

- Extension Pack for Java
- Debugger for Java
- Maven for Java
- Project Manager for Java
- Test Runner for Java

![image.png](https://blog.lc044.love/static/img/3bb459a177cba8d02ca9f883366a38b2.image.webp)

### 3.3 编译jdbc

1. 克隆代码并编译

    ```bash
    mkdir ~/proj
    cd ~/proj
    git clone https://gitcode.com/opengauss/openGauss-connector-jdbc.git
    cd openGauss-connnector-jdbc
    sh build.sh
    ```

    编译成功之后会显示

    ![](https://blog.lc044.love/static/img/a7038129608b22b872cbf17b6024495b.image.webp)

    编译后的jar包在output目录下

2. 编写测试代码

    新建测试文件夹

    ```bash
    mkdir -p pgjdbc-client/src/main/java/com/example/
    cd pgjdbc-client/src/main/java/com/example/
    ```

    新建测试文件 `PostgresTest.java`

    ```java
    package com.example;

    import java.sql.*;

    public class PostgresTest {
        public static void main(String[] args) {
            // 数据库连接信息
            String url = "jdbc:postgresql://localhost:33000/tpccdb";
            String username = "tpcc";
            String password = "tpcc@123";

            // SQL查询语句
            String sql = "SELECT * FROM users";

            try (Connection conn = DriverManager.getConnection(url, username, password);
                 Statement stmt = conn.createStatement();
                 ResultSet rs = stmt.executeQuery(sql)) {

                System.out.println("数据库连接成功！");
                System.out.println("服务器版本: " + conn.getMetaData().getDatabaseProductVersion());

                System.out.println("\n查询结果:");
                while (rs.next()) {
                    int id = rs.getInt("id");
                    String name = rs.getString("name");
                    double salary = rs.getDouble("age");
                    System.out.printf("ID: %d, 姓名: %s, 年龄: %.2f%n", id, name, salary);
                }

            } catch (SQLException e) {
                System.err.println("数据库操作失败: " + e.getMessage());
                e.printStackTrace();
            }
        }
    }    
    ```
    ![](https://blog.lc044.love/static/img/2850339e039a395b3420fbe3542e816f.image.webp)

3. 配置Maven依赖

    ```java
    cd ~/proj/opengauss-connector-jdbc/pgjdbc-client/
    ```

    在`pgjdbc-client`目录下创建`pom.xml`文件，写入下面的配置信息

    ```xml
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                                 http://maven.apache.org/maven-v4_0_0.xsd">

        <modelVersion>4.0.0</modelVersion>
        <parent>
            <groupId>com.huawei</groupId>
            <groupId>pgjdbc-aggregate</artifactId>
            <version>42.2.5</version>
        </parent>
        <artifactId>pgjdbc-client</artifactId>

        <dependencies>
            
            <dependency>
                <groupId>org.opengauss</groupId>
                <artifactId>opengauss-jdbc</artifactId>
                <version>7.0.0-RC2</version>
            </dependency>
        </dependencies>
        
    </project>
    ```

    其中parent字段的groupId、groupId、version内容要与`openGauss-connector-jdbc`路径下的`pom.xml`里的内容完全对应

    ![](https://blog.lc044.love/static/img/e78354b938330b497994de61b3291f7c.image.webp)
    
    dependency字段的groupId、groupId、version内容要与`openGauss-connector-jdbc/pgjdbc`路径下的`pom.xml`里的内容完全对应。

    ![](https://blog.lc044.love/static/img/31f2f7d2bbcf7177dfee6058bd6388bf.image.webp)

    修改`openGauss-connector-jdbc/pom.xml`

    ```xml
      <modules>
        <module>pgjdbc</module>
        
        <module>pgjdbc-client</module> 
      </modules>
    ```

### 3.4 运行和调试代码

配置好上面的Maven依赖后，使用vscode打开`~/proj/openGauss-connector-jdbc/`文件夹，等待初始化一段时间。

正确加载完成后侧边栏最上面会显示有三个Java projects，三个maven项目

![image.png](https://blog.lc044.love/static/img/a8622cc0794e911b302284fca6ea4f20.image.webp)

此时打开`~/proj/opengauss-connector-jdbc/pgjdbc-client/PostgresTest.java`文件，main函数上面就会显示Run|Debug两个按钮

![](https://blog.lc044.love/static/img/efe4c08330a0d3aba5c14964f0a32877.image.webp)

点击`Run`就会直接运行main函数

![image.png](https://blog.lc044.love/static/img/38eb9ca2165fb1a29fe216a5756798c6.image.webp)

设置好断点，点击`Debug`即可进行调试（可以直接在pgjdbc下的驱动源码打断点）

![](https://blog.lc044.love/static/img/65d40e8898ada6fbf907ba9678fc9eb2.image.webp)

![](https://blog.lc044.love/static/img/08830e7de76d5b6770ec2ae9f4b02e30.image.webp)

## 4 参考资料

1. [豆包](https://www.doubao.com/chat/)
2. [ChatGPT](https://chatgpt.com/?model=auto)

openGauss-JDBC 调试方法

# 服务器网关切换后域名解析故障排查实录

## 一、故障现象：IP能通，域名却“失踪”了？

上周在维护测试环境时遇到一个诡异的网络问题：某服务器（主机A）出现**能ping通外网IP（如8.8.8.8），但无法ping通域名** 的异常现象。其他配置未变更，仅网关从`172.19.0.150`改为`172.19.0.179`。这种“能通IP不通域名”的症状，直觉指向DNS解析链路异常，但具体问题点需要一步步拆解。

![](https://blog.lc044.love/static/img/5520f3a31bc534f2ea6ce017b16b85e8.image.webp)

毫无疑问，这个问题肯定是 DNS 的问题，但是 DNS 哪出了问题，却非常诡异。

## 二、初步排查：定位DNS解析的“断链点”

### 0. **更换网关，DNS解析正常**

更换另一个网关，网络恢复正常了，说明是网关的问题，那么问题就来了，一般来说 DNS 解析是跟网关没有关系的，网关有问题的话应该 Ping 不通 IP，只更换网关恢复正常说明 DNS 配置又没问题，这就是诡异的点：**网关跟DNS到底有什么关系**。

**ChatGPT这么说：**

![](https://blog.lc044.love/static/img/fc0a0106b0be56d5195852f3e6e94b8d.image.webp)

### 1. **DNS配置验证：先看基础设置**

* **查看当前DNS服务器**

  ```bash
  cat /etc/resolv.conf  
  # 输出nameserver 8.8.8.8（已手动设置公共DNS）
  ```

  ✅ 确认主机已正确配置DNS服务器（8.8.8.8），但问题依旧存在，说明配置无错，需排查网络通路。

### 2. **路由与连通性测试：ping与traceroute的双重验证**

* **测试DNS服务器连通性**

  ```bash
  ping 8.8.8.8  # 通！说明ICMP协议可达
  traceroute 8.8.8.8  # 路由路径正常，无明显丢包
  ```

  ✅ 物理链路和基础路由正常，但域名解析仍失败，问题聚焦到**DNS协议层面**。

### 3. **DNS解析实测：用工具撕开“表象”**

* **手动触发解析请求**

  ```bash
  nslookup baidu.com  # 超时无响应
  dig baidu.com  # 同样卡住，无返回结果
  ```

  ❌ 直接证据：DNS查询未成功获取响应，说明请求可能未送达或被拦截。


## 三、深度诊断：抓包工具揭露“协议级封锁”

### 1. **tcpdump抓包：监控DNS流量细节**

执行抓包命令后再次发起解析请求：

```bash
sudo tcpdump -i enp2s0f0 port 53 -n
```

**关键输出分析**：

* **UDP请求**：主机向8.8.8.8发送了UDP 53端口的A记录查询（`A? baidu.com`），但**无任何响应包**。
* **TCP请求**：尝试使用TCP协议重新查询（`dig +tcp baidu.com`），抓包显示**三次握手成功，且DNS服务器返回了解析结果**（包含baidu.com的IP地址）。

🔍 **核心结论**：

* UDP 53端口的DNS请求被网关或链路设备拦截，导致解析失败；
* TCP 53端口未受限制，说明问题出在**协议级过滤**（常见于防火墙对UDP DNS的封锁）。

## 四、网关特性分析：iKuai路由器的“特殊规则”

由于故障网关为**iKuai（爱快）路由器**，结合其功能特性进一步排查：

### 1. **防火墙策略检查**

登录iKuai管理后台（`http://172.19.0.179`），进入 **安全设置 &gt; 防火墙规则**，发现一条针对**UDP协议、目标端口53**的出站拦截规则。该规则默认阻断内网主机通过UDP协议访问外部DNS服务器，以防止DNS放大攻击，但误判导致正常解析请求被拦截。

### 2. **规则调整与验证**

* **修改规则**：将拦截动作改为“允许”，并指定目标端口为53（UDP）。
* **重启网络服务**：确保规则生效。
* **复测解析**：

  ```bash
  dig baidu.com  # 秒级返回解析结果，问题解决！
  ```

## 五、技术总结：从现象到本质的排查逻辑

### 1. **故障链还原**

`网关切换` → `触发UDP 53端口拦截规则` → `DNS查询请求（UDP）无法回包` → `域名解析失败`。
关键点：**UDP与TCP协议的差异化处理**——多数防火墙默认允许TCP 80/443等常用端口，但可能对UDP协议实施更严格的策略。

### 2. **通用排查方法论**

* **分层验证**：按“物理层→网络层→传输层→应用层”顺序排查，先确认IP连通性，再聚焦协议细节。
* **工具优先**：善用`ping/traceroute/dig/tcpdump`等工具，通过抓包获取原始流量数据，避免主观臆断。
* **设备特性适配**：不同厂商的网络设备（如iKuai、华为、Cisco）可能有默认安全策略，需结合官方文档分析规则逻辑。

## 六、延伸思考：DNS解析的“攻防博弈”

当前网络环境中，DNS常成为安全策略的“敏感点”：

* **运营商层面**：部分ISP会拦截非官方DNS请求，强制使用自有解析服务；
* **企业防火墙**：为防范数据泄露，可能限制UDP 53端口，仅允许通过HTTP(S)/TLS加密通道传输DNS数据（如DoH/DoT）。

**应对建议**：

* 若遇UDP封锁，可临时使用TCP解析（`dig +tcp`）或部署DNS加密工具（如cloudflared）；
* 长期方案需与网络管理员协同，在安全策略与业务需求间找到平衡点。

## 结语

这次故障排查看似围绕“DNS解析”，实则涉及网络协议特性、设备策略配置、安全规则适配等多个技术维度。作为运维人员，保持“用数据说话”的习惯（如抓包分析），比依赖经验判断更能快速定位问题。下次遇到类似“能通IP不通服务”的场景，不妨从协议层开始抽丝剥茧，往往能柳暗花明。

服务器网关切换后域名解析故障排查实录

## 一、openGauss中的事务持久性

　　和业界几乎所有的数据库一样，openGauss通过将事务对于数据库的修改写入可以永久（长时间）保存的存储介质中，来保证事务的持久性。这个过程被称为事务的持久化过程。持久化过程是保证事务持久性所必不可少的环节，其效率对于数据库整体性能影响很大，常常成为数据库的性能瓶颈所在。

　　最常用的存储介质是磁盘。对于磁盘来说，其每次读写操作都有一个“启动”代价，因此在单位时间内（每秒内），一个磁盘可以进行的读写操作次数（Input/Output Operations Per Second，简称IOPS）是有上限的。HDD磁盘的IOPS一般在1000次/秒以下，SSD磁盘的IOPS可以达到10000次/秒左右。另外一方面，如果多个磁盘读写请求的数据在磁盘上是相邻的，那么可以被合并为一次读写操作，这导致磁盘顺序读写的性能通常要远优于随机读写。

　　一般来说，尤其是在OLTP场景下，用户对于数据库数据的修改是比较分散随机的。如果在持久化过程中，直接将这些分散的数据写入磁盘，那么这个随机写入的性能是比较差的。因此，数据库通常都采用预写日志（Write Ahead Log，简称WAL）来避免持久化过程中的随机IO，如图4(a)所示。所谓预写日志，是指在事务提交的时候，先将事务对于数据库的修改写入一个顺序追加的WAL日志文件中。由于WAL日志的写操作是顺序IO，因此其可以达到一个比较高的性能。另一方面，对于真正修改的物理数据文件，再等待合适的时机写入磁盘，以尽可能合并该数据文件上的IO操作。

　　在一个事务完成日志的下盘操作（即写入磁盘）以后，该事务就可以完成提交动作。如果在此之后数据库发生宕机，那么数据库会首先从已经写入磁盘的WAL文件中恢复出该事务对于数据库的修改操作，从而保证事务一旦提交即具备持久性的特点。

　　下面结合图4(b)中的例子，简单说明数据库故障恢复的原理。假设一个事务需要在表A（对应数据文件A）和表B（对应数据文件B）中各插入一行新的记录，在数据库内部，其执行的顺序如下：

　　（1）记录修改数据文件A的日志，

　　（2）记录修改数据文件B的日志，

　　（3）在数据文件A中写入新的记录，

　　（4）在数据文件B中写入新的记录。

　　在上述过程中，如果在第（4）步执行时数据库发生宕机，那么该事务对于数据文件B的修改可能全部或部分丢失。当数据库再次启动以后，在其能够接受新的业务之前，需要将这些可能丢失的修改从日志中找回来（该操作被称为日志回放操作）。

　　在日志回放过程中，数据库会根据日志记录的先后顺序，依次读取每个日志的内容，然后判断该日志记录的事务对数据库数据文件的修改是否和当前相关数据文件的内容一致。如果一致，说明上次数据库停机之前修改已经写入数据文件中，该日志修改无需回放；如果不一致，说明上次数据库停机之前修改还未写入数据文件中，上次数据库停机可能是异常宕机导致，该日志对应的事务操作需要重新在相关数据文件中再次执行，才能保证恢复成功。

　　对于本例，在数据库恢复过程中，首先读取到在数据文件A中插入记录的日志，将数据文件A读取上来之后，发现数据文件A中已经包含该记录，因此该日志无需回放；然后读取到在数据文件B中插入记录的日志，将数据文件B读取上来之后，发现数据文件B中未包含新插入的记录，因此需要将日志中的记录再次写入到数据文件B中，从而完成恢复。最终，该事务对于数据库所有的修改都得以恢复出来，事务的持久性得到了保证。

![network-asset-640-20250519224440-eokqneg.webp](/static/img/fb5f847b30a1ec1902d0bacafb5c8734.network-asset-640-20250519224440-eokqneg.webp)

　　(a) WAL日志和数据页面的关系示意图

![](https://blog.lc044.love/static/img/fb5f847b30a1ec1902d0bacafb5c8734.network-asset-640-20250519224440-eokqneg.webp)

　　(b)WAL日志和故障恢复示意图

　　图4  WAL日志和事务持久性示意图

## 二、WAL 日志：核心同步内容

　　WAL（Write-Ahead Logging）日志记录了数据库的**物理变更**（如数据页修改）和**逻辑操作**（如事务提交），是主备同步的基础。主备之间通过**WAL 日志的传输和重放**实现数据一致性：

1. **主库**：所有事务修改先记录到 WAL，通过`WAL Sender`​进程发送给备库。
2. **备库**：通过`WAL Receiver`​接收日志，并应用（重放）到本地数据文件，保持与主库一致。

　　**关键点**：WAL 日志包含了事务的最终结果（如提交 / 回滚），但不直接同步事务的中间状态（如未提交的事务）。

### 主备复制中的 Undo 日志同步

　　在 OpenGauss 的主备架构中，**Undo 日志本身不直接同步到备库**，但与 Undo 相关的关键信息会通过 WAL 日志间接同步：

#### 1. **WAL 日志包含 Undo 相关操作**

　　WAL 日志记录了**事务对 Undo 日志的修改操作**（如创建、更新 Undo 记录），但不包含 Undo 日志的完整内容。例如：

* 当主库事务提交时，WAL 会记录 “提交事务 X” 的操作，备库重放此操作时会标记相应 Undo 记录为 “已提交”。
* 若事务回滚，WAL 会记录 “回滚事务 X”，备库通过重放此操作触发 Undo 日志的应用，恢复数据。

#### 2. **备库本地生成 Undo 日志**

　　备库在重放 WAL 日志时，会**本地生成自己的 Undo 日志**，用于支持 MVCC 和事务回滚。这些 Undo 日志基于主库 WAL 中的操作重建，而非直接复制主库的 Undo 日志。

### 通过备库 Undo 日志判断事务状态的局限性

　　虽然备库上存在 Undo 日志，但**无法直接通过 Undo 日志判断主库事务的实时执行情况**：

#### 1. **Undo 日志反映的是本地状态**

　　备库的 Undo 日志是重放 WAL 后的结果，仅反映**备库自身的事务状态**。例如：

* 若主库有未提交的事务，备库可能根本不知道该事务的存在（除非 WAL 已发送相关信息）。
* 备库上的 Undo 日志状态可能滞后于主库，尤其是在异步复制模式下。

#### 2. **事务中间状态不完整**

　　Undo 日志主要记录**数据变更前的状态**，而非事务的执行流程。例如：

* Undo 日志无法告诉你事务当前执行到哪条 SQL 语句。
* 无法通过 Undo 日志判断事务是否处于等待锁的状态。

#### 3. **备库只读限制**

　　备库通常作为只读节点（支持读操作），其 Undo 日志仅用于支持查询的多版本读，而非处理写事务。因此，备库只需根据 WAL 重放结果本地维护 Undo 日志，无需与主库的 Undo 日志完全一致，备库的 Undo 日志状态与主库的写事务状态无直接关联。

## 主备日志同步状态

　　用户可以通过参数设置当前事务的同步方式。

　　**该参数属于USERSET类型参数，可被任何用户在任何时刻设置。**

　　通常情况下，一个事务产生的日志的同步顺序如下：

1. 主机将日志内容写入本地内存。
2. 主机将本地内存中的日志写入本地文件系统。
3. 主机将本地文件系统中的日志内容刷盘。
4. 主机将日志内容发送给备机。
5. 备机接受到日志内容，存入备机内存。
6. 备机将备机内存中的日志写入备机文件系统。
7. 备机将备机文件系统中的日志内容刷盘。
8. 备机回放日志，完成对数据文件的增量更新。

　　参数取值范围：枚举类型

* on：表示主机事务提交需要等待备机将对应日志刷新到磁盘。
* off：表示主机事务提交无需等待主机自身将对应日志刷新到磁盘，通常也称为异步提交。
* local：表示主机事务提交需要等待主机自身将对应日志刷新到磁盘，通常也称为本地提交。
* remote\_write：表示主机事务提交需要等待备机将对应日志写到文件系统（无需刷新到磁盘）。
* remote\_receive：表示主机事务提交需要等待备机接收到对应日志数据（无需写入文件系统）。
* remote\_apply：表示主机事务提交需要等待备机完成对应日志的回放操作。

### 同步机制对比表

|状态类型|是否同步到备库？|同步方式|一致性保障|
| ----------| ----------------------------| -------------------------------------| --------------------|
|**WAL 日志**|✅ 必须同步|实时传输与重放|数据变更的强一致性|
|**事务状态**|✅ 最终状态（提交 / 回滚）|通过 WAL 日志中的提交记录(CLOG)同步|最终一致性|
|**锁状态**|❌ 不同步|备库不维护锁表，提升为主库时重建|切换后重新初始化|
|**快照状态**|❌ 不同步|查询时本地生成快照|查询时刻的一致性|


　　‍

　　‍


openGauss事务机制（二）

事务是数据库操作的执行单位，需要满足最基本的ACID（原子性、一致性、隔离性、持久性）属性。

 **（1） 原子性：** 一个事务提交之后要么全部执行，要么全部不执行。

 **（2） 一致性：** 事务的执行不能破坏数据库的完整性和一致性。

 **（3） 隔离性：** 事务的隔离性是指在并发中，一个事务的执行不能被其他事务干扰。

 **（4） 持久性：** 一旦事务完成提交，那么它对数据库的状态变更就会永久保存在数据库中。

**显式事务和隐式事务**

* **显式事务**是指，用户在所执行的一条或多条SQL语句的前后，显式添加了开启事务`START TRANSACTION语句`和提交事务`COMMIT`语句。
* **隐式事务**是指，用户在所执行的一条或多条SQL语句的前后，没有显式添加开启事务和提交事务的语句。在这种情况下，每一条SQL语句在开始执行时，openGauss内部都会为其开启一个事务，并且在该语句执行完成之后，自动提交该事务。

## 一、事务整体架构和代码概览

事务模块总体结构如图1所示。

![图1 总体结构](https://fastly.jsdelivr.net/gh/bucketio/img14@main/2025/05/29/1748525342310-250c0510-cc7e-4b43-96ff-80b3bfeaa1a3.png)

在openGauss中，事务的实现与存储引擎的实现有很强关联，代码主要集中在src/gausskernel/storage/access/transam及src/gausskernel/storage/lmgr下，关键文件如图1所示。

1. **事务管理器**：事务系统的中枢，它的实现是一个有限循环状态机，通过接受外部系统的命令并根据当前事务所处的状态决定事务的下一步执行过程。
2. **日志管理器**：用来记录事务执行的状态以及数据变化的过程，包括事务提交日志(CLOG)、事务提交序列日志（CSNLOG）以及事务日志（XLOG）。其中CLOG日志只用来记录事务执行的结果状态，CSNLOG记录日志提交的顺序，用于可见性判断；XLOG是数据的redo日志，用于恢复及持久化。
3. **线程管理机制**：通过一片内存区域记录所有线程的事务信息，任何一个线程可以通过访问该区域获取其他事务的状态信息。
4. **MVCC机制**：openGauss系统中，事务执行读流程结合各事务提交的CSN序列号，采用了多版本并发控制机制，实现了元组的读和写互不阻塞。详细可见性判断方法见“二 事务并发控制”。
5. **锁管理器**：实现系统的写并发控制，通过锁机制来保证事务写流程的隔离性。

## 二、事务并发控制

事务并发控制机制用来保证并发执行事务的情况下openGauss的ACID特性。下面将逐一介绍事务并发控制的各组成部分。

###  （一）事务状态机

openGauss将事务系统分为上层（事务块TBlockState）以及底层（TransState）两个层次。通过分层的设计，在处理上层业务时可以屏蔽具体细节，实现灵活支持客户端各类事务执行语句（BEGIN/START TRANSACTION/COMMIT/ROLLBACK/END）。

1. **事务块TBlockState**：客户端query的状态，用于提高用户操作数据的灵活性，用事务块的形式支持在一个事务中执行多条query语句。
2. **底层事务TransState**：内核端视角，记录了整个事务当前处于的具体状态。

#### 1. 事务上层状态机

事务块上层状态机结构体代码如下：

```c++
typeset enum TBlockState
{
	/* 不在事务块中的状态：单条SQL语句 */
	TBLOCK_DEFAULT,/* 事务块缺省状态 */
	TBLOCK_STARTED,/*执行单条query 语句*/
	
	/* 处于事务块中的状态：一个事务包含多条语句 */
	TBLOCK_BEGIN,/* 遇到事务开始命令BEGIN/START TRANSACTION */
	TBLOCK_INPROGRESS,/* 表明正在事务块处理过程中*/
	TBLOCK_END,/ *遇到事务结束命令END/COMMIT */
	TBLOCK_ABORT,/* 事务块内执行报错，等待客户端执行ROLLBACK */
	TBLOCK_ABORT_END,/ *在事务块内执行报错后，接收客户端执行ROLLBACK */
	TBLOCK_ABORT_PENDING,/* 事务块内执行成功，接收客户端执行ROLLBACK（期望事务回滚）*/
	TBLOCK_PREPARE,/ *两阶段提交事务，收到PREPARE TRANSACTION命令*/
	
	/* 子事务块状态,与上述事务块状态类似 */
	TBLOCK_SUBBEGIN,/* 遇到子事务开始命令SAVEPOINT */
	TBLOCK_SUBINPROGRESS,/* 表明正在子事务块处理过程中*/
	TBLOCK_SUBRELEASE,/* 遇到子事务结束命令RELEASE SAVEPOINT */
	TBLOCK_SUBCOMMIT,/* 遇到事务结束命令END/COMMIT 从最底层的子事务递归的提交到最顶层事务*/
	TBLOCK_SUBABORT,/* 子事务块内执行报错，等待客户端ROLLBACK TO/ROLLBACK */
	TBLOCK_SUBABORT_END,/* 在子事务块内执行报错后，接收到客户端ROLLBACK TO上层子事务/ROLLBACK */
	TBLOCK_SUBABORT_PENDING,/* 子事务块内执行成功，接收客户端执行的ROLLBACK TO上层子事务/ROLLBACK */
	TBLOCK_SUBRESTART,/* 子事务块内执行成功，收到ROLLBACK TO当前子事务*/
	TBLOCK_SUBABORT_RESTART/* 子事务块内执行报错后，接收到ROLLBACK TO当前子事务*/
} TBlockState;
```

为了便于理解，可以先不关注子事务块的状态。当理解了主事务的状态机行为后，子事务块的状态机转换同父事务类似。父子事务的关系类似于一个栈的实现，父事务的子事务相较于父事务后开始先结束。

显式事务块的状态机及相应的转换函数如图2所示。


![图2事务块的状态机](https://fastly.jsdelivr.net/gh/bucketio/img4@main/2025/05/29/1748525395555-b3796f0c-3d18-4646-9206-c47f0a45b827.png)


**表1 事务块状态**

| 事务状态     | 事务状态机结构体             |
| -------------- | ------------------------------ |
| 默认         | TBLOCK\_DEFAULT           |
| 已开始       | TBLOCK\_STARTED           |
| 事务块开启   | TBLOCK\_BEGIN             |
| 事务块运行中 | TBLOCK\_INPROGRESS        |
| 事务块结束   | TBLOCK\_END               |
| 回滚         | TBLOCK\_ABORT             |
| 回滚结束     | TBLOCK\_ABORT\_END     |
| 回滚等待     | TBLOCK\_ABORT\_PENDING |

在无异常情形下，一个事务块的状态机如图2所示按照默认（TBLOCK\_DEFAULT）-\>已开始（TBLOCK\_STARTED）-\>事务块开启（TBLOCK\_BEGIN）-\>事务块运行中（TBLOCK\_INPROGRESS）-\>事务块结束（TBLOCK\_END）-\>默认（TBLOCK\_DEFAULT）循环。剩余的状态机是在上述正常场景下的各个状态点的异常处理分支。

1. 在进入事务块运行中（TBLOCK\_INPROGRESS）之前出错，因为事务还没有开启，直接报错并回滚，清理资源回到默认（TBLOCK\_DEFAULT）状态。
2. 在事务块运行中（TBLOCK\_INPROGRESS）出错分为2种情形。

    1. 事务执行失败：事务块运行中（TBLOCK\_INPROGRESS）-\>回滚（TBLOCK\_ABORT）-\>回滚结束（TBLOCK\_ABORT\_END）-\>默认（TBLOCK\_DEFAULT）；
    2. 用户手动回滚执行成功的事务：事务块运行中（TBLOCK\_INPROGRESS）-\>回滚等待（TBLOCK\_ABORT\_PENDING）-\>默认（TBLOCK\_DEFAULT）。
3. 在用户执行COMMIT语句时出错：事务块结束（TBLOCK\_END）-\>默认（TBLOCK\_DEFAULT）。由图2可以看出，事务开始后离开默认（TBLOCK\_DEFAULT）状态，事务完全结束后回到默认（TBLOCK\_DEFAULT）状态。
4. openGauss同时还支持隐式事务块，当客户端执行单条SQL语句时可以自动提交，其状态机相对比较简单：按照默认（TBLOCK\_DEFAULT）-\>已开始（TBLOCK\_STARTED）-\>默认（TBLOCK\_DEFAULT）循环。

#### **2. 事务底层状态**

TransState结构体代码如下：从内核视角的事务状态，真正意义上的事务状态。

```c++
typedef enum TransState
{
	TRANS_DEFAULT,/* 当前为空闲缺省状态，无事务开启*/
	TRANS_START,/* 事务正在开启*/
	TRANS_INPROGRESS,/* 事务开始完毕，进入事务运行中*/
	TRANS_COMMIT,/* 事务正在提交*/
	TRANS_ABORT,/* 事务正在回滚*/
	TRANS_PREPARE/* 两阶段提交事务进入PREPARE TRANSACTION阶段*/
} TransState;
```

![图3事务底层状态](https://fastly.jsdelivr.net/gh/bucketio/img11@main/2025/05/29/1748525448439-7c64ab29-4445-4eb8-9acb-5685a33e70f1.png)

内核内部底层状态如图3所示，底层状态机的描述见结构体TransState。
（1） 在事务开启前事务状态为TRANS\_DEFAULT。
（2） 事务开启过程中事务状态为TRANS\_START。
（3） 事务成功开启后一直处于TRANS\_INPROGRESS。
（4） 事务结束/回滚的过程中为TARNS\_COMMIT/ TRANS\_ABORT。
（5） 事务结束后事务状态回到TRANS\_DEFAULT。

###  **（二）事务ID分配及CLOG/CSNLOG**

为了在数据库内部区别不同的事务，openGauss数据库会为它们分配唯一的标识符，即事务id（transaction id，缩写xid），xid是uint64单调递增的序列。当事务结束后，使用CLOG记录是否提交，使用CSNLOG（commit sequence number log）记录该事务提交的序列，用于可见性判断。

#### **1. 64位xid及其分配**

openGauss对每一个写事务均会分配一个唯一标识。当事务插入时，会将事务信息写到元组头部的xmin，代表插入该元组的xid；当事务进行更新和删除时，会将当前事务信息写到元组头部的xmax，代表删除该元组的xid。当前事务id的分配采用的是uint64单调递增序列，为了节省空间以及兼容老的版本，当前设计是将元组头部的xmin/xmax分成两部分存储，元组头部的xmin/xmax均为uint32的数字；页面的头部存储64位的xid\_base，为当前页面的xid\_base。

元组结构如图8所示，页面头结构如图9所示，那么对于每一条元组真正的xmin、xmax计算公式即为：元组头中xmin/xmax + 页面xid\_base。


![图8 元组结构](https://fastly.jsdelivr.net/gh/bucketio/img11@main/2025/05/29/1748525574749-a3891231-c049-489d-9527-fb7558b2af4a.png)


![图9 页面头结构](https://fastly.jsdelivr.net/gh/bucketio/img11@main/2025/05/29/1748525595270-a95fb881-c1a7-4038-b24f-1dde9de28bce.png)

当页面不断有更大的xid插入进来时，可能超过“xid\_base + 232”，此时需要通过调节xid\_base来满足所有元组的xmin/xmax都可以通过该值及元组头部的值计算出来，详细逻辑见“2. CLOG、CSNLOG”内“3） 关键函数：”中的第(3)小节。

为了使xid不消耗过快，openGauss当前只对写事务进行xid的分配，只读事务不会额外分配xid，也就是说并不是任何事务一开始都会分配xid，只有真正使用xid时才会去分配。在分配子事务xid时，如果父事务还未分配xid，则会先给父事务分配xid，再给子事务分配xid，确保子事务的xid比父事务大。理论上64位xid已经足够使用：假设数据库的tps为1000万，即1秒钟处理1000万个事务，64xid可以使用58万年。

#### **2. CLOG、CSNLOG**

CLOG以及CSNLOG分别维护事务ID-\>CommitLog以及事务ID-\>CommitSeqNoLog的映射关系。由于内存的资源有限，并且系统中可能会有长事务存在，内存中可能无法存放所有的映射关系，此时需要将这些映射写盘成物理文件，所以产生了CLOG（XID-\>CommitLog Map）、CSNLOG（XID-\>CommitSeqNoLog Map）文件。CSNLOG以及CLOG均采用了SLRU（simple least recently used，简单最近最少使用）机制来实现文件的读取及刷盘操作。

1） CLOG用于记录事务id的提交状态。openGauss中对于每个事务id使用2个bit位来标识它的4种状态。CLOG定义代码如下：

```C++
#define CLOG_XID_STATUS_IN_PROGRESS 0x00  表示事务未开始或还在运行中（故障场景可能是crash）
#define CLOG_XID_STATUS_COMMITTED 0x01 表示该事务已经提交
#define CLOG_XID_STATUS_ABORTED 0x02 表示该事务已经回滚
#define CLOG_XID_STATUS_SUB_COMMITTED 0x03 表示子事务已经提交而父事务状态未知
```

CLOG页面的物理组织形式如图10所示。

![图10CLOG页面的物理组织形式](/static/img/708021e04f6422059a85d412aceeb636.image-20250522005406-di4yqj3.webp)

图10表示事务1、4、5还在运行中，事务2已经提交，事务3已经回滚。

2） CSNLOG用于记录事务提交的序列号。openGauss为每个事务id分配8个字节uint64的CSN号，所以一个8kB页面能保存1k个事务的CSN号。CSNLOG达到一定大小后会分块，每个CSNLOG文件块的大小为256kB。同xid号类似，CSN号预留了几个特殊的号。CSNLOG定义代码如下：

```C++
#define COMMITSEQNO_INPROGRESS UINT64CONST(0x0) 表示该事务还未提交或回滚
#define COMMITSEQNO_ABORTED UINT64CONST(0x1) 表示该事务已经回滚
#define COMMITSEQNO_FROZEN UINT64CONST(0x2) 表示该事务已提交，且对任何快照可见
#define COMMITSEQNO_FIRST_NORMAL UINT64CONST(0x3) 事务正常的CSN号起始值
#define COMMITSEQNO_COMMIT_INPROGRESS (UINT64CONST(1) << 62) 事务正在提交中
```

同CLOG相似，CSNLOG的物理结构体如图11所示。

![图11 CSNLOG的物理结构体](/static/img/e282fc06a36918f3faed44fd78111e64.image-20250522005352-nolbyi1.webp)

事务id 2048、2049、2050、2051、2052、2053的对应的CSN号依次是5、4、7、10、6、8；也就是说事务提交的次序依次是2049-\>2048-\>2052-\>2050-\>2053-\>2051。

### （三）**CSN机制**

1） CSN原理简单如图1所示

![图1 CSN原理](/static/img/9d7758943973d5364c169d5eeac0a2ef.network-asset-v2-54fe468a67fcbce05332944e31d13292_r-20250522091607-z6n8xvv.webp)

每个非只读事务在运行过程中会取得一个xid号，在事务提交时会推进CSN，同时会将当前CSN与事务的xid映射关系保存起来（CSNLOG）。图5-12中，实心竖线标识取snapshot（快照）时刻，会获取最新提交CSN（3）的下一个值4。TX1、TX3、TX5已经提交，对应的CSN号分别是1、2、3。TX2、TX4、TX6正在运行，TX7、TX8是未来还未开启的事务。对于当前snapshot而言，严格小于CSN号4的事务提交结果均可见；其余事务提交结果在获取快照时刻还未提交，不可见。

### （四）**提交流程**

事务提交流程如图3所示。

![图3提交流程](/static/img/42df4308d09442e83538ffc42a6cd328.image-20250529212314-nl1419d.webp)

（1） 设置CSN-XID映射commit-in-progress标记。

（2） 原子更新NextCommitSeqNo值。

（3） 生成redo日志，写CLOG，写CSNLOG。

（4） 更新PGPROC将对应的事务信息从PGPROC中移除，xid设置为InvalidTransactionId、xmin设置为InvalidTransactionId等。

**热备支持**

在事务的提交流程步骤（1）和（2）之间，增加 commit-in-progress 的XLOG 日志。备机在读快照时，首先获取轻量锁 ProcArrayLock ，并计算当前快照。如果使用当前快照中的CSN，碰到 XID 对应的 CSN 号有 COMMITSEQNO_INPROGRESS 标记，则必须等待相应的事务提交 XLOG 回放结束后再读取对应的 CSN 判断是否可见。为了实现上述等待操作，备机在对 commit-in-progress 的 XLOG 日志 做 redo 操作时，会调用 XactLockTableInsert 函数获取相应 XID 的事务排他锁；其他的读事务如果访问到该XID，会等待在此 XID 的事务锁上，直到相应的事务提交XLOg回放结束后再继续运行。


## 参考
  
[1]openGauss数据库源码解析，https://www.zhihu.com/column/c_1233714215367319552

openGauss事务机制（一）

👨🏻‍💻这是一个充满知识💬的链接，快点进来看看你的好友给你分享了什么干货吧❣️