Release History
Requirements

Introduction

Quick onboard

Deployment

Data Modeling

Connecting

Write data

Migration

Query

Operations and Maintenance

Performance Tuning

Troubleshooting

Reference Guide

SQL Reference

FAQ

gpconfig

1 Description

The gpconfig utility allows users to set, reset, or view configuration parameters in the postgresql.conf files across all instances in a YMatrix cluster (Master, Segments, and Mirrors). When setting a parameter, you can optionally specify a different value for the Master. For example, the max_connections parameter requires a different setting on the Master than on Segments. Use the --masteronly option to set or reset global parameters or parameters that apply only to the Master.

Not all parameters can be configured using gpconfig. For instance, you cannot use it to set the port parameter, which varies per Segment instance. Use the -l option to display a complete list of supported configuration parameters.

When a parameter is set using gpconfig, the value is added to the bottom of the postgresql.conf file. When a parameter is removed with gpconfig, it is commented out in the postgresql.conf file, restoring the default value. If you remove a parameter and later re-add it with a new value, two entries will exist: one commented out and one active at the bottom of the postgresql.conf file.

After setting a parameter, you may need to restart the cluster or reload the postgresql.conf file for changes to take effect. Whether a restart is required depends on the specific parameter.

To display the current value of a parameter in the system, use the -s option.

If you receive the following error when modifying a parameter with gpconfig:

GUC Validation Failed: mars3.degrade_min_run_size cannot be changed under normal conditions. Please refer to gpconfig documentation.

this indicates the parameter is protected. You must add the --skipvalidation option to make the change effective. For example:

gpconfig -c optimizer_force_multistage_agg -v false --skipvalidation

gpconfig uses the following environment variables to connect to the MXMaster instance and retrieve system configuration:

  • PGHOST
  • PGPORT
  • PGUSER
  • PGPASSWORD
  • PGDATABASE

2. Options

Option Description
-c param_name or --change param_name Changes a configuration parameter by adding a new entry at the end of the postgresql.conf file
-v value or --value value Specifies the value for the parameter set by the -c option. By default, this value applies to all Segments, Mirrors, Master, and Standby.
Parameter values that are not single characters or digits must be enclosed in single quotes (''). For strings containing spaces or special characters, use two single quotes or a backslash to escape ('' or \')
-m master_value or --mastervalue master_value Sets a separate value for the Master and Standby when configuring a parameter, different from the value used on Segments
--masteronly When specified, gpconfig modifies only the Master's postgresql.conf file
-r param_name or --remove param_name Removes a configuration parameter by commenting it out in the postgresql.conf file
-l or --list Lists all configuration parameters that can be modified using gpconfig
-s param_name or --show param_name Displays the current value of the specified configuration parameter across all instances (Master and Segments) in the YMatrix cluster. The displayed value reflects the currently active setting; if the cluster has not been restarted after a change, the old value is shown
--file Displays the value of the parameter as defined in the postgresql.conf file on all instances (Master and Segments). These values may not yet be active if the cluster has not been restarted.
Cannot be used with the --file-compare option
--file-compare Compares the currently active value of the parameter in the YMatrix cluster (Master and Segments) with the value in the postgresql.conf file.
If values differ, displays values from all hosts. If they match, shows a summary report.
Cannot be used with the --file option
--skipvalidation Skips validation checks when setting a parameter.
Use this option with caution
--verbose Displays additional log information during command execution
--debug Sets the log output level to debug
? or -h or --help Displays help information

3. Examples

View the shared_buffers configuration:

gpconfig -s shared_buffers

Set gp_resource_manager to queue:

gpconfig -c gp_resource_manager -v queue

Set max_connections to 180 on Segments and 60 on the Master:

gpconfig -c max_connections -v 180 -m 60
← Previous
mxstop
Next →
pgvector