PostgreSQL uses a centralized configuration system called GUC (Grand Unified Configuration) to control its behavior. Most users interact with these settings using commands like `SHOW`, `SET`, or by querying the `pg_settings` view. This gives the impression that all configuration parameters are accessible and behave uniformly. However, that is not always the case. Some parameters are intentionally hidden from standard views and commands. Others are restricted in how and where they can be modified. These differences are controlled by internal flags defined in the PostgreSQL source code. Understanding these flags helps explain why certain parameters behave differently from regular configuration settings.
Where Configuration Parameters Are Defined
If you are using the latest version of the PostgreSQL source code, then the configuration parameters are primarily defined in:
- guc_parameters.dat - declarative definitions of GUC variables
- guc.c and guc.h - core logic and flag definitions
If you are using an earlier PostgreSQL version, you can see the metadata of each postgres configuration in guc_tables.c file
The guc_parameters.dat file contains structured entries like:
{ name => 'default_with_oids', type => 'bool', context => 'PGC_USERSET', group => 'COMPAT_OPTIONS_PREVIOUS',
short_desc => 'WITH OIDS is no longer supported; this can only be false.',
flags => 'GUC_NO_SHOW_ALL | GUC_NOT_IN_SAMPLE',
variable => 'default_with_oids',
boot_val => 'false',
check_hook => 'check_default_with_oids',
},Each parameter includes metadata such as type, context, default value, and most importantly, flags that control its behavior.
What is GUC_NO_SHOW_ALL?
The GUC_NO_SHOW_ALL flag is defined in guc.h as:
#define GUC_NO_SHOW_ALL 0x000004 /* exclude from SHOW ALL */
This flag ensures that a parameter:
- Does not appear in SHOW ALL
- Does not appear in pg_settings
However, it can still be accessed directly using:
SHOW parameter_name;
Real Examples and Observations
Consider the following parameters:
- Ssl_renegotiation_limit
- Session_authorization
- Seed
- Role
- Is_superuser
- default_with_oids
Direct Access Using SHOW
show ssl_renegotiation_limit;
Result :
ssl_renegotiation_limit
-------------------------
0
(1 row)
show session_authorization;
Result :
session_authorization
-----------------------
postgres
(1 row)
show seed;
Result :
seed
-------------
unavailable
(1 row)
show role;
Result :
role
------
none
(1 row)
show is_superuser;
Result :
is_superuser
--------------
on
(1 row)
show default_with_oids;
Result :
default_with_oids
-------------------
off
(1 row)
Querying via pg_settings
select * from pg_settings
where name in (
'ssl_renegotiation_limit',
'session_authorization',
'seed',
'role',
'is_superuser',
'default_with_oids'
);
Result:
(0 rows)
Even though these parameters exist and can be accessed via SHOW, they are completely hidden from pg_settings. This is because PostgreSQL internally filters out parameters with the GUC_NO_SHOW_ALL flag when building the pg_settings view.
Why Are These Parameters Hidden?
There are several reasons why PostgreSQL hides certain parameters:
1. Internal or Security-Sensitive Parameters
Examples:
- is_superuser
- session_authorization
- role
These parameters directly relate to user identity and permissions. Hiding them prevents unintended exposure or misuse.
2. Runtime or Computed Values
Example:
This parameter is not stored like a regular configuration. Instead, it uses hooks such as:
- check_hook
- assign_hook
- Show_hook
In the guc_parameters.dat file you can see more examples
The output:
SHOW seed;
Result :
seed
-------------
unavailable
(1 row)
indicates that the value is dynamically computed or not persistently stored.
3. Deprecated or Compatibility Parameters
Examples:
- Default_with_oids
- ssl_renegotiation_limit
These parameters exist only for backward compatibility. They are retained to avoid breaking older configurations but are no longer functionally relevant.
4. Restricted Configuration Behavior
Many of these parameters include additional flags such as:
- GUC_NO_RESET
- GUC_NO_RESET_ALL
- GUC_DISALLOW_IN_FILE
These flags prevent:
- Resetting the parameter
- Including it in configuration files
Complete Overview of GUC Flags
The following flags are defined in guc.h:
define GUC_LIST_INPUT 0x000001
#define GUC_LIST_QUOTE 0x000002
#define GUC_NO_SHOW_ALL 0x000004
#define GUC_NO_RESET 0x000008
#define GUC_NO_RESET_ALL 0x000010
#define GUC_EXPLAIN 0x000020
#define GUC_REPORT 0x000040
#define GUC_NOT_IN_SAMPLE 0x000080
#define GUC_DISALLOW_IN_FILE 0x000100
#define GUC_CUSTOM_PLACEHOLDER 0x000200
#define GUC_SUPERUSER_ONLY 0x000400
#define GUC_IS_NAME 0x000800
#define GUC_NOT_WHILE_SEC_REST 0x001000
#define GUC_DISALLOW_IN_AUTO_FILE 0x002000
#define GUC_RUNTIME_COMPUTED 0x004000
#define GUC_ALLOW_IN_PARALLEL 0x008000
Explanation of Each Flag
- GUC_LIST_INPUT: Accepts list-style input values.
- GUC_LIST_QUOTE: Ensures list elements are quoted.
- GUC_NO_SHOW_ALL: Hides the parameter from SHOW ALL and pg_settings.
- GUC_NO_RESET: Prevents resetting the parameter.
- GUC_NO_RESET_ALL: Excludes the parameter from RESET ALL.
- GUC_EXPLAIN: Includes the parameter in EXPLAIN output.
- GUC_REPORT: Automatically reports changes to the client.
- GUC_NOT_IN_SAMPLE: Excludes it from postgresql.conf.sample.
- GUC_DISALLOW_IN_FILE: Cannot be set in postgresql.conf.
- GUC_CUSTOM_PLACEHOLDER: Placeholder for custom variables.
- GUC_SUPERUSER_ONLY: Visible only to superusers.
- GUC_IS_NAME: Restricts string length to PostgreSQL identifier limits.
- GUC_NOT_WHILE_SEC_REST: Cannot be set during security-restricted operations.
- GUC_DISALLOW_IN_AUTO_FILE: Cannot be set via auto configuration files.
- GUC_RUNTIME_COMPUTED: Value is computed at runtime.
- GUC_ALLOW_IN_PARALLEL: Can be used in parallel query execution.
Internal Behavior: Why pg_settings Skips These Parameters
Inside PostgreSQL source code file named guc_funcs.c, when building pg_settings, there is a filtering mechanism:
if (conf->flags & GUC_NO_SHOW_ALL)
continue;
This ensures that any parameter marked with GUC_NO_SHOW_ALL is completely excluded from the system view.
- Not all PostgreSQL configuration parameters are meant for user interaction.
- Some parameters are hidden intentionally using flags like GUC_NO_SHOW_ALL.
- Direct access using SHOW may still work even if the parameter is hidden from views.
- Flags in guc.h define the lifecycle, visibility, and restrictions of each parameter.
- Understanding these flags is essential when modifying PostgreSQL source code or creating custom GUC parameters.
The GUC system in PostgreSQL is more than just configuration. It is a controlled interface with layers of visibility and restrictions. Flags such as GUC_NO_SHOW_ALL allow PostgreSQL to maintain internal parameters, deprecated features, and sensitive settings without exposing them to standard tools.
For developers working with PostgreSQL internals, especially those customizing or extending the database, understanding these flags and their effects is critical. It provides insight into how PostgreSQL balances flexibility with safety and internal consistency.