Open search page
Hello, I’m DocuDroid!
Open Ask AI page
Submitting feedback
Thank you for rating our AI Search!
We would be grateful if you could share your thoughts so we can improve our AI Search for you and other readers.
GitHub

ggrebalance

Changes the topology of an existing Greengage DB cluster, including the number of segments and/or the set of hosts on which they are located.

IMPORTANT

In version 1.0, ggrebalance does not support cluster expansion. To increase the number of segments, use the gpexpand utility.

Synopsis

ggrebalance -x <segment_count>
    [-n <parallel_processes>] [-B <batch_size>]
    [{-H <hostname_1>,<hostname_2>,...,<hostname_N> | --target-hosts-file <filename>} |
     {{-A <hostname_1>,<hostname_2>,...,<hostname_N> | --add-hosts-file <filename>}
      {-R <hostname_1>,<hostname_2>,...,<hostname_N> | --remove-hosts-file <filename>}}]
    [{-d "<target_primary_datadir>,<target_mirror_datadir>" | --target-datadirs-file <filename>}]
    [-m grouped|spread] [--inplace-swap-roles] [-p]
    [--skip-resource-estimation] [--skip-rebalance]
    [{-T hh:mm:ss | -E 'YYYY-MM-DD hh:mm:ss'}]
    [{-D | -S | --no-progress}]
    [--hba-hostnames] [--replay-lag <replay_lag>] [-a]
    [--non-interactive-mode] [-y] [-l <log_dir>] [-q] [-v]
    [--seed <planner_seed>]

ggrebalance
    [-n <parallel_processes>] [-B <batch_size>]
    [{-T hh:mm:ss | -E 'YYYY-MM-DD hh:mm:ss'}]
    [{-D | -S | --no-progress}]
    [--hba-hostnames] [--replay-lag <replay_lag>] [-a]
    [--non-interactive-mode] [-y] [-l <log_dir>] [-q] [-v]

ggrebalance -r
    [-n <parallel_processes>] [-B <batch_size>]
    [{-T hh:mm:ss | -E 'YYYY-MM-DD hh:mm:ss'}]
    [{-D | -S | --no-progress}]
    [--hba-hostnames] [--replay-lag <replay_lag>] [-a]
    [--non-interactive-mode] [-y] [-l <log_dir>] [-q] [-v]

ggrebalance -c

ggrebalance -? | -h | --help | --usage

ggrebalance --version

Prerequisites

  • If new segment hosts are being added, they must have been installed and configured in the same way as the existing segment hosts. This includes:

    • Configuring the hardware and OS.

    • Installing the Greengage DB software.

    • Creating the gpadmin user account.

    • Exchanging SSH keys.

  • All segment hosts must have enough disk space available:

    • After a cluster shrink, data from the removed hosts is distributed among remaining segments, so their size grows proportionally.

    • During rebalance, a segment host may need to temporarily store more segments than in the final balanced state.

  • When redistributing data, Greengage DB must be running in production mode. Do not start Greengage DB in restricted (gpstart -R) or coordinator-only mode (gpstart -m).

NOTE

These utilities cannot be run while ggrebalance is running: gpbackup, gpcheckcat, gpconfig, gpexpand, gprestore.

IMPORTANT

When expanding or shrinking a Greengage DB cluster, you must deactivate Greengage DB interconnect proxies (ic-proxy) before making changes to the cluster topology. After completion, update the gp_interconnect_proxy_addresses parameter to the new topology and re-enable interconnect proxies. For information about Greengage DB interconnect proxies, see Configure proxies for interconnect.

Description

ggrebalance modifies the physical topology of a Greengage DB cluster by redistributing data between segments and adjusting their layout across hosts.

The utility supports the following types of topology changes:

  • adding and removing segment hosts (cluster expansion and shrink);

    IMPORTANT

    In version 1.0, ggrebalance does not support increasing the number of segments (cluster expansion). Use gpexpand for this operation.

  • changing the total number of segments in the cluster;

  • redistributing segments across hosts;

  • changing the mirror placement policy.

Depending on the provided options, ggrebalance can be used in the following scenarios:

  • remove or add hosts while preserving the total number of segments;

  • remove or add hosts and decrease the number of segments;

  • move segments to a different set of hosts;

  • move segments to a different set of hosts and decrease the number of segments;

  • change the mirror placement policy for existing segments;

  • redistribute segments across the same hosts to achieve a balanced configuration.

NOTE

ggrebalance requires segment mirroring to be enabled. If mirroring is not configured, the utility exits with an error without modifying the cluster.

