gpinitstandby

Adds and/or initializes a standby master host for a Greenplum Database system.

Synopsis

gpinitstandby { -s <standby_hostname> [-P port] | -r | -n } [-a] [-q] 
    [-D] [-S <standby_data_directory>] [-l <logfile_directory>] 
    [--hba-hostnames <boolean>] 
gpinitstandby -v 
gpinitstandby -?

Description

The gpinitstandby utility adds a backup, standby master instance to your Greenplum Database system. If your system has an existing standby master instance configured, use the -r option to remove it before adding the new standby master instance.

Before running this utility, make sure that the Greenplum Database software is installed on the standby master host and that you have exchanged SSH keys between the hosts. It is recommended that the master port is set to the same port number on the master host and the standby master host.

This utility should be run on the currently active primary master host. See the Greenplum Database Installation Guide for instructions.

The utility performs the following steps:

• Updates the Greenplum Database system catalog to remove the existing standby master information (if the -r option is supplied)
• Updates the Greenplum Database system catalog to add the new standby master instance information
• Edits the pg_hba.conf file of the Greenplum Database master to allow access from the newly added standby master
• Sets up the standby master instance on the alternate master host
• Starts the synchronization process

A backup, standby master instance serves as a ‘warm standby’ in the event of the primary master becoming non-operational. The standby master is kept up to date by transaction log replication processes (the walsender and walreceiver), which run on the primary master and standby master hosts and keep the data between the primary and standby master instances synchronized. If the primary master fails, the log replication process is shut down, and the standby master can be activated in its place by using the gpactivatestandby utility. Upon activation of the standby master, the replicated logs are used to reconstruct the state of the master instance at the time of the last successfully committed transaction.

The activated standby master effectively becomes the Greenplum Database master, accepting client connections on the master port and performing normal master operations such as SQL command processing and resource management.

Important

If the gpinitstandby utility previously failed to initialize the standby master, you must delete the files in the standby master data directory before running gpinitstandby again. The standby master data directory is not cleaned up after an initialization failure because it contains log files that can help in determining the reason for the failure.

If an initialization failure occurs, a summary report file is generated in the standby host directory /tmp. The report file lists the directories on the standby host that require clean up.

Options

-a (do not prompt)

Do not prompt the user for confirmation.

-D (debug)

Sets logging level to debug.

--hba-hostnames boolean

Optional. Controls whether this utility uses IP addresses or host names in the pg_hba.conf file when updating this file with addresses that can connect to Greenplum Database. When set to 0 — the default value — this utility uses IP addresses when updating this file. When set to 1, this utility uses host names when updating this file. For consistency, use the same value that was specified for HBA_HOSTNAMES when the Greenplum Database system was initialized. For information about how Greenplum Database resolves host names in the pg_hba.conf file, see Configuring Client Authentication.

-l logfile_directory

The directory to write the log file. Defaults to ~/gpAdminLogs.

-n (restart standby master)

Specify this option to start a Greenplum Database standby master that has been configured but has stopped for some reason.

-P port

This option specifies the port that is used by the Greenplum Database standby master. The default is the same port used by the active Greenplum Database master.

If the Greenplum Database standby master is on the same host as the active master, the ports must be different. If the ports are the same for the active and standby master and the host is the same, the utility returns an error.

-q (no screen output)

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

-r (remove standby master)

Removes the currently configured standby master instance from your Greenplum Database system.

-s standby_hostname

The host name of the standby master host.

-S standby_data_directory

The data directory to use for a new standby master. The default is the same directory used by the active master.

If the standby master is on the same host as the active master, a different directory must be specified using this option.

-v (show utility version)

Displays the version, status, last updated date, and checksum of this utility.

-? (help)

Displays the online help.

Examples

Add a standby master instance to your Greenplum Database system and start the synchronization process:

gpinitstandby -s host09

Start an existing standby master instance and synchronize the data with the current primary master instance:

gpinitstandby -n

Note

Do not specify the -n and -s options in the same command.

Add a standby master instance to your Greenplum Database system specifying a different port:

gpinitstandby -s myhost -P 2222

If you specify the same host name as the active Greenplum Database master, you must also specify a different port number with the -P option and a standby data directory with the -S option.

Remove the existing standby master from your Greenplum system configuration:

gpinitstandby -r

See Also

gpinitsystem, gpaddmirrors, gpactivatestandby