<!--
doc/src/sgml/ref/checkpoint.sgml
PostgreSQL documentation
-->

<refentry id="sql-checkpoint">
 <indexterm zone="sql-checkpoint">
  <primary>CHECKPOINT</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>CHECKPOINT</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CHECKPOINT</refname>
  <refpurpose>force a write-ahead log checkpoint</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
CHECKPOINT [ ( option [, ...] ) ]

<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>

    FLUSH_UNLOGGED [ <replaceable class="parameter">boolean</replaceable> ]
    MODE { FAST | SPREAD }
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   A checkpoint is a point in the write-ahead log sequence at which
   all data files for permanent relations have been updated to reflect the
   information in the log.  All data for permanent relation files will be
   flushed to disk.  Dirty buffers of unlogged relations are not flushed unless
   <literal>FLUSH_UNLOGGED</literal> is specified.  Refer to
   <xref linkend="wal-configuration"/> for more details about what happens
   during a checkpoint.
  </para>

  <para>
   By default, 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"/>).
   To request the checkpoint be spread over a longer interval, set the
   <literal>MODE</literal> option to <literal>SPREAD</literal>.
   <command>CHECKPOINT</command> is not intended for use during normal
   operation.
  </para>

  <para>
   The server may consolidate concurrently requested checkpoints.  Such
   consolidated requests will contain a combined set of options.  For example,
   if one session requests a fast checkpoint and another requests a spread
   checkpoint, the server may combine those requests and perform one fast
   checkpoint.
  </para>

  <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.
  </para>

  <para>
   Only superusers or users with the privileges of
   the <xref linkend="predefined-role-pg-checkpoint"/>
   role can call <command>CHECKPOINT</command>.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><literal>FLUSH_UNLOGGED</literal></term>
    <listitem>
     <para>
      Normally, <command>CHECKPOINT</command> does not flush dirty buffers of
      unlogged relations.  This option, which is disabled by default, enables
      flushing unlogged relations to disk.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>MODE</literal></term>
    <listitem>
     <para>
      When set to <literal>FAST</literal>, which is the default, the requested
      checkpoint will be completed as fast as possible, which may result in a
      significantly higher rate of I/O during the checkpoint.
     </para>
     <para>
      <literal>MODE</literal> can also be set to <literal>SPREAD</literal> to
      request the checkpoint be spread over a longer interval (controlled via
      the settings in <xref linkend="runtime-config-wal-checkpoints"/>), like a
      regular checkpoint scheduled by the system.  This can reduce the rate of
      I/O during the checkpoint.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">boolean</replaceable></term>
    <listitem>
     <para>
      Specifies whether the selected option should be turned on or off.
      You can write <literal>TRUE</literal>, <literal>ON</literal>, or
      <literal>1</literal> to enable the option, and <literal>FALSE</literal>,
      <literal>OFF</literal>, or <literal>0</literal> to disable it.  The
      <replaceable class="parameter">boolean</replaceable> value can also
      be omitted, in which case <literal>TRUE</literal> is assumed.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   The <command>CHECKPOINT</command> command is a
   <productname>PostgreSQL</productname> language extension.
  </para>
 </refsect1>
</refentry>
