Hi all,
I think that the page about the CHECKPOINT command:
http://www.postgresql.org/docs/current/static/sql-checkpoint.html
could really use some work.
The page is quite obtuse if you don't already understand what a checkpoint is.
The first sentence goes:
| Write-Ahead Logging (WAL) puts a checkpoint in
| the transaction log every so often.
but the reader still has no clue what a "checkpoint" actually is, and
the recursive definition isn't helping things any. And this next
sentence has more of the same problem, with the reader left equally
clueless:
| The CHECKPOINT command forces an immediate checkpoint
| when the command is issued, without waiting for a scheduled checkpoint.
There is this somewhat-helpful link in the next paragraph:
| Refer to Chapter 29 for more information about the WAL system.
Though it's not real clear from that sentence that Chapter 29 will
explain anything about what a checkpoint actually is (it does, but you
have to hunt through to the section "WAL Configuration" -- how is the
user supposed to know to go there to learn about what a checkpoint
is?)
Basically, I think the page should be structured to emphasize
1.) what is a "checkpoint" to a user who is not familiar with the term, and
2.) why would a user want to use the CHECKPOINT command?
To tackle 1.), I think a little bit of reorganization along with a
link to the right spot, namely:
http://www.postgresql.org/docs/current/static/wal-configuration.html
will go a long way. I've attached an admittedly rough patch to try to
address problem 1.).
As for 2.), there is no good answer on that page right now, other than
"not intended for use during normal operation". Off the top of my
head, the only suggested use I remember for CHECKPOINT is as a
recommended step before pg_start_backup(); anyone know of other uses?
And this bit:
| If executed during recovery, the CHECKPOINT command will
| force a restartpoint rather than writing a new checkpoint.
doesn't explain or link to what a "restartpoint" is, should it?
Josh