Database File Layout
本节从文件与目录层面描述存储格式。
当前查看 PostgreSQL 18.6。
说明
本节从文件与目录层面描述存储格式。
- 定义范围
- 同版本核心物理存储文档
PGDATA 内容
| 项目 | 说明 |
|---|---|
| PG_VERSION | 包含 PostgreSQL 大版本号的文件 |
| base | 包含各数据库子目录的目录 |
| current_logfiles | 记录日志收集器当前正在写入的日志文件的文件 |
| global | 包含集群级表（如 pg_database）的子目录 |
| pg_commit_ts | 包含事务提交时间戳数据的子目录 |
| pg_dynshmem | 包含动态共享内存子系统所用文件的子目录 |
| pg_logical | 包含逻辑解码状态数据的子目录 |
| pg_multixact | 包含多事务状态数据的子目录，用于共享行锁 |
| pg_notify | 包含 LISTEN/NOTIFY 状态数据的子目录 |
| pg_replslot | 包含复制槽数据的子目录 |
| pg_serial | 包含已提交的可串行化事务信息的子目录 |
| pg_snapshots | 包含已导出快照的子目录 |
| pg_stat | 包含统计子系统持久文件的子目录 |
| pg_stat_tmp | 包含统计子系统临时文件的子目录 |
| pg_subtrans | 包含子事务状态数据的子目录 |
| pg_tblspc | 包含指向表空间的符号链接的子目录 |
| pg_twophase | 包含预备事务状态文件的子目录 |
| pg_wal | 包含 WAL（预写式日志）文件的子目录 |
| pg_xact | 包含事务提交状态数据的子目录 |
| postgresql.auto.conf | 存储由 ALTER SYSTEM 设置的配置参数的文件 |
| postmaster.opts | 记录服务器上次启动所用命令行选项的文件 |
| postmaster.pid | 锁文件，记录当前 postmaster 的进程 ID（PID）、集群数据目录路径、postmaster 启动时间戳、端口号、Unix 域套接字目录路径（可能为空）、第一个有效的 listen_address（IP 地址或 *；未监听 TCP 时为空）以及共享内存段 ID。服务器关闭后此文件不存在。 |
手册定义
66.1. 数据库文件布局
66.1. 数据库文件布局
本节从文件与目录层面描述存储格式。
传统上，数据库集群的配置文件与数据文件一同存放在集群数据目录中。该目录通常称为 PGDATA，名称来自可用于指定它的环境变量；常见位置为 /var/lib/pgsql/data。同一台机器上可以存在多个由不同服务器实例管理的集群。
PGDATA 目录包含若干子目录和控制文件，如表 66.1所示。除这些必需项之外，集簇配置文件 postgresql.conf、pg_hba.conf 和 pg_ident.conf 传统上也存放在 PGDATA 中，不过也可以把它们放在其他地方。
表 66.1. PGDATA 的内容
| 项目 | 说明 |
|---|---|
PG_VERSION |
包含 PostgreSQL 大版本号的文件 |
base |
包含各数据库子目录的目录 |
current_logfiles |
记录日志收集器当前正在写入的日志文件的文件 |
global |
包含集群级表（如 pg_database）的子目录 |
pg_commit_ts |
包含事务提交时间戳数据的子目录 |
pg_dynshmem |
包含动态共享内存子系统所用文件的子目录 |
pg_logical |
包含逻辑解码状态数据的子目录 |
pg_multixact |
包含多事务状态数据的子目录，用于共享行锁 |
pg_notify |
包含 LISTEN/NOTIFY 状态数据的子目录 |
pg_replslot |
包含复制槽数据的子目录 |
pg_serial |
包含已提交的可串行化事务信息的子目录 |
pg_snapshots |
包含已导出快照的子目录 |
pg_stat |
包含统计子系统持久文件的子目录 |
pg_stat_tmp |
包含统计子系统临时文件的子目录 |
pg_subtrans |
包含子事务状态数据的子目录 |
pg_tblspc |
包含指向表空间的符号链接的子目录 |
pg_twophase |
包含预备事务状态文件的子目录 |
pg_wal |
包含 WAL（预写式日志）文件的子目录 |
pg_xact |
包含事务提交状态数据的子目录 |
postgresql.auto.conf |
存储由 ALTER SYSTEM 设置的配置参数的文件 |
postmaster.opts |
记录服务器上次启动所用命令行选项的文件 |
postmaster.pid |
锁文件，记录当前 postmaster 的进程 ID（PID）、集群数据目录路径、postmaster 启动时间戳、端口号、Unix 域套接字目录路径（可能为空）、第一个有效的 listen_address（IP 地址或 *；未监听 TCP 时为空）以及共享内存段 ID。服务器关闭后此文件不存在。 |
集群中每个数据库在 PGDATA/base 下都有一个子目录，名称为该数据库在 pg_database 中的 OID。这是数据库文件的默认存放位置，其系统目录也存储于此。
以下各节描述内置 heap 表访问方法与内置索引访问方法的行为。PostgreSQL 具有可扩展性，其他访问方法的工作方式可能不同。
每个表和索引都存储在单独的文件中。对于普通关系，这些文件以表或索引的文件节点编号命名，该编号可在 pg_class.relfilenode 中找到。但对于临时关系，文件名的形式为 t，其中 BBB_FFFBBB 是创建该文件的后端进程号，FFF 是文件节点编号。无论哪种情况，除了主文件（也称主分支）之外，每个表和索引还有一个空闲空间映射（见第 66.3 节），用于存储该关系可用空闲空间的信息。空闲空间映射存放在以文件节点编号加上 _fsm 后缀命名的文件中。表还拥有可见性映射，存放在带有 _vm 后缀的分支中，用于跟踪哪些页面已知不含死元组。可见性映射在第 66.4 节中有进一步说明。不记录 WAL 的表和索引还有第三个分支，称为初始化分支，存放在带有 _init 后缀的分支中（见第 66.5 节）。
小心
表的 filenode 通常与其 OID 相同，但并非总是如此。TRUNCATE、REINDEX、CLUSTER 及某些形式的 ALTER TABLE 等操作会改变 filenode 而保留 OID，因此不能假设二者相同。此外，包括 pg_class 自身在内的某些系统目录，其 pg_class.relfilenode 为零；实际 filenode 编号存储在更底层的数据结构中，可通过 pg_relation_filenode() 获取。
表或索引超过 1 GB 时，会拆分为以 GB 为单位的分段。第一个分段的文件名与 filenode 相同，之后依次为 filenode.1、filenode.2 等。这可避免某些平台的文件大小限制。1 GB 只是默认分段大小，可在编译 PostgreSQL 时通过 --with-segsize 配置选项调整。空闲空间映射和可见性映射分叉原则上也可能需要多个分段，但实践中很少发生。
如果一个表包含可能具有很大条目的列，它就会有关联的 TOAST 表，用于对那些大到无法直接保存在表行中的字段值进行行外存储。pg_class.reltoastrelid 会把该表关联到其 TOAST 表（如果存在的话）。更多信息见第 66.2 节。
表和索引的内容将在第 66.6 节中进一步讨论。
表空间会使上述情况更复杂。每个用户定义的表空间都在 PGDATA/pg_tblspc 下有一个符号链接，指向实际表空间目录，即 CREATE TABLESPACE 中指定的位置，链接名为表空间的 OID。实际目录中还有一个依赖 PostgreSQL 服务器版本命名的子目录，例如 PG_9.0_201008051，以便不同数据库版本可以共用同一个 CREATE TABLESPACE 位置而不冲突。版本子目录下，再为每个在此表空间中存储对象的数据库创建以其 OID 命名的子目录；表和索引使用 filenode 命名方案存放于此。pg_default 不通过 pg_tblspc 访问，而是对应 PGDATA/base；同样，pg_global 对应 PGDATA/global。
pg_relation_filepath() 给出任意关系相对于 PGDATA 的完整路径，通常可替代记忆上述多条规则。但该函数仅返回关系主分叉第一个分段的文件名；要找到该关系的全部文件，可能还需追加分段号和／或 _fsm、_vm、_init 后缀。
临时文件用于排序等无法完全放入内存的操作，创建于 PGDATA/base/pgsql_tmp。如果指定使用 pg_default 以外的表空间，则位于该表空间目录的 pgsql_tmp 子目录中。文件名形如 pgsql_tmpPPP.NNN，PPP 为所属后端的 PID，NNN 用来区分同一后端的不同临时文件。
相关条目
文档与源码
来源构建
- 版本
- 18.6
- 构建
- https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
- 来源指纹
555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f
版本比较
PostgreSQL 12 → 13: 属性变化。
以下差异保留原始字段名与英文源描述。
--- PostgreSQL 12
+++ PostgreSQL 13
@@ -99,7 +99,7 @@
},
{
"c0": "postmaster.pid",
- "c1": "A lock file recording the current postmaster process ID (PID), cluster data directory path, postmaster start timestamp, port number, Unix-domain socket directory path (empty on Windows), first valid listen_address (IP address or * , or empty if not listening on TCP), and shared memory segment ID (this file is not present after server shutdown)"
+ "c1": "A lock file recording the current postmaster process ID (PID), cluster data directory path, postmaster start timestamp, port number, Unix-domain socket directory path (could be empty), first valid listen_address (IP address or * , or empty if not listening on TCP), and shared memory segment ID (this file is not present after server shutdown)"
}
],
"title": "Contents of PGDATA"比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。
相关条目
导出 JSON · 返回存储结构 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。