pg_basebackup
From PostgreSQL
pg_basebackup
描述
pg_basebackup被用于获得一个正在运行的PostgreSQL数据库集簇的基础备份。获得这些备份不会影响连接到该数据库的其他客户端，并且可以被用于时间点恢复（见第 25.3 节）以及用作一个日志传送或流复制后备服务器的开始点（见第 26.2 节）。
pg_basebackup建立数据库集簇文件的一份二进制副本，同时保证系统进入和退出备份模式。备份总是从整个数据库集簇获得，不可能备份单个数据库或数据库对象。关于个体数据库备份，必须使用一个像pg_dump的工具。
备份通过一个常规PostgreSQL连接制作，并且使用复制协议。该连接必须由一个超级用户或者一个具有REPLICATION权限（第 21.2 节）的用户建立，并且pg_hba.conf必须显式地允许该复制连接。该服务器还必须被配置，使max_wal_senders设置得足够高以留出至少一个会话用于备份。
在同一时间可以有多个pg_basebackup运行，但是从性能的角度来说最好只做一个备份并且复制结果。
pg_basebackup不仅能从主控机也能从后备机创建一个基础备份。要从后备机获得一个备份，设置后备机让它能接受复制连接（也就是，设置max_wal_senders和hot_standby，并且配置基于主机的认证）。你将也需要在主控机上启用full_page_writes。
注意在来自后备机的在线备份中有一些限制：
-
不会在被备份的数据库集簇中创建备份历史文件。
-
不保证备份所需的所有 WAL 文件在备份结束时被归档。如果你计划将该备份用于一次归档恢复并且想要确保所有所需文件在那个时刻都可用，你需要通过使用-x将它们包括在备份中。
-
如果在在线备份期间后备机被提升为主控机，备份会失败。
-
备份所需的所有 WAL 记录必须包含足够的全页写，这要求你在主控机上启用full_page_writes并且不使用一个类似pg_compresslog的工具以archive_command从 WAL 文件中移除全页写。
选项
下列命令行选项控制输出的位置和格式。
- -D directory --pgdata= directory
-
将输出写到哪个目录。如果必要，pg_basebackup将创建该目录及任何父目录。该目录可能已经存在，但是如果该目录已经存在并且非空就是一个错误。
当备份处于 tar 模式中并且目录被指定为-（破折号）时，tar 文件将被写到stdout。
这个选项是必需的。
-
-F
format
--format= format -
为输出选择格式。format可以是下列之一：
-
p
plain -
把输出写成平面文件，使用和当前数据目录和表空间相同的布局。当集簇没有额外表空间时，整个数据库将被放在目标目录中。如果集簇包含额外的表空间，主数据目录将被放置在目标目录中，但是所有其他表空间将被放在它们位于服务器上的相同的绝对路径中。
这是默认格式。
-
t
tar -
将输出写成目标目录中的 tar 文件。主数据目录将被写入到一个名为base.tar的文件中，并且其他表空间将被以其 OID 命名。
如果值-（破折号）被指定为目标目录，tar 内容将被写到标准输出，适合于管道输出到其他程序，例如gzip。只有当集簇没有额外表空间时这才是可能的。
-
p
-
-r
rate
--max-rate= rate -
从该服务器传输数据的最大传输率。值的单位是千字节每秒。加上一个后缀M表示兆字节每秒。也接受后缀k，但是没有效果。合法的值在 32 千字节每秒到 1024 兆字节每秒之间。
其目标是限制在运行服务器上的pg_basebackup产生的影响。
这个选项总是会影响数据目录的传输。如果收集方法是fetch时，只有 WAL 文件受到影响。
-
-R
--write-recovery-conf -
在输出目录中（或者当使用 tar 格式时再基础归档文件中）写一个最小的recovery.conf来简化设置一个后备服务器。recovery.conf文件将记录连接设置（如果有）以及pg_basebackup所使用的复制槽，这样流复制后面就会使用相同的设置。
-
-S
slotname
--slot= slotname -
这个选项只能和-X stream一起使用。它导致 WAL 流使用指定的复制槽。如果该基础备份意图用作一个使用复制槽的流复制后备服务器，它应该使用recovery.conf中相同的复制槽名称。那样就可以确保服务器不会移除基础备份结束和流复制开始之前任何必要的 WAL 数据。
- -T olddir=newdir
--tablespace-mapping=olddir=newdir -
在备份期间将目录olddir中的表空间重定位到newdir中。为使之有效，olddir必须正好匹配表空间所在的路径（但如果备份中没有包含olddir中的表空间也不是错误）。olddir和newdir必须是绝对路径。如果一个路径凑巧包含了一个=符号，可用反斜线对它转义。对于多个表空间可以多次使用这个选项。例子见下文。
如果以这种方法重定位一个表空间，主数据目录中的符号链接会被更新成指向新位置。因此新数据目录已经可以被一个所有表空间位于更新后位置的新服务器实例使用。
- --xlogdir= xlogdir
-
指定用于事务日志目录的位置。xlogdir必须是绝对路径。只有当备份是平面文件模式时才能指定事务日志目录。
-
-x
--xlog -
使用这个选项等效于和方法fetch一起使用-X。
-
-X
method
--xlog-method= method -
在备份中包括所需的事务日志文件（WAL 文件）。这将包括所有在备份期间产生的事务日志。如果这个选项被指定，可以在抽取出的目录中直接启动一个 postmaster，而不需要参考日志归档，因此使得这是一个完全独立的备份。
我们支持下列收集事务日志的方法：
-
f
fetch -
在备份末尾收集事务日志文件。因此，有必要把wal_keep_segments参数设置得足够高，这样在备份末尾之前日志不会被移除。如果在要传输日志时它已经被轮转，备份将失败并且是不可用的。
-
s
stream -
在备份被创建时流传送事务日志。这将开启一个到服务器的第二连接并且在运行备份时并行开始流传输事务日志。因此，它将使用最多两个由max_wal_senders参数配置的连接。只要客户端能保持接收事务日志，使用这种模式不需要在主控机上保存额外的事务日志。
-
f
-
-z
--gzip -
启用对 tar 文件输出的 gzip 压缩，使用默认的压缩级别。只有使用 tar 格式时压缩才可用。
-
-Z
level
--compress= level -
启用对 tar 文件输出的 gzip 压缩，并且制定压缩机别（0 到 9，0 是不压缩，9 是最佳压缩）。只有使用 tar 格式时压缩才可用。
下列命令行选项控制备份的生成和程序的运行。
-
-c
fast|spread
--checkpoint= fast|spread -
将检查点模式设置为 fast 或 spread（默认）（见第 25.3.3 节）。
-
-l
label
--label= label -
为备份设置标签。如果没有指定，将使用一个默认值"pg_basebackup base backup"。
-
-P
--progress -
启用进度报告。启用这个选项将在备份期间发表一个大致的进度报告。由于数据库可能在备份期间改变，这仅仅是一种近似并且可能不会刚好在100%结束。特别地，当 WAL 日志被包括在备份中时，总数据量无法预先估计，并且在这种情况中估计的目标尺寸会在它经过不带 WAL 的总估计后增加。
当这个选项被启用时，备份开始时会列举整个数据库的尺寸，并且接着回头开始发送实际的内容。这可能使备份需要多花一点点时间，并且它在发送第一个数据之前花费的时间更长。
-
-v
--verbose -
启用冗长模式。将在启动和关闭期间输出一些额外步骤，并且如果进度报告也被启用，还会显示当前正在被处理的确切文件名。
下列命令行选项控制数据库连接参数。
-
-d
connstr
--dbname= connstr -
以一个连接字符串的形式指定用于连接到服务器的参数。详见第 32.1.1 节。
为了和其他客户端应用一致，该选项被称为--dbname。但是因为pg_basebackup并不连接到集簇中的任何特定数据库，连接字符串中的数据库名将被忽略。
-
-h
host
--host= host -
指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。默认值取自PGHOST环境变量（如果设置），否则会尝试一个 Unix 域套接字连接。
-
-p
port
--port= port -
指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。默认用PGPORT环境变量中的值（如果设置），或者一个编译在程序中的默认值。
-
-s
interval
--status-interval= interval -
指定发送回服务器的状态包之间的秒数。这允许我们更容易地监控服务器的进度。一个零值完全禁用这种周期性的状态更新，不过当服务器需要时还是会有一个更新会被发送来避免超时导致的断开连接。默认值是 10 秒。
-
-U
username
--username= username -
要作为哪个用户连接。
-
-w
--no-password -
从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个.pgpass文件），那儿连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。
-
-W
--password -
强制pg_basebackup在连接到一个数据库之前提示要求一个口令。
这个选项不是必不可少的，因为如果服务器要求口令认证，pg_basebackup将自动提示要求一个口令。但是，pg_basebackup将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用-W来避免额外的连接尝试。
其他选项也可用：
-
-V
--version -
打印pg_basebackup版本并退出。
-
-?
--help -
显示有关pg_basebackup命令行参数的帮助并退出。
注解
备份将包括数据目录和表空间中的所有文件，包括配置文件以及第三方放置在该目录中的任何附加文件。但是只复制常规文件和目录。符号链接（除了用于表空间的）和特殊的设备文件会被跳过（细节见第 51.3 节）。
表空间默认将以普通格式备份到与它们在服务器上相同的路径中，除非使用了--tablespace-mapping选项。如果没有这个选项并且表空间正在使用，在同一台服务器上进行普通格式的基础备份将无法工作，因为备份必须要写入到与原始表空间相同的目录位置。
在使用 tar 格式模式时，用户应负责在启动 PostgreSQL 服务器前解压每一个 tar 文件。如果有额外的表空间，用于它们的 tar 文件需要被解压到正确的位置。在这种情况下，服务器将根据包含在base.tar文件中的tablespace_map文件的内容为那些表空间创建符号链接。
pg_basebackup可以和具有相同或较低主版本的服务器一起工作，最低是 9.1。但是，WAL 流模式（-X 流）只能和版本为 9.3 及以上版本的服务器一起工作。当前版本的 tar 格式模式（--format=tar）只能用于版本 9.5 及以上的服务器。
例子
要创建服务器mydbserver的一个基础备份并将它存储在本地目录/usr/local/pgsql/data中：
$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
要创建本地服务器的一个备份，为其中每一个表空间产生一个压缩过的 tar 文件，并且将它存储在目录backup中，在运行期间显示一个进度报告：
$ pg_basebackup -D backup -Ft -z -P
要创建一个单一表空间本地数据库的备份并且使用bzip2压缩它：
$ pg_basebackup -D - -Ft | bzip2 > backup.tar.bz2
（如果在该数据库中有多个表空间，这个命令将失败）。
要创建一个本地数据库的备份，其中/opt/ts中的表空间被重定位到./backup/ts：
$ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts