Preparing Configuration File

Configuration File Introduction

Before installing the database, PTK can be used to create a configuration file for defining the expected database cluster topology.

To install a local single-instance database, run the following command to generate a template configuration file.

ptk template -l > config.yaml

To install a multi-instance cluster, run the following command to generate a template configuration file.

ptk template > config.yaml

After PTK is run, a config.yaml file is generated in the current folder. You need to modify the configuration according to Your own server and directory plan.

If there is the password field, you need to run ptk encrypt to encrypt the password and then add the ciphertext to the configuration file.

Note: If you hope to use a non-root user to connect the target server by SSH, make sure that the user has the sudo permission on the target server.

Configuration method: Add the following content (replacing USERNAME with SSH connection user name) to the sudoers files in the /etc directory: [USERNAME] ALL=(ALL) NOPASSWD:ALL

Interactive Creation

PTK also supports interactive creation of a configuration file. You can perform the following command to perform interactive creation:

ptk template create

After the command is run, the interactive terminal is displayed. You need to only reply the questions in sequence.

Note: During db_server configuration, if the SSH login information is the same, it can be used repeatedly.

After the interactive terminal exits, a config.yaml file will be automatically created in the current folder.

Configuration File Field Description

The following is an example of a completed configuration file:

In YAML syntax, strings do not need to be quoted by default, if the string contains spaces or special characters, they need to be put in quotes, for more details about YAML syntax, please refer to Appendix: YAML Syntax

global:
  # cluster name
  cluster_name: c1
  # system user for running db
  user: omm
  # system user group, same as username if not given
  group: omm
  # system user password, use 'ptk encrypt' to encrypt it if not empty
  user_password: ""
  # database password, use 'ptk encrypt' to encrypt it if not empty
  db_password: ""
  # database port
  db_port: 26000
  # base directory for install MogDB server
  # PTK will create an application directory, a data directory, a tools directory, a log directory, and a temporary directory in this directory.
  base_dir: /opt/mogdb
  # list of parameters supported by gs_initdb, appended to the command during installation
  gs_initdb_opts:
  - --encoding=UTF-8
  - --dbcompatibility=A
  # Add server IPs that allow off-cluster access to the database
  extra_hba_conf:
  - type: host
    database: all
    user: all
    address: <IP>/32
    method: sha256
    option:
  # Configuration of the CM component, the value takes effect when the CM component is enabled
  cm_option:
    # The installation directory of CM, if you don't fill it in, the cm directory will be created in the base_dir directory by default.
    # dir: /opt/mogdb/cm
    # CM Server port
    cm_server_port: 15300
    # Virtual IP, this value requires a supported version of CM to take effect
    db_service_vip: ""
    # CM Server configuration, which is updated to cm_server.conf
    cm_server_conf:
      # instance_heartbeat_timeout: 2
      # ...
    # CM Agent configuration, which is updated to cm_agent.conf
    cm_agent_conf:
      # log_max_size: 10240
      # ...
db_servers:
  - host: <IP>
    # Database port, can be omitted, automatically inherits the db_port configured in global section.
    db_port: 26000
    # database role, options: primary, standby, cascade_standby
    role: primary
    # available zone name, the value takes effect when the CM component is enabled
    az_name: AZ1
    # available zone priority, the lower the value the higher the priority, minimum 1, this value takes effect when the CM component is enabled
    az_priority: 1
    # Upstream standby node IP for cascaded standby, required for cascaded standby only
    upstream_host:
    # Supported parameters in postgresql.conf
    db_conf:
      # replication_type: 1
    # SSH configuration for connecting to the server
    ssh_option:
      port: 22
      user: root
      # SSH login password, does not support plaintext, need to use ptk encrypt to fill in after encryption
      password:
# cm server list, if it is not listed here, it will be deployed on each db_server's machine during installation
# Note that this configuration does not mean that CM will be installed, you need to specify the --install-cm option in the command line during installation for it to take effect.
cm_servers:
  - host: <IP>
    # CM Server port, default is global.cm_option.cm_server_port
    port: 15300
    # SSH configuration information, if the db_server has been configured on the same machine, you don't need to configure it here
    ssh_option:

The configuration file includes three parts, including global, db_servers and cm_servers.

global: describes the common information of all instances in a cluster.
db_servers: shows the instance list. Each element represents an instance.
cm_servers: describes the CM server node information, which takes effect only if the --install-cm option is specified, or can be omitted, and is deployed with db_servers by default.

Global Configuration

