containers/bitnami/pgpool

Bitnami Secure Image for Pgpool-II

Pgpool-II is the PostgreSQL proxy. It stands between PostgreSQL servers and their clients providing connection pooling, load balancing, automated failover, and replication.

Overview of Pgpool-II Trademarks: This software listing is packaged by Bitnami. The respective trademarks mentioned in the offering are owned by the respective companies, and use of them does not imply any affiliation or endorsement.

TL;DR

Docker Compose

docker run --name pgpool bitnami/pgpool:latest

You can find the default credentials and available configuration options in the Environment Variables section.

Why use Bitnami Secure Images?

Those are hardened, minimal CVE images built and maintained by Bitnami. Bitnami Secure Images are based on the cloud-optimized, security-hardened enterprise OS Photon Linux. Why choose BSI images?

• Hardened secure images of popular open source software with Near-Zero Vulnerabilities
• Vulnerability Triage & Prioritization with VEX Statements, KEV and EPSS Scores
• Compliance focus with FIPS, STIG, and air-gap options, including secure bill of materials (SBOM)
• Software supply chain provenance attestation through in-toto
• First class support for the internet’s favorite Helm charts

Each image comes with valuable security metadata. You can view the metadata in our public catalog here. Note: Some data is only available with commercial subscriptions to BSI.

If you are looking for our previous generation of images based on Debian Linux, please see the Bitnami Legacy registry.

How to deploy Pgpool-II in Kubernetes?

Deploying Bitnami applications as Helm Charts is the easiest way to get started with our applications on Kubernetes. Read more about the installation in the Bitnami PostgreSQL HA Chart GitHub repository.

Why use a non-root container?

Non-root container images add an extra layer of security and are generally recommended for production environments. However, because they run as a non-root user, privileged tasks are typically off-limits. Learn more about non-root containers in our docs.

Supported tags and respective Dockerfile links

Learn more about the Bitnami tagging policy and the difference between rolling tags and immutable tags in our documentation page.

Get this image

The recommended way to get the Bitnami Pgpool-II Docker Image is to pull the prebuilt image from the Docker Hub Registry.

docker pull bitnami/pgpool:latest

To use a specific version, you can pull a versioned tag. You can view the list of available versions in the Docker Hub Registry.

docker pull bitnami/pgpool:[TAG]

If you wish, you can also build the image yourself by cloning the repository, changing to the directory containing the Dockerfile and executing the docker build command. Remember to replace the APP, VERSION and OPERATING-SYSTEM path placeholders in the example command below with the correct values.

git clone https://github.com/bitnami/containers.git
cd bitnami/APP/VERSION/OPERATING-SYSTEM
docker build -t bitnami/APP:latest .

Using docker-compose.yaml

Please be aware this file has not undergone internal testing. Consequently, we advise its use exclusively for development or testing purposes.

Connecting to other containers

Using Docker container networking, a different server running inside a container can easily be accessed by your application containers and vice-versa.

Containers attached to the same network can communicate with each other using the container name as the hostname.

Configuration

The following section describes how to configure the application

Initializing with custom scripts

Everytime the container is started, it will execute the files with extension .sh located at /docker-entrypoint-initdb.d after initializing Pgpool-II.

Securing Pgpool-II traffic

Pgpool-II supports the encryption of connections using the SSL/TLS protocol. Should you desire to enable this optional feature, you may use the following environment variables to configure the application:

• PGPOOL_ENABLE_TLS: Whether to enable TLS for traffic or not. Defaults to no.
• PGPOOL_TLS_CERT_FILE: File containing the certificate file for the TLS traffic. No defaults.
• PGPOOL_TLS_KEY_FILE: File containing the key for certificate. No defaults.
• PGPOOL_TLS_CA_FILE: File containing the CA of the certificate. If provided, Pgpool-II will authenticate TLS/SSL clients by requesting them a certificate (see ref). No defaults.
• PGPOOL_TLS_PREFER_SERVER_CIPHERS: Whether to use the server's TLS cipher preferences rather than the client's. Defaults to yes.

When enabling TLS, Pgpool-II will support both standard and encrypted traffic by default, but prefer the latter.

Alternatively, you may also provide this configuration in your custom configuration file.

Configuration file

You can override the default configuration by providing a configuration file. Set PGPOOL_USER_CONF_FILE with the path of the file, and this will be added to the default configuration. You can also override the default hba configuration by providing a hba configuration file. Set PGPOOL_USER_HBA_FILE with the path of the file, and this will overwrite the default hba configuration.

Refer to the server configuration manual for the complete list of configuration options.

Re-attaching nodes

Pgpool-II does not reattach nodes automatically, to reattach a node you have to get the id of the node and then run the attach command manually.

Step 1: Get the node id

To get the node id first connect to the pgpool container and open a psql session:

docker exec -it pgpool bash

PGPASSWORD=$PGPOOL_POSTGRES_PASSWORD psql -U $PGPOOL_POSTGRES_USERNAME -h localhost

and run: show pool_nodes;