Balanced state

A target cluster configuration is considered balanced if it satisfies the following conditions:

  • each segment host contains the same number of primary segments;

  • mirror segments are distributed according to the selected mirror policy (grouped or spread);

  • no primary segment and its mirror are located on the same host.

If such a topology cannot be built based on the supplied arguments, ggrebalance reports an error and does not perform any changes.

Execution workflow

When executed, ggrebalance performs a sequence of phases to safely transition the cluster to the target topology:

  1. Plan generation and validation

    First, the utility constructs a rebalance plan — an ordered sequence of steps required to reach the target configuration. Plan execution must end with a balanced state; it must also be technically feasible. If any of these conditions are not satisfied, the utility reports an error and stops before making any changes. You can inspect the generated plan without proceeding to rebalance actions using the --show-plan option.

  2. State initialization

    A schema named ggrebalance is created in the postgres database. This schema stores metadata about the rebalance operation and tracks execution progress.

  3. Segment count adjustment (optional)

    If the target number of segments differs from the current configuration, ggrebalance adjusts it. In this phase, the utility executes ALTER TABLE …​ REBALANCE operations for regular tables, materialized views, and writable external tables to redistribute data across the new segment set.

  4. Segment relocation

    Segment instances are moved across hosts according to the plan. This phase may include switchovers — role swaps between primary segments and their mirrors. A switchover is performed when copying data of a primary segment because primary segments cannot be moved in a working cluster. To move the data, the primary segment swaps roles with its mirror. Each switchover requires a user confirmation unless the --approve-swap-roles option is specified.

After successful completion, the ggrebalance schema remains in the cluster and contains the completed operation metadata. Before starting a new rebalance operation, remove it using ggrebalance -c.

If execution fails, the information about rebalance plan and operation progress remains in the ggrebalance schema. You can continue this operation later or roll back to the original state.

A rebalance operation can be split into multiple sessions using the -T (maximum duration) or -E (end time) options. In this mode, progress is persisted in the ggrebalance schema. To continue an interrupted operation, run ggrebalance without topology-changing options, or specify a new time limit with -T or -E.

If a rebalance operation is interrupted or encounters an error, you can attempt to roll it back using the -r option.

Options

-a | --analyze

Runs ANALYZE on all user tables after a successful rebalance to update optimizer statistics. If the number of segments is not changed as a result of the operation, this option is ignored.

--add-hosts-file <filename>

Specifies a file containing a list of hosts to add to the cluster during expansion, one host per line. To specify new hosts in a command-line argument, use --add-hosts.

-A | --add-hosts <hostname_1>,<hostname_2>,…​,<hostname_N>

Specifies a comma-separated list of hosts to add to the cluster during expansion. To specify new hosts in a file, use --add-hosts-file.

-B | --batch-size <batch_size>

Sets the maximum number of segment instances per host to process concurrently during segment relocation. This parameter limits the number of segment operations (copy, start, stop) running simultaneously on a single host. The default value is 4. Valid values are 1 — 128.

-c | --clean

Removes the existing ggrebalance schema and files created by a previous rebalance operation, except for log files. Use this option after a successful rebalance to allow starting a new operation.

-d | --target-datadirs "<target_primary_datadir>,<target_mirror_datadir>"

Specifies the location of data directories for segment instances on hosts added during expansion. The value must be a double-quoted string containing two directory paths separated by a comma: first — for primary segments, second — for mirrors. ggrebalance creates these directories on all new hosts if they do not exist.

To specify data directories for new hosts in a file, use --target-datadirs-file.

-D | --detailed-progress

Displays detailed information about the operation progress in the ggrebalance.rebalance_progress view.

-E | --end 'YYYY-MM-DD hh:mm:ss'

Specifies the end UTC timestamp for the current rebalance session. The operation stops gracefully when the specified time is reached, preserving progress.

--hba-hostnames

(Optional) Whether to use IP addresses or host names in the pg_hba.conf file when updating this file with addresses that can connect to Greengage DB. By default, the utility uses IP addresses when updating this file. For consistency, use the same value that was specified for HBA_HOSTNAMES when the Greengage DB system was initialized.

-H | --target-hosts <hostname_1>,<hostname_2>,…​,<hostname_N>

The complete list of hosts of the target cluster after the operation, separated by commas. The list must include all target hosts and only those hosts, regardless of whether they belong to the cluster before the operation.

To specify the target set of hosts in a file, use --target-hosts-file.

--inplace-swap-roles

