From 72d422a5227ef6f76f412486a395aba9f53bf3f0 Mon Sep 17 00:00:00 2001 From: Andrew Dunstan Date: Tue, 12 May 2015 09:29:10 -0400 Subject: Map basebackup tablespaces using a tablespace_map file Windows can't reliably restore symbolic links from a tar format, so instead during backup start we create a tablespace_map file, which is used by the restoring postgres to create the correct links in pg_tblspc. The backup protocol also now has an option to request this file to be included in the backup stream, and this is used by pg_basebackup when operating in tar mode. This is done on all platforms, not just Windows. This means that pg_basebackup will not not work in tar mode against 9.4 and older servers, as this protocol option isn't implemented there. Amit Kapila, reviewed by Dilip Kumar, with a little editing from me. --- doc/src/sgml/backup.sgml | 32 +++++++++++++++++++------------- doc/src/sgml/func.sgml | 14 ++++++++------ doc/src/sgml/protocol.sgml | 15 ++++++++++++++- doc/src/sgml/ref/pg_basebackup.sgml | 14 +++++++++++++- 4 files changed, 54 insertions(+), 21 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index e25e0d0edf7..def43a21da2 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -836,8 +836,11 @@ SELECT pg_start_backup('label'); pg_start_backup creates a backup label file, called backup_label, in the cluster directory with information about your backup, including the start time and label - string. The file is critical to the integrity of the backup, should - you need to restore from it. + string. The function also creates a tablespace map file, + called tablespace_map, in the cluster directory with + information about tablespace symbolic links in pg_tblspc/ + if one or more such link is present. Both files are critical to the + integrity of the backup, should you need to restore from it. @@ -965,17 +968,20 @@ SELECT pg_stop_backup(); It's also worth noting that the pg_start_backup function - makes a file named backup_label in the database cluster - directory, which is removed by pg_stop_backup. - This file will of course be archived as a part of your backup dump file. - The backup label file includes the label string you gave to - pg_start_backup, as well as the time at which - pg_start_backup was run, and the name of the starting WAL - file. In case of confusion it is therefore possible to look inside a - backup dump file and determine exactly which backup session the dump file - came from. However, this file is not merely for your information; its - presence and contents are critical to the proper operation of the system's - recovery process. + makes files named backup_label and + tablesapce_map in the database cluster directory, + which are removed by pg_stop_backup. These files will of + course be archived as a part of your backup dump file. The backup label + file includes the label string you gave to pg_start_backup, + as well as the time at which pg_start_backup was run, and + the name of the starting WAL file. In case of confusion it is therefore + possible to look inside a backup dump file and determine exactly which + backup session the dump file came from. The tablespace map file includes + the symbolic link names as they exist in the directory + pg_tblspc/ and the full path of each symbolic link. + These files are not merely for your information; their presence and + contents are critical to the proper operation of the system's recovery + process. diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 1ee4f634d3a..bf8d72e9ff9 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -16591,11 +16591,12 @@ SELECT set_config('log_statement_stats', 'off', false); pg_start_backup accepts an arbitrary user-defined label for the backup. (Typically this would be the name under which the backup dump file will be stored.) The function - writes a backup label file (backup_label) into the - database cluster's data directory, performs a checkpoint, - and then returns the backup's starting transaction log location as text. - The user can ignore this result value, but it is - provided in case it is useful. + writes a backup label file (backup_label) and, if there + are any links in the pg_tblspc/ directory, a tablespace map + file (tablespace_map) into the database cluster's data + directory, performs a checkpoint, and then returns the backup's starting + transaction log location as text. The user can ignore this result value, + but it is provided in case it is useful. postgres=# select pg_start_backup('label_goes_here'); pg_start_backup @@ -16610,7 +16611,8 @@ postgres=# select pg_start_backup('label_goes_here'); - pg_stop_backup removes the label file created by + pg_stop_backup removes the label file and, if it exists, + the tablespace_map file created by pg_start_backup, and creates a backup history file in the transaction log archive area. The history file includes the label given to pg_start_backup, the starting and ending transaction log locations for diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index ac13d3201ce..d985204566c 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1882,7 +1882,7 @@ The commands accepted in walsender mode are: - BASE_BACKUP [LABEL 'label'] [PROGRESS] [FAST] [WAL] [NOWAIT] [MAX_RATE rate] + BASE_BACKUP [LABEL 'label'] [PROGRESS] [FAST] [WAL] [NOWAIT] [MAX_RATE rate] [TABLESPACE_MAP] BASE_BACKUP @@ -1968,6 +1968,19 @@ The commands accepted in walsender mode are: + + + 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. + + + diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index 642fccf325f..07d3a5a1dcf 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -587,11 +587,23 @@ PostgreSQL documentation tablespaces. + + When tar format mode is used, it is the user's responsibility to unpack each + tar file before starting postgres. If there are additional tablespaces, the + tar files for them need to be unpacked in the correct locations. In this + case the symbolic links for those tablespaces will be created by Postgres + according to the contents of the tablespace_map file that is + included in the base.tar file. + + pg_basebackup works with servers of the same or an older major version, down to 9.1. However, WAL streaming mode (-X - stream) only works with server version 9.3 and later. + stream) only works with server version 9.3 and later, and tar format mode + (--format=tar) of the current version only works with server version 9.5 + or later. + -- cgit v1.2.3