postgres=# 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       | pg-0     | 5432 | down     | 0.500000  | standby | 0          | true              | 0                 |                   |                        | 2020-07-09 15:50:41
 1       | pg-1     | 5432 | up       | 0.500000  | primary | 0          | false             | 0                 |                   |                        | 2020-07-09 15:48:31
(2 rows)

In this example pg-0 is the node we want to reattach, we will use node 0.

Step 2: reattach the node

Now exit psql console and run the following command, 0 is the node id we got in the previous step.

pcp_attach_node -h localhost -U $PGPOOL_ADMIN_USERNAME 0

This command will prompt for a password, this password is the one set in the environment variable: PGPOOL_ADMIN_PASSWORD

Environment variables

The following tables list the main variables you can set.

Customizable environment variables

Name	Description	Default Value
PGPOOL_WORK_DIR	Pgpool-II working directory.	/tmp
PGPOOL_USER_CONF_FILE	Custom Pgpool-II configuration file to be appended at Pgpool-II configuration file.	nil
PGPOOL_USER_HBA_FILE	Custom Pgpool-II host-based authentication configuration to be appended to Pgpool-II host-based authentication configuration file.	nil
PGPOOL_PASSWD_FILE	Pgpool-II pool password file.	pool_passwd
PGPOOL_PORT_NUMBER	Pgpool-II port number.	5432
PGPOOL_ENABLE_POOL_HBA	Enable Pgpool-II host-based authentication.	yes
PGPOOL_ENABLE_POOL_PASSWD	Enable Pgpool-II pool password.	yes
PGPOOL_ENABLE_LOAD_BALANCING	Enable Load-Balancing.	yes
PGPOOL_ENABLE_STATEMENT_LOAD_BALANCING	Enable Statement Load-Balancing.	no
PGPOOL_DISABLE_LOAD_BALANCE_ON_WRITE	Disable Load-Balancing on write queries.	transaction
PGPOOL_ENABLE_CONNECTION_CACHE	Enable Pgpool-II connection cache.	yes
PGPOOL_TIMEOUT	Pgpool-II timeout (in seconds).	360
PGPOOL_CONNECT_TIMEOUT	Pgpool-II connection timeout (in milliseconds).	10000
PGPOOL_MAX_POOL	Pgpool-II maximum number of cached connections.	15
PGPOOL_HEALTH_CHECK_PERIOD	Pgpool-II Health Check period (in seconds).	30
PGPOOL_HEALTH_CHECK_TIMEOUT	Pgpool-II Health Check timeout (in seconds).	10
PGPOOL_HEALTH_CHECK_MAX_RETRIES	Pgpool-II Health Check max retries.	5
PGPOOL_HEALTH_CHECK_RETRY_DELAY	Pgpool-II Health Check retry delay (in seconds).	5
PGPOOL_HEALTH_CHECK_PSQL_TIMEOUT	Pgpool-II Health Check psql timeout (in seconds).	15
PGPOOL_AUTO_FAILBACK	Enable Pgpool-II auto_failback on false primaries detection.	no
PGPOOL_DISCARD_STATUS	Discard Pgpool-II status file on restarts.	yes
PGPOOL_SR_CHECK_USER	Pgpool-II Streaming Replication Check username.	nil
PGPOOL_SR_CHECK_PASSWORD	Pgpool-II Streaming Replication Check password.	nil
PGPOOL_SR_CHECK_DATABASE	Pgpool-II Streaming Replication Check database.	postgres
PGPOOL_SR_CHECK_PERIOD	Pgpool-II Streaming Replication Check period (in seconds).	30
PGPOOL_HEALTH_CHECK_USER	Pgpool-II Health Check username.	$PGPOOL_SR_CHECK_USER
PGPOOL_HEALTH_CHECK_PASSWORD	Pgpool-II Health Check password.	$PGPOOL_SR_CHECK_PASSWORD
PGPOOL_ADMIN_USERNAME	Pgpool-II Admin username.	nil
PGPOOL_ADMIN_PASSWORD	Pgpool-II Admin password.	nil
PGPOOL_POSTGRES_USERNAME	PostgreSQL backend admin username.	postgres
PGPOOL_POSTGRES_PASSWORD	PostgreSQL backend admin password.	nil
PGPOOL_POSTGRES_CUSTOM_USERS	Comma, semi-colon or space separated list of custom users to create.	nil
PGPOOL_POSTGRES_CUSTOM_PASSWORDS	Comma, semi-colon or space separated list of passwords for the custom users to create.	nil
PGPOOL_ENABLE_LDAP	Enable LDAP on Pgpool-II.	no
PGPOOL_AUTHENTICATION_METHOD	Pgpool-II authentication method.	scram-sha-256
PGPOOL_AES_KEY	Pgpool-II AES key.	head -c 20 /dev/urandom | base64
PGPOOL_ENABLE_TLS	Enable TLS on Pgpool-II.	no
PGPOOL_TLS_CA_FILE	Pgpool-II TLS authentication CA file.	nil
PGPOOL_TLS_CERT_FILE	Pgpool-II TLS authentication cert file.	nil
PGPOOL_TLS_KEY_FILE	Pgpool-II TLS authentication key file.	nil
PGPOOL_TLS_PREFER_SERVER_CIPHERS	Prefer server TLS authentication ciphers.	yes
PGPOOL_ENABLE_LOG_CONNECTIONS	Enable Pgpool-II log connections	no
PGPOOL_ENABLE_LOG_HOSTNAME	Show clients hostnames on Pgpool-II connections logs.	no
PGPOOL_ENABLE_LOG_PCP_PROCESSES	Enable PCP processes logging.	yes
PGPOOL_ENABLE_LOG_PER_NODE_STATEMENT	Enable logging every SQL statement for each DB node separately.	no
PGPOOL_BACKEND_NODES	Comma, semi-colon or space separated list of PostgreSQL backend nodes.	nil
PGPOOL_BACKEND_APPLICATION_NAMES	Comma, semi-colon or space separated list of PostgreSQL backend application names.	nil
PGPOOL_FAILOVER_ON_BACKEND_SHUTDOWN	Enable failover recovery on backend shutdown.	on
PGPOOL_FAILOVER_ON_BACKEND_ERROR	Enable failover recovery on backend error.	off
PGPOOL_DAEMON_USER	Pgpool-II daemon user	pgpool
PGPOOL_DAEMON_GROUP	Pgpool-II daemon group	pgpool