Allows temporary placement of primary segments on the same host as their mirrors during execution. By default, ggrebalance avoids co-locating primary and mirror segments and may require additional intermediate hosts to perform relocation safely. This option is needed when the number of hosts is not enough to perform all relocations through intermediate hosts. However, fault tolerance might be temporarily reduced during segment movement.

-l | --log-dir <log_dir>

The directory to which log files are written. The default location is ~/gpAdminLogs.

-m | --mirror-mode grouped|spread

Sets the mirroring policy to use in the cluster after rebalance: grouped (default) or spread.

-n | --parallel <parallel_processes>

The parallelism level of the operation:

  • during segment relocation, defines the number of hosts processed concurrently;

  • during segment count changes (table redistribution), defines the maximum number of tables processed in parallel.

The default value is 4. Valid values are 1 — 96.

--no-progress

Disables progress reporting in the ggrebalance.rebalance_progress view.

--non-interactive-mode

Runs in non-interactive mode. The utility does not prompt for user input and automatically applies default options when user interaction is required.

-p | --show-plan

Displays the generated rebalance plan without executing it.

-q | --quiet

Runs in quiet mode. Command output is not displayed on the screen, but is still written to the log file.

-r | --rollback

Rolls back the interrupted operation if possible.

--remove-hosts-file <filename>

Specifies a file containing a list of hosts to remove from the cluster during shrink, one host per line. To specify hosts to remove in a command-line argument, use --remove-hosts.

--replay-lag <replay_lag>

Replay lag (in GBs) allowed on mirror when rebalancing the segments. If the current replay lag exceeds this threshold, then rebalance will be aborted.

-R | --remove-hosts <hostname_1>,<hostname_2>,…​,<hostname_N>

Specifies a comma-separated list of hosts to remove from the cluster during shrink. To specify hosts to remove in a file, use --remove-hosts-file.

--seed <planner_seed>

Specifies a seed value to guarantee stable plan generation across different ggrebalance runs. Valid values are non-negative integers.

--skip-rebalance

Skips the final balancing phase even if this leaves the resulting cluster unbalanced. Use this option to change the number of segments without enforcing uniform segment distribution.

--skip-resource-estimation

Skips validation of available disk space and other resource checks before execution. Use with caution, as insufficient resources may cause the operation to fail.

-S | --simple-progress

Displays simplified progress information in the ggrebalance.rebalance_progress view.

--target-datadirs-file <filename>

Specifies a file containing data directory paths for segment instances on hosts added during expansion. The file must contain two lines with directory paths: first — for primary segments, second — for mirrors. ggrebalance creates these directories on all new hosts if they do not exist.

To specify data directories for new hosts in command-line arguments, use --target-datadirs.

--target-hosts-file <filename>

Specifies a file containing the complete list of target cluster hosts after the operation, one per line. The file must include all target hosts and only those hosts, regardless of whether they belong to the cluster before the operation. To specify target hosts in a command-line argument, use --target-hosts.

-T | --duration hh:mm:ss

Specifies the maximum duration of the current rebalance session. The operation stops gracefully when the time limit is reached and can be resumed later.

-v | --verbose

Sets logging output to verbose.

-x | --target-segment-count <segment_count>

Specifies the target number of primary segments in the cluster. This number may be less than or greater than the current segment number. ggrebalance will perform a shrink or expansion in these respective cases. Valid values are 1 — 4096.

This option is required to start a new rebalance operation. If omitted, ggrebalance attempts to resume a previously interrupted operation.

-y | --approve-swap-roles

Automatically approves segment switchovers (primary-mirror role swaps) in the interactive mode without asking for user confirmation.

--version

Prints the ggrebalance version and exits.

-? | -h | --help | --usage

Displays help information and exits.

Examples

Remove a host from the cluster and reduce the number of segments:

$ ggrebalance --target-segment-count 6 --remove-hosts sdw4

Show the rebalance plan without making any changes to the cluster:

$ ggrebalance --show-plan \
    --mirror-mode grouped \
    --target-segment-count 6 \
    --remove-hosts sdw4

Redistribute segments across the same hosts to improve balance:

$ ggrebalance --target-segment-count 8

Run a rebalance session with a time limit:

$ ggrebalance --target-segment-count 6 --remove-hosts sdw4 -T 00:30:00

Resume a previously interrupted operation:

$ ggrebalance

Roll back an interrupted operation:

$ ggrebalance -r

Clean up the ggrebalance schema after completing the operation:

$ ggrebalance -c
Previous
Partitioning: classic syntax
Next
rebalance_status