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

gpaddmirrors

Adds mirror segments to a Greengage DB system that was initially configured without mirroring.

Synopsis

gpaddmirrors [ -p <port_offset> ]
             [ -m <datadir_config_file> [ -a ] ]
             [ -s ]
             [ -d <master_data_directory> ]
             [ -b <segment_batch_size> ]
             [ -B <batch_size> ]
             [ -l <logfile_directory> ]
             [ -v ]
             [ --hba-hostnames ]

gpaddmirrors -i <mirror_config_file>
             [ -a ]
             [ -d <master_data_directory> ]
             [ -b <segment_batch_size> ]
             [ -B <batch_size> ]
             [ -l <logfile_directory> ]
             [ -v ]

gpaddmirrors -o <output_sample_mirror_config>
             [ -s ]
             [ -m <datadir_config_file> ]

gpaddmirrors -?

gpaddmirrors --version

Description

The gpaddmirrors utility configures mirror segment instances for an existing Greengage DB system that was initially configured with primary segment instances only. The utility will create the mirror instances and begin the online replication process between the primary and mirror segment instances. Once all mirrors are synchronized with their primaries, your Greengage DB system is fully data redundant.

IMPORTANT

During the online replication process, Greengage DB should be in a quiescent state — workloads and other queries should not be running.

By default, the utility will prompt you for the file system location(s) where it will create the mirror segment data directories. If you do not want to be prompted, you can pass in a file containing the file system locations using the -m option.

The mirror locations and ports must be different from your primary segment data locations and ports.

The utility creates a unique data directory for each mirror segment instance in the specified location using the predefined naming convention. There must be the same number of file system locations declared for mirror segment instances as for primary segment instances. You can specify the same directory name multiple times if you want your mirror data directories created in the same location, or you can enter a different data location for each mirror. Enter the absolute path, for example:

Enter mirror segment data directory location 1 of 2 > /data1/mirror
Enter mirror segment data directory location 2 of 2 > /data1/mirror

or:

Enter mirror segment data directory location 1 of 2 > /data1/mirror1
Enter mirror segment data directory location 2 of 2 > /data1/mirror2

Alternatively, you can run the gpaddmirrors utility and supply a detailed configuration file using the -i option. This is useful if you want your mirror segments on a completely different set of hosts than your primary segments. The format of the mirror configuration file is:

<contentID>|<address>|<port>|<data_dir>

where contentID is the segment instance content ID, address is the host name or IP address of the segment host, port is the communication port, and data_dir is the segment instance data directory. For example:

0|sdw5|11000|/data1/mirror/gpseg0
1|sdw5|11001|/data1/mirror/gpseg1

The gp_segment_configuration system catalog table can help you determine your current primary segment configuration so that you can plan your mirror segment configuration. For example, run the following query:

SELECT dbid, content, address as host_address, port, datadir
FROM gp_segment_configuration
ORDER BY dbid;

If you are creating mirrors on alternate mirror hosts, the new mirror segment hosts must be pre-installed with the Greengage DB software and configured exactly the same as the existing primary segment hosts.

You must make sure that the user who runs gpaddmirrors (the gpadmin user) has permissions to write to the data directory locations specified. You may want to create these directories on the segment hosts and chown them to the appropriate user before running gpaddmirrors.

NOTE

gpaddmirrors uses secure shell (SSH) connections between systems to perform its tasks. In large Greengage DB deployments, cloud deployments, or deployments with a large number of segments per host, this utility may exceed the host’s maximum threshold for unauthenticated connections. Consider updating the SSH MaxStartups configuration parameter to increase this threshold. For more information about SSH configuration options, refer to the SSH documentation for your Linux distribution.

Options

-a

Run in non-interactive mode — do not prompt for information. Must supply a configuration file with either -m or -i if this option is used.

-b <segment_batch_size>

The maximum number of segments per host to operate on in parallel. Valid values are 1 to 128. If not specified, the utility will start processing up to 64 segments in parallel on each host.

-B <batch_size>

The number of hosts to work on in parallel. If not specified, the utility will start working on up to 16 hosts in parallel. Valid values are 1 to 64.

-d <master_data_directory>

The master data directory. If not specified, the value set for MASTER_DATA_DIRECTORY will be used.

--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.

-i <mirror_config_file>

A configuration file containing one line for each mirror segment you want to create. You must have one mirror segment instance listed for each primary segment in the system. The format of this file is as follows (as per attributes in the gp_segment_configuration catalog table):

<contentID>|<address>|<port>|<data_dir>

where contentID is the segment instance content ID, address is the host name or IP address of the segment host, port is the communication port, and data_dir is the segment instance data directory. For information about using a hostname or IP address, see Specify hosts using hostnames or IP addresses. Also, see Use host systems with multiple NICs.

