更新时间：2026-10-21 GMT+08:00

WAL日志

预写式日志WAL（Write Ahead Log，也称为Xlog）是指如果要修改数据文件，必须是在这些修改操作已经记录到日志文件之后才能进行修改，即在描述这些变化的日志记录刷新到永久存储器之后。在系统崩溃时，可以使用WAL日志对集群进行恢复操作。WAL日志记录的详细程度分为几个级别，由参数wal_level控制。

日志运行机制

GaussDB启动时，会分配一段内存用来缓存数据库运行期间生成的日志，这个缓冲区大小由参数wal_buffers控制。要确保事务的持久化，Wal_buffers中的日志就需要落盘。

WAL日志会在以下两种情况下写硬盘：

Commit 事务提交时。系统会调用fdatasync函数，将wal_buffers中的WAL数据写入WAL日志文件。（wal_sync_method可控制commit时调用的函数，默认为fdatasync）。
walWriter定期写。 walWriter进程会定期将wal_buffers中的WAL数据写入WAL日志文件。wal_writer_delay 参数用来控制walwriter进程工作的时间间隔，默认200ms。如果时间过长可能造成WAL缓冲区的内存不足，时间过短会引起WAL不断写入，增加磁盘I/O负担。

日志文件存储路径

路径为数据目录/pg_xlog。

CN的WAL日志存储路径为 /<cn数据目录>/pg_xlog。单个WAL日志文件的大小默认为16MB，通过参数wal_segment_size设置，一般不做调整。
```
gaussdb=# SHOW wal_segment_size;
wal_segment_size
-----------------
16MB
(1 row)
```

以一个DN为例，数据目录可以通过如下命令查询。其中/opt/gaussdb/data/dn/db_6001代表集群节点的数据目录，当前节点的Xlog日志存放在 /opt/gaussdb/data/dn/db_6001/pg_xlog目录。

$ cm_ctl query -Cvd
[    CMServer State    ]
node                               instance                 state
------------------------------------------------------------------------
1    192.168.10.182    1     /opt/gaussdb/data/cm/cm_server    Primary

[   Cluster State   ]

cluster_state  : Normal
redistributing : No
balanced       : Yes
current_az : AZ_ALL

[    Datanode State    ]

node                               instance                 state
--------------------------------------------------------------------------
1    192.168.10.182 6001    /opt/gaussdb/data/dn/dn_6001 P Primary Normal

日志文件命名格式

日志文件以段文件的形式存储的，每个段为16MB，并分割成若干页，每页8KB。一个段文件的名称由24个十六进制组成，对WAL日志的命名由如下部分组成：时间线+日志文件标号+日志文件段标号，请参考表1。

日志文件的段标号上限为FF，若有下一个WAL日志文件，需要将文件标号+1，段标号归零，例如0000000100000000000000FF的后一个文件为000000010000000100000000。时间线由1开始，日志文件标号和日志文件的段标号由0开始。

表1 WAL日志文件命名规范
字段名称	字段含义
timeline	时间线。取值范围：8位16进制数字。
wal_file_num	日志文件标号。取值范围：8位16进制数字。
wal_segment_num	日志文件段标号。取值范围：8位16进制数字。

典型的WAL日志文件名如下所示，每个WAL日志文件大小均为16MB。

-rW----- 1 gaussdb d gaussdb d 16777216 Jun 11 	12:33 0000000100000001000000F2
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 11 	18:10 0000000100000001000000F3
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 11 	22:18 0000000100000001000000F4
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 12	03:58 0000000100000001000000F5
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 12	07:59 0000000100000001000000F6
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 12	13:45 0000000100000001000000F7
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 12	17:30 0000000100000001000000F8
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 12	23:10 0000000100000001000000F9
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 13	03:10 0000000100000001000000FA
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 13	08:39 0000000100000001000000FB
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 13	12:43 0000000100000001000000FC
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 13	17:08 0000000100000001000000FD
-rW----- 1 gaussdb d gaussdb d 16777216 Jun 13	16:32 0000000100000001000000FE