Read-only environment variables

Name	Description	Value
PGPOOL_BASE_DIR	Pgpool-II installation directory.	${BITNAMI_ROOT_DIR}/pgpool
PGPOOL_BIN_DIR	Pgpool-II binaries directory.	${PGPOOL_BASE_DIR}/bin
PGPOOL_DATA_DIR	Pgpool-II data directory.	${PGPOOL_BASE_DIR}/data
PGPOOL_DEFAULT_CONF_DIR	Pgpool-II default configuration directory.	${PGPOOL_BASE_DIR}/conf.default
PGPOOL_CONF_DIR	Pgpool-II configuration directory.	${PGPOOL_BASE_DIR}/conf
PGPOOL_DEFAULT_ETC_DIR	Pgpool-II default etc directory.	${PGPOOL_BASE_DIR}/etc.default
PGPOOL_ETC_DIR	Pgpool-II etc directory.	${PGPOOL_BASE_DIR}/etc
PGPOOL_LOG_DIR	Pgpool-II logs directory.	${PGPOOL_BASE_DIR}/logs
PGPOOL_TMP_DIR	Pgpool-II temporary directory.	${PGPOOL_BASE_DIR}/tmp
PGPOOL_INITSCRIPTS_DIR	Pgpool-II init scripts directory.	/docker-entrypoint-initdb.d
PGPOOL_CONF_FILE	Pgpool-II configuration file.	${PGPOOL_CONF_DIR}/pgpool.conf
PGPOOL_PCP_CONF_FILE	Performance Co-Pilot (PCP) configuration file.	${PGPOOL_ETC_DIR}/pcp.conf
PGPOOL_PGHBA_FILE	Pgpool-II host-based authentication configuration file.	${PGPOOL_CONF_DIR}/pool_hba.conf
PGPOOL_LOG_FILE	Pgpool-II log file.	${PGPOOL_LOG_DIR}/pgpool.log
PGPOOL_PID_FILE	Pgpool-II pid file.	${PGPOOL_TMP_DIR}/pgpool.pid
PGPOOLKEYFILE	Pgpool-II pool key file.	${PGPOOL_CONF_DIR}/.pgpoolkey

FIPS configuration in Bitnami Secure Images

The Bitnami Pgpool-II Docker image from the Bitnami Secure Images catalog includes extra features and settings to configure the container with FIPS capabilities. You can configure the next environment variables:

• OPENSSL_FIPS: whether OpenSSL runs in FIPS mode or not. yes (default), no.

Logging

The Bitnami Pgpool-II Docker image sends the container logs to stdout. To view the logs:

docker logs pgpool

You can configure the containers logging driver using the --log-driver option if you wish to consume the container logs differently. In the default configuration docker uses the json-file driver.

Notable Changes

4.3.1-debian-10-r67

• The ENV PGPOOL_AUTHENTICATION_METHOD default value has been changed from md5 to scram-sha-256 as our bitnami/postgresql-repmgr:latest image now uses PSQL v14, which has scram-sha-256 as the default auth method.

4.1.1-debian-10-r35

• The Pgpool container has been migrated to a "non-root" user approach. Previously the container ran as the root user and the Pgpool daemon was started as the pgpool user. From now on, both the container and the Pgpool daemon run as user 1001. You can revert this behavior by changing USER 1001 to USER root in the Dockerfile.
• No backwards compatibility issues are expected.
• Environment variables related to LDAP configuration were renamed removing the PGPOOL_ prefix. For instance, to indicate the LDAP URI to use, you must set LDAP_URI instead of PGPOOL_LDAP_URI.

4.1.0-centos-7-r8

• 4.1.0-centos-7-r8 is considered the latest image based on CentOS.
• Standard supported distros: Debian & OEL.

License

Copyright © 2026 Broadcom. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.