PGPOOL_SETUP(1)

📦

version 4.7.2 · 7 versions

💖 PGPOOL_SETUP(1) 💖

okay bestie, so this is the manual page for pgpool_setup from the pgpool-II 4.7.2 Documentation and honestly? it's giving lab setup fairy. let's get into it ✨

🎀 NAME 🎀

pgpool_setup — creates a temporary installation of a Pgpool-II cluster. yes, the whole thing. for free. no cap. 👑

✨ SYNOPSIS ✨

pgpool_setup [option...]

🌸 DESCRIPTION 🌸

so pgpool_setup spins up a temporary installation of a Pgpool-II cluster, and that bundle includes a Pgpool-II installation plus however many PostgreSQL installations you asked for, all chilling under the current directory. 🫶

bestie listen — the current directory has to be empty before you run pgpool_setup. empty empty. like, cleared.

🚨 also: pgpool_setup is for testing purpose only and should not be used to create production installations. do not do it. i'm serious. 💀

pgpool_setup executes ssh against localhost. so you need to configure ssh so it can login to localhost without password. set that up first or it's over. 🔑

right now pgpool_setup supports streaming replication mode, native replication mode, raw mode, logical replication mode and snapshot isolation mode. and if you want watchdog support? that's a whole different girl — see watchdog_setup(1) for details. 🦋

💅 OPTIONS 💅

pgpool_setup accepts the following command-line arguments:

-m mode — picks the running mode. mode can be r (native replication mode), s (streaming replication mode), n (raw mode), l (logical replication mode), or i (snapshot isolation mode). omit it and s is assumed. slay, default behavior. 🌈
-n num_clusters — how many PostgreSQL installations you want. omit it and 2 is used. ✌️
-p base_port — sets the base port number used by Pgpool-II and PostgreSQL. here's the math bestie: Pgpool-II port is base_port. pcp port is base_port + 1. the first PostgreSQL node's port is base_port + 2, second PostgreSQL node's port is base_port + 3 and so on. 📐

if the -pg option is specified, the first PostgreSQL node's port is assigned to pg_base_port, the second PostgreSQL node's port is pg_base_port + 1 and so on.

omit this and 11000 is used.

-pg pg_base_port — sets the base port number used by PostgreSQL. the first PostgreSQL node's port is base_port + 2, second PostgreSQL node's port is base_port + 3 and so on. 🔢

omit this and base_port+2 is used.

--no-stop — does not stop pgpool and PostgreSQL after the work. it just... leaves them running. main character energy, no cleanup era. 👑
-d — starts pgpool with debug mode. 🐛
-s — in streaming replication mode, use a replication slot instead of archive. here's why that matters: since the archive directory is shared by all PostgreSQL clusters, if a standby is promoted, the time line in the archive directory will be changed and other standby servers will be stopped. 😭 using a replication slot does not have this problem and is always preferable if you can use PostgreSQL 9.4 or later, which supports replication slot. the replication slot name used by pgpool_setup is pgpool_setup_slot. 🌟
-r — uses the pg_rewind command in the recovery script (basebackup.sh). if the command fails, it switches to using the ordinal rsync command. in certain cases recovery using pg_rewind is much faster than rsync since it does not copy the whole database cluster. ⚡
-e — omits creating the PostgreSQL database. this option is intended to be used by watchdog_setup and is probably useless for other purposes. iykyk. 🙈
-t — sets some additional parameters to pgpool.conf so that the regression test can perform tests against an existing installation. currently the parameter is health_check_test. 🧪
-c — uses the sample scripts and configuration files installed in /etc/pgpool-II/ directory. 📁

this option was added for the purpose of testing the sample scripts and configuration files contained in Pgpool-II RPM packages. so make sure you have installed the sample scripts and configuration files in /etc/pgpool-II/ directory before you specify this option. ⚠️

🌈 ENVIRONMENT VARIABLES 🌈

pgpool_setup recognizes the following environment variables:

PGPOOL_INSTALL_DIR — the Pgpool-II installation directory. Pgpool-II binaries are expected to be placed under PGPOOL_INSTALL_DIR/bin, and pgpool.conf and pool_hba.conf etc. are expected to be placed under PGPOOL_INSTALL_DIR/etc. the default is /usr/local. 🏠
PGPOOLDIR — the path to Pgpool-II configuration files. the default is PGPOOL_INSTALL_DIR/etc. 🗂️
PGBIN — the path to PostgreSQL commands such as initdb, pg_ctl and psql. the default is /usr/local/pgsql/bin. 🛠️
PGLIB — the path to PostgreSQL shared libraries. the default is /usr/local/pgsql/lib. 📚
PGSOCKET_DIR — the path to the Unix socket directory. the default is /tmp. 🔌
INITDBARG — the arguments for the initdb command. the default is "--no-locale -E UTF_8". ⚙️
USE_REPLICATION_SLOT — if "true", in streaming replication mode, use replication slot instead of archive. this brings the same effect as the -s option being specified. 🎰
USE_PG_REWIND — if "true", in streaming replication mode, use pg_rewind in the basebackup.sh script. this brings the same effect as the -r option being specified. 🌀
ENABLE_TEST — if "true", acts as if the -t option is specified. ✅
TEST_SAMPLES — if "true", acts as if the -c option is specified. ✅

