pgpool-II 부록 : PCP Commands

PCP 커맨드

PCP 커맨드는 네트워크를 통해 pgpool-II을 관리하는 UNIX 명령문입니다.

PCP 접속 인증

PCP 유저와 암호는 pgpool-II 설치시 생성되는 /etc/pgpool-II 디렉토리 안에 pcp.conf 에서 선언해야합니다. 다른 위치에 pcp.conf 파일을 위치하고 싶으면 pgpool을 시작할 때, -F 옵션으로 지정하면 됩니다.

PCP 패스워드 파일

사용자 홈 디렉토리에 있는 .pcppass 파일 또는 다른 위치일 경우 환경변수 PCPPASSFILE로 .pcppass파일 위치를 지정할 수 있습니다.

PCP 커맨드에 -w 또는 --no-password 옵션을 적을 경우, 사용할 암호를 입력합니다. 이 파일의 형식은 다음과 같습니다.

HOSTNAME:PORT:USERNAME:PASSWORD

PCP 커맨드를 사용할 때 -h 옵션을 사용하지 않으면 기본적으로 localhost로 검색됩니다.

그리고 .pcppass 파일은 권한을 꼭!!!!!!!!!!!!!! 0600 으로 지정해주어야합니다.

chmod 0600 ~/.pcppass

PCP 공통 옵션

pcp_command [옵션]

 

옵션	설명
-h hostname --host=hostname	서버가 실행중 인 시스템의 호스트 이름입니다. 값이 / 로 시작하면 Unix 도메인 소켓의 디렉토리로 사용됩니다.
-p port --port=port	PCP 포트 번호. 지정하지 않을 경우 기본값은 9898 입니다.
-U username --username=username	PCP 인증을 위한 사용자 이름을 지정합니다. 지정하지 않을 경우 OS 사용자 이름이 기본값입니다.
-w --no-password	암호를 묻지 않습니다. .pcppass 파일에서 암호를 읽어오며, 암호에 문제가 있을 경우 명령문은 실패합니다.
-W --password	강제로 암호 프롬프트를 표시합니다.
-d --debug	디버그 메세지를 활성화 합니다.
-v --verbose	상세 출력 모드를 활성화 합니다.
-V --version	버전을 표시합니다.
-? --help	도움말을 표시합니다.

PCP 커맨드 종류

pcp_node_count

pcp_node_count [옵션]

• 총 데이터베이스 노드 수를 표시합니다.
• pgpool.conf 에 정의된 총 데이터베이스 노드 수를 표시합니다.
• 노드 상태 즉, attached/detached 상태를 구분하지 않고 모든 노드의 수를 계산합니다.
• 예시

[test@localhost:~]$ pcp_node_count -h /var/run/test -w
2

pcp_node_info

pcp_node_info [옵션] [node_id]

• 주어진 노드 ID에 대한 정보를 표시합니다.
• 옵션

옵션	설명
-n node_id --node-id=node_id	정보를 가져올 백엔드 노드의 ID
-a --all	모든 백엔드 노드 정보를 표시합니다.

• 예시

-v 옵션과 같이 커맨드를 실행하면 각 값이 어떤 값을 의미하는지 알 수 있습니다.

[test@localhost:~]$ pcp_node_info -h /var/run/test -w
192.168.40.133 5432 1 0.500000 waiting up primary primary 0 none none 2023-06-10 13:25:10
192.168.40.134 5432 1 0.500000 waiting up standby standby 0 none none 2023-06-10 13:25:10

[test@localhost:~]$ pcp_node_info -h /var/run/test -v -w
Hostname               : 192.168.40.133
Port                   : 5432
Status                 : 2
Weight                 : 0.500000
Status Name            : up
Backend Status Name    : up
Role                   : primary
Backend Role           : primary
Replication Delay      : 0
Replication State      : none
Replication Sync State : none
Last Status Change     : 2023-06-10 13:27:25

Hostname               : 192.168.40.134
Port                   : 5432
Status                 : 2
Weight                 : 0.500000
Status Name            : up
Backend Status Name    : up
Role                   : standby
Backend Role           : standby
Replication Delay      : 0
Replication State      : none
Replication Sync State : none
Last Status Change     : 2023-06-10 13:27:25

상태가 waiting 이라고 나오긴 하는데 up이 되기 전 단계 같다. 상태가 아직 변경 안됐을 뿐, SQL 문으로 노드 조회하면 up으로 나오며, 그 후 다시 pcp_node_info 커맨드를 사용하면 waiting에서 up으로 변경된 것을 확인할 수 있습니다. 그래서 저는 노드 정보 확인할 때는 주로 pcp 커맨드 말고 SQL 커맨드로 확인합니다! SQL 커맨드를 입력하면 다음과 같이 출력됩니다.

