From 843fd49772e48a2cf8b0b8821e20b2352343fe33 Mon Sep 17 00:00:00 2001 From: Daria Lepikhova Date: Mon, 28 Sep 2026 16:48:06 +0200 Subject: [PATCH v4 1/2] doc: Clarify that base backup progress counts uncompressed archive data The documentation described base backup progress in terms of data streamed, which could be mistaken for the amount of data sent over the connection when server-side compression is enabled. Clarify that the counters measure archive data before server-side compression. The progress report message was also documented as counting bytes from the current tablespace, although it reports a cumulative count for the whole backup. Correct the description to say that the count covers all tablespaces since the backup began. Backpatch to 15, where both the progress report message and server-side compression were introduced. Discussion: https://postgr.es/m/CAK49S1ASwk7L-7LYUUz1MU_+uQnZ75srva2XRR4r-w0HCVZeUQ@mail.gmail.com Backpatch-through: 15 --- doc/src/sgml/monitoring.sgml | 8 +++++--- doc/src/sgml/protocol.sgml | 11 +++++++---- doc/src/sgml/ref/pg_basebackup.sgml | 4 ++-- src/include/backup/basebackup_sink.h | 8 +++++--- 4 files changed, 19 insertions(+), 12 deletions(-) diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 67ae6fd5f7e..52d4241a2ff 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -8150,8 +8150,9 @@ FROM pg_stat_get_backend_idset() AS backendid; backup_total bigint - Total amount of data that will be streamed. This is estimated and - reported as of the beginning of + Total amount of data that will be streamed. This counts archive data + before any server-side compression. The estimate is reported as of + the beginning of the streaming database files phase. Note that this is only an approximation since the database may change during streaming database files phase @@ -8170,7 +8171,8 @@ FROM pg_stat_get_backend_idset() AS backendid; backup_streamed bigint - Amount of data streamed. This counter only advances + Amount of data streamed. This counts archive data before any server-side + compression. This counter only advances when the phase is streaming database files or transferring wal files. diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 8ced69f283b..e3839518b13 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -3425,8 +3425,10 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" size (int8) - The approximate size of the tablespace, in kilobytes (1024 bytes), - if progress report has been requested; otherwise it's null. + The approximate size of the archive that will be generated for the + tablespace, in kilobytes (1024 bytes), if progress report has been + requested; otherwise it's null. This size is measured before any + server-side compression. @@ -3524,8 +3526,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int64 - The number of bytes from the current tablespace for which - processing has been completed. + The cumulative number of bytes processed across all tablespaces + since the backup began. This counts archive data before any + server-side compression. diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index 3117968d125..b4a0faccf41 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -725,8 +725,8 @@ PostgreSQL documentation always being NULL. - Without this option, the backup will start by enumerating - the size of the entire database, and then go back and send + Without this option, the backup will start by estimating the total + amount of data that will be streamed, and then go back and send the actual contents. This may make the backup take slightly longer, and in particular it will take longer before the first data is sent. This option is useful to avoid such estimation diff --git a/src/include/backup/basebackup_sink.h b/src/include/backup/basebackup_sink.h index 96fa2c4eaba..043eeb5c4e4 100644 --- a/src/include/backup/basebackup_sink.h +++ b/src/include/backup/basebackup_sink.h @@ -51,10 +51,12 @@ typedef struct bbsink_ops bbsink_ops; * 'tablespace_num' is the index of the current tablespace within the list * stored in 'tablespaces'. * - * 'bytes_done' is the number of bytes read so far from $PGDATA. + * 'bytes_done' is the number of bytes of archive data generated so far. This + * is counted before any server-side compression. * - * 'bytes_total' is the total number of bytes estimated to be present in - * $PGDATA, if we have estimated this. + * 'bytes_total' is the total number of bytes of archive data estimated to be + * generated, if we have estimated this. The estimate is for data before any + * server-side compression. * * 'bytes_total_is_valid' is true if and only if a proper estimate has been * stored into 'bytes_total'. -- 2.56.0