Field Name	Description	Value Type	Default Value	Mandatory or Not	Remarks
cluster_name	Cluster name	String	`cluster_` is the prefix of a cluster name by default.	Yes
user	Operating system user	String	omm	No
group	Operating system user group	String	omm	No
user_password	Operating system user password	String	Null	No	The value needs to be encrypted by running the `encrypt` command.
db_password	Database password	String	Null	No	The value needs to be encrypted by running the encrypt command. If the field is not set, it can be set during installation.
db_port	Listening port of a database	Integer	26000	No
base_dir	Base directory for database installation	String	/opt/mogdb	No	If this field is set, the app_dir, log_dir, data_dir, tool_dir, cm_dir, and tmp_dir fields can be optional and automatically put in the specified directory of this field.
app_dir	Application directory of a database	String	/opt/mogdb/app	No
log_dir	Database log directory	String	/opt/mogdb/log	No
data_dir	Database data directory	String	/opt/mogdb/data	No
tool_dir	Database tool directory	String	/opt/mogdb/tool	No
tmp_dir	Directory of the temporary database file	String	/tmp	No
core_file_dir	Directory of the system core file	String	Null	No	If this field is set, the `kernel.core_pattern` value will be changed.
gs_initdb_opts	gs_initdb parameters for database initialization	String list	no	An element maps a parameter. If the `--locale` parameter is not set, PTK will set the element to `--no-locale` by default.
ssh_option	SSH connection authentication information	ssh_option	no	If an instance needs to be connected remotely but the instance-level ssh_option is not configured, the field in the global will prevail.
cm_option	CM configuration parameter	cm_option	no	The field takes effect when `--install-cm` is specified during installation.

db_servers Configuration

Field Name	Description	Value Type	Default Value	Mandatory or Not	Remarks
host	IP address of an instance	String	Null	Yes
db_port	Instance port	Integer	26000	No	If this field is not configured, the field in the global will prevail.
ha_ips	HA IP address list for instance log replication	String list	Null	No
ha_port	HA port for log replication	Integer	26001	No
role	Database instance role	String	Null	No	The value can be `primary`, `standby`, and `cascade_standby`. If this field is not configured, an instance in a cluster will be chosen as the primary instance randomly. Other instances will become standby instances.
upstream_host	IP address of the upstream standby of the cascaded standby	String	Null	Mandatory for a cascaded standby
az_name	AZ name	String	AZ1	No
az_priority	AZ priority	Integer	1	The smaller the value, the higher the priority.
xlog_dir	xlog log directory	String	Null	The xlog will be put in the pg_log of the `log_dir` directory. This field cannot be configured under the data directory. Otherwise, an error will occur during database starting.
db_conf	Database GUC parameter configuration	Dictionary	Null	The dictionary key is a parameter in postgresql.conf.
ssh_option	SSH connection authentication for connecting an instance	ssh_option	no	If this field is not configured, the field in the global will prevail.

cm_servers

Field Name	Description	Value Type	Default Value	Mandatory or Not	Remarks
host	IP address of an instance	String	Null	Yes
port	CM server port	Integer	15300	No	If it is not specified, the value of `global.cm_option.cm_server_port` is used.
ssh_option	SSH authentication information for instance connection	ssh_option	No	If it is not specified, the field in the global or the configuration of the same IP address in db_servers can be used.

cm_option

Field Name	Description	Value Type	Default Value	Mandatory or Not	Remarks
dir	CM installation directory	String	$base_dir/cm	Yes
cm_server_port	Listening port of the CM server	Integer	15300	No
db_service_vip	Virtual IP address (which needs to be supported by CM)	String	Null	No
cm_server_conf	CM sever configuration parameter	Dictionary	Null	No	The dictionary key of the field supports any parameter of cm_server. PTK will set this value in cm_server.conf .
cm_agent_conf	CM agent configuration parameter	Dictionary	Null	No	The dictionary key of the field supports any parameter of cm_agent. PTK will set this value in cm_agent.conf .

ssh_option

Field Name	Description	Value Type	Default Value	Mandatory or Not	Remarks
host	IP address of a host	String	IP address of an instance	No	If a host is to be configured as a proxy jump server, this field is mandatory.
port	SSH connection port	Integer	22	No
user	SSH connection user	String	root	No	If the connection user is not root, make sure that the user has the sudo permission without the code.
password	SSH connection password	String	Null	No	The value needs to be encrypted by running the `encrypt` command.
key_file	SSH connection key file	String	Null	No
passphrase	Password of the SSH connection key file	String	Null	No
conn_timeout	SSH connection timeout duration	Duration	1m	No
exec_timeout	Command execution timeout duration	Duration	10m	No
proxy	Jump server configuration	ssh_option	Null	No	The jump server can be connected for only once.