Skip site navigation (1) Skip section navigation (2)

Docs for archive_cleanup_command are poor

From: Brendan Jurd <direvus(at)gmail(dot)com>
To: pgsql-hackers(at)postgresql(dot)org, pgsql-docs(at)postgresql(dot)org
Subject: Docs for archive_cleanup_command are poor
Date: 2010-10-09 01:04:21
Message-ID: AANLkTin7HkSNoXimB5XQq69Wnw4a04oBSM1EiRGEOTZ3@mail.gmail.com (view raw or flat)
Thread:
Lists: pgsql-docspgsql-hackers
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.

Cheers,
BJ

Responses

pgsql-docs by date

Next:From: Peter EisentrautDate: 2010-10-10 10:55:22
Subject: Re: [INTERFACES] ECPG Documentation Improvement (re-post)
Previous:From: Josh KupershmidtDate: 2010-10-08 13:21:32
Subject: Re: Asynchronous I/O in Postgres

pgsql-hackers by date

Next:From: Brendan JurdDate: 2010-10-09 02:13:07
Subject: Keywords in pg_hba.conf should be field-specific
Previous:From: Robert HaasDate: 2010-10-09 00:40:03
Subject: Re: Sync Replication with transaction-controlled durability

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group