Sync guc.c and postgresql.conf.sample with the SGML docs.

It seems that various people have moved GUCs around in the config.sgml
listing without bothering to make the code agree.  Ensure that the
config_group codes assigned to GUCs match where they are listed in
config.sgml.  Likewise ensure that postgresql.conf.sample lists GUCs
in the same sub-section and same ordering as they appear in config.sgml.

(I've got some doubts about some of these choices, but for the purposes
of this patch, we'll treat config.sgml as gospel.)

Notably, this requires adding a WAL_RECOVERY config_group value,
because 1d257577e didn't.  As long as we're renumbering that enum
anyway, let's take out the values corresponding to major groups
that are divided into sub-groups.  No GUC should be assigned to the
major group itself, so those values just create a temptation to
do the wrong thing, while adding work for translators.

In passing, adjust the short_desc strings for PRESET_OPTIONS GUCs
to uniformly use the phrasing "Shows XYZ.", removing the impression
some of these strings left that you can set the value.

While some of these errors are old, no back-patch, as changing the
contents of the pg_settings view in stable branches seems more likely
to be seen as a compatibility break than anything helpful.

Bharath Rupireddy, Justin Pryzby, Tom Lane

Discussion: https://postgr.es/m/16997-ff16127f6e0d1390@postgresql.org
Discussion: https://postgr.es/m/20210413123139.GE6091@telsasoft.com
This commit is contained in:
Tom Lane 2021-05-08 12:13:33 -04:00
parent f9b809e7fb
commit a55a98477b
3 changed files with 72 additions and 96 deletions

View File

@ -703,16 +703,12 @@ const char *const config_group_names[] =
gettext_noop("Ungrouped"),
/* FILE_LOCATIONS */
gettext_noop("File Locations"),
/* CONN_AUTH */
gettext_noop("Connections and Authentication"),
/* CONN_AUTH_SETTINGS */
gettext_noop("Connections and Authentication / Connection Settings"),
/* CONN_AUTH_AUTH */
gettext_noop("Connections and Authentication / Authentication"),
/* CONN_AUTH_SSL */
gettext_noop("Connections and Authentication / SSL"),
/* RESOURCES */
gettext_noop("Resource Usage"),
/* RESOURCES_MEM */
gettext_noop("Resource Usage / Memory"),
/* RESOURCES_DISK */
@ -725,20 +721,18 @@ const char *const config_group_names[] =
gettext_noop("Resource Usage / Background Writer"),
/* RESOURCES_ASYNCHRONOUS */
gettext_noop("Resource Usage / Asynchronous Behavior"),
/* WAL */
gettext_noop("Write-Ahead Log"),
/* WAL_SETTINGS */
gettext_noop("Write-Ahead Log / Settings"),
/* WAL_CHECKPOINTS */
gettext_noop("Write-Ahead Log / Checkpoints"),
/* WAL_ARCHIVING */
gettext_noop("Write-Ahead Log / Archiving"),
/* WAL_RECOVERY */
gettext_noop("Write-Ahead Log / Recovery"),
/* WAL_ARCHIVE_RECOVERY */
gettext_noop("Write-Ahead Log / Archive Recovery"),
/* WAL_RECOVERY_TARGET */
gettext_noop("Write-Ahead Log / Recovery Target"),
/* REPLICATION */
gettext_noop("Replication"),
/* REPLICATION_SENDING */
gettext_noop("Replication / Sending Servers"),
/* REPLICATION_PRIMARY */
@ -747,8 +741,6 @@ const char *const config_group_names[] =
gettext_noop("Replication / Standby Servers"),
/* REPLICATION_SUBSCRIBERS */
gettext_noop("Replication / Subscribers"),
/* QUERY_TUNING */
gettext_noop("Query Tuning"),
/* QUERY_TUNING_METHOD */
gettext_noop("Query Tuning / Planner Method Configuration"),
/* QUERY_TUNING_COST */
@ -757,8 +749,6 @@ const char *const config_group_names[] =
gettext_noop("Query Tuning / Genetic Query Optimizer"),
/* QUERY_TUNING_OTHER */
gettext_noop("Query Tuning / Other Planner Options"),
/* LOGGING */
gettext_noop("Reporting and Logging"),
/* LOGGING_WHERE */
gettext_noop("Reporting and Logging / Where to Log"),
/* LOGGING_WHEN */
@ -766,17 +756,13 @@ const char *const config_group_names[] =
/* LOGGING_WHAT */
gettext_noop("Reporting and Logging / What to Log"),
/* PROCESS_TITLE */
gettext_noop("Process Title"),
/* STATS */
gettext_noop("Statistics"),
gettext_noop("Reporting and Logging / Process Title"),
/* STATS_MONITORING */
gettext_noop("Statistics / Monitoring"),
/* STATS_COLLECTOR */
gettext_noop("Statistics / Query and Index Statistics Collector"),
/* AUTOVACUUM */
gettext_noop("Autovacuum"),
/* CLIENT_CONN */
gettext_noop("Client Connection Defaults"),
/* CLIENT_CONN_STATEMENT */
gettext_noop("Client Connection Defaults / Statement Behavior"),
/* CLIENT_CONN_LOCALE */
@ -787,8 +773,6 @@ const char *const config_group_names[] =
gettext_noop("Client Connection Defaults / Other Defaults"),
/* LOCK_MANAGEMENT */
gettext_noop("Lock Management"),
/* COMPAT_OPTIONS */
gettext_noop("Version and Platform Compatibility"),
/* COMPAT_OPTIONS_PREVIOUS */
gettext_noop("Version and Platform Compatibility / Previous PostgreSQL Versions"),
/* COMPAT_OPTIONS_CLIENT */
@ -1188,7 +1172,7 @@ static struct config_bool ConfigureNamesBool[] =
check_bonjour, NULL, NULL
},
{
{"track_commit_timestamp", PGC_POSTMASTER, REPLICATION,
{"track_commit_timestamp", PGC_POSTMASTER, REPLICATION_SENDING,
gettext_noop("Collects transaction commit time."),
NULL
},
@ -1297,7 +1281,7 @@ static struct config_bool ConfigureNamesBool[] =
NULL, NULL, NULL
},
{
{"recovery_prefetch", PGC_SIGHUP, WAL_SETTINGS,
{"recovery_prefetch", PGC_SIGHUP, WAL_RECOVERY,
gettext_noop("Prefetch referenced blocks during recovery."),
gettext_noop("Read ahead of the current replay position to find uncached blocks.")
},
@ -1306,7 +1290,7 @@ static struct config_bool ConfigureNamesBool[] =
NULL, assign_recovery_prefetch, NULL
},
{
{"recovery_prefetch_fpw", PGC_SIGHUP, WAL_SETTINGS,
{"recovery_prefetch_fpw", PGC_SIGHUP, WAL_RECOVERY,
gettext_noop("Prefetch blocks that have full page images in the WAL."),
gettext_noop("On some systems, there is no benefit to prefetching pages that will be "
"entirely overwritten, but if the logical page size of the filesystem is "
@ -1869,7 +1853,7 @@ static struct config_bool ConfigureNamesBool[] =
{
{"integer_datetimes", PGC_INTERNAL, PRESET_OPTIONS,
gettext_noop("Datetimes are integer based."),
gettext_noop("Shows whether datetimes are integer based."),
NULL,
GUC_REPORT | GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
},
@ -2416,7 +2400,7 @@ static struct config_int ConfigureNamesInt[] =
{
{"data_directory_mode", PGC_INTERNAL, PRESET_OPTIONS,
gettext_noop("Mode of the data directory."),
gettext_noop("Shows the mode of the data directory."),
gettext_noop("The parameter value is a numeric mode specification "
"in the form accepted by the chmod and umask system "
"calls. (To use the customary octal format the number "
@ -2772,7 +2756,7 @@ static struct config_int ConfigureNamesInt[] =
},
{
{"wal_decode_buffer_size", PGC_POSTMASTER, WAL_ARCHIVE_RECOVERY,
{"wal_decode_buffer_size", PGC_POSTMASTER, WAL_RECOVERY,
gettext_noop("Maximum buffer size for reading ahead in the WAL during recovery."),
gettext_noop("This controls the maximum distance we can read ahead in the WAL to prefetch referenced blocks."),
GUC_UNIT_BYTE
@ -3393,7 +3377,7 @@ static struct config_int ConfigureNamesInt[] =
},
{
{"tcp_keepalives_idle", PGC_USERSET, CLIENT_CONN_OTHER,
{"tcp_keepalives_idle", PGC_USERSET, CONN_AUTH_SETTINGS,
gettext_noop("Time between issuing TCP keepalives."),
gettext_noop("A value of 0 uses the system default."),
GUC_UNIT_S
@ -3404,7 +3388,7 @@ static struct config_int ConfigureNamesInt[] =
},
{
{"tcp_keepalives_interval", PGC_USERSET, CLIENT_CONN_OTHER,
{"tcp_keepalives_interval", PGC_USERSET, CONN_AUTH_SETTINGS,
gettext_noop("Time between TCP keepalive retransmits."),
gettext_noop("A value of 0 uses the system default."),
GUC_UNIT_S
@ -3426,7 +3410,7 @@ static struct config_int ConfigureNamesInt[] =
},
{
{"tcp_keepalives_count", PGC_USERSET, CLIENT_CONN_OTHER,
{"tcp_keepalives_count", PGC_USERSET, CONN_AUTH_SETTINGS,
gettext_noop("Maximum number of TCP keepalive retransmits."),
gettext_noop("This controls the number of consecutive keepalive retransmits that can be "
"lost before a connection is considered dead. A value of 0 uses the "
@ -3506,7 +3490,7 @@ static struct config_int ConfigureNamesInt[] =
},
{
{"track_activity_query_size", PGC_POSTMASTER, RESOURCES_MEM,
{"track_activity_query_size", PGC_POSTMASTER, STATS_COLLECTOR,
gettext_noop("Sets the size reserved for pg_stat_activity.query, in bytes."),
NULL,
GUC_UNIT_BYTE
@ -3528,7 +3512,7 @@ static struct config_int ConfigureNamesInt[] =
},
{
{"tcp_user_timeout", PGC_USERSET, CLIENT_CONN_OTHER,
{"tcp_user_timeout", PGC_USERSET, CONN_AUTH_SETTINGS,
gettext_noop("TCP user timeout."),
gettext_noop("A value of 0 uses the system default."),
GUC_UNIT_MS
@ -3573,7 +3557,7 @@ static struct config_int ConfigureNamesInt[] =
},
{
{"client_connection_check_interval", PGC_USERSET, CLIENT_CONN_OTHER,
{"client_connection_check_interval", PGC_USERSET, CONN_AUTH_SETTINGS,
gettext_noop("Sets the time interval between checks for disconnection while running queries."),
NULL,
GUC_UNIT_MS
@ -4102,7 +4086,7 @@ static struct config_string ConfigureNamesString[] =
/* See main.c about why defaults for LC_foo are not all alike */
{
{"lc_collate", PGC_INTERNAL, CLIENT_CONN_LOCALE,
{"lc_collate", PGC_INTERNAL, PRESET_OPTIONS,
gettext_noop("Shows the collation order locale."),
NULL,
GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
@ -4113,7 +4097,7 @@ static struct config_string ConfigureNamesString[] =
},
{
{"lc_ctype", PGC_INTERNAL, CLIENT_CONN_LOCALE,
{"lc_ctype", PGC_INTERNAL, PRESET_OPTIONS,
gettext_noop("Shows the character classification and case conversion locale."),
NULL,
GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
@ -4209,8 +4193,8 @@ static struct config_string ConfigureNamesString[] =
{
/* Can't be set in postgresql.conf */
{"server_encoding", PGC_INTERNAL, CLIENT_CONN_LOCALE,
gettext_noop("Sets the server (database) character set encoding."),
{"server_encoding", PGC_INTERNAL, PRESET_OPTIONS,
gettext_noop("Shows the server (database) character set encoding."),
NULL,
GUC_IS_NAME | GUC_REPORT | GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
},
@ -4429,7 +4413,7 @@ static struct config_string ConfigureNamesString[] =
{
{"ssl_library", PGC_INTERNAL, PRESET_OPTIONS,
gettext_noop("Name of the SSL library."),
gettext_noop("Shows the name of the SSL library."),
NULL,
GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
},

View File

@ -85,6 +85,10 @@
#tcp_user_timeout = 0 # TCP_USER_TIMEOUT, in milliseconds;
# 0 selects the system default
#client_connection_check_interval = 0 # time between checks for client
# disconnection while running queries;
# 0 for never
# - Authentication -
#authentication_timeout = 1min # 1s-600s
@ -178,17 +182,17 @@
# - Asynchronous Behavior -
#backend_flush_after = 0 # measured in pages, 0 disables
#effective_io_concurrency = 1 # 1-1000; 0 disables prefetching
#maintenance_io_concurrency = 10 # 1-1000; 0 disables prefetching
#max_worker_processes = 8 # (change requires restart)
#max_parallel_maintenance_workers = 2 # taken from max_parallel_workers
#max_parallel_workers_per_gather = 2 # taken from max_parallel_workers
#parallel_leader_participation = on
#max_parallel_maintenance_workers = 2 # taken from max_parallel_workers
#max_parallel_workers = 8 # maximum number of max_worker_processes that
# can be used in parallel operations
#parallel_leader_participation = on
#old_snapshot_threshold = -1 # 1min-60d; -1 disables; 0 is immediate
# (change requires restart)
#backend_flush_after = 0 # measured in pages, 0 disables
#------------------------------------------------------------------------------
@ -212,9 +216,9 @@
# fsync_writethrough
# open_sync
#full_page_writes = on # recover from partial page writes
#wal_compression = off # enable compression of full-page writes
#wal_log_hints = off # also do full page writes of non-critical updates
# (change requires restart)
#wal_compression = off # enable compression of full-page writes
#wal_init_zero = on # zero-fill new WAL files
#wal_recycle = on # recycle WAL files
#wal_buffers = -1 # min 32kB, -1 sets based on shared_buffers
@ -229,17 +233,11 @@
# - Checkpoints -
#checkpoint_timeout = 5min # range 30s-1d
#max_wal_size = 1GB
#min_wal_size = 80MB
#checkpoint_completion_target = 0.9 # checkpoint target duration, 0.0 - 1.0
#checkpoint_flush_after = 0 # measured in pages, 0 disables
#checkpoint_warning = 30s # 0 disables
# - Prefetching during recovery -
#wal_decode_buffer_size = 512kB # lookahead window used for prefetching
#recovery_prefetch = off # prefetch pages referenced in the WAL?
#recovery_prefetch_fpw = off # even pages logged with full page?
#max_wal_size = 1GB
#min_wal_size = 80MB
# - Archiving -
@ -252,6 +250,12 @@
#archive_timeout = 0 # force a logfile segment switch after this
# number of seconds; 0 disables
# - Recovery -
#recovery_prefetch = off # prefetch pages referenced in the WAL?
#recovery_prefetch_fpw = off # even pages logged with full page?
#wal_decode_buffer_size = 512kB # lookahead window used for prefetching
# - Archive Recovery -
# These are only used in recovery mode.
@ -298,12 +302,11 @@
#max_wal_senders = 10 # max number of walsender processes
# (change requires restart)
#max_replication_slots = 10 # max number of replication slots
# (change requires restart)
#wal_keep_size = 0 # in megabytes; 0 disables
#max_slot_wal_keep_size = -1 # in megabytes; -1 disables
#wal_sender_timeout = 60s # in milliseconds; 0 disables
#max_replication_slots = 10 # max number of replication slots
# (change requires restart)
#track_commit_timestamp = off # collect timestamp of transaction commit
# (change requires restart)
@ -360,25 +363,26 @@
# - Planner Method Configuration -
#enable_async_append = on
#enable_bitmapscan = on
#enable_gathermerge = on
#enable_hashagg = on
#enable_hashjoin = on
#enable_incremental_sort = on
#enable_indexscan = on
#enable_indexonlyscan = on
#enable_material = on
#enable_resultcache = on
#enable_mergejoin = on
#enable_nestloop = on
#enable_parallel_append = on
#enable_seqscan = on
#enable_sort = on
#enable_incremental_sort = on
#enable_resultcache = on
#enable_tidscan = on
#enable_partitionwise_join = off
#enable_partitionwise_aggregate = off
#enable_parallel_hash = on
#enable_partition_pruning = on
#enable_async_append = on
#enable_partitionwise_join = off
#enable_partitionwise_aggregate = off
#enable_seqscan = on
#enable_sort = on
#enable_tidscan = on
# - Planner Cost Constants -
@ -387,8 +391,11 @@
#cpu_tuple_cost = 0.01 # same scale as above
#cpu_index_tuple_cost = 0.005 # same scale as above
#cpu_operator_cost = 0.0025 # same scale as above
#parallel_tuple_cost = 0.1 # same scale as above
#parallel_setup_cost = 1000.0 # same scale as above
#parallel_tuple_cost = 0.1 # same scale as above
#min_parallel_table_scan_size = 8MB
#min_parallel_index_scan_size = 512kB
#effective_cache_size = 4GB
#jit_above_cost = 100000 # perform JIT compilation if available
# and query more expensive than this;
@ -399,10 +406,6 @@
# query is more expensive than this;
# -1 disables
#min_parallel_table_scan_size = 8MB
#min_parallel_index_scan_size = 512kB
#effective_cache_size = 4GB
# - Genetic Query Optimizer -
#geqo = on
@ -419,9 +422,9 @@
#constraint_exclusion = partition # on, off, or partition
#cursor_tuple_fraction = 0.1 # range 0.0-1.0
#from_collapse_limit = 8
#jit = on # allow JIT compilation
#join_collapse_limit = 8 # 1 disables collapsing of explicit
# JOIN clauses
#jit = on # allow JIT compilation
#plan_cache_mode = auto # auto, force_generic_plan or
# force_custom_plan
@ -450,6 +453,11 @@
# can include strftime() escapes
#log_file_mode = 0600 # creation mode for log files,
# begin with 0 to use octal notation
#log_rotation_age = 1d # Automatic rotation of logfiles will
# happen after that time. 0 disables.
#log_rotation_size = 10MB # Automatic rotation of logfiles will
# happen after that much log output.
# 0 disables.
#log_truncate_on_rotation = off # If on, an existing log file with the
# same name as the new log file will be
# truncated rather than appended to.
@ -458,11 +466,6 @@
# or size-driven rotation. Default is
# off, meaning append to existing files
# in all cases.
#log_rotation_age = 1d # Automatic rotation of logfiles will
# happen after that time. 0 disables.
#log_rotation_size = 10MB # Automatic rotation of logfiles will
# happen after that much log output.
# 0 disables.
# These are relevant when logging to syslog:
#syslog_facility = 'LOCAL0'
@ -470,7 +473,7 @@
#syslog_sequence_numbers = on
#syslog_split_messages = on
# This is only relevant when logging to eventlog (win32):
# This is only relevant when logging to eventlog (Windows):
# (change requires restart)
#event_source = 'PostgreSQL'
@ -597,21 +600,21 @@
# - Query and Index Statistics Collector -
#track_activities = on
#track_activity_query_size = 1024 # (change requires restart)
#track_counts = on
#track_io_timing = off
#track_wal_io_timing = off
#track_functions = none # none, pl, all
#track_activity_query_size = 1024 # (change requires restart)
#stats_temp_directory = 'pg_stat_tmp'
# - Monitoring -
#compute_query_id = off
#log_statement_stats = off
#log_parser_stats = off
#log_planner_stats = off
#log_executor_stats = off
#log_statement_stats = off
#------------------------------------------------------------------------------
@ -665,11 +668,11 @@
# error
#search_path = '"$user", public' # schema names
#row_security = on
#default_table_access_method = 'heap'
#default_tablespace = '' # a tablespace name, '' uses the default
#default_toast_compression = 'pglz' # 'pglz' or 'lz4'
#temp_tablespaces = '' # a list of tablespace names, '' uses
# only default tablespace
#default_table_access_method = 'heap'
#default_toast_compression = 'pglz' # 'pglz' or 'lz4'
#check_function_bodies = on
#default_transaction_isolation = 'read committed'
#default_transaction_read_only = off
@ -679,16 +682,15 @@
#lock_timeout = 0 # in milliseconds, 0 is disabled
#idle_in_transaction_session_timeout = 0 # in milliseconds, 0 is disabled
#idle_session_timeout = 0 # in milliseconds, 0 is disabled
#vacuum_freeze_min_age = 50000000
#vacuum_freeze_table_age = 150000000
#vacuum_multixact_freeze_min_age = 5000000
#vacuum_multixact_freeze_table_age = 150000000
#vacuum_freeze_min_age = 50000000
#vacuum_failsafe_age = 1600000000
#vacuum_multixact_freeze_table_age = 150000000
#vacuum_multixact_freeze_min_age = 5000000
#vacuum_multixact_failsafe_age = 1600000000
#bytea_output = 'hex' # hex, escape
#xmlbinary = 'base64'
#xmloption = 'content'
#gin_fuzzy_search_limit = 0
#gin_pending_list_limit = 4MB
# - Locale and Formatting -
@ -720,18 +722,15 @@
# - Shared Library Preloading -
#shared_preload_libraries = '' # (change requires restart)
#local_preload_libraries = ''
#session_preload_libraries = ''
#shared_preload_libraries = '' # (change requires restart)
#jit_provider = 'llvmjit' # JIT library to use
# - Other Defaults -
#dynamic_library_path = '$libdir'
#client_connection_check_interval = 0 # time between checks for client
# disconnection while running queries;
# 0 for never
#gin_fuzzy_search_limit = 0
#------------------------------------------------------------------------------
# LOCK MANAGEMENT
@ -775,10 +774,10 @@
#restart_after_crash = on # reinitialize after backend crash?
#remove_temp_files_after_crash = on # remove temporary files after
# backend crash?
#recovery_init_sync_method = fsync # fsync, syncfs (Linux 5.8+)
#data_sync_retry = off # retry or panic on failure to fsync
# data?
# (change requires restart)
#recovery_init_sync_method = fsync # fsync, syncfs (Linux 5.8+)
#------------------------------------------------------------------------------

View File

@ -48,55 +48,48 @@ typedef struct config_var_value
} config_var_value;
/*
* Groupings to help organize all the run-time options for display
* Groupings to help organize all the run-time options for display.
* Be sure this agrees with the way the options are categorized in config.sgml!
*/
enum config_group
{
UNGROUPED,
UNGROUPED, /* use for options not shown in pg_settings */
FILE_LOCATIONS,
CONN_AUTH,
CONN_AUTH_SETTINGS,
CONN_AUTH_AUTH,
CONN_AUTH_SSL,
RESOURCES,
RESOURCES_MEM,
RESOURCES_DISK,
RESOURCES_KERNEL,
RESOURCES_VACUUM_DELAY,
RESOURCES_BGWRITER,
RESOURCES_ASYNCHRONOUS,
WAL,
WAL_SETTINGS,
WAL_CHECKPOINTS,
WAL_ARCHIVING,
WAL_RECOVERY,
WAL_ARCHIVE_RECOVERY,
WAL_RECOVERY_TARGET,
REPLICATION,
REPLICATION_SENDING,
REPLICATION_PRIMARY,
REPLICATION_STANDBY,
REPLICATION_SUBSCRIBERS,
QUERY_TUNING,
QUERY_TUNING_METHOD,
QUERY_TUNING_COST,
QUERY_TUNING_GEQO,
QUERY_TUNING_OTHER,
LOGGING,
LOGGING_WHERE,
LOGGING_WHEN,
LOGGING_WHAT,
PROCESS_TITLE,
STATS,
STATS_MONITORING,
STATS_COLLECTOR,
AUTOVACUUM,
CLIENT_CONN,
CLIENT_CONN_STATEMENT,
CLIENT_CONN_LOCALE,
CLIENT_CONN_PRELOAD,
CLIENT_CONN_OTHER,
LOCK_MANAGEMENT,
COMPAT_OPTIONS,
COMPAT_OPTIONS_PREVIOUS,
COMPAT_OPTIONS_CLIENT,
ERROR_HANDLING_OPTIONS,