Add immediate and flush_all options to checkpoint

Field reports indicate that some users are running CHECKPOINT just
before shutting down to reduce the amount of data that the shutdown
checkpoint has to write out, making restarts faster.

That works well unless big unlogged tables are in play; a regular
CHECKPOINT does not flush these. Hence, add a CHECKPOINT option to force
flushing of all relations. Since it's easy enough, also add an IMMEDIATE
option to allow avoiding triggering a fast checkpoint.

Author: df7cb

doc/src/sgml/ref/checkpoint.sgml

@@ -21,7 +21,12 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-CHECKPOINT
+CHECKPOINT [ ( option [, ...] ) ]
+
+<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
+
+    IMMEDIATE [ <replaceable class="parameter">boolean</replaceable> ]
+    FLUSH_ALL [ <replaceable class="parameter">boolean</replaceable> ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -31,18 +36,18 @@ CHECKPOINT
   <para>
    A checkpoint is a point in the write-ahead log sequence at which
    all data files have been updated to reflect the information in the
-   log.  All data files will be flushed to disk.  Refer to
+   log.  All data files will be flushed to disk, except for relations marked <literal>UNLOGGED</literal>.  Refer to
    <xref linkend="wal-configuration"/> for more details about what happens
    during a checkpoint.
   </para>
 
   <para>
+   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"/>).
    The <command>CHECKPOINT</command> command forces an immediate
-   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.
+   checkpoint by default when the command is issued, without waiting for a
+   regular checkpoint scheduled by the system.
   </para>
 
   <para>
@@ -58,6 +63,46 @@ CHECKPOINT
   </para>
  </refsect1>
 
+ <refsect1>
+  <title>Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><literal>IMMEDIATE</literal></term>
+    <listitem>
+     <para>
+      Requests the checkpoint to start immediately and run at full speed
+      without spreading the I/O load out. Defaults to on.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><literal>FLUSH_ALL</literal></term>
+    <listitem>
+     <para>
+      Requests the checkpoint to also flush data of <literal>UNLOGGED</literal>
+      relations. Defaults to off.
+     </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>
 

src/backend/parser/gram.y

@@ -2034,6 +2034,14 @@ CheckPointStmt:
 					CheckPointStmt *n = makeNode(CheckPointStmt);
 
 					$$ = (Node *) n;
+					n->options = NULL;
+				}
+			| CHECKPOINT '(' utility_option_list ')'
+				{
+					CheckPointStmt *n = makeNode(CheckPointStmt);
+
+					$$ = (Node *) n;
+					n->options = $3;
 				}
 		;
 

src/backend/tcop/utility.c

@@ -943,6 +943,11 @@ standard_ProcessUtility(PlannedStmt *pstmt,
 			break;
 
 		case T_CheckPointStmt:
+			CheckPointStmt   *stmt = (CheckPointStmt *) parsetree;
+			ListCell   *lc;
+			bool		immediate = true;
+			bool		flush_all = false;
+
 			if (!has_privs_of_role(GetUserId(), ROLE_PG_CHECKPOINT))
 				ereport(ERROR,
 						(errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
@@ -952,7 +957,26 @@ standard_ProcessUtility(PlannedStmt *pstmt,
 						 errdetail("Only roles with privileges of the \"%s\" role may execute this command.",
 								   "pg_checkpoint")));
 
-			RequestCheckpoint(CHECKPOINT_IMMEDIATE | CHECKPOINT_WAIT |
+			/* Parse options list */
+			foreach(lc, stmt->options)
+			{
+				DefElem    *opt = (DefElem *) lfirst(lc);
+
+				if (strcmp(opt->defname, "immediate") == 0)
+					immediate = defGetBoolean(opt);
+				else if (strcmp(opt->defname, "flush_all") == 0)
+					flush_all = defGetBoolean(opt);
+				else
+					ereport(ERROR,
+							(errcode(ERRCODE_SYNTAX_ERROR),
+							 errmsg("unrecognized CHECKPOINT option \"%s\"", opt->defname),
+							 errhint("valid options are \"IMMEDIATE\" and \"FLUSH_ALL\""),
+							 parser_errposition(pstate, opt->location)));
+			}
+
+			RequestCheckpoint(CHECKPOINT_WAIT |
+							  (immediate ? CHECKPOINT_IMMEDIATE : 0) |
+							  (flush_all ? CHECKPOINT_FLUSH_ALL : 0) |
 							  (RecoveryInProgress() ? 0 : CHECKPOINT_FORCE));
 			break;
 

src/bin/psql/tab-complete.in.c

@@ -3125,6 +3125,11 @@ match_previous_words(int pattern_id,
 		COMPLETE_WITH_VERSIONED_SCHEMA_QUERY(Query_for_list_of_procedures);
 	else if (Matches("CALL", MatchAny))
 		COMPLETE_WITH("(");
+/* CHECKPOINT */
+	else if (Matches("CHECKPOINT"))
+		COMPLETE_WITH("(");
+	else if (Matches("CHECKPOINT", "("))
+		COMPLETE_WITH("IMMEDIATE", "FLUSH_ALL");
 /* CLOSE */
 	else if (Matches("CLOSE"))
 		COMPLETE_WITH_QUERY_PLUS(Query_for_list_of_cursors,

src/include/nodes/parsenodes.h

@@ -4015,6 +4015,7 @@ typedef struct RefreshMatViewStmt
 typedef struct CheckPointStmt
 {
 	NodeTag		type;
+	List	   *options;
 } CheckPointStmt;
 
 /* ----------------------

src/test/regress/expected/stats.out

@@ -925,9 +925,9 @@ CREATE TEMP TABLE test_stats_temp AS SELECT 17;
 DROP TABLE test_stats_temp;
 -- Checkpoint twice: The checkpointer reports stats after reporting completion
 -- of the checkpoint. But after a second checkpoint we'll see at least the
--- results of the first.
-CHECKPOINT;
+-- results of the first. And while at it, test checkpoint options.
 CHECKPOINT;
+CHECKPOINT (immediate, flush_all);
 SELECT num_requested > :rqst_ckpts_before FROM pg_stat_checkpointer;
  ?column? 
 ----------

src/test/regress/sql/stats.sql

@@ -438,9 +438,9 @@ DROP TABLE test_stats_temp;
 
 -- Checkpoint twice: The checkpointer reports stats after reporting completion
 -- of the checkpoint. But after a second checkpoint we'll see at least the
--- results of the first.
-CHECKPOINT;
+-- results of the first. And while at it, test checkpoint options.
 CHECKPOINT;
+CHECKPOINT (immediate, flush_all);
 
 SELECT num_requested > :rqst_ckpts_before FROM pg_stat_checkpointer;
 SELECT wal_bytes > :wal_bytes_before FROM pg_stat_wal;