pdbcli configuration guide

1. Overall structure and editing principles

• File structure:

  • all.children: Groups hosts by function (cm, db, proxy) and defines group-level variables.

  • all.hosts: Defines the aliases and corresponding IP addresses for all hosts in the cluster.

  • all.vars: Defines global variables that apply to the entire cluster.

• Editing principles:

  • Do not manually modify the all.hosts section. The polarflex-deploy.sh script automatically replaces the placeholders with the machine IP addresses that you pass as parameters.

  • Do not manually modify the all.children.*.hosts section. By default, the complete cm, db, and proxy components are deployed on all nodes.

  • Adjust parameters in the global all.vars and group-specific all.children.*.vars sections as needed.

  • After modification, ensure that the YAML file maintains correct indentation and key names. Use true/false for Boolean values. Port values must be integers. Strings that do not contain spaces do not require quotation marks.

2. Group definitions (all.children)

1. cm:

   • children.cm.hosts: A list of hosts where the cluster management (CM) service is deployed. Typically, one or three hosts are used to achieve high availability (HA).

     Note

     Adding or removing CM nodes usually requires rerunning the deployment or performing a cluster-level CM operation.

2. db:

   • children.db.hosts.*.polardb_polar_hostid: The unique numeric ID of the database node within the cluster.

   • children.db.hosts.*.polardb_node_type: The node type. This can be omitted for the primary node. For a secondary node, it must be explicitly specified as standby.

   • children.db.vars.polardb_custom_params: Custom database parameters that are passed through to the PostgreSQL kernel.

     Parameter	Example value	Description	Suggestion
     max_standby_streaming_delay	900000	The maximum time (in milliseconds) that a secondary database waits when applying streaming Write-Ahead Logging (WAL) from the primary database if a conflicting query is encountered. If this time is exceeded, the conflicting query is canceled to ensure WAL replay continues. 900000 ms = 15 minutes.	Keep the default value.
     max_connections	3300	The maximum number of concurrent connections allowed for the instance.	Set this value based on your business needs and connection management strategy. Avoid setting it too high to prevent memory exhaustion. Restart the instance after modification. You can usually keep the default value.
     polar_max_super_conns	1500	The maximum number of concurrent connections allowed for a superuser in PolarDB.	Keep the default value.
     max_slot_wal_keep_size	64000	The maximum amount of WAL (in MB) that each replication slot can retain. When this limit is reached, the oldest WAL files are reclaimed, and streaming replication between the primary and secondary databases is interrupted. This prevents the disk from filling up. The default value is approximately 62.5 GB.	Set this based on disk capacity, downstream lag, and send latency. It is critical to monitor replication slot lag. A low limit can cause WAL files generated by the primary database to be reclaimed during high-write scenarios. This leads to replication interruption, making the secondary database unavailable and requiring a manual rebuild. If streaming replication is in synchronous mode, an interruption prevents the primary node from accepting writes.
     log_statement	ddl	Controls the granularity of SQL statements recorded in the log: `none`, `ddl`, `mod`, or `all`. By default, only DDL statements are logged.	Set as needed. Avoid enabling `all` for long periods to prevent rapid log growth and performance impact.

   • children.db.vars.polardb_service_restart_sec: The number of seconds to wait between nodes during a rolling restart of the service. Keep the default value.

   • children.db.vars.hugepage_enabled: Specifies whether to enable enormous pages in the operating system (on/off). If enabled, you must also configure enormous pages at the operating system level.

3. proxy:

   children.proxy.hosts: A list of hosts where the proxy service is deployed. Typically, it is deployed on multiple hosts to ensure availability.

3. Global variables (all.vars)

This section describes the global variables in all.vars. Some parameters in the configuration file contain {{}}. These parameters are automatically replaced during one-click deployment and do not require manual modification. For parameters not listed here, keep the default values. The installer automatically manages and configures them. Parameters in the following list, such as the data directory and ports, cannot be modified after installation. To change them, you must uninstall and delete the cluster, and then redeploy it.