Document restrictions regarding incremental backups and standbys.

robertmhaas · robertmhaas · commit 744ddc6c6a0f · 2024-07-25T15:45:06.000-04:00
If you try to take an incremental backup on a standby and there hasn't been much system activity, it might fail. Document why this happens. Also add a hint to the error message you get, to make it more likely that users will understand what has gone wrong. Laurenz Albe and Robert Haas Discussion: https://postgr.es/m/5468641ad821dad7aa3b2d65bf843146443a1b68.camel@cybertec.at
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
@@ -925,6 +925,17 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
     to manage. For a large database all of which is heavily modified,
     incremental backups won't be much smaller than full backups.
    </para>
+
+   <para>
+    An incremental backup is only possible if replay would begin from a later
+    checkpoint than for the previous backup upon which it depends.  If you
+    take the incremental backup on the primary, this condition is always
+    satisfied, because each backup triggers a new checkpoint.  On a standby,
+    replay begins from the most recent restartpoint.  Therefore, an
+    incremental backup of a standby server can fail if there has been very
+    little activity since the previous backup, since no new restartpoint might
+    have been created.
+   </para>
   </sect2>
 
   <sect2 id="backup-lowlevel-base-backup">
diff --git a/src/backend/backup/basebackup_incremental.c b/src/backend/backup/basebackup_incremental.c
@@ -441,7 +441,8 @@ PrepareForIncrementalBackup(IncrementalBackupInfo *ib,
 						 errmsg("manifest requires WAL from final timeline %u ending at %X/%X, but this backup starts at %X/%X",
 								range->tli,
 								LSN_FORMAT_ARGS(range->end_lsn),
-								LSN_FORMAT_ARGS(backup_state->startpoint))));
+								LSN_FORMAT_ARGS(backup_state->startpoint)),
+						 errhint("This can happen for incremental backups on a standby if there was little activity since the previous backup.")));
 		}
 		else
 		{

Original file line number	Diff line number	Diff line change
`@@ -441,7 +441,8 @@ PrepareForIncrementalBackup(IncrementalBackupInfo *ib,`
`441`	`441`	`errmsg("manifest requires WAL from final timeline %u ending at %X/%X, but this backup starts at %X/%X",`
`442`	`442`	`range->tli,`
`443`	`443`	`LSN_FORMAT_ARGS(range->end_lsn),`
`444`		`- LSN_FORMAT_ARGS(backup_state->startpoint))));`
	`444`	`+ LSN_FORMAT_ARGS(backup_state->startpoint)),`
	`445`	`+ errhint("This can happen for incremental backups on a standby if there was little activity since the previous backup.")));`
`445`	`446`	`}`
`446`	`447`	`else`
`447`	`448`	`{`