Re: [HACKERS] Docs for archive_cleanup_command are poor

On Tue, Oct 12, 2010 at 8:28 AM, Fujii Masao <masao(dot)fujii(at)gmail(dot)com> wrote:
> On Sat, Oct 9, 2010 at 10:04 AM, Brendan Jurd <direvus(at)gmail(dot)com> wrote:
>> Hi folks,
>>
>> I have just set up HS+SR for the first time, and for the most part,
>> the docs were excellent.  The one exception for me was the discussion
>> of archive_cleanup_command.  This is a pretty important part of
>> constructing a healthy standby server, and IMO the docs don't give it
>> the treatment it deserves.
>>
>> Under "25.2.4. Setting Up a Standby Server", we have:
>>
>> "You can use archive_cleanup_command to prune the archive of files no
>> longer needed by the standby."
>>
>> ... then a few paragraphs later ...
>>
>> "If you're using a WAL archive, its size can be minimized using the
>> archive_cleanup_command  option to remove files that are no longer
>> required by the standby server. Note however, that if you're using the
>> archive for backup purposes, you need to retain files needed to
>> recover from at least the latest base backup, even if they're no
>> longer needed by the standby."
>>
>> So there are a couple of brief mentions of what
>> archive_cleanup_command is for, but nothing about how it works, no
>> exampes of how to use it, and no links at all.  Contrast how we deal
>> with archive_command, restore_command and primary_conninfo.
>>
>> I'd like to suggest a few ways we could improve on this:
>>
>> 1. Remove the former paragraph.  It's stranded out there on its own in
>> the middle of some unrelated text, and doesn't say anything of
>> substance not also said in the latter paragraph.
>>
>> 2. Include an example archive_cleanup_command in the recovery.conf
>> example snippet.
>>
>> 3. Link to 26.1 which actually explains how a_c_c works.
>>
>> 4. Mention, and link to, pg_archivecleanup from both 25.2.4 and 26.1.
>> This is the utility that most newcomers to WAL archiving will want to
>> use, so it's rather weird of us not to advertise it.
>>
>> I'm willing to write a patch for this, but I thought I'd raise the
>> suggestions on-list first, before getting too invested.  So, please
>> comment if you have an opinion on this.
>
> Agreed.

Is someone working on a patch?

> And, ISTM that we should mention that we must not just specify
> pg_archivecleanup in archive_cleanup_command when there are multiple
> standby servers. This is because, in that case, we must calculate
> the oldest restart point in those standbys and delete the archived
> WAL files according to that point.

How do we expect people to do that, by the way?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company