From 7fd87b7dcb9c626fa6abb3d526de284a93f232c5 Mon Sep 17 00:00:00 2001 From: Asif Rehman Date: Fri, 14 Feb 2020 17:02:51 +0500 Subject: [PATCH 6/6] parallel backup - documentation --- doc/src/sgml/protocol.sgml | 366 ++++++++++++++++++++++++++++ doc/src/sgml/ref/pg_basebackup.sgml | 19 ++ 2 files changed, 385 insertions(+) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 80275215e0..e332d1ac45 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -2700,6 +2700,372 @@ The commands accepted in replication mode are: + + + START_BACKUP + [ LABEL 'label' ] + [ FAST ] + START_BACKUP + + + + Instructs the server to prepare for performing on-line backup. The following + options are accepted: + + + LABEL 'label' + + + Sets the label of the backup. If none is specified, a backup label + of start backup will be used. The quoting rules + for the label are the same as a standard SQL string with + turned on. + + + + + FAST + + + Request a fast checkpoint. + + + + + + + In response to this command, server will send out a single result set. The + first column contains the start position given in XLogRecPtr format, and + the second column contains the corresponding timeline ID. + + + + + + STOP_BACKUP + [ NOWAIT ] + STOP_BACKUP + + + + Instructs the server to finish performing on-line backup. + + + NOWAIT + + + By default, the backup will wait until the last required WAL + segment has been archived, or emit a warning if log archiving is + not enabled. Specifying NOWAIT disables both + the waiting and the warning, leaving the client responsible for + ensuring the required log is available. + + + + + + + In response to this command, server will send out a single result set. The + first column contains the start position given in XLogRecPtr format, the + second column contains the corresponding timeline ID and the third column + contains the contents of the backup_label file. + + + + + + LIST_TABLESPACES + [ PROGRESS ] + LIST_TABLESPACES + + + + Instruct the server to return a list of tablespaces available in data + directory. + + + PROGRESS + + + Request information required to generate a progress report. This will + send back an approximate size in the header of each tablespace, which + can be used to calculate how far along the stream is done. This is + calculated by enumerating all the file sizes once before the transfer + is even started, and might as such have a negative impact on the + performance. In particular, it might take longer before the first data + is streamed. Since the database files can change during the backup, + the size is only approximate and might both grow and shrink between + the time of approximation and the sending of the actual files. + + + + + + + In response to this command, server will send one result set. + The result set will have one row for each tablespace. The fields in this + row are: + + + spcoid (oid) + + + The OID of the tablespace, or null if it's the base directory. + + + + + spclocation (text) + + + The full path of the tablespace directory, or null if it's the base + directory. + + + + + size (int8) + + + The approximate size of the tablespace, in kilobytes (1024 bytes), + if progress report has been requested; otherwise it's null. + + + + + + + + + + LIST_FILES + [ TABLESPACE ] + LIST_FILES + + + + This command instructs the server to return a list of files available + in the given tablespace. + + + TABLESPACE + + + name of the tablespace. If its empty or not provided then 'base' tablespace + is assumed. + + + + + + + In response to this command, server will send out a result set. The fields + in this result set are: + + + path (text) + + + The path and name of the file. In case of tablespace, it is an absolute + path on the database server, however, in case of base + tablespace, it is relative to $PGDATA. + + + + + type (char) + + + A single character, identifying the type of file. + + + + 'f' - Regular file. Can be any relation or + non-relation file in $PGDATA. + + + + + 'd' - Directory. + + + + + 'l' - Symbolic link. + + + + + + + + size (int8) + + + The approximate size of the file, in kilobytes (1024 bytes). It's null + if type is 'd' or 'l'. + + + + + mtime (Int64) + + + The file or directory last modification time, as seconds since the Epoch. + + + + + + + The list will contain all files in tablespace directory, regardless of whether + they are PostgreSQL files or other files added to the same directory. The only + excluded files are: + + + + postmaster.pid + + + + + postmaster.opts + + + + + pg_internal.init (found in multiple directories) + + + + + Various temporary files and directories created during the operation + of the PostgreSQL server, such as any file or directory beginning + with pgsql_tmp and temporary relations. + + + + + Unlogged relations, except for the init fork which is required to + recreate the (empty) unlogged relation on recovery. + + + + + pg_wal, including subdirectories. If the backup is run + with WAL files included, a synthesized version of pg_wal + will be included, but it will only contain the files necessary for the backup + to work, not the rest of the contents. + + + + + pg_dynshmem, pg_notify, + pg_replslot, pg_serial, + pg_snapshots, pg_stat_tmp, and + pg_subtrans are copied as empty directories (even if + they are symbolic links). + + + + + Files other than regular files and directories, such as symbolic + links (other than for the directories listed above) and special + device files, are skipped. (Symbolic links + in pg_tblspc are maintained.) + + + + + + + + + LIST_WAL_FILES + START_WAL_LOCATION X/X + END_WAL_LOCATION X/X + LIST_WAL_FILES + + + + Instruct the server to return a list of WAL files available in pg_wal directory. + The following options are accepted: + + + START_WAL_LOCATION + + + The starting WAL position when START BACKUP command was issued, + returned in the form of XLogRecPtr format. + + + + + END_WAL_LOCATION + + + The ending WAL position when STOP BACKUP command was issued, + returned in the form of XLogRecPtr format. + + + + + + + In response to this command, server will send out a result and each row will + consist of a WAL file entry. The result set will have the same fields as + LIST_FILES command. + + + + + + SEND_FILES ( 'FILE' [, ...] ) + [ START_WAL_LOCATION X/X ] + [ NOVERIFY_CHECKSUMS ] + SEND_FILES + + + + Instructs the server to send the contents of the requested FILE(s). + + + A clause of the form SEND_FILES ( 'FILE', 'FILE', ... ) [OPTIONS] + is accepted where one or more FILE(s) can be requested. + + + In response to this command, one or more CopyResponse results will be sent, + one for each FILE requested. The data in the CopyResponse results will be + a tar format (following the “ustar interchange format” specified in the + POSIX 1003.1-2008 standard) dump of the tablespace contents, except that + the two trailing blocks of zeroes specified in the standard are omitted. + + + The following options are accepted: + + + START_WAL_LOCATION + + + The starting WAL position when START BACKUP command was issued, + returned in the form of XLogRecPtr format. + + + + + NOVERIFY_CHECKSUMS + + + By default, checksums are verified during a base backup if they are + enabled. Specifying NOVERIFY_CHECKSUMS disables + this verification. + + + + + + + diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index fc9e222f8d..3b1d9c9ba6 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -536,6 +536,25 @@ PostgreSQL documentation + + + + + + + Create n threads to copy + backup files from the database server. pg_basebackup + will open n +1 connections + to the database. Therefore, the server must be configured with + set high enough to accommodate all + connections. + + + parallel mode only works with plain format. + + + + -- 2.21.1 (Apple Git-122.3)