WAL日志文件名的数字一般情况下是顺序增长使用的（要把所有可用数字都用光也需要非常长的时间），但也存在循环使用的情况。

日志内容说明

WAL日志的内容取决于记录事务的类型，在系统崩溃时可以利用WAL日志进行恢复。

默认配置下，GaussDB每次启动时会先读取WAL日志进行恢复。

日志使用场景

数据库崩溃恢复：数据库意外崩溃时，因为Xlog日志中已经完整记录了数据库的变化，在数据库重启后就可以通过回放checkpoint之后的Xlog日志，把之前修改过的数据页面（记录在Xlog里，但是还没有来得及修改数据文件）落盘，确保数据的完整性。这个过程是在数据库启动后自动完成的。

主备DN数据同步：GaussDB的备DN通过接收来自主DN的Xlog，然后应用Xlog来达到主备一致。主库和备库之间的数据同步也可以通过Xlog来实现。

数据库备份恢复：用GaussRoach对GaussDB做备份时，不仅要复制数据文件，还需要备份期间产生的Xlog，才能构成一个完整的备份。使用全量备份或增量备份+Xlog，可以做到指定时间点的恢复，即恢复到全量备份之后的指定时间点（即PITR: Point-In-Time Recovery）。

逻辑复制：逻辑复制工具，如DRS，是通过对Xlog的解析来获取数据流并进行增量数据同步的。

Xlog的回收

数据库运行期间，会持续生成Xlog日志，GaussDB通过checkpoint机制来进行Xlog日志清理（通常被称为Xlog回收）。Xlog日志回收相关参数请参见表2，参数设置方式请参见设置参数。

表2 Xlog日志回收相关参数
参数名称	参数说明
checkpoint_timeout	设置自动检查点之间的最长时间。在上一次自动检查点后，多长时间必须做下一次自动检查点，默认值为15min。如果在两次自动检查点期间堆积的Xlog日志数量大于checkpoint_segments设置的值，也会触发一次自动检查点。
checkpoint_segments	设置checkpoint_timeout周期内所保留WAL日志文件的最大数量。每个日志文件大小为16MB。
enable_incremental_checkpoint	增量检查点开关，默认值为on。
incremental_checkpoint_timeout	开启增量检查点开关（enable_incremental_checkpoint）之后，设置自动检查点之间的最长时间。默认值为1min。即每分钟会启动一次增量检查点，同样会检查是否有Xlog需要清理。
wal_keep_segments	Xlog日志文件的数量，设置“pg_xlog”目录下保留日志文件的最小数量。备机通过获取主机的Xlog日志进行流复制。默认值为128。一般情况下，数据库在执行checkpoint时，会检查当前的pg_xlog目录下的Xlog数量是否大于wal_keep_segments设置的值，如果数量大于wal_keep_segments值，就从旧的一端开始清理，保留wal_keep_segments设定数量的Xlog日志。
enable_xlog_prune	设置在任一备机断连时，主机是否根据Xlog日志的大小超过参数max_size_for_xlog_prune的值而回收日志，on为开启。在备机断联时，为确保主备DN间Xlog日志是连续的，将不对Xlog日志进行清理。但是，如果开启enable_xlog_prune，且Xlog堆积的容量大于max_size_for_xlog_prune指定的值，一般为256GB，同样会触发Xlog日志清理。
max_size_for_xlog_prune	在备机故障时主机保留的Xlog最大数量。在enable_xlog_prune打开时生效，工作机制如下： replconninfo系列guc参数配置的所有备机都连接主机时，则该参数不生效。 replconninfo系列guc参数配置的备机存在断连时，则该参数生效。当主机Xlog日志量大于该参数值，会强制回收。例外：在同步提交模式下（即synchronous_commit参数不是local/off时），如果存在连接中的备机，则主机会考虑保留多数派备机中最小日志接受位置以后的日志，这种情况下，保留的日志可能多于max_size_for_xlog_prune参数值。若存在build中的备机，则该参数不生效，主机日志会全量保留，防止build操作期间由于日志被回收引发的失败。

维护建议

WAL日志对数据库异常恢复有重要的作用，建议定期对WAL日志进行备份。

父主题： 日志参考