COMMAND NAME: gpaddmirrors

Adds mirror segments to a Apache Cloudberry system that was 
initially configured without mirroring.


*****************************************************
SYNOPSIS
*****************************************************


gpaddmirrors [-p <port_offset>] [-m <datadir_config_file> [-a]] [-s] 
             [-d <coordinator_data_directory>] [-B <parallel_processes>] 
             [-l <logfile_directory>] [-v]

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

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

gpaddmirrors -? 

gpaddmirrors --version


*****************************************************
DESCRIPTION
*****************************************************
The gpaddmirrors utility configures mirror segment instances for an 
existing Apache Cloudberry 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 Apache Cloudberry system is fully data redundant.

IMPORTANT: During the online replication process, Apache Cloudberry 
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 than your primary 
segment data locations and ports.

The utility will create 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. It is OK to 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 > /gpdb/mirror
Enter mirror segment data directory location 2 of 2 > /gpdb/mirror
OR
Enter mirror segment data directory location 1 of 2 > /gpdb/m1
Enter mirror segment data directory location 2 of 2 > /gpdb/m2

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:

<content>|<address>|<port>|<datadir>

For example:

0|sdw1-1|60000|/gpdata/mirror1/gp0
1|sdw1-1|60001|/gpdata/mirror2/gp1

The gp_segment_configuration system catalog tables 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 creating your mirrors on alternate mirror hosts, the new 
mirror segment hosts must be pre-installed with the Cloudberry 
Database 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.


*****************************************************
OPTIONS
*****************************************************

-a

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


-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: 1-64


-b <segment_batch_size>

The number of segments per host to work on in parallel. If not
specified, the utility will start working on up to 64 segments
in parallel on each host it is working on.
Valid values: 1-128


-d <coordinator_data_directory>

 The coordinator data directory. If not specified, the value set for 
 $COORDINATOR_DATA_DIRECTORY will be used.


-i <mirror_config_file>

 A configuration file containing one line for each mirror segment 
 you want to create. You must have one mirror segment 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):

   <content>|<address>|<port>|<datadir>


-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 will prompt you for locations. Each line in the file specifies 
 a mirror data directory location. For example:
   /gpdata/m1
   /gpdata/m2
   /gpdata/m3
   /gpdata/m4


-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 a primary segment has port 50001, then its mirror 
 will use a database port of 51001 by default.


-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 Cloudberry 
 Database array. Spreading is only allowed if there is a sufficient 
 number of hosts in the array (number of hosts is greater than 
 or equal to the number of segment instances per host).


--hba-hostnames

 Optional. use hostnames instead of CIDR in pg_hba.conf


-v

 Sets logging output to verbose.


--version

 Displays the version of this utility.


-?

 Displays the online help.


*****************************************************
EXAMPLES
*****************************************************

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

  $ gpaddmirrors -p 100


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

$ gpaddmirrors -i mirror_config_file

Where the mirror_config_file looks something like this:

0|sdw1-1|52001|53001|54001|/gpdata/mir1/gp0
1|sdw1-2|52002|53002|54002|/gpdata/mir2/gp1
2|sdw2-1|52001|53001|54001|/gpdata/mir1/gp2
3|sdw2-2|52002|53002|54002|/gpdata/mir2/gp3


Output a sample mirror configuration file to use with gpaddmirrors -i:

  $ gpaddmirrors -o /home/gpadmin/sample_mirror_config


*****************************************************
SEE ALSO
*****************************************************

gpinitsystem, gpinitstandby, gpactivatestandby
