pgpool-II 4.7.2 Documentation
Prev | Up | Appendix A. Release Notes | Next

# A.3. Release 4.7.0

> Release Date: 2025-12-23

## A.3.1. Overview

This release of Pgpool-II includes several enhancements, such as the removal of the legacy Slony mode, strengthened security, enhanced frontend/backend protocol compatibility, and improved operational transparency.

Major enhancements are as follows:

- Retire Slony mode.

- Rename `logdir` parameter to `work_dir`.

- Add support for frontend/backend protocol version 3.2.

- Enhance security for watchdog and heartbeat receiver.

- Add new fields to `pcp_proc_info` and `show pool_pools` to display client information, and add `pgpool_adm_pcp_proc_info` extension function.

- Make online recovery database configurable.

- Import PostgreSQL 18's SQL parser.

## A.3.2. Migration to Version 4.7

- Retire `Slony` mode. (Tatsuo Ishii)

  Previously Pgpool-II accepted `slony` mode as one of the backend_clustering_mode to support `Slony-I` (https://www.slony.info/). However the latest `Slony-I` was released in 2022, nearly 3 years ago at this point. And we heard nothing from users about retiring `Slony` mode. This suggests that there would be no active `Slony-I` mode users. So let's drop `Slony-I` support.

  Discussion: [pgpool-general: 9486] Retiring slony mode

  Discussion: Re: [pgpool-general: 9486] Retiring slony mode

- Change log_pcp_processes default to `off`. (Tatsuo Ishii)

  Previously `log_pcp_processes` default was `on`, and it could produce excessive log lines if admins use pcp commands frequently to monitor pgpool status. Also the log is kind of debugging message, thus it is best to change its default value to `off`.

  Discussion: Proposal: change log_pcp_processes default to off

- Make online recovery database configurable. (Bo Peng)

  A new configuration parameter recovery_database has been added to allow users to specify the database used for online recovery. Previously, this value was hardcoded as `template1`. The default is now set to `postgres`.

  For users migrating from versions earlier than 4.6, compatibility can be maintained by setting `recovery_database = 'template1'`, or by creating the necessary extension for online recovery in the `postgres` database.

- Rename `logdir` parameter to work_dir. (Taiki Koshino)

  Previously, the directory for storing `pgpool_status` and lock files was specified by the `logdir` parameter. However, since the name `logdir` was misleading, the parameter has been renamed to `work_dir` for clarity. The default value is `/tmp`, which is the same as the previous parameter `logdir`.

  For backward compatibility, the old `logdir` parameter is still supported. If the old parameter `logdir` is used, Pgpool-II will set its value to `work_dir` and throw a warning message.

## A.3.3. Changes

- Import PostgreSQL 18 new parser. (Bo Peng)

  Major changes of PostgreSQL 18 parser include:

  - Allow generated columns to be virtual

  - Add OLD/NEW support to RETURNING in DML queries

  - Addition of various constraints (e.g. WITHOUT OVERLAPS, ENFORCED / NOT ENFORCED)

  - etc.

- Restrict watchdog and heartbeat receiver to listen only on configured addresses. (Bo Peng)

  Previously, both the watchdog and heartbeat receiver processes listen on all interfaces. For security reasons, they now listen only on the addresses specified by `hostname` and `heartbeat_hostname`.

- Cleanup watchdog source code. (Tatsuo Ishii)

  - Remove wd_is_upper_ok() from wd_utils.h because there's no actual definition for it.

  - Make wd_get_ping_result() and wd_issue_ping_command() static. It's only used in wd_ping.c.

- Emit warning if life check has not started yet. (Tatsuo Ishii)

  Currently lifecheck emits a log only when life check becomes ready. This is inconvenient for admins since they need to keep on watching log file until life check is ready. This commit makes the life check process to emit additional warnings periodically until life check has started. The interval of the warnings is wd_interval * 10 seconds. However for the first time at lifecheck starting, no warning is emitted since it is likely that lifecheck is not ready at that point.

- Add support for frontend/backend protocol 3.2. (Tatsuo Ishii)

  - Implement NegotiateProtocolVersion message.

    Implementing the message is necessary when frontend requests the protocol version 3.2 (i.e. PostgreSQL 18+ or compatible clients), while backend still only supports 3.0 (i.e. backend is PostgreSQL 17 or before).

    This commit handles the message so that the message is forwarded from backend to frontend when there's no connection cache exists.

    If connection cache exists, pgpool sends the message, which has been saved at the time when the connection cache was created, to frontend.

    Discussion: Feature: implement NegotiateProtocolVersion message

  - Implement protocol version 3.2 BackendKeyData and query cancel message.

    Starting from PostgreSQL 18, frontend/backend protocol has been changed to 3.2. In the changes the BackendKeyData and query cancel message are modified to allow variable length cancel key.

    This commit implements the changes and now we can connect to PostgreSQL frontend and backend using 3.2 protocol.

        Example session is:
        PGMAXPROTOCOLVERSION="3.2" psql -p 11000 test

    Discussion: Implement protocol 3.2 BackendKeyData and cancel request message

- Add pgpool_adm_pcp_proc_info. (Tatsuo Ishii)

  This commit adds new pgpool_adm extension function: pcp_proc_info. Also add new fields: client_host, client_port and SQL statement to pcp_proc_info and "show pool_pools". With these additions now it is possible to track the relationship among clients of pgpool, pgpool itself and PostgreSQL.

  Moreover the commit allows to know what commands (statements) are last executed by using pcp_proc_info. Previously it was not possible unless looking into the pgpool log.

  lipcp.so version is bumped from 2.0.0 to 3.0.0.

- Enhance lifecheck log. (Tatsuo Ishii)

  Previously when wd_lifecheck_method = 'query', life checking prints SQL without application name if "%a" is specified in log_line_prefix. This commit add application_name "lifecheck_ping" to make the log looks better. Since this changes user visible behavior, I do not apply this to stable branches.

  Discussion: [pgpool-hackers: 4603] life check log is not nicea

- Replace random() with pg_prng random function. (Martijn van Duren, Tatsuo Ishii)

  Previously we used random() for choosing load balancing node. However PostgreSQL has better random number generator: pg_prng.c. This commit imports the file and use pg_prng_double() to generate random number in range [0.0, 1.0). The seed is generated using pg_strong_random().

  Discussion: [pgpool-hackers: 4588] Shuffle random functions and use better random numbers

- Retry bind on watchdog receive socket. (Tatsuo Ishii)

  Occasionally 028.watchdog_enable_consensus_with_half_votes times out due to failure on binding watchdog receive socket. This commit tries to mitigate the issue by retrying bind. Currently the retry is performed up to 5 times and each retry is with 1 second sleep.

- Import likely/unlikely from PostgreSQL. (Tatsuo Ishii)

  These macros are not only useful to enhance performance (if correctly used) but make porting codes from PostgreSQL to pgpool easier since the macros occasionally used in the code.

  Discussion: [pgpool-hackers: 4599] Porting likely/unlikely

- Replace PostmasterRandom() with pg_strong_random(). (Tatsuo Ishii)

  Our PostmasterRandmon() was imported from PostgreSQL long time ago (in 2016). In the same year PostgreSQL replaced PostmasterRandmon() with pg_strong_random()(src/port/pg_strong_random.c). This commit follows it.

  Discussion: [pgpool-hackers: 4588] Shuffle random functions and use better random numbers

- Fall back to prompting for password if reading from `.pcppass` file fails. (Bo Peng)

  If reading password from `.pcppass` file fails, it should fall back to prompting the user for input, similar to how PostgreSQL handles `.pgpass`.

  This commit also changes the following messages to be displayed without requiring the `-d` option:

      WARNING: password file \"%s\" is not a plain file
      WARNING: password file \"%s\" has group or world access; permissions should be u=rw (0600) or less

  Discussion: [pgpool-hackers: 4589] If reading password from .pcppass file fails, try to read it from prompt.

- Remove or downgrade inappropriate log messages at pgpool startup. (Tatsuo Ishii)

- Add major version information to the configuration file. (Bo Peng)

## A.3.4. Documents

- Fix documentation for `enum` parameters reported as `strings`. (Taiki Koshino)

  Fix documentations for 6 parameters:

      log_standby_delay
      log_backend_messages
      wd_lifecheck_method
      memqcache_method
      disable_load_balance_on_write
      backend_clustering_mode

- Enhance query cache doc. (Tatsuo Ishii)

  Pgpool refuses to cache a query calling functions returning `TIMESTAMP WITH TIMEZONE`, `TIME WITH TIMEZONE`. If there are multiple functions having same name and one of them returns `TIMESTAMP WITH TIMEZONE`, `TIME WITH TIMEZONE`, pgpool refuses to cache even if one of them does not return the data types. So add a note on this along with workaround.

## A.3.5. Test Tools

- Allow to specify VIP in watchdog_setup. (Tatsuo Ishii)

  This commit allows to specify VIP parameter (`delegate_ip`) in `watchdog_setup` using new option `-vip [ip]`. If ip is omitted, `127.0.0.1` is assumed. Even if vip option is specified, pgpool will not actually set the VIP to the system: if_up_cmd, if_down_cmd are just set to echo command and do nothing except emit a log. This option is intended to trace the action of Pgpool-II regarding VIP handling.

  Discussion: Enhance watchdog_setup

## A.3.6. Regression Tests

- Fix 038.pcp_commands regression test. (Tatsuo Ishii)

  The result of the test showed local host IP. Although the IP can be either IPv4 or IPv6, the test script hadn't considered it. To fix this, now test.sh converts IPv4 and IPv6 IP to "localhost".

- Stabilize 029.cert_passphrase regression test. (Tatsuo Ishii)

  When ssl_passphrase_command is not valid, the error message is typically "bad decrypt" but it seems sometimes "wrong tag".

Prev | Home | Next
Release 4.7.1 | Up | Release 4.6.7