## 皮克\_基本备份

皮克\_basebackup — 对 PostgreSQL 集群进行基本备份

## 概要

`pg_basebackup` [*`选项`*...]

## 描述

皮克\_basebackup 用于对正在运行的 PostgreSQL 数据库集群进行基本备份。备份是在不影响数据库的其他客户端的情况下进行的，并且可以用于时间点恢复（请参阅[第 26.3 节](continuous-archiving.html)) 并作为日志传送或流复制备用服务器的起点（请参阅[第 27.2 节](warm-standby.html)）。

皮克\_basebackup 制作数据库集群文件的精确副本，同时确保服务器自动进入和退出备份模式。总是对整个数据库集群进行备份；无法备份单个数据库或数据库对象。对于选择性备份，另一种工具，例如[皮克\_倾倒](app-pgdump.html)必须使用。

备份是通过使用复制协议的常规 PostgreSQL 连接进行的。必须使用具有以下内容的用户 ID 建立连接`复制`权限（见[第 22.2 节](role-attributes.html)) 或者是超级用户，并且[`pg_hba.conf`](auth-pg-hba-conf.html)必须允许复制连接。服务器还必须配置[最大限度\_沃尔\_发件人](runtime-config-replication.html#GUC-MAX-WAL-SENDERS)设置得足够高以提供至少一个用于备份的 walsender 和一个用于 WAL 流式传输（如果使用）。

可以有多个`pg_basebackup`s 同时运行，但从性能的角度来看，通常只进行一次备份并复制结果会更好。

皮克\_basebackup 不仅可以从主服务器，还可以从备用服务器进行基本备份。要从备用数据库进行备份，请设置备用数据库以便它可以接受复制连接（即，设置`max_wal_senders`和[热的\_支持](runtime-config-replication.html#GUC-HOT-STANDBY)，并配置其`pg_hba.conf`适当）。您还需要启用[满的\_页\_写](runtime-config-wal.html#GUC-FULL-PAGE-WRITES)在初级。

请注意，从备用数据库进行备份有一些限制：

-   备份的数据库集群中没有创建备份历史文件。

-   皮克\_basebackup 不能强制备用数据库在备份结束时切换到新的 WAL 文件。当您使用`-X 无`，如果主节点上的写活动很低，pg_basebackup 可能需要等待很长时间才能切换和归档备份所需的最后一个 WAL 文件。在这种情况下，运行可能很有用`pg_switch_wal`在主节点上以触发立即 WAL 文件切换。

-   如果在备份期间将备用数据库提升为主数据库，则备份将失败。

-   备份所需的所有 WAL 记录必须包含足够的整页写入，这需要您启用`full_page_writes`在初级上而不是使用像 pg 这样的工具\_压缩日志为`归档命令`从 WAL 文件中删除整页写入。

    每当 pg_basebackup 进行基本备份，服务器的`pg_stat_progress_basebackup`view 将报告备份的进度。看[第 28.4.5 节](progress-reporting.html#BASEBACKUP-PROGRESS-REPORTING)详情。

## 选项

以下命令行选项控制输出的位置和格式：

`-D *`目录`*`\
`--pgdata=*`目录`*`

设置要写入输出的目标目录。皮克\_如果此目录不存在，basebackup 将创建此目录（以及任何缺少的父目录）。如果它已经存在，它必须是空的。

当备份为 tar 格式时，目标目录可以指定为`-`（破折号），导致 tar 文件被写入`标准输出`.

此选项是必需的。

`-F *`格式`*`\
`--格式=*`格式`*`

选择输出格式。*`格式`*可以是以下之一：

`p`\
`清楚的`

将输出写入纯文件，与源服务器的数据目录和表空间具有相同的布局。当集群没有额外的表空间时，整个数据库将被放置在目标目录中。如果集群包含额外的表空间，主数据目录将放置在目标目录中，但所有其他表空间将放置在与源服务器上相同的绝对路径中。（看`--表空间映射`改变它。）

这是默认格式。

`吨`\
`柏油`

将输出作为 tar 文件写入目标目录。主数据目录的内容将被写入一个名为`基础.tar`，并且每个其他表空间将被写入以该表空间的 OID 命名的单独 tar 文件。

如果目标目录指定为`-`（破折号），tar 内容将被写入标准输出，适合管道到（例如）gzip。仅当集群没有额外的表空间并且不使用 WAL 流时才允许这样做。

`-R`\
`--write-recovery-conf`

创建一个[`待机信号`](warm-standby.html#FILE-STANDBY-SIGNAL) [](<>)文件并将连接设置附加到`postgresql.auto.conf`目标目录中的文件（或使用 tar 格式时在基本存档文件中）。这简化了使用备份结果设置备用服务器的过程。

这`postgresql.auto.conf`文件将记录连接设置，如果指定，则记录该 pg 的复制槽\_basebackup 正在使用，因此流复制稍后将使用相同的设置。

`-T *`旧目录`*=*`新目录`*`\
`--表空间映射=*`旧目录`*=*`新目录`*`

重定位目录中的表空间*`旧目录`*到*`新目录`*在备份期间。为了有效，*`旧目录`*必须与源服务器上定义的表空间的路径规范完全匹配。（但是如果里面没有表空间也不是错误*`旧目录`*在源服务器上。）同时*`新目录`*是接收主机文件系统中的一个目录。与主目标目录一样，*`新目录`*不必已经存在，但如果它确实存在，它必须是空的。两个都*`旧目录`*和*`新目录`*必须是绝对路径。如果任一路径需要包含等号 (`=`)，在其前面加上反斜杠。可以为多个表空间多次指定此选项。

如果以这种方式重定位表空间，则主数据目录内的符号链接将更新为指向新位置。因此，新数据目录已准备好用于所有表空间都在更新位置的新服务器实例。

目前，此选项仅适用于纯输出格式；如果选择了 tar 格式，则忽略它。

`--waldir=*`瓦尔迪尔`*`

设置要写入 WAL（预写日志）文件的目录。默认情况下，WAL 文件将放置在`pg_wal`目标目录的子目录，但此选项可用于将它们放置在其他位置。*`瓦尔迪尔`*必须是绝对路径。与主目标目录一样，*`瓦尔迪尔`*不必已经存在，但如果它确实存在，它必须是空的。仅当备份为纯格式时才能指定此选项。

`-X *`方法`*`\
`--wal方法=*`方法`*`

在备份中包含所需的 WAL（预写日志）文件。这将包括备份期间生成的所有预写日志。除非方法`没有`指定后，可以在目标目录中启动 postmaster 而无需查阅日志存档，从而使输出成为完全独立的备份。

下列*`方法`*支持用于收集预写日志的 s：

`n`\
`没有`

不要在备份中包含预写日志。

`f`\
`拿来`

在备份结束时收集预写日志文件。因此，有必要对源服务器的[沃尔\_保持\_尺寸](runtime-config-replication.html#GUC-WAL-KEEP-SIZE)参数设置得足够高，以便在备份结束之前不会删除所需的日志数据。如果所需的日志数据在传输之前已被回收，则备份将失败并且无法使用。

使用 tar 格式时，预写日志文件将包含在`基础.tar`文件。

`s`\
`溪流`

在进行备份时流式传输预写日志数据。此方法将打开与服务器的第二个连接，并在运行备份时开始并行传输预写日志。因此，它将需要两个复制连接，而不仅仅是一个。只要客户端能够跟上预写日志数据，使用这种方法就不需要在源服务器上保存额外的预写日志。

当使用 tar 格式时，预写日志文件将被写入一个名为`pg_wal.tar`（如果服务器是10之前的版本，文件会被命名为`pg_xlog.tar`）。

此值为默认值。

`-z`\
`--gzip`

使用默认压缩级别启用 tar 文件输出的 gzip 压缩。压缩仅在使用 tar 格式时可用，并且后缀`.gz`将自动添加到所有 tar 文件名中。

`-Z *`等级`*`\
`--压缩=*`等级`*`

启用 tar 文件输出的 gzip 压缩，并指定压缩级别（0 到 9，0 表示不压缩，9 表示最佳压缩）。压缩仅在使用 tar 格式时可用，并且后缀`.gz`将自动添加到所有 tar 文件名中。

以下命令行选项控制备份的生成和程序的调用：

`-c *`快速|传播`*`\
`--检查点=*`快速|传播`*`

将检查点模式设置为快速（立即）或传播（默认）（请参阅[第 26.3.3 节](continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP)）。

`-C`\
`--创建槽`

指定由`- 投币口`应在开始备份之前创建选项。如果插槽已存在，则会引发错误。

`-l *`标签`*`\
`--标签=*`标签`*`

设置备份的标签。如果未指定，则默认值为“`pg_basebackup 基本备份`“ 将会被使用。

`-n`\
`--免洗`

默认情况下，当`pg_basebackup`中止错误，它会删除它可能在发现无法完成作业之前创建的所有目录（例如，目标目录和预写日志目录）。此选项禁止整理，因此对调试很有用。

请注意，表空间目录不会以任何方式清理。

`-N`\
`--不同步`

默认情况下，`pg_basebackup`将等待所有文件安全地写入磁盘。此选项导致`pg_basebackup`无需等待即可返回，这更快，但意味着随后的操作系统崩溃可能会使基本备份损坏。通常，此选项可用于测试，但不应在创建生产安装时使用。

`-P`\
`- 进步`

启用进度报告。打开此选项将在备份期间提供大致的进度报告。由于数据库在备份过程中可能会发生变化，这只是一个近似值，可能不会完全结束`100%`.特别是当备份中包含WAL日志时，无法预先估计总数据量，这种情况下，一旦超过了没有WAL的总估计，估计的目标大小就会增加。

`-r *`速度`*`\
`--最大速率=*`速度`*`

设置从源服务器收集数据的最大传输速率。这对于限制 pg 的影响很有用\_服务器上的基本备份。值以千字节每秒为单位。使用后缀`米`表示每秒兆字节。的后缀`ķ`也被接受，并且没有效果。有效值介于每秒 32 千字节和每秒 1024 兆字节之间。

此选项始终影响数据目录的传输。仅当收集方法为`拿来`.

`-S *`槽名`*`\
`--槽=*`槽名`*`

此选项只能与`-X 流`.它导致 WAL 流使用指定的复制槽。如果基本备份打算用作使用复制槽的流复制备用，则备用应使用与复制槽名称相同的复制槽名称[基本的\_投币口\_姓名](runtime-config-replication.html#GUC-PRIMARY-SLOT-NAME).这确保了主服务器在基本备份结束和新备用数据库上的流复制开始之间的时间内不会删除任何必要的 WAL 数据。

指定的复制槽必须存在，除非选项`-C`也被使用。

如果未指定此选项并且服务器支持临时复制槽（版本 10 及更高版本），则临时复制槽将自动用于 WAL 流式传输。

`-v`\
`--详细`

启用详细模式。将在启动和关闭期间输出一些额外的步骤，如果还启用了进度报告，则会显示当前正在处理的确切文件名。

`--manifest-checksums=*`算法`*`

指定应应用于备份清单中包含的每个文件的校验和算法。目前可用的算法有`没有`,`CRC32C`,`SHA224`,`SHA256`,`SHA3​​84`， 和`SHA512`.默认是`CRC32C`.

如果`没有`被选中，备份清单将不包含任何校验和。否则，它将使用指定算法包含备份中每个文件的校验和。此外，清单将始终包含一个`SHA256`自身内容的校验和。这`沙`算法的 CPU 密集程度明显高于`CRC32C`，因此选择其中之一可能会增加完成备份所需的时间。

使用 SHA 哈希函数为希望验证备份未被篡改的用户提供每个文件的加密安全摘要，而 CRC32C 算法提供计算速度更快的校验和；它擅长捕捉由于意外更改而导致的错误，但不抵抗恶意修改。请注意，为了对有权访问备份的对手有用，备份清单需要安全地存储在其他地方，或者以其他方式验证自备份以来没有被修改。

[皮克\_验证备份](app-pgverifybackup.html)可用于根据备份清单检查备份的完整性。

`--manifest-force-encode`

强制备份清单中的所有文件名进行十六进制编码。如果未指定此选项，则仅对非 UTF8 文件名进行十六进制编码。此选项主要用于测试读取备份清单文件的工具是否正确处理这种情况。

`--no-estimate-size`

防止服务器估计将流式传输的备份数据总量，从而导致`备份总计`列中的`pg_stat_progress_basebackup`永远存在`空值`.

如果没有这个选项，备份将从枚举整个数据库的大小开始，然后返回并发送实际内容。这可能会使备份时间稍长一些，尤其是在发送第一个数据之前需要更长时间。如果估计时间太长，此选项对于避免此类估计时间很有用。

使用时不允许此选项`- 进步`.

`--无清单`

禁用备份清单的生成。如果未指定此选项，服务器将生成并发送备份清单，可以使用[皮克\_验证备份](app-pgverifybackup.html).清单是备份中存在的每个文件的列表，但可能包含的任何 WAL 文件除外。它还存储每个文件的大小、上次修改时间和可选的校验和。

`--无槽`

防止为备份创建临时复制槽。

默认情况下，如果选择了日志流，但没有给出插槽名称`-S`选项，然后创建一个临时复制槽（如果源服务器支持）。

此选项的主要目的是允许在服务器没有空闲复制槽时进行基本备份。几乎总是首选使用复制槽，因为它可以防止所需的 WAL 在备份期间被服务器删除。

`--no-verify-checksums`

如果在从中获取基本备份的服务器上启用校验和，则禁用校验和验证。

默认情况下，校验和被验证，校验和失败将导致非零退出状态。但是，在这种情况下不会删除基本备份，就好像`--免洗`选项已被使用。校验和验证失败也会在[`pg_stat_database`](monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW)看法。

以下命令行选项控制与源服务器的连接：

`-d *`connstr`*`\
`--dbname=*`connstr`*`

指定用于连接到服务器的参数，作为[连接字符串](libpq-connect.html#LIBPQ-CONNSTRING);这些将覆盖任何冲突的命令行选项。

该选项被称为`--dbname`为了与其他客户端应用程序保持一致，但因为 pg_basebackup 不连接到集群中的任何特定数据库，连接字符串中的任何数据库名称都将被忽略。

`-h *`主持人`*`\
`--主机=*`主持人`*`

指定运行服务器的机器的主机名。如果该值以斜杠开头，则将其用作 Unix 域套接字的目录。默认值取自`PGHOST`环境变量，如果设置，则尝试 Unix 域套接字连接。

`-p *`港口`*`\
`--端口=*`港口`*`

指定服务器正在侦听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认为`PGPORT`环境变量（如果设置）或编译的默认值。

`-s *`间隔`*`\
`--状态间隔=*`间隔`*`

指定状态数据包发送回源服务器之间的秒数。较小的值允许更准确地监控服务器的备份进度。零值将完全禁用定期状态更新，尽管在服务器请求时仍会发送更新，以避免基于超时的断开连接。默认值为 10 秒。

`-U *`用户名`*`\
`--用户名=*`用户名`*`

指定要连接的用户名。

`-w`\
`--无密码`

防止发出密码提示。如果服务器需要密码验证，而密码无法通过其他方式获得，例如`.pgpass`文件，连接尝试将失败。此选项在没有用户输入密码的批处理作业和脚本中很有用。

`-W`\
`- 密码`

部队pg_basebackup 在连接到源服务器之前提示输入密码。

这个选项从来都不是必需的，因为 pg\_如果服务器要求密码验证，basebackup 会自动提示输入密码。然而，pg_basebackup 将浪费一次连接尝试，发现服务器需要密码。在某些情况下，值得输入`-W`以避免额外的连接尝试。

其他选项也可用：

`-V`\
`- 版本`

打印 pg_basebackup 版本并退出。

`-？`\
`- 帮助`

显示关于 pg 的帮助\_basebackup 命令行参数，然后退出。

## 环境

与大多数其他 PostgreSQL 实用程序一样，此实用程序使用 libpq 支持的环境变量（请参阅[第 34.15 节](libpq-envars.html)).

环境变量`PG_颜色`指定是否在诊断消息中使用颜色。可能的值是`总是`, `汽车`和`从不`.

## 笔记

备份开始时，需要在源服务器上执行检查点。这可能需要一些时间（尤其是如果`--检查点=快速`未使用），在此期间\_basebackup将显示为空闲。

备份将包括数据目录和表空间中的所有文件，包括配置文件和第三方放置在目录中的任何其他文件，PostgreSQL管理的某些临时文件除外。但只复制常规文件和目录，只保留用于表空间的符号链接。指向PostgreSQL已知的某些目录的符号链接被复制为空目录。跳过其他符号链接和特殊设备文件。看见[第53.4节](protocol-replication.html)了解确切的细节。

在普通格式中，表空间将备份到源服务器上的相同路径，除非`--表空间映射`被使用了。如果没有此选项，在使用表空间的情况下，在与服务器相同的主机上运行纯格式基本备份将不起作用，因为备份必须写入与原始表空间相同的目录位置。

当使用tar格式时，用户有责任在启动使用数据的PostgreSQL服务器之前解压缩每个tar文件。如果有额外的表空间，则需要将它们的tar文件解压缩到正确的位置。在这种情况下，这些表空间的符号链接将由服务器根据`表空间映射`包含在`基础焦油`文件

pg_basebackup适用于相同或较旧的主要版本（9.1以下）的服务器。但是，WAL流媒体模式(`-X流`)仅适用于9.3及更高版本的服务器和tar格式(`--格式=焦油`)仅适用于9.5及更高版本的服务器。

pg\_如果在源群集上启用了组权限，basebackup将保留数据文件的组权限。

## 例子

要在创建服务器的基本备份，请执行以下操作：`mydbserver`并将其存储在本地目录中`/usr/local/pgsql/data`:

```
$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
```

为本地服务器创建一个备份，为每个表空间创建一个压缩的tar文件，并将其存储在目录中`备份`，运行时显示进度报告：

```
$ pg_basebackup -D backup -Ft -z -P
```

要创建单个表空间本地数据库的备份，并使用bzip2对其进行压缩，请执行以下操作：

```
$ pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2
```

（如果数据库中有多个表空间，此命令将失败。）

创建本地数据库的备份，其中表空间`/opt/ts`被转移到`/备份/ts`:

```
$ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts
```

## 另见

[pg\_倾倒](app-pgdump.html), [第28.4.5节](progress-reporting.html#BASEBACKUP-PROGRESS-REPORTING)