Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Subject: Clarifying pg_rewind failure risks due to asynchronous file deletions
To: pgsql-docs@lists.postgresql.org
From: PG Doc comments form <noreply@postgresql.org>
Cc: juliana.crespo@enterprisedb.com
Reply-To: juliana.crespo@enterprisedb.com, pgsql-docs@lists.postgresql.org
Date: Wed, 11 Mar 2026 17:44:45 +0000
Message-ID: 
 <177325108551.1938400.15560714772530033016@wrigleys.postgresql.org>
Auto-Submitted: auto-generated
Archived-At: 
 <https://www.postgresql.org/message-id/177325108551.1938400.15560714772530033016%40wrigleys.postgresql.org>
Precedence: bulk

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/18/app-pgrewind.html
Description:

Reference Page: https://www.postgresql.org/docs/current/app-pgrewind.html

Proposed Enhancement: Include an explicit warning in the **"Description"**
or **"Warnings"** section regarding the requirement for the target data
directory to remain static during the rewind process.

Reasoning: While the documentation states that `pg_rewind` "will fail
immediately if it finds files it cannot write directly to," it does not
currently warn against asynchronous file deletions within the target
`$PGDATA` (or tablespace/WAL directories) while the utility is running.

In high-concurrency or automated environments, background processes=E2=80=
=94such as
the **WAL summarizer** cleanup, automated log rotations, or external
archiver tools (e.g., `pgbackrest` spooling)=E2=80=94may remove files that
`pg_rewind` has already indexed for synchronization. This results in a fatal
"No such file or directory" error during the final stages of the rewind,
often leaving the target directory in an unrecoverable state.

Suggested Phrasing:

"Warning: The target data directory must remain static during the rewind
operation. Any asynchronous file modifications or deletions=E2=80=94such as=
 those
performed by automated log rotation, WAL summary cleanups, or external
backup tools=E2=80=94may cause `pg_rewind` to fail. If a file is removed af=
ter the
synchronization process has begun, the utility may error out, leaving the
target cluster in an inconsistent state that requires a new base backup."