Thread: description of CHECKPOINT command confusing
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
Attachment
On Wed, Oct 12, 2011 at 12:02 PM, Josh Kupershmidt <schmiddy@gmail.com> wrote: > 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.). +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: It's for preventing pg_start_backup() from taking lots of time? If so, you're right in 8.3 and before. In 8.4 and later, instead, you can specify whether pg_start_backup() performs smoothed checkpoint or immediate one, by using the second argument of pg_start_backup(). I'm not sure if there are other use cases during normal operation. > | 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? It's helpful to link to that. What a "restartpoint" is explained in also http://www.postgresql.org/docs/current/static/wal-configuration.html Regards, -- Fujii Masao NIPPON TELEGRAPH AND TELEPHONE CORPORATION NTT Open Source Software Center
On Wed, Oct 12, 2011 at 1:14 AM, Fujii Masao <masao.fujii@gmail.com> wrote: > On Wed, Oct 12, 2011 at 12:02 PM, Josh Kupershmidt <schmiddy@gmail.com> wrote: > It's for preventing pg_start_backup() from taking lots of time? If so, > you're right in 8.3 and before. In 8.4 and later, instead, you can specify > whether pg_start_backup() performs smoothed checkpoint or immediate > one, by using the second argument of pg_start_backup(). Neat, I hadn't seen that change to pg_start_backup(). > I'm not sure if there are other use cases during normal operation. If there's no real use-case for the command, I think the existing text of "not intended for use during normal operation" is fine. > It's helpful to link to that. What a "restartpoint" is explained in also > http://www.postgresql.org/docs/current/static/wal-configuration.html I wonder if it'd be helpful to break up that page into sub-sections, it is quite a large single section now. That might make it easier to link into that page for explaining restartpoint. Slightly updated patch attached. Josh
Attachment
On Thu, Oct 13, 2011 at 10:44 AM, Josh Kupershmidt <schmiddy@gmail.com> wrote: > On Wed, Oct 12, 2011 at 1:14 AM, Fujii Masao <masao.fujii@gmail.com> wrote: >> I'm not sure if there are other use cases during normal operation. > > If there's no real use-case for the command, I think the existing text > of "not intended for use during normal operation" is fine. Agreed. >> It's helpful to link to that. What a "restartpoint" is explained in also >> http://www.postgresql.org/docs/current/static/wal-configuration.html > > I wonder if it'd be helpful to break up that page into sub-sections, > it is quite a large single section now. That might make it easier to > link into that page for explaining restartpoint. +1 > Slightly updated patch attached. Looks good. Regards, -- Fujii Masao NIPPON TELEGRAPH AND TELEPHONE CORPORATION NTT Open Source Software Center
On Fri, Oct 14, 2011 at 1:17 AM, Fujii Masao <masao.fujii@gmail.com> wrote: >> Slightly updated patch attached. > > Looks good. Committed. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company