-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathfaq.html
161 lines (157 loc) · 15.9 KB
/
faq.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head>
<title>pgBackRest - Frequently Asked Questions
</title><meta http-equiv="Content-Type" content="text/html;charset=utf-8"></meta>
<meta property="og:site_name" content="pgBackRest - Reliable PostgreSQL Backup & Restore"></meta>
<meta property="og:title" content="pgBackRest - Frequently Asked Questions"></meta>
<meta property="og:type" content="website"></meta>
<link rel="icon" href="favicon.png" type="image/png"></link>
<meta property="og:image:type" content="image/png"></meta>
<meta property="og:image" content="http://www.pgbackrest.org/logo.png"></meta>
<meta name="description" content="pgBackRest Frequently Asked Questions (FAQ)."></meta>
<meta property="og:description" content="pgBackRest Frequently Asked Questions (FAQ)."></meta>
<link rel="stylesheet" href="default.css" type="text/css"></link>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-VKCRNV73H1"></script>
<script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','G-VKCRNV73H1');</script>
</head><body><div class="page-header"><div class="page-header-title">
pgBackRest
</div><div class="page-header-subtitle">
Frequently Asked Questions
</div></div><div class="page-menu"><div class="menu-body"><div class="menu"><a class="menu-link" href="/">
Home
</a></div><div class="menu"><a class="menu-link" href="user-guide-index.html">
User Guides
</a></div><div class="menu"><a class="menu-link" href="release.html">
Releases
</a></div><div class="menu"><a class="menu-link" href="configuration.html">
Configuration
</a></div><div class="menu"><a class="menu-link" href="command.html">
Commands
</a></div><div class="menu"><a class="menu-link" href="metric.html">
Metrics
</a></div></div></div><div class="page-toc"><div class="page-toc-header"><div class="page-toc-title">
Table of Contents
</div></div><div class="page-toc-body"><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#introduction">
Introduction
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#timeout">
What if I get the <q>could not find WAL segment</q> error?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#manual-expire">
How do I manually purge a backup set?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#optimize-config">
How can I configure options independently for each command?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#s3-bucket">
Can I use dots (periods) in my S3 bucket name?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#old-package">
Where can I find packages for older versions of <span class="backrest">pgBackRest</span>?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#backup-standby">
Why does a backup attempt fail when <span class="br-option">backup-standby=y</span> and the standby database is down?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#standby-repo">
Should I setup my repository on a standby host?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#time-based-pitr">
Time-based Point-in-Time Recovery does not appear to work, why?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#archive-suffix">
What does the WAL archive suffix mean?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#restore-speed">
Does it take longer to restore specific backup types (full, differential, incremental)?
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#self-contained-backup">
How can I export a backup for use in a network-isolated environment?
</a></div></div></div></div><div class="page-body"><div class="section1"><a id="introduction"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Introduction
</div></div><div class="section-body"><div class="section-body-text">
Frequently Asked Questions are intended to provide details for specific questions that may or may not be covered in the User Guide, Configuration, or Command reference. If you are unable to find details for your specific issue here, remember that the <span class="backrest">pgBackRest</span> <a href="https://github.com/pgbackrest/pgbackrest/issues">Issues List in GitHub</a> is also a valuable resource.
</div></div></div><div class="section1"><a id="timeout"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
What if I get the <q>could not find WAL segment</q> error?
</div></div><div class="section-body"><div class="section-body-text">
The cause of this error can be a result of many different issues, some of which may be:
</div><ul class="list-unordered"><li class="list-unordered">
misconfigured archive_command
</li><li class="list-unordered">
misconfigured <span class="backrest">pgBackRest</span> configuration files
</li><li class="list-unordered">
network or permissions issue
</li><li class="list-unordered">
third party product (e.g. S3, Swift or Minio) configuration issue
</li><li class="list-unordered">
large amount of WAL queueing to be archived
</li></ul><div class="section-body-text">
It is advisable to:
</div><ul class="list-unordered"><li class="list-unordered">
check the archive_command in <span class="postgres">PostgreSQL</span>
</li><li class="list-unordered">
check the <span class="backrest">pgBackRest</span> configuration settings on each host (e.g. pg* settings are set on the repository host and repo* settings on the pg host)
</li><li class="list-unordered">
run the <span class="cmd">check</span> command with <span class="br-setting">--archive-timeout</span> set to a higher value than in the <span class="backrest">pgBackRest</span> configuration file (or default) to see if the WAL queue needs more time to clear. If the system is generating a lot of WAL, then consider configuring <a href="https://pgbackrest.org/user-guide.html#async-archiving">asynchronous archiving</a>
</li></ul></div></div><div class="section1"><a id="manual-expire"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
How do I manually purge a backup set?
</div></div><div class="section-body"><div class="section-body-text">
A full backup set can be expired using the <span class="br-setting">--set</span> option as explained in <a href="https://pgbackrest.org/command.html#command-expire">Command Reference: Expire</a>.
</div></div></div><div class="section1"><a id="optimize-config"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
How can I configure options independently for each command?
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> has the ability to set options independently in the configuration file for each command. <a href="https://pgbackrest.org/user-guide.html#quickstart/configure-stanza">Configure Cluster Stanza</a> details this feature as well as option precedence.
</div><div class="section-body-text">
For example, the <span class="br-option">process-max</span> option can be optimized for each command:
</div>
<pre class="code-block">[global]
# used where not overridden
process-max=2
[global:backup]
# more cores for backup
process-max=4
[global:restore]
# all the cores for restore
process-max=8
[global:archive-push]
# more cores for archive-push
process-max=3
[global:archive-get]
# fewer cores for archive-get
process-max=1</pre>
</div></div><div class="section1"><a id="s3-bucket"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Can I use dots (periods) in my S3 bucket name?
</div></div><div class="section-body"><div class="section-body-text">
<span class="host">RFC-2818</span> does not allow wildcards to match on a dot (.) so s3 bucket names must not contain dots. If there are dots in the S3 bucket name then an error such as <q>unable to find hostname 'my.backup.bucket.s3.amazonaws.com' in certificate common name or subject alternative names</q> will occur.
</div></div></div><div class="section1"><a id="old-package"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Where can I find packages for older versions of <span class="backrest">pgBackRest</span>?
</div></div><div class="section-body"><div class="section-body-text">
The <a href="https://apt.postgresql.org">apt.postgresql.org</a> repository maintains an <a href="https://apt-archive.postgresql.org">archive of older versions</a>. Debian also maintains <a href="https://snapshot.debian.org/binary/pgbackrest/">snapshots</a> of all test builds.
</div></div></div><div class="section1"><a id="backup-standby"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Why does a backup attempt fail when <span class="br-option">backup-standby=y</span> and the standby database is down?
</div></div><div class="section-body"><div class="section-body-text">
Configuring backup from standby is generally intended to reduce load on the primary, so switching backups to the primary when the standby is down often defeats the point. Putting more load on the primary in a situation where there are already failures in the system is not recommended. Backups are not critical as long as you have one that is fairly recent -- the important thing is to keep up with WAL archiving. There is plenty of time to get a backup when the system is stable again.
</div><div class="section-body-text">
If you really need a backup, the solution is to have more standbys or remove <span class="br-option">backup-standby</span>. This can be overridden on the command line with <span class="br-option">--no-backup-standby</span>, so there is no need to reconfigure for a one-off backup.
</div></div></div><div class="section1"><a id="standby-repo"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Should I setup my repository on a standby host?
</div></div><div class="section-body"><div class="section-body-text">
No. When primary and standby databases are configured, the <span class="backrest">pgBackRest</span> configuration files should be symmetric in order to seamlessly handle failovers. If they are not, the configurations will need to be changed on failover or further problems may result.
</div><div class="section-body-text">
See the <a href="user-guide.html#repo-host">Dedicated Repository Host</a> section of the <span class="host">User Guide</span> for more information.
</div></div></div><div class="section1"><a id="time-based-pitr"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Time-based Point-in-Time Recovery does not appear to work, why?
</div></div><div class="section-body"><div class="section-body-text">
The most common mistake when using time-based Point-in-Time Recovery is forgetting to choose a backup set that is before the target time. <span class="backrest">pgBackRest</span> will attempt to discover a backup to play forward from the time specified by the <span class="br-setting">--target=</span> if the <span class="br-setting">--set</span> option is not specified. If a backup set cannot be found, then restore will default to the latest backup. However, if the latest backup is after the target time, then <span class="br-setting">--target=</span> is not considered valid by <span class="postgres">PostgreSQL</span> and is therefore ignored, resulting in WAL recovery to the latest time available.
</div><div class="section-body-text">
To use the <span class="br-setting">--set</span> option, choose a backup set by running the <span class="cmd">info</span> command and finding the backup with a timestamp stop that is before the target time. Then when running the restore, specify the option <span class="br-setting">--set=BACKUP_LABEL</span> where <span class="id">BACKUP_LABEL</span> is the chosen backup set.
</div><div class="section-body-text">
See the <a href="user-guide.html#pitr">Point-in-Time Recovery</a> section of the <span class="host">User Guide</span> for more information.
</div></div></div><div class="section1"><a id="archive-suffix"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
What does the WAL archive suffix mean?
</div></div><div class="section-body"><div class="section-body-text">
The suffix is the SHA1 checksum used to verify file integrity. There is no way to omit it.
</div></div></div><div class="section1"><a id="restore-speed"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Does it take longer to restore specific backup types (full, differential, incremental)?
</div></div><div class="section-body"><div class="section-body-text">
The various backup types require the same amount of time to restore. Restore retrieves files based on the backup manifest, which may reference files from a previous backup in the case of incremental or differential backups. While there could be differences in time spent <i>making</i> a given backup (depending on backup type), database size determines restore time (disk I/O, network I/O, etc. being equal).
</div></div></div><div class="section1"><a id="self-contained-backup"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
How can I export a backup for use in a network-isolated environment?
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> uses the repository not only to store backups and WAL archives but also to maintain essential metadata required for features such as compression, encryption, and file bundling. Because of this, simply copying a backup along with a subset of WAL files usually will not work unless very specific and restrictive conditions are met.
</div><div class="section-body-text">
However, there is a workaround if your goal is to create a self-contained export of a database that you can transfer (e.g., via USB). You can make a backup with the <a href="https://pgbackrest.org/command.html#command-backup/category-command/option-archive-copy">--archive-copy</a> option enabled to ensure that the necessary WAL segments are stored along with the backup. Then, restore it using <a href="https://pgbackrest.org/command.html#command-restore/category-command/option-type">--type=none</a> --pg1-path=/your/target/path. This produces a restored PostgreSQL data directory with all required WAL files already placed in <span class="id">pg_wal</span>, similar to what <span class="file">pg_basebackup</span> would create.
</div><div class="section-body-text">
You can then copy this directory to another system, and <span class="postgres">PostgreSQL</span> should be able to recover from it without needing access to the <span class="backrest">pgBackRest</span> repository.
</div><div class="section-body-text">
Please note that recovering this backup will not result in a timeline switch, which means that this cluster should not push WAL to the original repository that it was exported from. If the new cluster is in a network-isolated environment this should not be a problem.
</div></div></div></div><div class="page-footer">
Copyright © 2015-2025, The PostgreSQL Global Development Group, <a href="https://github.com/pgbackrest/pgbackrest/blob/main/LICENSE">MIT License</a>. Updated April 21, 2025
</div></body></html>