-l <logfile_directory>

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

-m <datadir_config_file>

A configuration file containing a list of file system locations where the mirror data directories will be created. If not supplied, the utility prompts you for locations. Each line in the file specifies a mirror data directory location. For example:

/data1/mirror1
/data1/mirror2
/data1/mirror3
/data1/mirror4
-o <output_sample_mirror_config>

If you are not sure how to lay out the mirror configuration file used by the -i option, you can run gpaddmirrors with this option to generate a sample mirror configuration file based on your primary segment configuration. The utility will prompt you for your mirror segment data directory locations (unless you provide these in a file using -m). You can then edit this file to change the host names to alternate mirror hosts if necessary.

-p <port_offset>

(Optional) This number is used to calculate the database ports used for mirror segments. The default offset is 1000. Mirror port assignments are calculated as follows:

primary_port + offset = mirror_database_port

For example, if primary segments run on ports from 10000 to 10003, and -p value is 5000, mirror segments will occupy ports from 15000 to 15003.

-s

Spreads the mirror segments across the available hosts. The default is to group a set of mirror segments together on an alternate host from their primary segment set. Mirror spreading will place each mirror on a different host within the Greengage DB cluster. Spreading is only allowed if there is a sufficient number of hosts in the array (number of hosts is greater than the number of segment instances per host).

-v

Set logging output to verbose.

--version

Display the version of this utility.

-?

Display help.

Specify hosts using hostnames or IP addresses

When specifying a mirroring configuration using the gpaddmirrors option -i, you can specify either a hostname or an IP address for the address value.

  • If you specify a hostname, the resolution of the hostname to an IP address should be done locally for security. For example, you should use entries in a local /etc/hosts file to map the hostname to an IP address. The resolution of a hostname to an IP address should not be performed by an external service such as a public DNS server. You must stop the Greengage DB system before you change the mapping of a hostname to a different IP address.

  • If you specify an IP address, the address should not be changed after the initial configuration. When segment mirroring is enabled, replication from the primary to the mirror segment will fail if the IP address changes from the configured value. For this reason, you should use a hostname when enabling mirroring using the -i option unless you have a specific requirement to use IP addresses.

When enabling a mirroring configuration that adds hosts to the Greengage DB system, gpaddmirrors populates the gp_segment_configuration catalog table with the mirror segment instance information. Greengage DB uses the address value of the gp_segment_configuration catalog table when looking up host systems for Greengage DB interconnect (internal) communication between the master and segment instances and between segment instances, and for other internal communication.

Use host systems with multiple NICs

If host systems are configured with multiple NICs, you can initialize a Greengage DB system to use each NIC as a Greengage DB host system. You must ensure that the host systems are configured with sufficient resources to support all the segment instances being added to the host. Also, if you enable segment mirroring, you must ensure that the Greengage DB system configuration supports failover if a host system fails.

For example, this is a segment instance configuration for a Greengage DB system. The segment host gp6m is configured with two NICs, gp6m-1 and gp6m-2, where the Greengage DB system uses gp6m-1 for the master segment and gp6m-2 for segment instances.

SELECT content, role, port, hostname, address
FROM gp_segment_configuration;

Result:

 content | role | port  | hostname | address
---------+------+-------+----------+----------
      -1 | p    |  5432 | gp6m     | gp6m-1
       0 | p    | 40000 | gp6m     | gp6m-2
       0 | m    | 50000 | gp6s     | gp6s
       1 | p    | 40000 | gp6s     | gp6s
       1 | m    | 50000 | gp6m     | gp6m-2
(5 rows)

Examples

Add mirroring to an existing Greengage DB system using the same set of hosts as your primary data. Calculate the mirror database ports by adding 5000 to the current primary segment port numbers:

$ gpaddmirrors -p 5000

Generate a sample mirror configuration file with the -o option to use with gpaddmirrors -i:

$ gpaddmirrors -o mirror_conf_file

Add mirroring to an existing Greengage DB system using a different set of hosts from your primary data:

$ gpaddmirrors -i mirror_config_file

mirror_config_file might look like this:

0|sdw5|11000|/data1/mirror/gpseg0
1|sdw5|11001|/data1/mirror/gpseg1
2|sdw6|11000|/data1/mirror/gpseg2
3|sdw6|11001|/data1/mirror/gpseg3
4|sdw7|11000|/data1/mirror/gpseg4
5|sdw7|11001|/data1/mirror/gpseg5
6|sdw8|11000|/data1/mirror/gpseg6
7|sdw8|11001|/data1/mirror/gpseg7

See also

Previous
gpactivatestandby
Next
gpcheckcat