🦋 EXAMPLE 🦋

okay this is the moment. watch her work:

$ pgpool_setup
PostgreSQL major version: 124
Starting set up in streaming replication mode
creating startall and shutdownall
creating failover script
creating database cluster /tmp/test/data0...done.
update postgresql.conf
creating pgpool_remote_start
creating basebackup.sh
creating recovery.conf
creating database cluster /tmp/test/data1...done.
update postgresql.conf
creating pgpool_remote_start
creating basebackup.sh
creating recovery.conf
temporarily start data0 cluster to create extensions
temporarily start pgpool-II to create standby nodes
 node_id | hostname | port  | status | lb_weight |  role   | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
---------+----------+-------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
 0       | /tmp     | 11002 | up     | 0.500000  | primary | 0          | true              | 0                 |                   |                        | 2020-08-18 13:50:19
 1       | /tmp     | 11003 | down   | 0.500000  | standby | 0          | false             | 0                 |                   |                        | 2020-08-18 13:50:18
(2 rows)

recovery node 1...pcp_recovery_node -- Command Successful
done.
creating follow primary script
 node_id | hostname | port  | status | lb_weight |  role   | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
---------+----------+-------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
 0       | /tmp     | 11002 | up     | 0.500000  | primary | 0          | true              | 0                 |                   |                        | 2020-08-18 13:50:19
 1       | /tmp     | 11003 | up     | 0.500000  | standby | 0          | false             | 0                 |                   |                        | 2020-08-18 13:50:23
(2 rows)

shutdown all

pgpool-II setting for streaming replication mode is done.
To start the whole system, use /tmp/test/startall.
To shutdown the whole system, use /tmp/test/shutdownall.
pcp command user name is "t-ishii", password is "t-ishii".
Each PostgreSQL, pgpool-II and pcp port is as follows:
#1 port is 11002
#2 port is 11003
pgpool port is 11000
pcp port is 11001
The info above is in README.port.
t-ishii$ ./startall
waiting for server to start....5744 2020-08-18 13:50:27 JST LOG:  starting PostgreSQL 12.4 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0, 64-bit
5744 2020-08-18 13:50:27 JST LOG:  listening on IPv4 address "0.0.0.0", port 11002
5744 2020-08-18 13:50:27 JST LOG:  listening on IPv6 address "::", port 11002
5744 2020-08-18 13:50:27 JST LOG:  listening on Unix socket "/tmp/.s.PGSQL.11002"
5744 2020-08-18 13:50:27 JST LOG:  redirecting log output to logging collector process
5744 2020-08-18 13:50:27 JST HINT:  Future log output will appear in directory "log".
 done
server started
waiting for server to start....5757 2020-08-18 13:50:27 JST LOG:  starting PostgreSQL 12.4 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0, 64-bit
5757 2020-08-18 13:50:27 JST LOG:  listening on IPv4 address "0.0.0.0", port 11003
5757 2020-08-18 13:50:27 JST LOG:  listening on IPv6 address "::", port 11003
5757 2020-08-18 13:50:27 JST LOG:  listening on Unix socket "/tmp/.s.PGSQL.11003"
5757 2020-08-18 13:50:27 JST LOG:  redirecting log output to logging collector process
5757 2020-08-18 13:50:27 JST HINT:  Future log output will appear in directory "log".
 done
server started
t-ishii$ psql -p 11000 test
psql (12.4)
Type "help" for help.

test=# show pool_nodes;
 node_id | hostname | port  | status | lb_weight |  role   | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
---------+----------+-------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
 0       | /tmp     | 11002 | up     | 0.500000  | primary | 0          | true              | 0                 |                   |                        | 2020-08-18 13:50:32
 1       | /tmp     | 11003 | up     | 0.500000  | standby | 0          | false             | 0                 | streaming         | async                  | 2020-08-18 13:50:32
(2 rows)

ate. periodt. 💅🔥

and that's the whole page bestie!! this one's from pgpool-II 4.7.2, dated 2023, and it's page PGPOOL_SETUP(1) of the manual. go build something cute in /tmp and remember — testing only, never production. mwah 🫶💖✨

📦 where this page comes from

ubuntu stonking: pgpool2 4.7.2-1build1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms