Installation and deployment

Hardware requirements

Before installing PolarDB for PostgreSQL (PolarFlex), ensure your hardware meets the following minimum requirements. Plan your final hardware configuration based on your business needs, data volume, and expected database performance.

Software requirements

strings /lib64/libc.so.6 | grep "^GLIBC_2."

Pre-configure the operating system

Disable the Transparent Huge Pages feature on your operating system. Run the following command to check the current configuration:

cat /sys/kernel/mm/transparent_hugepage/enabled

If the output is always madvise [never], Transparent Huge Pages is already disabled. Otherwise, run the following command to disable it:

echo never > /sys/kernel/mm/transparent_hugepage/enabled

Prepare the configuration file

The pdbcli configuration file defines essential settings for the database installation, such as host storage, port configurations, and database parameters. The default configuration file is config.yaml, located in the polarflex-${version}/ directory.

To help you configure config.yaml, templates for different scenarios are provided in the same directory. For more information about parameter settings, see the pdbcli configuration guide.

If you use the polarflex-deploy.sh one-click deployment script to set up the service, you must modify the parameters in the corresponding configuration file template. The polarflex-deploy.sh script automatically generates config.yaml from the template during runtime.

Note that the following two parameters must be configured before you create the cluster and cannot be modified after creation.

• Compatibility mode

  PolarDB for PostgreSQL (PolarFlex) offers two compatibility modes: Postgres-compatible and Oracle-compatible.

  The default is the Postgres-compatible mode. To enable the Oracle-compatible mode, you must set compatibility_mode: ora at the end of the configuration file template.

• File directory

  By default, the database files are located in a subdirectory of /var/lib/thirdDB. You can change this path by using the polardb_data_root_dir parameter in the configuration file. Because the default directory might have limited disk space, we strongly recommend choosing a suitable directory based on your host's disk capacity and the expected volume of database files.

# This example shows how to configure a three-host cluster with the IP addresses 10.XX.XX.1,
# 10.XX.XX.2, and 10.XX.XX.3. Modify the settings according to your actual environment.
all:
  children:
    cm:
      hosts:
        host01: null
        host02: null
        host03: null
      var: null
    db:
      hosts:
        host01:
          polardb_polar_hostid: 1
        host02:
          polardb_polar_hostid: 2
          polardb_node_type: standby
        host03:
          polardb_polar_hostid: 3
          polardb_node_type: standby
      vars:
        polardb_custom_params:
        - max_standby_streaming_delay = 900000
        - max_connections = 3300
        - superuser_reserved_connections = 15
        - polar_max_super_conns = 1500
        polardb_service_restart_sec: 5
        hugepage_enabled: off
    proxy:
      hosts:
        host01: null
        host02: null
      var: null
  hosts:
    host01:
      ansible_host: 10.XX.XX.1 # HOST01_IP 
    host02:
      ansible_host: 10.XX.XX.2 # HOST02_IP 
    host03:
      ansible_host: 10.XX.XX.3 # HOST03_IP 
  vars:
    ansible_group_priority: 99
    ansible_python_interpreter: /usr/bin/{{python}}
    cluster_id: polardb1
    cm_consensus_port: 7001
    cm_service_port: 5001
    cm_tls_service_port: 6001
    cm_db_sync_mode: SYNC
    polardb_data_root_dir: /var/lib/thirdDB
    polardb_enable_direct_io: false
    polardb_multi_instance_per_host: true
    polardb_polar_enable_pfs_mode: false
    polardb_port: 1523 # Direct connection port for the database
    polardb_proxy_port: 12369 # Proxy port for strong consistency
    polardb_proxy_port_rwlb: 12370 # Proxy port for read/write splitting
    polardb_proxy_admin_port: 12371
    polardb_storage_mode: local_filesystem_mode
    polardb_user: polar1
    primary_db_host: host01
    ue_node_driver_service_port: 12355
    compatibility_mode: pg # To use the Oracle-compatible mode, change pg to ora before installation.

Install and create the cluster

The polarflex directory contains the polarflex-deploy.sh one-click installation script. Run the command that corresponds to your desired number of cluster nodes:

• To create a cluster with one primary and two standby nodes (default configuration: config_template.yaml):

  bash polarflex-deploy.sh -m "10.XX.XX.1" -p 'password' -m "10.XX.XX.2" -p 'password' -m "10.XX.XX.3" -p 'password'

• To create a primary/standby cluster (default configuration: config_master_slave.yaml):

  bash polarflex-deploy.sh -m "10.XX.XX.1" -p 'password' -m "10.XX.XX.2" -p 'password'

• To create a single-node cluster (default configuration: config_single_node.yaml):

  bash polarflex-deploy.sh -m "10.XX.XX.1" -p 'password'

The -m parameter specifies the server host address, and -p specifies the root password for the corresponding server host. You can add the -w parameter to deploy prometheus and grafana with a single command. To view cluster monitoring, access port 3000 on the machine where you ran the polarflex-deploy.sh script.

bash polarflex-deploy.sh -m "10.XX.XX.1" -p 'password' -m "10.XX.XX.2" -p 'password' -m "10.XX.XX.3" -p 'password' -w

The script performs the following steps:

1. Configures passwordless SSH login based on the specified server host IP addresses and their root passwords.

2. Generates the config.yaml configuration file from a template file such as config_template.yaml.

3. Runs pdbcli install cluster to install the required dependencies for the cluster.

4. Runs pdbcli create cluster to create the database cluster.

Check the cluster status

Run pdbcli status to check the cluster status. The installation is successful if the statuses of the cluster_manager, master, standby, and proxy nodes are all RUNNING, and the work_path matches the directory specified in the configuration file.

Using config file: ./config.yaml
Cluster Status:
{
	"phase": "RunningPhase",
	"cluster_manager": [
		{
			"endpoint": "172.x.x.x:5001",
			"phase": "RUNNING"
		},
		{
			"endpoint": "172.x.x.x:5001",
			"phase": "RUNNING"
		},
		{
			"endpoint": "172.x.x.x:5001",
			"phase": "RUNNING"
		}
	],
	"master": {
		"endpoint": "172.x.x.x:1523",
		"cust_id": "0",
		"work_path": "/var/lib/thirdDB/clusters/polardb1",
		"phase": "RUNNING",
		"start_at": "2025-03-13 19:41:50"
	},
	"standby": [
		{
			"endpoint": "172.x.x.x:1523",
			"cust_id": "0",
			"work_path": "/var/lib/thirdDB/clusters/polardb1",
			"phase": "RUNNING",
			"start_at": "2025-03-13 19:42:02",
			"sync_status": "SYNC"
		},
		{
			"endpoint": "172.x.x.x:1523",
			"cust_id": "0",
			"work_path": "/var/lib/thirdDB/clusters/polardb1",
			"phase": "RUNNING",
			"start_at": "2025-03-13 19:42:02",
			"sync_status": "SYNC"
		}
	],
	"proxy": [
		{
			"endpoint": "172.x.x.x:12369",
			"phase": "RUNNING"
		},
		{
			"endpoint": "172.x.x.x:12369",
			"phase": "RUNNING"
		}
	],
	"plugins": [
		{
			"name": "golang-manager",
			"status": "Plugin run err topo is null errCount 2"
		}
	],
	"disk": {
		"state": "UNLOCK",
		"quota": "UNSET",
		"usage": ""
	}

Check the database connection

After the cluster starts, you can use the built-in psql client from the PolarDB for PostgreSQL (PolarFlex) kernel binary package to test the connection.

The following resources are created by default during cluster creation:

• A user named admin with the password postgres.

• A database named admin_db.

The default access port for the cluster is 1523. Run the following command to check cluster connectivity:

PGPASSWORD=postgres /u01/polardb_pg/bin/psql -h localhost -p1523 -U admin -d admin_db -c 'SHOW polardb_version'

If the command returns the minor kernel version number of the PolarDB for PostgreSQL (PolarFlex) cluster, such as PolarDB V2.0.14.13.26.0, the database is installed correctly and the kernel version is correct.

Check the compatibility mode

After the cluster starts, you can use the built-in psql client from the PolarDB for PostgreSQL (PolarFlex) kernel binary package to query the current engine compatibility mode.

PGPASSWORD=postgres /u01/polardb_pg/bin/psql -h localhost -p1523 -U admin -d admin_db -c 'SHOW polar_compatibility_mode'

The possible results are:

• pg: Indicates the Postgres-compatible mode.

• ora: Indicates the Oracle-compatible mode.

Check the processes

When a PolarDB for PostgreSQL (PolarFlex) cluster starts successfully, it creates a file named postmaster.pid in the database directory. The first line of this file contains the process ID (PID) of the PolarDB engine daemon process. You can run the command ps -ef | grep <pid> to view all PolarDB for PostgreSQL (PolarFlex) cluster processes. Common auxiliary processes include:

• postgres: logger: The PolarDB logging process.

• postgres: checkpointer: The PolarDB periodic checkpoint process.

• postgres: background writer: The PolarDB periodic dirty page flushing process.

• postgres: walwriter: The PolarDB periodic WAL log flushing process.

• postgres: autovacuum launcher: The PolarDB automatic cleanup scheduling process.

• postgres: stats collector: The PolarDB statistics collection process.