On Wed, 2025-06-11 at 17:53 +0200, Christoph Berg wrote:
> I haven't implemented a WAIT option yet since I didn't want to decide
> that without more votes in either direction.
I had a look at it, and I have suggestions for the documentation.
> --- a/doc/src/sgml/ref/checkpoint.sgml
> +++ b/doc/src/sgml/ref/checkpoint.sgml
> [...]
> <para>
> - The <command>CHECKPOINT</command> command forces a fast
> - checkpoint when the command is issued, without waiting for a
> - regular checkpoint scheduled by the system (controlled by the settings in
> - <xref linkend="runtime-config-wal-checkpoints"/>).
> - <command>CHECKPOINT</command> is not intended for use during normal
> - operation.
> + Running <command>CHECKPOINT</command> is not required during normal
> + operation; the system schedules checkpoints automatically (controlled by
> + the settings in <xref linkend="runtime-config-wal-checkpoints"/>).
> + <command>CHECKPOINT</command> can be beneficial to run before operations
> + such as binary backups or shutting down
> <productname>PostgreSQL</productname>
> + as this can reduce the amount of data to be flushed for the next
> checkpoint
> + within these operations. Specifically, <literal>UNLOGGED</literal> table
> + data is otherwise only flushed by the shutdown checkpoint.
> </para>
How about the following for added clarity:
Running an explicit <command>CHECKPOINT</command> is not required during
normal operation; the system schedules checkpoints automatically (controlled
by the settings in <xref linkend="runtime-config-wal-checkpoints"/>).
However, it can be useful to perform an explicit checkpoint immediately
before shutting down the server or performing an online file system backup,
if you want the checkpoint implicit in these operations to be as fast as
possible. In particular, <literal>UNLOGGED</literal> table data only get
flushed to disk during a shutdown checkpoint, so you should use the option
<literal>FLUSH_UNLOGGED</literal> for an explicit checkpoint right before a
shutdown.
> <para>
> If executed during recovery, the <command>CHECKPOINT</command> command
> - will force a restartpoint (see <xref linkend="wal-configuration"/>)
> - rather than writing a new checkpoint.
> + will force a restartpoint rather than writing a new checkpoint. (The
> + operation will be a no-op if there is no corresponding checkpoint in the
> + write-ahead log.) If a checkpoint is already being written when a
> + <command>CHECKPOINT</command> is issued, the running checkpoint is
> upgraded
> + with this command's <literal>MODE</literal> and
> + <literal>FLUSH_UNLOGGED</literal> options.
> </para>
Oh, interesting; I wasn't aware of that. That means that running CHECKPOINT
(FLUSH_UNLOGGED) is less useful than I thought, since there is often already
a spread checkpoint running. Would it be useful to recommend that you should
run the command twice when aiming for a fast shutdown?
@@ -58,6 +69,54 @@ CHECKPOINT
</para>
</refsect1>
+ <refsect1>
+ <title>Parameters</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>MODE</literal></term>
+ <listitem>
+ <para>
+ The <command>CHECKPOINT</command> command forces a fast checkpoint by
+ default when the command is issued, without waiting for a regular
+ checkpoint scheduled by the system.
+ </para>
+ <para>
+ A <literal>SPREAD</literal> checkpoint will instead spread out the write
+ load as determined by the
+ <xref linkend="guc-checkpoint-completion-target"/> setting, like the
+ system-scheduled checkpoints.
+ </para>
+ </listitem>
+ </varlistentry>
I find this somewhat confusing; how about
<para>
The default <literal>FAST</literal> mode causes the checkpoint to be
performed as fast as possible. A <literal>SPREAD</literal> checkpoint
will instead spread out the write load as determined by the
<xref linkend="guc-checkpoint-completion-target"/> setting, like the
system-scheduled checkpoints.
</para>
+ <varlistentry>
+ <term><literal>FLUSH_UNLOGGED</literal></term>
+ <listitem>
+ <para>
+ All data files except for those marked as <literal>UNLOGGED</literal>
+ are flushed to disk during a checkpoint. Enabling this option will also
+ flush <literal>UNLOGGED</literal> relations; the default is off.
+ </para>
+ </listitem>
+ </varlistentry>
How about:
<varlistentry>
<term><literal>FLUSH_UNLOGGED</literal></term>
<listitem>
<para>
Normally, data files marked as <literal>UNLOGGED</literal> are not
flushed to disk during a checkpoint. Enabling this option will also
flush <literal>UNLOGGED</literal> relations. This option is disabled
by default.
</para>
</listitem>
</varlistentry>
Yours,
Laurenz Albe
