Repository navigation
Expand file tree
/
Copy pathcommand.html
More file actions
3986 lines (3986 loc) · 345 KB
/
Copy pathcommand.html
File metadata and controls
3986 lines (3986 loc) · 345 KB
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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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 - Command Reference
</title><meta http-equiv="Content-Type" content="text/html;charset=utf-8"></meta>
<meta name="viewport" content="width=device-width, initial-scale=1"></meta>
<meta property="og:site_name" content="pgBackRest - Reliable PostgreSQL Backup & Restore"></meta>
<meta property="og:title" content="pgBackRest - Command Reference"></meta>
<meta property="og:type" content="website"></meta>
<link rel="icon" href="logo.svg" type="image/svg+xml"></link>
<meta property="og:image" content="https://pgbackrest.org/card.png"></meta>
<meta property="og:image:type" content="image/png"></meta>
<meta property="og:image:width" content="1200"></meta>
<meta property="og:image:height" content="630"></meta>
<meta property="og:image:alt" content="pgBackRest - Reliable PostgreSQL Backup & Restore"></meta>
<meta name="twitter:card" content="summary_large_image"></meta>
<meta name="description" content="The pgBackRest Command Reference details all commands and options."></meta>
<meta property="og:description" content="The pgBackRest Command Reference details all commands and options."></meta>
<link rel="stylesheet" href="default.css?v=27b4dc4a" type="text/css"></link>
<script src="default.js?v=c642056a" defer="defer"></script>
<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 class="page-sidebar"><div class="page-header"><a class="page-header-logo" href="/"><span class="page-header-logo-name">
pgBackRest
</span></a><div class="page-header-title">
pgBackRest
</div><div class="page-header-subtitle">
Command Reference
</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"><span class="menu-current">
Commands
</span></div><div class="menu"><a class="menu-link" href="news.html">
News
</a></div><div class="menu"><a class="menu-link" href="faq.html">
FAQ
</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-inner"><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-title"><a href="#introduction">
Introduction
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#section-general">
General Options
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-annotate">
Annotate Backup
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-archive-get">
Archive Get
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-archive-push">
Archive Push
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-backup">
Backup
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-check">
Check Configuration
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-expire">
Expire Backups
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-help">
Help
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-info">
Repository Info
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-repo-get">
Repository Get
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-repo-ls">
Repository List
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-restore">
Restore Backup
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-server">
TLS Server
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-server-ping">
TLS Server Ping
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-stanza-create">
Stanza Create
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-stanza-delete">
Stanza Delete
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-stanza-upgrade">
Stanza Upgrade
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-start">
Stanza Start
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-stop">
Stanza Stop
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-verify">
Repository Verify
</a></div></div><div class="section1-toc"><div class="section1-toc-title"><a href="#command-version">
Version
</a></div></div></div></div></div><div class="page-body"><div class="section1"><a id="introduction"></a><div class="section-body"><div class="section-body-text">
Commands are used to execute the various <span class="backrest">pgBackRest</span> functions. Every option applicable to a command is listed with that command, even if it applies to one or more other commands. An option that can only be set on the command-line is described in <a href="#section-general">General Options</a> below and an option that may also be configured in <span class="file">pgbackrest.conf</span> is described in the <a href="configuration.html">Configuration Reference</a>.
</div><div class="section-body-text">
Non-boolean options configured in <span class="file">pgbackrest.conf</span> can be reset to default on the command-line by using the <span class="id">reset-</span> prefix. This feature may be used to restore a backup directly on a repository host. Normally, <span class="backrest">pgBackRest</span> will error because it can see that the database host is remote and restores cannot be done remotely. By adding <span class="br-option">--reset-pg1-host</span> on the command-line, <span class="backrest">pgBackRest</span> will ignore the remote database host and restore locally. It may be necessary to pass a new <span class="br-option">--pg1-path</span> to force the restore to happen in a specific path, i.e. not the path used on the database host.
</div><div class="section-body-text">
The <span class="id">no-</span> prefix may be used to set a boolean option to false on the command-line.
</div><div class="section-body-text">
Any option may be set in an environment variable using the <span class="id">PGBACKREST_</span> prefix and the option name in all caps replacing <span class="id">-</span> with <span class="id">_</span>, e.g. <span class="br-option">pg1-path</span> becomes <span class="id">PGBACKREST_PG1_PATH</span> and <span class="br-option">stanza</span> becomes <span class="id">PGBACKREST_STANZA</span>. Boolean options are represented as they would be in a configuration file, e.g. <span class="id">PGBACKREST_COMPRESS="n"</span>, and <span class="id">reset-*</span> variants are not allowed. Options that can be specified multiple times on the command-line or in a config file can be represented by separating the values with colons, e.g. <span class="id">PGBACKREST_DB_INCLUDE="db1:db2"</span>.
</div><div class="section-body-text">
Command-line options override environment options which override config file options.
</div><div class="section-body-text">
See <a href="configuration.html#introduction">Configuration Introduction</a> for information on option types
</div></div></div><div class="section1"><a id="section-general"></a><div class="section1-header"><div class="section1-title">
General Options
</div></div><div class="section-body"><div class="section2"><a id="section-general/option-config"></a><div class="section2-header"><div class="section2-title">
Config (<span class="id">--config</span>)
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> configuration file.
</div><div class="section-body-text">
Use this option to specify a different configuration file than the default.
</div>
<pre class="code-block" tabindex="0">default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf</pre>
</div></div><div class="section2"><a id="section-general/option-config-include-path"></a><div class="section2-header"><div class="section2-title">
Config Include Path (<span class="id">--config-include-path</span>)
</div></div><div class="section-body"><div class="section-body-text">
Path to additional <span class="backrest">pgBackRest</span> configuration files.
</div><div class="section-body-text">
Configuration files existing in the specified location with extension <span class="file">.conf</span> will be concatenated with the <span class="backrest">pgBackRest</span> configuration file, resulting in one configuration file.
</div>
<pre class="code-block" tabindex="0">default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d</pre>
</div></div><div class="section2"><a id="section-general/option-config-path"></a><div class="section2-header"><div class="section2-title">
Config Path (<span class="id">--config-path</span>)
</div></div><div class="section-body"><div class="section-body-text">
Base path of <span class="backrest">pgBackRest</span> configuration files.
</div><div class="section-body-text">
This setting is used to override the default base path setting for the <span class="br-option">--config</span> and <span class="br-option">--config-include-path</span> options unless they are explicitly set on the command-line.
</div><div class="section-body-text">
For example, passing only <span class="id">--config-path=/conf/pgbackrest</span> results in the <span class="br-option">--config</span> default being set to <span class="id">/conf/pgbackrest/pgbackrest.conf</span> and the <span class="br-option">--config-include-path</span> default being set to <span class="id">/conf/pgbackrest/conf.d</span>.
</div>
<pre class="code-block" tabindex="0">default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest</pre>
</div></div><div class="section2"><a id="section-general/option-dry-run"></a><div class="section2-header"><div class="section2-title">
Dry Run (<span class="id">--dry-run</span>)
</div></div><div class="section-body"><div class="section-body-text">
Execute a dry-run for the command.
</div><div class="section-body-text">
The <span class="br-option">--dry-run</span> option is a command-line only option and can be passed when it is desirable to determine what modifications will be made by the command without the command actually making any modifications.
</div>
<pre class="code-block" tabindex="0">default: n
example: --dry-run</pre>
</div></div><div class="section2"><a id="section-general/option-raw"></a><div class="section2-header"><div class="section2-title">
Raw Data (<span class="id">--raw</span>)
</div></div><div class="section-body"><div class="section-body-text">
Do not transform data.
</div><div class="section-body-text">
Do not transform (i.e, encrypt, decompress, etc.) data for the current command.
</div>
<pre class="code-block" tabindex="0">default: n
example: --raw</pre>
</div></div><div class="section2"><a id="section-general/option-repo"></a><div class="section2-header"><div class="section2-title">
Set Repository (<span class="id">--repo</span>)
</div></div><div class="section-body"><div class="section-body-text">
Set repository.
</div><div class="section-body-text">
Set the repository for a command to operate on.
</div><div class="section-body-text">
For example, this option may be used to perform a restore from a specific repository, rather than letting <span class="backrest">pgBackRest</span> choose.
</div>
<pre class="code-block" tabindex="0">allowed: [1, 256]
example: --repo=1</pre>
</div></div><div class="section2"><a id="section-general/option-stanza"></a><div class="section2-header"><div class="section2-title">
Stanza (<span class="id">--stanza</span>)
</div></div><div class="section-body"><div class="section-body-text">
Defines the stanza.
</div><div class="section-body-text">
A stanza is the configuration for a <span class="postgres">PostgreSQL</span> database cluster that defines where it is located, how it will be backed up, archiving options, etc. Most db servers will only have one <span class="postgres">PostgreSQL</span> database cluster and therefore one stanza, whereas backup servers will have a stanza for every database cluster that needs to be backed up.
</div><div class="section-body-text">
It is tempting to name the stanza after the primary cluster but a better name describes the databases contained in the cluster. Because the stanza name will be used for the primary and all replicas it is more appropriate to choose a name that describes the actual function of the cluster, such as app or dw, rather than the local cluster name, such as main or prod.
</div>
<pre class="code-block" tabindex="0">example: --stanza=main</pre>
</div></div></div></div><div class="section1"><a id="command-annotate"></a><div class="section1-header"><div class="section1-title">
Annotate Backup (<span class="id">annotate</span>)
</div></div><div class="section-body"><div class="section-body-text">
Annotations included with the <span class="cmd">backup</span> command can be added, modified, or removed afterwards using the <span class="cmd">annotate</span> command.
</div><div class="section2"><a id="command-annotate/category-command"></a><div class="section2-header"><div class="section2-title">
Command Options
</div></div><div class="section-body"><div class="section3"><a id="command-annotate/category-command/option-annotation"></a><div class="section3-header"><div class="section3-title">
Backup Annotation (<span class="id">--annotation</span>)
</div></div><div class="section-body"><div class="section-body-text">
Annotate backup with user-defined key/value pairs.
</div><div class="section-body-text">
Users can attach informative key/value pairs to the backup. This option may be used multiple times to attach multiple annotations.
</div><div class="section-body-text">
Annotations are output by the <span class="cmd">info</span> command text output when a backup is specified with <span class="br-option">--set</span> and always appear in the JSON output.
</div>
<pre class="code-block" tabindex="0">example: --annotation=source="Sunday backup for website database"</pre>
</div></div><div class="section3"><a id="command-annotate/category-command/option-set"></a><div class="section3-header"><div class="section3-title">
Set (<span class="id">--set</span>)
</div></div><div class="section-body"><div class="section-body-text">
Backup set to annotate.
</div><div class="section-body-text">
The backup set to annotate.
</div>
<pre class="code-block" tabindex="0">example: --set=20150131-153358F_20150131-153401I</pre>
</div></div></div></div><div class="section2"><a id="command-annotate/category-general"></a><div class="section2-header"><div class="section2-title">
General Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-general/option-allow-root">Allow Run as Root (<span class="id">--allow-root</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-buffer-size">Buffer Size (<span class="id">--buffer-size</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-cmd-ssh">SSH Client Command (<span class="id">--cmd-ssh</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-compress-level-network">Network Compress Level (<span class="id">--compress-level-network</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config">Config (<span class="id">--config</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config-include-path">Config Include Path (<span class="id">--config-include-path</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config-path">Config Path (<span class="id">--config-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-io-timeout">I/O Timeout (<span class="id">--io-timeout</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-lock-path">Lock Path (<span class="id">--lock-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-neutral-umask">Neutral Umask (<span class="id">--neutral-umask</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-priority">Set Process Priority (<span class="id">--priority</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-protocol-timeout">Protocol Timeout (<span class="id">--protocol-timeout</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-sck-keep-alive">Socket Keep Alive (<span class="id">--sck-keep-alive</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-stanza">Stanza (<span class="id">--stanza</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-count">TCP Keep Alive Count (<span class="id">--tcp-keep-alive-count</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-idle">TCP Keep Alive Idle (<span class="id">--tcp-keep-alive-idle</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-interval">TCP Keep Alive Interval (<span class="id">--tcp-keep-alive-interval</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tls-cipher-12">TLSv1.2 Cipher Suites (<span class="id">--tls-cipher-12</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tls-cipher-13">TLSv1.3 Cipher Suites (<span class="id">--tls-cipher-13</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-annotate/category-log"></a><div class="section2-header"><div class="section2-title">
Log Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-console">Console Log Level (<span class="id">--log-level-console</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-file">File Log Level (<span class="id">--log-level-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-stderr">Std Error Log Level (<span class="id">--log-level-stderr</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-path">Log Path (<span class="id">--log-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-subprocess">Log Subprocesses (<span class="id">--log-subprocess</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-timestamp">Log Timestamp (<span class="id">--log-timestamp</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-annotate/category-repository"></a><div class="section2-header"><div class="section2-title">
Repository Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="#section-general/option-repo">Set Repository (<span class="id">--repo</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-container">Azure Repository Container (<span class="id">--repo-azure-container</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-key-type">Azure Repository Key Type (<span class="id">--repo-azure-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-uri-style">Azure Repository URI Style (<span class="id">--repo-azure-uri-style</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-cipher-type">Repository Cipher Type (<span class="id">--repo-cipher-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-bucket">GCS Repository Bucket (<span class="id">--repo-gcs-bucket</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-endpoint">GCS Repository Endpoint (<span class="id">--repo-gcs-endpoint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-key-type">GCS Repository Key Type (<span class="id">--repo-gcs-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-user-project">GCS Repository Project ID (<span class="id">--repo-gcs-user-project</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host">Repository Host (<span class="id">--repo-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-ca-file">Repository Host Certificate Authority File (<span class="id">--repo-host-ca-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-ca-path">Repository Host Certificate Authority Path (<span class="id">--repo-host-ca-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-cert-file">Repository Host Certificate File (<span class="id">--repo-host-cert-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-cmd">Repository Host Command (<span class="id">--repo-host-cmd</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config">Repository Host Configuration (<span class="id">--repo-host-config</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config-include-path">Repository Host Configuration Include Path (<span class="id">--repo-host-config-include-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config-path">Repository Host Configuration Path (<span class="id">--repo-host-config-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-key-file">Repository Host Key File (<span class="id">--repo-host-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-port">Repository Host Port (<span class="id">--repo-host-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-type">Repository Host Protocol Type (<span class="id">--repo-host-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-user">Repository Host User (<span class="id">--repo-host-user</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-path">Repository Path (<span class="id">--repo-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-bucket">S3 Repository Bucket (<span class="id">--repo-s3-bucket</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-endpoint">S3 Repository Endpoint (<span class="id">--repo-s3-endpoint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-key-type">S3 Repository Key Type (<span class="id">--repo-s3-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-kms-key-id">S3 Repository KMS Key ID (<span class="id">--repo-s3-kms-key-id</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-process-cmd">S3 Authentication Process Command (<span class="id">--repo-s3-process-cmd</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-region">S3 Repository Region (<span class="id">--repo-s3-region</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-requester-pays">S3 Repository Requestor Pays (<span class="id">--repo-s3-requester-pays</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-role">S3 Repository Role (<span class="id">--repo-s3-role</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-service">S3 Repository Service (<span class="id">--repo-s3-service</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-sts-host">S3 Repository STS Endpoint (<span class="id">--repo-s3-sts-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-uri-style">S3 Repository URI Style (<span class="id">--repo-s3-uri-style</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host">SFTP Repository Host (<span class="id">--repo-sftp-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-fingerprint">SFTP Repository Host Fingerprint (<span class="id">--repo-sftp-host-fingerprint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-key-check-type">SFTP Host Key Check Type (<span class="id">--repo-sftp-host-key-check-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-key-hash-type">SFTP Repository Host Key Hash Type (<span class="id">--repo-sftp-host-key-hash-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-port">SFTP Repository Host Port (<span class="id">--repo-sftp-host-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-user">SFTP Repository Host User (<span class="id">--repo-sftp-host-user</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-known-host">SFTP Known Hosts File (<span class="id">--repo-sftp-known-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-private-key-file">SFTP Repository Private Key File (<span class="id">--repo-sftp-private-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-public-key-file">SFTP Repository Public Key File (<span class="id">--repo-sftp-public-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-ca-file">Repository Storage CA File (<span class="id">--repo-storage-ca-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-ca-path">Repository Storage TLS CA Path (<span class="id">--repo-storage-ca-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-host">Repository Storage Host (<span class="id">--repo-storage-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-port">Repository Storage Port (<span class="id">--repo-storage-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-prefetch">Repository Storage Prefetch (<span class="id">--repo-storage-prefetch</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-read-over">Repository Storage Read Over (<span class="id">--repo-storage-read-over</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-tag">Repository Storage Tag (<span class="id">--repo-storage-tag</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-upload-chunk-size">Repository Storage Upload Chunk Size (<span class="id">--repo-storage-upload-chunk-size</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-verify-tls">Repository Storage Certificate Verify (<span class="id">--repo-storage-verify-tls</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-type">Repository Type (<span class="id">--repo-type</span>)</a>
</li></ul></div></div></div></div><div class="section1"><a id="command-archive-get"></a><div class="section1-header"><div class="section1-title">
Archive Get (<span class="id">archive-get</span>)
</div></div><div class="section-body"><div class="section-body-text">
This command is used by <span class="postgres">PostgreSQL</span> to restore a backup, perform PITR, or as an alternative to streaming for keeping a replica up to date. WAL segments are required for <span class="postgres">PostgreSQL</span> recovery or to maintain a replica.
</div><div class="section-body-text">
When multiple repositories are configured, WAL will be fetched from the repositories in priority order (e.g. <span class="id">repo1</span>, <span class="id">repo2</span>, etc.). In general it is better if faster/cheaper storage has higher priority. If a repository is specified with the <span class="br-option">--repo</span> option then only that repository will be searched.
</div><div class="section-body-text">
The <span class="cmd">archive-get</span> command is configured and generated by <span class="backrest">pgBackRest</span> during a restore for use by <span class="postgres">PostgreSQL</span>. See <a href="user-guide.html#pitr">Point-in-Time Recovery</a> for an example.
</div><div class="section2"><a id="command-archive-get/category-command"></a><div class="section2-header"><div class="section2-title">
Command Options
</div></div><div class="section-body"><div class="section3"><a id="command-archive-get/category-command/option-archive-async"></a><div class="section3-header"><div class="section3-title">
Asynchronous Archiving (<span class="id">--archive-async</span>)
</div></div><div class="section-body"><div class="section-body-text">
Push/get WAL segments asynchronously.
</div><div class="section-body-text">
Enables asynchronous operation for the <span class="cmd">archive-push</span> and <span class="cmd">archive-get</span> commands.
</div><div class="section-body-text">
Asynchronous operation is more efficient because it can reuse connections and take advantage of parallelism. See the <span class="br-option">spool-path</span>, <span class="br-option">archive-get-queue-max</span>, and <span class="br-option">archive-push-queue-max</span> options for more information.
</div>
<pre class="code-block" tabindex="0">default: n
example: --archive-async</pre>
</div></div><div class="section3"><a id="command-archive-get/category-command/option-archive-get-queue-max"></a><div class="section3-header"><div class="section3-title">
Maximum Archive Get Queue Size (<span class="id">--archive-get-queue-max</span>)
</div></div><div class="section-body"><div class="section-body-text">
Maximum size of the <span class="backrest">pgBackRest</span> archive-get queue.
</div><div class="section-body-text">
Specifies the maximum size of the <span class="cmd">archive-get</span> queue when <span class="br-option">archive-async</span> is enabled. The queue is stored in the <span class="br-option">spool-path</span> and is used to speed providing WAL to <span class="postgres">PostgreSQL</span>.
</div>
<pre class="code-block" tabindex="0">default: 128MiB
allowed: [0B, 4PiB]
example: --archive-get-queue-max=1GiB</pre>
</div></div><div class="section3"><a id="command-archive-get/category-command/option-archive-missing-retry"></a><div class="section3-header"><div class="section3-title">
Retry Missing WAL Segment (<span class="id">--archive-missing-retry</span>)
</div></div><div class="section-body"><div class="section-body-text">
Retry missing WAL segment
</div><div class="section-body-text">
Retry a WAL segment that was previously reported as missing by the <span class="cmd">archive-get</span> command when in asynchronous mode. This prevents notifications in the spool path from a prior restore from being used and possibly causing a recovery failure if consistency has not been reached.
</div><div class="section-body-text">
Disabling this option allows <span class="postgres">PostgreSQL</span> to more reliably recognize when the end of the WAL in the archive has been reached, which permits it to switch over to streaming from the primary. With retries enabled, a steady stream of WAL being archived will cause <span class="postgres">PostgreSQL</span> to continue getting WAL from the archive rather than switch to streaming.
</div><div class="section-body-text">
When disabling this option it is important to ensure that the spool path for the stanza is empty. The <span class="cmd">restore</span> command does this automatically if the spool path is configured at restore time. Otherwise, it is up to the user to ensure the spool path is empty.
</div>
<pre class="code-block" tabindex="0">default: y
example: --no-archive-missing-retry</pre>
</div></div><div class="section3"><a id="command-archive-get/category-command/option-archive-timeout"></a><div class="section3-header"><div class="section3-title">
Archive Timeout (<span class="id">--archive-timeout</span>)
</div></div><div class="section-body"><div class="section-body-text">
Archive timeout.
</div><div class="section-body-text">
Set maximum time, in seconds, to wait for each WAL segment to reach the <span class="backrest">pgBackRest</span> archive repository. The timeout applies to the <span class="cmd">check</span> and <span class="cmd">backup</span> commands when waiting for WAL segments required for backup consistency to be archived.
</div>
<pre class="code-block" tabindex="0">default: 1m
allowed: [100ms, 1d]
example: --archive-timeout=30</pre>
</div></div></div></div><div class="section2"><a id="command-archive-get/category-general"></a><div class="section2-header"><div class="section2-title">
General Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-general/option-allow-root">Allow Run as Root (<span class="id">--allow-root</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-buffer-size">Buffer Size (<span class="id">--buffer-size</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-cmd">pgBackRest Command (<span class="id">--cmd</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-cmd-ssh">SSH Client Command (<span class="id">--cmd-ssh</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-compress-level-network">Network Compress Level (<span class="id">--compress-level-network</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config">Config (<span class="id">--config</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config-include-path">Config Include Path (<span class="id">--config-include-path</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config-path">Config Path (<span class="id">--config-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-io-timeout">I/O Timeout (<span class="id">--io-timeout</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-lock-path">Lock Path (<span class="id">--lock-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-neutral-umask">Neutral Umask (<span class="id">--neutral-umask</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-priority">Set Process Priority (<span class="id">--priority</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-process-max">Process Maximum (<span class="id">--process-max</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-protocol-timeout">Protocol Timeout (<span class="id">--protocol-timeout</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-sck-keep-alive">Socket Keep Alive (<span class="id">--sck-keep-alive</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-spool-path">Spool Path (<span class="id">--spool-path</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-stanza">Stanza (<span class="id">--stanza</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-count">TCP Keep Alive Count (<span class="id">--tcp-keep-alive-count</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-idle">TCP Keep Alive Idle (<span class="id">--tcp-keep-alive-idle</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-interval">TCP Keep Alive Interval (<span class="id">--tcp-keep-alive-interval</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tls-cipher-12">TLSv1.2 Cipher Suites (<span class="id">--tls-cipher-12</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tls-cipher-13">TLSv1.3 Cipher Suites (<span class="id">--tls-cipher-13</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-archive-get/category-log"></a><div class="section2-header"><div class="section2-title">
Log Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-console">Console Log Level (<span class="id">--log-level-console</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-file">File Log Level (<span class="id">--log-level-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-stderr">Std Error Log Level (<span class="id">--log-level-stderr</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-path">Log Path (<span class="id">--log-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-subprocess">Log Subprocesses (<span class="id">--log-subprocess</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-timestamp">Log Timestamp (<span class="id">--log-timestamp</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-archive-get/category-maintainer"></a><div class="section2-header"><div class="section2-title">
Maintainer Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-maintainer/option-pg-version-force">Force PostgreSQL Version (<span class="id">--pg-version-force</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-archive-get/category-repository"></a><div class="section2-header"><div class="section2-title">
Repository Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="#section-general/option-repo">Set Repository (<span class="id">--repo</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-container">Azure Repository Container (<span class="id">--repo-azure-container</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-key-type">Azure Repository Key Type (<span class="id">--repo-azure-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-uri-style">Azure Repository URI Style (<span class="id">--repo-azure-uri-style</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-cipher-type">Repository Cipher Type (<span class="id">--repo-cipher-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-bucket">GCS Repository Bucket (<span class="id">--repo-gcs-bucket</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-endpoint">GCS Repository Endpoint (<span class="id">--repo-gcs-endpoint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-key-type">GCS Repository Key Type (<span class="id">--repo-gcs-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-user-project">GCS Repository Project ID (<span class="id">--repo-gcs-user-project</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host">Repository Host (<span class="id">--repo-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-ca-file">Repository Host Certificate Authority File (<span class="id">--repo-host-ca-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-ca-path">Repository Host Certificate Authority Path (<span class="id">--repo-host-ca-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-cert-file">Repository Host Certificate File (<span class="id">--repo-host-cert-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-cmd">Repository Host Command (<span class="id">--repo-host-cmd</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config">Repository Host Configuration (<span class="id">--repo-host-config</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config-include-path">Repository Host Configuration Include Path (<span class="id">--repo-host-config-include-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config-path">Repository Host Configuration Path (<span class="id">--repo-host-config-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-key-file">Repository Host Key File (<span class="id">--repo-host-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-port">Repository Host Port (<span class="id">--repo-host-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-type">Repository Host Protocol Type (<span class="id">--repo-host-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-user">Repository Host User (<span class="id">--repo-host-user</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-path">Repository Path (<span class="id">--repo-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-bucket">S3 Repository Bucket (<span class="id">--repo-s3-bucket</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-endpoint">S3 Repository Endpoint (<span class="id">--repo-s3-endpoint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-key-type">S3 Repository Key Type (<span class="id">--repo-s3-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-kms-key-id">S3 Repository KMS Key ID (<span class="id">--repo-s3-kms-key-id</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-process-cmd">S3 Authentication Process Command (<span class="id">--repo-s3-process-cmd</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-region">S3 Repository Region (<span class="id">--repo-s3-region</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-requester-pays">S3 Repository Requestor Pays (<span class="id">--repo-s3-requester-pays</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-role">S3 Repository Role (<span class="id">--repo-s3-role</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-service">S3 Repository Service (<span class="id">--repo-s3-service</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-sts-host">S3 Repository STS Endpoint (<span class="id">--repo-s3-sts-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-uri-style">S3 Repository URI Style (<span class="id">--repo-s3-uri-style</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host">SFTP Repository Host (<span class="id">--repo-sftp-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-fingerprint">SFTP Repository Host Fingerprint (<span class="id">--repo-sftp-host-fingerprint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-key-check-type">SFTP Host Key Check Type (<span class="id">--repo-sftp-host-key-check-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-key-hash-type">SFTP Repository Host Key Hash Type (<span class="id">--repo-sftp-host-key-hash-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-port">SFTP Repository Host Port (<span class="id">--repo-sftp-host-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-user">SFTP Repository Host User (<span class="id">--repo-sftp-host-user</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-known-host">SFTP Known Hosts File (<span class="id">--repo-sftp-known-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-private-key-file">SFTP Repository Private Key File (<span class="id">--repo-sftp-private-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-public-key-file">SFTP Repository Public Key File (<span class="id">--repo-sftp-public-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-ca-file">Repository Storage CA File (<span class="id">--repo-storage-ca-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-ca-path">Repository Storage TLS CA Path (<span class="id">--repo-storage-ca-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-host">Repository Storage Host (<span class="id">--repo-storage-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-port">Repository Storage Port (<span class="id">--repo-storage-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-prefetch">Repository Storage Prefetch (<span class="id">--repo-storage-prefetch</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-read-over">Repository Storage Read Over (<span class="id">--repo-storage-read-over</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-tag">Repository Storage Tag (<span class="id">--repo-storage-tag</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-upload-chunk-size">Repository Storage Upload Chunk Size (<span class="id">--repo-storage-upload-chunk-size</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-verify-tls">Repository Storage Certificate Verify (<span class="id">--repo-storage-verify-tls</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-target-time">Target Time for Repository (<span class="id">--repo-target-time</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-type">Repository Type (<span class="id">--repo-type</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-archive-get/category-stanza"></a><div class="section2-header"><div class="section2-title">
Stanza Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-stanza/option-pg-path">PostgreSQL Path (<span class="id">--pg-path</span>)</a>
</li></ul></div></div></div></div><div class="section1"><a id="command-archive-push"></a><div class="section1-header"><div class="section1-title">
Archive Push (<span class="id">archive-push</span>)
</div></div><div class="section-body"><div class="section-body-text">
Accepts a WAL segment from <span class="postgres">PostgreSQL</span> and archives it in each repository defined by the indexed <span class="br-setting">repo-path</span> option (see the <a href="configuration.html#section-repository">Repository</a> section for information on configuring repositories). The WAL segment may be pushed immediately to the archive or stored locally depending on the value of <span class="br-setting">archive-async</span>. With multiple repositories configured, <span class="cmd">archive-push</span> will attempt to push to as many repositories as possible.
</div><div class="section-body-text">
The <span class="cmd">archive-push</span> is intended to be configured and called by <span class="postgres">PostgreSQL</span>. See <a href="user-guide.html#quickstart/configure-archiving">Configure Archiving</a> for an example.
</div><div class="section2"><a id="command-archive-push/category-command"></a><div class="section2-header"><div class="section2-title">
Command Options
</div></div><div class="section-body"><div class="section3"><a id="command-archive-push/category-command/option-archive-async"></a><div class="section3-header"><div class="section3-title">
Asynchronous Archiving (<span class="id">--archive-async</span>)
</div></div><div class="section-body"><div class="section-body-text">
Push/get WAL segments asynchronously.
</div><div class="section-body-text">
Enables asynchronous operation for the <span class="cmd">archive-push</span> and <span class="cmd">archive-get</span> commands.
</div><div class="section-body-text">
Asynchronous operation is more efficient because it can reuse connections and take advantage of parallelism. See the <span class="br-option">spool-path</span>, <span class="br-option">archive-get-queue-max</span>, and <span class="br-option">archive-push-queue-max</span> options for more information.
</div>
<pre class="code-block" tabindex="0">default: n
example: --archive-async</pre>
</div></div><div class="section3"><a id="command-archive-push/category-command/option-archive-check"></a><div class="section3-header"><div class="section3-title">
Check Archive (<span class="id">--archive-check</span>)
</div></div><div class="section-body"><div class="section-body-text">
Check that WAL segments are in the archive before backup completes.
</div><div class="section-body-text">
Checks that all WAL segments required to make the backup consistent are present in the WAL archive. It's a good idea to leave this as the default unless you are using another method for archiving.
</div><div class="section-body-text">
This option must be enabled if <span class="br-option">archive-copy</span> is enabled.
</div>
<pre class="code-block" tabindex="0">default: y
example: --no-archive-check</pre>
</div></div><div class="section3"><a id="command-archive-push/category-command/option-archive-mode-check"></a><div class="section3-header"><div class="section3-title">
Check Archive Mode (<span class="id">--archive-mode-check</span>)
</div></div><div class="section-body"><div class="section-body-text">
Check the <span class="postgres">PostgreSQL</span> <span class="br-setting">archive_mode</span> setting.
</div><div class="section-body-text">
Enabled by default, this option disallows <span class="postgres">PostgreSQL</span> <span class="br-setting">archive_mode=always</span>.
</div><div class="section-body-text">
WAL segments pushed from a standby server might be logically the same as WAL segments pushed from the primary but have different checksums. Disabling archiving from multiple sources is recommended to avoid conflicts.
</div><div class="admonition"><div class="caution">
CAUTION:
</div><div class="caution-text">
If this option is disabled then it is critical to ensure that only one archiver is writing to the repository via the <span class="cmd">archive-push</span> command.
</div></div>
<pre class="code-block" tabindex="0">default: y
example: --no-archive-mode-check</pre>
</div></div><div class="section3"><a id="command-archive-push/category-command/option-archive-push-batch-size"></a><div class="section3-header"><div class="section3-title">
Archive Push Batch Size (<span class="id">--archive-push-batch-size</span>)
</div></div><div class="section-body"><div class="section-body-text">
Maximum amount of WAL to push per asynchronous run.
</div><div class="section-body-text">
In asynchronous mode the <span class="cmd">archive-push</span> process pushes all the WAL segments that are ready in a single run. Since <span class="br-option">archive-push-queue-max</span> is only checked at the start of each run, a run that processes a very large number of segments can let the queue grow well beyond the limit before it is rechecked.
</div><div class="section-body-text">
This option limits the amount of WAL processed per run so the process exits and is spawned again by the next <span class="cmd">archive-push</span>, which rechecks the queue. Lower values recheck the queue more often at the cost of spawning the asynchronous process more frequently. The value is rounded down to a whole number of WAL segments but at least one segment is always processed.
</div>
<pre class="code-block" tabindex="0">default: 16GiB
allowed: [1MiB, 4PiB]
example: --archive-push-batch-size=1GiB</pre>
</div></div><div class="section3"><a id="command-archive-push/category-command/option-archive-push-queue-max"></a><div class="section3-header"><div class="section3-title">
Maximum Archive Push Queue Size (<span class="id">--archive-push-queue-max</span>)
</div></div><div class="section-body"><div class="section-body-text">
Maximum size of the <span class="postgres">PostgreSQL</span> archive queue.
</div><div class="section-body-text">
After the limit is reached, the following will happen:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="backrest">pgBackRest</span> will notify <span class="postgres">PostgreSQL</span> that the WAL was successfully archived, then <b>DROP IT</b>.
</li><li class="list-unordered">
A warning will be output to the <span class="postgres">PostgreSQL</span> log.
</li></ul><div class="section-body-text">
If this occurs then the archive log stream will be interrupted and PITR will not be possible past that point. A new backup will be required to regain full restore capability.
</div><div class="section-body-text">
In asynchronous mode the entire queue will be dropped to prevent spurts of WAL getting through before the queue limit is exceeded again.
</div><div class="section-body-text">
In asynchronous mode this limit is only checked at the start of each <span class="cmd">archive-push</span> run, so the queue can grow beyond it within a single run. Reduce <span class="br-option">archive-push-batch-size</span> to check the queue more frequently.
</div><div class="section-body-text">
The purpose of this feature is to prevent the log volume from filling up at which point <span class="postgres">PostgreSQL</span> will stop completely. Better to lose the backup than have <span class="postgres">PostgreSQL</span> go down.
</div>
<pre class="code-block" tabindex="0">allowed: [0B, 4PiB]
example: --archive-push-queue-max=1TiB</pre>
<div class="section-body-text">
Deprecated Name: archive-queue-max
</div></div></div><div class="section3"><a id="command-archive-push/category-command/option-archive-timeout"></a><div class="section3-header"><div class="section3-title">
Archive Timeout (<span class="id">--archive-timeout</span>)
</div></div><div class="section-body"><div class="section-body-text">
Archive timeout.
</div><div class="section-body-text">
Set maximum time, in seconds, to wait for each WAL segment to reach the <span class="backrest">pgBackRest</span> archive repository. The timeout applies to the <span class="cmd">check</span> and <span class="cmd">backup</span> commands when waiting for WAL segments required for backup consistency to be archived.
</div>
<pre class="code-block" tabindex="0">default: 1m
allowed: [100ms, 1d]
example: --archive-timeout=30</pre>
</div></div></div></div><div class="section2"><a id="command-archive-push/category-general"></a><div class="section2-header"><div class="section2-title">
General Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-general/option-allow-root">Allow Run as Root (<span class="id">--allow-root</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-buffer-size">Buffer Size (<span class="id">--buffer-size</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-cmd">pgBackRest Command (<span class="id">--cmd</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-cmd-ssh">SSH Client Command (<span class="id">--cmd-ssh</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-compress">Compress (<span class="id">--compress</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-compress-level">Compress Level (<span class="id">--compress-level</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-compress-level-network">Network Compress Level (<span class="id">--compress-level-network</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-compress-type">Compress Type (<span class="id">--compress-type</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config">Config (<span class="id">--config</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config-include-path">Config Include Path (<span class="id">--config-include-path</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-config-path">Config Path (<span class="id">--config-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-io-timeout">I/O Timeout (<span class="id">--io-timeout</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-lock-path">Lock Path (<span class="id">--lock-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-neutral-umask">Neutral Umask (<span class="id">--neutral-umask</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-priority">Set Process Priority (<span class="id">--priority</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-process-max">Process Maximum (<span class="id">--process-max</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-protocol-timeout">Protocol Timeout (<span class="id">--protocol-timeout</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-sck-keep-alive">Socket Keep Alive (<span class="id">--sck-keep-alive</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-spool-path">Spool Path (<span class="id">--spool-path</span>)</a>
</li><li class="list-unordered">
<a href="#section-general/option-stanza">Stanza (<span class="id">--stanza</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-count">TCP Keep Alive Count (<span class="id">--tcp-keep-alive-count</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-idle">TCP Keep Alive Idle (<span class="id">--tcp-keep-alive-idle</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tcp-keep-alive-interval">TCP Keep Alive Interval (<span class="id">--tcp-keep-alive-interval</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tls-cipher-12">TLSv1.2 Cipher Suites (<span class="id">--tls-cipher-12</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-general/option-tls-cipher-13">TLSv1.3 Cipher Suites (<span class="id">--tls-cipher-13</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-archive-push/category-log"></a><div class="section2-header"><div class="section2-title">
Log Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-console">Console Log Level (<span class="id">--log-level-console</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-file">File Log Level (<span class="id">--log-level-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-level-stderr">Std Error Log Level (<span class="id">--log-level-stderr</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-path">Log Path (<span class="id">--log-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-subprocess">Log Subprocesses (<span class="id">--log-subprocess</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-log/option-log-timestamp">Log Timestamp (<span class="id">--log-timestamp</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-archive-push/category-maintainer"></a><div class="section2-header"><div class="section2-title">
Maintainer Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-maintainer/option-archive-header-check">WAL Header Check (<span class="id">--archive-header-check</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-maintainer/option-pg-version-force">Force PostgreSQL Version (<span class="id">--pg-version-force</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-archive-push/category-repository"></a><div class="section2-header"><div class="section2-title">
Repository Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-container">Azure Repository Container (<span class="id">--repo-azure-container</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-key-type">Azure Repository Key Type (<span class="id">--repo-azure-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-azure-uri-style">Azure Repository URI Style (<span class="id">--repo-azure-uri-style</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-cipher-type">Repository Cipher Type (<span class="id">--repo-cipher-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-bucket">GCS Repository Bucket (<span class="id">--repo-gcs-bucket</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-endpoint">GCS Repository Endpoint (<span class="id">--repo-gcs-endpoint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-key-type">GCS Repository Key Type (<span class="id">--repo-gcs-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-gcs-user-project">GCS Repository Project ID (<span class="id">--repo-gcs-user-project</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host">Repository Host (<span class="id">--repo-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-ca-file">Repository Host Certificate Authority File (<span class="id">--repo-host-ca-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-ca-path">Repository Host Certificate Authority Path (<span class="id">--repo-host-ca-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-cert-file">Repository Host Certificate File (<span class="id">--repo-host-cert-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-cmd">Repository Host Command (<span class="id">--repo-host-cmd</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config">Repository Host Configuration (<span class="id">--repo-host-config</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config-include-path">Repository Host Configuration Include Path (<span class="id">--repo-host-config-include-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-config-path">Repository Host Configuration Path (<span class="id">--repo-host-config-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-key-file">Repository Host Key File (<span class="id">--repo-host-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-port">Repository Host Port (<span class="id">--repo-host-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-type">Repository Host Protocol Type (<span class="id">--repo-host-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-host-user">Repository Host User (<span class="id">--repo-host-user</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-path">Repository Path (<span class="id">--repo-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-bucket">S3 Repository Bucket (<span class="id">--repo-s3-bucket</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-endpoint">S3 Repository Endpoint (<span class="id">--repo-s3-endpoint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-key-type">S3 Repository Key Type (<span class="id">--repo-s3-key-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-kms-key-id">S3 Repository KMS Key ID (<span class="id">--repo-s3-kms-key-id</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-process-cmd">S3 Authentication Process Command (<span class="id">--repo-s3-process-cmd</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-region">S3 Repository Region (<span class="id">--repo-s3-region</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-requester-pays">S3 Repository Requestor Pays (<span class="id">--repo-s3-requester-pays</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-role">S3 Repository Role (<span class="id">--repo-s3-role</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-service">S3 Repository Service (<span class="id">--repo-s3-service</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-sts-host">S3 Repository STS Endpoint (<span class="id">--repo-s3-sts-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-s3-uri-style">S3 Repository URI Style (<span class="id">--repo-s3-uri-style</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host">SFTP Repository Host (<span class="id">--repo-sftp-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-fingerprint">SFTP Repository Host Fingerprint (<span class="id">--repo-sftp-host-fingerprint</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-key-check-type">SFTP Host Key Check Type (<span class="id">--repo-sftp-host-key-check-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-key-hash-type">SFTP Repository Host Key Hash Type (<span class="id">--repo-sftp-host-key-hash-type</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-port">SFTP Repository Host Port (<span class="id">--repo-sftp-host-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-host-user">SFTP Repository Host User (<span class="id">--repo-sftp-host-user</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-known-host">SFTP Known Hosts File (<span class="id">--repo-sftp-known-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-private-key-file">SFTP Repository Private Key File (<span class="id">--repo-sftp-private-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-sftp-public-key-file">SFTP Repository Public Key File (<span class="id">--repo-sftp-public-key-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-ca-file">Repository Storage CA File (<span class="id">--repo-storage-ca-file</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-ca-path">Repository Storage TLS CA Path (<span class="id">--repo-storage-ca-path</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-host">Repository Storage Host (<span class="id">--repo-storage-host</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-port">Repository Storage Port (<span class="id">--repo-storage-port</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-prefetch">Repository Storage Prefetch (<span class="id">--repo-storage-prefetch</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-read-over">Repository Storage Read Over (<span class="id">--repo-storage-read-over</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-tag">Repository Storage Tag (<span class="id">--repo-storage-tag</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-upload-chunk-size">Repository Storage Upload Chunk Size (<span class="id">--repo-storage-upload-chunk-size</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-storage-verify-tls">Repository Storage Certificate Verify (<span class="id">--repo-storage-verify-tls</span>)</a>
</li><li class="list-unordered">
<a href="configuration.html#section-repository/option-repo-type">Repository Type (<span class="id">--repo-type</span>)</a>
</li></ul></div></div><div class="section2"><a id="command-archive-push/category-stanza"></a><div class="section2-header"><div class="section2-title">
Stanza Options
</div></div><div class="section-body"><ul class="list-unordered"><li class="list-unordered">
<a href="configuration.html#section-stanza/option-pg-path">PostgreSQL Path (<span class="id">--pg-path</span>)</a>
</li></ul></div></div></div></div><div class="section1"><a id="command-backup"></a><div class="section1-header"><div class="section1-title">
Backup (<span class="id">backup</span>)
</div></div><div class="section-body"><div class="section-body-text">
When multiple repositories are configured, <span class="backrest">pgBackRest</span> will backup to the highest priority repository (e.g. <span class="id">repo1</span>) unless the <span class="br-option">--repo</span> option is specified.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> does not have a built-in scheduler so it's best to run it from cron or some other scheduling mechanism.
</div><div class="section-body-text">
See <a href="user-guide.html#quickstart/perform-backup">Perform a Backup</a> for more details and examples.
</div><div class="section2"><a id="command-backup/category-command"></a><div class="section2-header"><div class="section2-title">
Command Options
</div></div><div class="section-body"><div class="section3"><a id="command-backup/category-command/option-annotation"></a><div class="section3-header"><div class="section3-title">
Backup Annotation (<span class="id">--annotation</span>)
</div></div><div class="section-body"><div class="section-body-text">
Annotate backup with user-defined key/value pairs.
</div><div class="section-body-text">
Users can attach informative key/value pairs to the backup. This option may be used multiple times to attach multiple annotations.
</div><div class="section-body-text">
Annotations are output by the <span class="cmd">info</span> command text output when a backup is specified with <span class="br-option">--set</span> and always appear in the JSON output.
</div>
<pre class="code-block" tabindex="0">example: --annotation=source="Sunday backup for website database"</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-archive-check"></a><div class="section3-header"><div class="section3-title">
Check Archive (<span class="id">--archive-check</span>)
</div></div><div class="section-body"><div class="section-body-text">
Check that WAL segments are in the archive before backup completes.
</div><div class="section-body-text">
Checks that all WAL segments required to make the backup consistent are present in the WAL archive. It's a good idea to leave this as the default unless you are using another method for archiving.
</div><div class="section-body-text">
This option must be enabled if <span class="br-option">archive-copy</span> is enabled.
</div>
<pre class="code-block" tabindex="0">default: y
example: --no-archive-check</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-archive-copy"></a><div class="section3-header"><div class="section3-title">
Copy Archive (<span class="id">--archive-copy</span>)
</div></div><div class="section-body"><div class="section-body-text">
Copy WAL segments needed for consistency to the backup.
</div><div class="section-body-text">
This slightly paranoid option protects against corruption in the WAL segment archive by storing the WAL segments required for consistency directly in the backup. WAL segments are still stored in the archive so this option will use additional space.
</div><div class="section-body-text">
It is best if the <span class="cmd">archive-push</span> and <span class="cmd">backup</span> commands have the same <span class="br-setting">compress-type</span> (e.g. <span class="id">lz4</span>) when using this option. Otherwise, the WAL segments will need to be recompressed with the <span class="br-setting">compress-type</span> used by the backup, which can be fairly expensive depending on how much WAL was generated during the backup.
</div><div class="section-body-text">
On restore, the WAL segments will be present in <span class="path">pg_xlog/pg_wal</span> and <span class="postgres">PostgreSQL</span> will use them in preference to calling the <span class="id">restore_command</span>.
</div><div class="section-body-text">
The <span class="br-option">archive-check</span> option must be enabled if <span class="br-option">archive-copy</span> is enabled.
</div>
<pre class="code-block" tabindex="0">default: n
example: --archive-copy</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-archive-mode-check"></a><div class="section3-header"><div class="section3-title">
Check Archive Mode (<span class="id">--archive-mode-check</span>)
</div></div><div class="section-body"><div class="section-body-text">
Check the <span class="postgres">PostgreSQL</span> <span class="br-setting">archive_mode</span> setting.
</div><div class="section-body-text">
Enabled by default, this option disallows <span class="postgres">PostgreSQL</span> <span class="br-setting">archive_mode=always</span>.
</div><div class="section-body-text">
WAL segments pushed from a standby server might be logically the same as WAL segments pushed from the primary but have different checksums. Disabling archiving from multiple sources is recommended to avoid conflicts.
</div><div class="admonition"><div class="caution">
CAUTION:
</div><div class="caution-text">
If this option is disabled then it is critical to ensure that only one archiver is writing to the repository via the <span class="cmd">archive-push</span> command.
</div></div>
<pre class="code-block" tabindex="0">default: y
example: --no-archive-mode-check</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-archive-timeout"></a><div class="section3-header"><div class="section3-title">
Archive Timeout (<span class="id">--archive-timeout</span>)
</div></div><div class="section-body"><div class="section-body-text">
Archive timeout.
</div><div class="section-body-text">
Set maximum time, in seconds, to wait for each WAL segment to reach the <span class="backrest">pgBackRest</span> archive repository. The timeout applies to the <span class="cmd">check</span> and <span class="cmd">backup</span> commands when waiting for WAL segments required for backup consistency to be archived.
</div>
<pre class="code-block" tabindex="0">default: 1m
allowed: [100ms, 1d]
example: --archive-timeout=30</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-backup-standby"></a><div class="section3-header"><div class="section3-title">
Backup from Standby (<span class="id">--backup-standby</span>)
</div></div><div class="section-body"><div class="section-body-text">
Backup from the standby cluster.
</div><div class="section-body-text">
Enable backup from standby to reduce load on the primary cluster. This option requires that both the <span class="host">primary</span> and <span class="host">standby</span> hosts be configured.
</div><div class="section-body-text">
The following modes are supported:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="id">y</span> - Standby is required for backup.
</li><li class="list-unordered">
<span class="id">prefer</span> - Backup from standby if available otherwise backup from primary.
</li><li class="list-unordered">
<span class="id">n</span> - Backup from primary only.
</li></ul>
<pre class="code-block" tabindex="0">default: n
example: --backup-standby=y</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-checksum-page"></a><div class="section3-header"><div class="section3-title">
Page Checksums (<span class="id">--checksum-page</span>)
</div></div><div class="section-body"><div class="section-body-text">
Validate data page checksums.
</div><div class="section-body-text">
Directs <span class="backrest">pgBackRest</span> to validate all data page checksums while backing up a cluster. This option is automatically enabled when data page checksums are enabled on the cluster.
</div><div class="section-body-text">
Failures in checksum validation will not abort a backup. Rather, warnings will be emitted in the log (and to the console with default settings) and the list of invalid pages will be stored in the backup manifest.
</div>
<pre class="code-block" tabindex="0">example: --no-checksum-page</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-checksum-page-error"></a><div class="section3-header"><div class="section3-title">
Error on Invalid Page Checksums (<span class="id">--checksum-page-error</span>)
</div></div><div class="section-body"><div class="section-body-text">
Error on invalid page checksums.
</div><div class="section-body-text">
When enabled with the <span class="br-option">checksum-page</span> option, a failure in page checksum validation will terminate the backup.
</div>
<pre class="code-block" tabindex="0">default: n
example: --no-checksum-page-error</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-exclude"></a><div class="section3-header"><div class="section3-title">
Path/File Exclusions (<span class="id">--exclude</span>)
</div></div><div class="section-body"><div class="section-body-text">
Exclude paths/files from the backup.
</div><div class="section-body-text">
All exclusions are relative to <span class="path">$PGDATA</span>. If the exclusion ends with / then only files in the specified directory will be excluded, e.g. <span class="br-option">--exclude=junk/</span> will exclude all files in the <span class="path">$PGDATA/junk</span> directory but include the directory itself. If the exclusion does not end with / then the file may match the exclusion exactly or match with / appended to the exclusion, e.g. <span class="br-option">--exclude=junk</span> will exclude the <span class="path">$PGDATA/junk</span> directory and all the files it contains.
</div><div class="section-body-text">
<b>Be careful using this feature -- it is very easy to exclude something critical that will make the backup inconsistent. Be sure to test your restores!</b>
</div><div class="section-body-text">
All excluded files will be logged at <span class="id">info</span> level along with the exclusion rule. Be sure to audit the list of excluded files to ensure nothing unexpected is being excluded.
</div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
Exclusions are not honored on delta restores. Any files/directories that were excluded by the backup will be <i>removed</i> on delta restore.
</div></div><div class="section-body-text">
This option should not be used to exclude <span class="postgres">PostgreSQL</span> logs from a backup. Logs can be moved out of the <span class="id">PGDATA</span> directory using the <span class="postgres">PostgreSQL</span> <span class="br-setting">log_directory</span> setting, which has the benefit of allowing logs to be preserved after a restore.
</div><div class="section-body-text">
Multiple exclusions may be specified on the command-line or in a configuration file.
</div>
<pre class="code-block" tabindex="0">example: --exclude=junk/</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-expire-auto"></a><div class="section3-header"><div class="section3-title">
Expire Auto (<span class="id">--expire-auto</span>)
</div></div><div class="section-body"><div class="section-body-text">
Automatically run the <span class="cmd">expire</span> command after a successful backup.
</div><div class="section-body-text">
The setting is enabled by default. Use caution when disabling this option as doing so will result in retaining all backups and archives indefinitely, which could cause your repository to run out of space. The <span class="cmd">expire</span> command will need to be run regularly to prevent this from happening.
</div><div class="section-body-text">
When <span class="cmd">expire</span> is run automatically after a successful backup it uses the configuration of the <span class="cmd">backup</span> command, so options set only in an <span class="cmd">expire</span> command section (e.g. <span class="id">[global:expire]</span>) are not applied. To apply <span class="cmd">expire</span>-specific configuration, disable this option and run the <span class="cmd">expire</span> command separately.
</div>
<pre class="code-block" tabindex="0">default: y
example: --expire-auto</pre>
</div></div><div class="section3"><a id="command-backup/category-command/option-force"></a><div class="section3-header"><div class="section3-title">
Force (<span class="id">--force</span>)
</div></div><div class="section-body"><div class="section-body-text">
Force an offline backup.
</div><div class="section-body-text">
When used with <span class="br-option">--no-start-stop</span> a backup will be run even if <span class="backrest">pgBackRest</span> thinks that <span class="postgres">PostgreSQL</span> is running. <b>This option should be used with extreme care as it will likely result in a bad backup.</b>
</div><div class="section-body-text">
There are some scenarios where a backup might still be desirable under these conditions. For example, if a server crashes and the database cluster volume can only be mounted read-only, it would be a good idea to take a backup even if <span class="file">postmaster.pid</span> is present. In this case it would be better to revert to the prior backup and replay WAL, but possibly there is a very important transaction in a WAL segment that did not get archived.