[test@localhost:~]$ psql -p 9999 -c "show pool_nodes;"
 node_id |    hostname    | port | status | pg_status | lb_weight |  role   | pg_role | select_cnt | load_balance_node | replication_delay | replicatio
n_state | replication_sync_state | last_status_change
---------+----------------+------+--------+-----------+-----------+---------+---------+------------+-------------------+-------------------+-----------
--------+------------------------+---------------------
 0       | 192.168.40.133 | 5432 | up     | up        | 0.500000  | primary | primary | 0          | false             | 0                 |
        |                        | 2023-06-10 13:27:25
 1       | 192.168.40.134 | 5432 | up     | up        | 0.500000  | standby | standby | 0          | true              | 0                 |
        |                        | 2023-06-10 13:27:25
(2 rows)

pcp_health_check_stats

pcp_health_check_stats [옵션] [node_id]

• 주어진 노드 ID에 대한 health check 통계 데이터를 표시합니다.
• 옵션

옵션	설명
-n node_id --node-id=node_id	정보를 가져올 백엔드 노드의 ID

• 예시

-v 옵션과 같이 커맨드를 실행하면 각 값이 어떤 값을 의미하는지 알 수 있습니다.

[test@localhost:~]$ pcp_health_check_stats -h /var/run/test -w 0
0 192.168.40.133 5432 up primary 2023-06-10 13:27:25 128 128 0 0 0 0.000000 0 8 1 4.460938 2023-06-10 13:46:36 2023-06-10 13:46:36

[test@localhost:~]$ pcp_health_check_stats -h /var/run/test -w -v 0
Node Id                       : 0
Host Name                     : 192.168.40.133
Port                          : 5432
Status                        : up
Role                          : primary
Last Status Change            : 2023-06-10 13:27:25
Total Count                   : 143
Success Count                 : 143
Fail Count                    : 0
Skip Count                    : 0
Retry Count                   : 0
Average Retry Count           : 0.000000
Max Retry Count               : 0
Max Health Check Duration     : 8
Minimum Health Check Duration : 1
Average Health Check Duration : 4.412587
Last Health Check             : 2023-06-10 13:49:06
Last Successful Health Check  : 2023-06-10 13:49:06
Last Skip Health Check        :
Last Failed Health Check      :

기본적인 노드 정보와 상태, 언제 마지막으로 상태가 변했는지, health check 평균, 최대 재시도, 주기, 마지막 health check 등 health check 와 관련된 여러 정보를 확인할 수 있습니다.

pcp_watchdog_info

pcp_watchdog_info [ 옵션 ] [ watchdog_id ]

• pgpool-II의 watchdog 프로세스의 상태를 표시합니다.
• 옵션

옵션	설명
-n node_id --node-id=watchdog_id	정보를 가져올 다른 pgpool-II 노드의 인덱스를 지정합니다. 인덱스 번호에 0을 입력하면 자기 자신의 watchdog 정보를 가져옵니다. 지정하지 않으면 모든 watchdog 노드의 정보를 표시합니다.

• 예시

-v 옵션과 같이 커맨드를 실행하면 각 값이 어떤 값을 의미하는지 알 수 있습니다.

[test@localhost:pgpool-II]$  pcp_watchdog_info -h /var/run/test/ -w
2 2 YES 192.168.40.134:9999 Linux localhost.localdomain 192.168.40.134

192.168.40.134:9999 Linux localhost.localdomain 192.168.40.134 9999 9000 4 LEADER 0 MEMBER
192.168.40.133:9999 Linux localhost.localdomain 192.168.40.133 9999 9000 7 STANDBY 0 MEMBER

