Technical Analysis: Small fixes for CHECKPOINT FLUSH_UNLOGGED

Context and Background

This thread addresses two minor but important polish issues with the recently committed feature "Add FLUSH_UNLOGGED option to CHECKPOINT command." The FLUSH_UNLOGGED option was introduced to give users explicit control over whether a CHECKPOINT operation flushes dirty buffers belonging to unlogged relations to disk. By default, CHECKPOINT now skips unlogged relations (since their data is ephemeral and not WAL-logged, flushing them during checkpoint is unnecessary for crash recovery purposes). The FLUSH_UNLOGGED option allows users to override this behavior when they explicitly want unlogged relation data persisted to disk (e.g., for clean shutdown scenarios or specific operational needs).

Core Problems Identified

1. Tab-Completion Gap for FLUSH_UNLOGGED Boolean Values

The FLUSH_UNLOGGED option accepts a boolean value (ON/OFF), but psql's tab-completion infrastructure was not updated to suggest these values. This is a usability regression compared to other CHECKPOINT options like REPACK, which properly suggests ON/OFF when the user hits tab. The fix follows the established pattern in psql's tab-complete.c for boolean-valued options.

Technical Detail: In psql's tab-completion system, each option that accepts boolean values needs to be explicitly registered in the completion logic. The existing code for REPACK already demonstrates the correct pattern, so this is a straightforward addition to the same code path.

2. Stale Documentation in checkpoint.sgml

The introduction of FLUSH_UNLOGGED changed the default behavior of CHECKPOINT — it no longer flushes all data files to disk, only logged relations by default. However, the documentation still contained the original language stating "All data files will be flushed to disk," which is now technically inaccurate. This is a documentation correctness issue that could mislead users about what CHECKPOINT actually does post-feature.

Architectural Significance: This documentation issue highlights a broader concern in PostgreSQL development: when a feature changes default behavior of an existing command, all documentation touchpoints must be audited. The checkpoint documentation is particularly important because DBAs rely on precise understanding of what CHECKPOINT guarantees for their backup and recovery procedures.

Proposed Solutions

The patch is split into two commits for review clarity:

1. Tab-completion fix: Adds FLUSH_UNLOGGED to the boolean-value completion list in psql's tab-complete.c, following the existing pattern used by REPACK.

2. Documentation fix: Updates checkpoint.sgml to accurately reflect that the default CHECKPOINT no longer flushes unlogged relation buffers, while noting that FLUSH_UNLOGGED can be used to restore the old behavior.

Design Decisions and Implications

The decision to make CHECKPOINT skip unlogged relations by default is architecturally sound: unlogged relations have no WAL records, so their buffers don't need to be flushed for crash recovery consistency. Flushing them was always wasted I/O during checkpoints. The FLUSH_UNLOGGED option preserves backward compatibility for users who depended on the old behavior (e.g., for orderly shutdown scenarios where they want all data on disk regardless of logging status).

The split into two commits follows PostgreSQL convention for separating logically independent changes, even when small, to maintain clean git history and enable potential selective revert.

Assessment

These are trivial but necessary fixes that demonstrate good community testing practices — a contributor tested a newly committed feature, found rough edges, and provided clean patches. The quick acceptance by the feature's maintainer indicates confidence in the fixes' correctness and low risk.