From fa4fe2ed932ddef90ff2e4cff1e42715139f8d4c Mon Sep 17 00:00:00 2001 From: Asif Rehman Date: Thu, 7 Nov 2019 16:52:40 +0500 Subject: [PATCH 7/7] parallel backup documentation --- doc/src/sgml/protocol.sgml | 386 ++++++++++++++++++++++++++++ doc/src/sgml/ref/pg_basebackup.sgml | 20 ++ 2 files changed, 406 insertions(+) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 80275215e0..22d620c346 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -2700,6 +2700,392 @@ The commands accepted in replication mode are: + + + START_BACKUP + [ LABEL 'label' ] + [ PROGRESS ] + [ FAST ] + [ TABLESPACE_MAP ] + + 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. + + + + + + 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. + + + + + + FAST + + + Request a fast checkpoint. + + + + + + TABLESPACE_MAP + + + Include information about symbolic links present in the directory + pg_tblspc in a file named + tablespace_map. The tablespace map file includes + each symbolic link name as it exists in the directory + pg_tblspc/ and the full path of that symbolic link. + + + + + + + + In response to this command, server will send out three result sets. + + + The first ordinary result set contains the starting position of the + backup, in a single row with two columns. The first column contains + the start position given in XLogRecPtr format, and the second column + contains the corresponding timeline ID. + + + + The second ordinary result set has 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. + + + + + + + + The final result set will be sent in a single row with two columns. The + first column contains the data of backup_label file, + and the second column contains the data of tablespace_map. + + + + + + + STOP_BACKUP + [ LABEL 'label' ] + [ WAL ] + [ NOWAIT ] + + STOP_BACKUP + + + + + Instructs the server to finish performing on-line backup. The following + options are accepted: + + + LABEL'string' + + + Provides the content of backup_label file to the backup. The content are + the same that were returned by START_BACKUP. + + + + + WAL + + + Include the necessary WAL segments in the backup. This will include + all the files between start and stop backup in the + pg_wal directory of the base directory tar + file. + + + + + 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 one or more CopyResponse + results followed by a single result set, containing the WAL end position of + the backup. The CopyResponse contains pg_control and + WAL files, if stop backup is run with WAL option. + + + + + + SEND_BACKUP_FILELIST + SEND_BACKUP_FILELIST + + + + + Instruct the server to return a list of files and directories, available in + data directory. In response to this command, server will send one result set + per tablespace. The result sets consist of following fields: + + + + + 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, identifing 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. + + + + + + + This list will contain all files and directories in the $PGDATA, 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.) + + + + Owner, group, and file mode are set if the underlying file system on the server + supports it. + + + + + + SEND_BACKUP_FILES ( 'FILE' [, ...] ) + [ MAX_RATE rate ] + [ NOVERIFY_CHECKSUMS ] + [ START_WAL_LOCATION ] + + SEND_BACKUP_FILES + + + + + Instructs the server to send the contents of the requested FILE(s). + + + + A clause of the form SEND_BACKUP_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: + + + MAX_RATE rate + + + Limit (throttle) the maximum amount of data transferred from server + to client per unit of time. The expected unit is kilobytes per second. + If this option is specified, the value must either be equal to zero + or it must fall within the range from 32 kB through 1 GB (inclusive). + If zero is passed or the option is not specified, no restriction is + imposed on the transfer. + + + + + + NOVERIFY_CHECKSUMS + + + By default, checksums are verified during a base backup if they are + enabled. Specifying NOVERIFY_CHECKSUMS disables + this verification. + + + + + + START_WAL_LOCATION + + + The starting WAL position when START BACKUP command was issued, + returned in the form of XLogRecPtr format. + + + + + + + diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index fc9e222f8d..339e68bda7 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -536,6 +536,26 @@ 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.0 (Apple Git-122.2)