[[test@localhost:~]$ pcp_watchdog_info -h /var/run/test -w -v
Watchdog Cluster Information
Total Nodes              : 2
Remote Nodes             : 1
Member Remote Nodes      : 1
Alive Remote Nodes       : 1
Nodes required for quorum: 2
Quorum state             : QUORUM EXIST
Local node escalation    : YES
Leader Node Name         : 192.168.40.133:9999 Linux localhost.localdomain
Leader Host Name         : 192.168.40.133

Watchdog Node Information
Node Name         : 192.168.40.133:9999 Linux localhost.localdomain
Host Name         : 192.168.40.133
Delegate IP       : 192.168.40.200
Pgpool port       : 9999
Watchdog port     : 9000
Node priority     : 1
Status            : 4
Status Name       : LEADER
Membership Status : MEMBER

Node Name         : 192.168.40.134:9999 Linux localhost.localdomain
Host Name         : 192.168.40.134
Delegate IP       : 192.168.40.200
Pgpool port       : 9999
Watchdog port     : 9000
Node priority     : 1
Status            : 7
Status Name       : STANDBY
Membership Status : MEMBER

위와 같이 전체 노드수, remote 노드수와 같은 노드 수 정보나 쿼럼 매커니즘을 위해 필요한 노드 갯수, 쿼럼이 존재 하는지에 대한 정보를 알 수 있습니다.

아래 watchdog node information 부분을 보면 status name 이 있는데 VIP를 가진 node가 LEADER가 되고 나머지는 STANDBY 노드가 됩니다. VIP가 다른 노드로 옮겨지게 되면 이 status도 변경되게 됩니다. delegate IP는 VIP를 뜻합니다.

pcp_proc_count

pcp_proc_count [ 옵션 ]

• pgpool-II 하위 프로세스 ID 목록을 표시합니다.
• 옵션

옵션 설명

옵션	설명
-n node_id --node-id=node_id	정보를 가져올 백엔드 노드의 ID

• 예시

[test@localhost:~]$ pcp_proc_count -h /var/run/test -w
4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4813 4814 4815 4816 4817 4818 4819 4820

pcp_proc_info

pcp_proc_info [ 옵션 ] [ pgpool_child_processid ]

• 옵션으로 지정한 pgpool-II 하위 프로세스 ID 에 대한 정보를 표시합니다.
• -a 또는 -P로 프로세스를 지정하지 않으면 모든 하위 프로세스의 정보를 표시합니다. 만약 하위 프로세스가 없을 경우 다음과 같은 메세지가 출력됩니다.

[test@localhost:~]$ pcp_proc_info -h /var/run/test -w No process information available

• 옵션

옵션	설명
-a --all	모든 하위 프로세스에 대한 정보를 표시합니다.
-P PID --process-id=PID	pgpool-II의 하위 프로세스를 지정합니다.

• 예시

하위 프로세스 연결을 위해 pgbench로 pgpool-II 에 연결합니다. host는 VIP , port는 pgpool-II 포트인 9999로 연결하여 진행합니다.

pgbench -h 192.168.40.200 -p 9999 -T 120 -c 3

그리고 전체 하위 프로세스를 조회해봅니다.

[test@localhost:~]$ pcp_proc_info -h /var/run/test -w
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:44 1 9078 1 8802 0 Idle in transaction
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:44 1 5596 1 8802 1 Idle in transaction
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:55 1 9079 1 8803 0 Idle
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:55 1 5597 1 8803 1 Idle
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:30 1 9077 1 8805 0 Idle in transaction
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:30 1 5595 1 8805 1 Execute command

[test@localhost:~]$ pcp_proc_info -h /var/run/test -w
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:44 1 9078 1 8802 0 Idle in transaction
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:44 1 5596 1 8802 1 Idle in transaction
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:55 1 9079 1 8803 0 Idle in transaction
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:55 1 5597 1 8803 1 Idle in transaction
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:30 1 9077 1 8805 0 Idle in transaction
postgres postgres 2023-06-16 17:57:28 1 3 0 2023-06-16 17:57:57 2023-06-16 17:57:57 0 2023-06-16 17:57:30 1 5595 1 8805 1 Idle in transaction

-v 옵션을 같이 적어주면 상세하게 확인할 수 있습니다.

[test@localhost:~]$ pcp_proc_info -h /var/run/test -w -v
Database                  : postgres
Username                  : postgres
Start time                : 2023-06-16 17:57:28
Client connection count   : 0
Major                     : 3
Minor                     : 0
Backend connection time   : 2023-06-16 18:03:25
Client connection time    : 2023-06-16 18:03:25
Client idle duration      : 0
Client disconnection time :
Pool Counter              : 1
Backend PID               : 11221
Connected                 : 1
PID                       : 8788
Backend ID                : 0
Status                    : Execute command

Database                  : postgres
Username                  : postgres
Start time                : 2023-06-16 17:57:28
Client connection count   : 0
Major                     : 3
Minor                     : 0
Backend connection time   : 2023-06-16 18:03:25
Client connection time    : 2023-06-16 18:03:25
Client idle duration      : 0
Client disconnection time :
Pool Counter              : 1
Backend PID               : 5748
Connected                 : 1
PID                       : 8788
Backend ID                : 1
Status                    : Execute command

pcp_pool_status

pcp_pool_status [ 옵션 ]

• pgpool.conf에 작성한 대로 파라미터 값을 표시합니다.
• 예시

[test@localhost:~]$ pcp_pool_status -h /var/run/test -w
name : backend_clustering_mode
value: 1
desc : clustering mode

name : listen_addresses
value: *
desc : host name(s) or IP address(es) to listen on

name : port
value: 9999
desc : pgpool accepting port number

name : socket_dir
value: /var/run/test
desc : pgpool socket directory

name : pcp_listen_addresses
value: *
desc : host name(s) or IP address(es) for pcp process to listen on

name : pcp_port
value: 9898
desc : PCP port # to bind

name : pcp_socket_dir
value: /var/run/test
desc : PCP socket directory

name : enable_pool_hba
value: 1
desc : if true, use pool_hba.conf for client authentication

name : pool_passwd
value: pool_passwd
.....

pcp_detach_node

pcp_detach_node [ 옵션 ] [ node_id ] [ gracefully ]

• pgpool-II 에서 지정한 노드를 분리합니다. 이 커맨드를 사용하면 연결을 강제로 종료합니다.
• failover_command 와 follow_primary_command가 설정돼있을 경우 이 커맨드를 실행하여 연결을 끊고 기능을 수행합니다.
• pgpool-II 과 연결은 종료하지만 실제로 실행중인 백엔드 노드 연결을 건드리지 않습니다.
• 분리된 노드를 다시 연결하려면 pcp_recovery_node 커맨드를 사용하여 연결할 수 있습니다.
• 그러나 replication delay가 존재하지 않고 각 노드의 역할 즉, primary와 standby 가 변경되지 않는다면 pcp_attach_node를 사용하여 다시 연결할 수 있습니다.
• 옵션

옵션	설명
-n node_id --node-id=node_id	분리할 백엔드 노드 ID를 입력합니다.
-g --gracefully	모든 클라이언트의 연결이 끊어질때까지 기다립니다.

pcp_attach_node

pcp_attach_node [ 옵션 ] [ node_id ]

• pgpool-II 에서 지정된 노드를 연결합니다.
• 옵션

옵션	설명
-n node_id --node-id=node_id	연결 할 백엔드 노드 ID를 입력합니다.

pcp_promote_node

pcp_promote_node [options...] [node_id] [gracefully] [switchover]

• 지정한 노드를 pgpool-II의 새 primary노드로 승격합니다.
• 이 커맨드는 streaming replication 에서만 실행 가능합니다.
• -s 옵션을 사용하지 않으면 standby 노드는 연결하지 않고 primary 노드만 변경됩니다. 이때 지정하지 않은 노드는 down 상태로 변경되며, 실제 PostgreSQL 서버를 down 시키는 것이 아니라 pgpool-II 과의 연결 상태만 down 시킵니다.
• -s 옵션이 지정됐을 경우, pgpool-II 은 현재 primary를 분리하고 failover_command를 실행하여 지정한 노드를 primary로 승격합니다. 그리고 전에 primary였던 노드를 follow_primary_command를 실행하여 standby노드로 변경합니다.
• 옵션

옵션	설명
-n node_id --node-id=node_id	primary로 승격할 노드 ID를 입력합니다. 지정된 노드는 up 또는 waiting 이어야합니다.
-g --gracefully	모든 클라이언트의 연결이 끊어질때까지 기다립니다.
-s --switchover	follow_primary 커맨드를 실행하여 지정된 노드가 실제로 승격시키도록 합니다.

예시는 뒤 포스트에서 실제로 switchover을 사용하여 실습하며 커맨드를 사용해보도록 하겠습니다!

pcp_stop_pgpool

pcp_stop_pgpool [ 옵션 ] [ 모드 ]

• pgpool-II 프로세스를 종료합니다.
• 옵션

옵션	설명
-m mode --mode=mode	해당 모드로 pgpool-II을 종료합니다. 아래 모드 중에 선택할 수 있으며 기본값은 smart 입니다. - s, smart : 스마트 모드 - f, fast : 빠른 모드 - i, 즉시: 즉시 모드
-s scope  --scope=scope	커맨드가 영향을 미치는 범위를 지정합니다. 아래 모드 중에 선택할 수 있으며 기본값은 local 입니다. - c, cluster: 클러스터에 포함되는 모든 pgpool-II 프로세스를 종료합니다. - l, local : 로컬 Pgpool-II 노드만 종료

아래 모드 중에 선택할 수 있으며 기본값은 smart 입니다.

pcp_reload_config

pcp_reload_config [ 옵션 ]

• pgpool-II 의 config 파일을 reload합니다.
• 옵션

옵션	설명
-s scope --scope=scope	커맨드가 영향을 미치는 범위를 지정합니다. 아래 모드 중에 선택할 수 있으며 기본값은 local 입니다. - c, cluster: 클러스터에 포함되는 모든 pgpool-II 의 config 파일을 reload 합니다. - l, local :로컬 Pgpool-II 의 config 파일을 reload 합니다.

 

pcp_recovery_node

pcp_recovery_node [ 옵션 ] [ node_id ]

• 지정한 백엔드 노드를 복구한 후 , 다시 pgpool-II 클러스터에 연결합니다.
• 옵션

옵션	설명
-n node_id --node-id=node_id	복구할 노드의 ID를 입력합니다.

• 예시는 뒤의 Online recovery 할때 직접 이 커맨드를 실행하여 진행해보도록 하겠습니다!