Patroni

-------------

Released 2025-02-20

**Stability improvements**

- Compatibility with ``python-json-logger>=3.1`` (Alexander Kukushkin)

Get rid of the warnings produced by the old API usage.

- Compatibility with Python 3.13 (Alexander Kukushkin)

Run tests against Python 3.13.

- Compatibility with ``pyinstaller>=4.4`` (Joe Jensen)

Fall back to the default ``iter_modules`` if ``pyinstaller`` ``toc`` attribute is not present.

- Fix issues with PostgreSQL 9.5 support (Alexander Kukushkin)

- Properly handle ``pg_rewind`` output format.
- Consider ``synchronous_standby_names`` format not supporting "num" specification.

- Compatibility with the latest changes in ``urlparse`` (Alexander Kukushkin)

``urlparse`` doesn't accept multiple hosts with ``[]`` character in URL anymore. To mitigate the problem, switch to the native wrappers of ``PQconninfoParse()`` from ``libpq``, when it is possible, and use our implementation only for older ``psycopg2`` versions that are linked with an outdated version of ``libpq``.


**Bugfixes**

- Show only the members to be restarted upon restart confirmation (András Váczi)

Previously, when doing ``patronictl restart <clustername> --pending``, the confirmation listed all members, regardless of whether their restart is pending.

- Cancel long-running jobs on Patroni stop and remove data directory on replica bootstrap failure (Alexander Kukushkin)

Previously, Patroni could be doing replica bootstrap, while ``pg_basebackup`` / ``wal-g`` / ``pgBackRest`` / ``barman`` or similar keep running.

- Properly handle cluster names with a slash in ``patronictl edit-config`` (Antoni Mur)

Replace a forward slash in ``cluster_name`` with an underscore.

- Avoid dropping physical slots too early (Alexander Kukushkin)

Postpone removal of physical replication slots containing ``xmin`` after a failover: on the new primary -- until this member is promoted, on replicas -- until there is a leader in the cluster.

- Handle all exceptions raised by subprocess in ``controldata()`` (Alexander Kukushkin)

Patroni was not properly handling all exceptions possibly raised when calling ``pg_controldata`` utility.

- Fix bug with a slot for a former leader not retained on failover (Alexander Kukushkin)

Avoid falsely relying on members being present in DCS, while on failover ``/member`` key for the former leader is expiring exactly at the same time.

- Fix a couple of bugs in the quorum state machine (Alexander Kukushkin)

- When evaluating whether there are healthy nodes for a leader race, before demoting we need to take into account quorum requirements. Without it, the former leader may end up in recovery surrounded by asynchronous nodes.
- ``QuorumStateResolver`` wasn't correctly handling the case when a replica node quickly joined and disconnected.


**Improvements**

- Improve error on am empty or non-dictionary configuration file (Julian)

Throw a more explicit exception when validating if Patroni configuration file contains a valid ``Mapping`` object.

-------------

Released 2024-11-22

**Stability improvements**

- Add compatibility with the ``py-consul`` module (Alexander Kukushkin)

``python-consul`` module is unmaintained for a long time, while ``py-consul`` is the official replacement. Backward compatibility with python-consul is retained.

- Add compatibility with the ``prettytable>=3.12.0`` module (Alexander Kukushkin)

Address deprecation warnings.

- Compatibility with the ``ydiff==1.4.2`` module (Alexander Kukushkin)

Fix compatibility issues for the latest version, constrain version in ``requirements.txt``, and introduce latest version compatibility test.

**Bugfixes**

- Run ``on_role_change`` callback after a failed primary recovery (Polina Bungina, Alexander Kukushkin)

Additionally run ``on_role_change`` callback for a primary that failed to start after a crash to increase chances the callback is executed, even if the further start as a replica fails.

- Fix a thread leak in ``patronictl list -W`` (Alexander Kukushkin)

Cache DCS instance object to avoid thread leak.

- Ensure only supported parameters are written to the connection string (Alexander Kukushkin)

Patroni used to pass parameters introduced in newer versions to the connection string, which had been leading to connection errors.

-------------

Released 2024-10-18

**Bugfixes**

- Disable ``pgaudit`` when creating users not to expose password (kviset)

Patroni was logging ``superuser``, ``replication``, and ``rewind`` passwords on their creation when ``pgaudit`` extension was enabled.

- Fix issue with mixed setups: primary on pre-Patroni v4 and replicas on v4+ (Alexander Kukushkin)

Use ``xlog_location`` extracted from ``/members`` key instead of trying to get a member's slot position from ``/status`` key if Patroni version running on the leader is pre-4.0.0. Not doing so has been causing WALs accumulation on replicas.

- Do not ignore valid PostgreSQL GUCs that don't have Patroni validator (Polina Bungina)

Still check against ``postgres --describe-config`` if a GUC does not have a Patroni validator but is, in fact, a valid GUC.


**Improvements**

- Recheck annotations on 409 status code when reading leader object in K8s (Alexander Kukushkin)

Avoid an additional update if ``PATCH`` request was canceled by Patroni, while the request successfully updated the target.

- Add support of ``sslnegotiation`` client-side connection option (Alexander Kukushkin)

``sslnegotiation`` was added to the final PostgreSQL 17 release.

-------------

Released 2024-09-17

**Bugfixes**

- Handle exceptions while discovering configuration validation files (Alexander Kukushkin)

Skip directories for which Patroni does not have sufficient permissions to perform list operations.

- Make sure inactive hot physical replication slots don't hold ``xmin`` (Alexander Kukushkin, Polina Bungina)

Since version 3.2.0 Patroni creates physical replication slots for all members on replicas and periodically moves them forward using ``pg_replication_slot_advance()`` function. However if for any reason ``hot_standby_feedback`` is enabled and the primary is demoted to replica, the now inactive slots have ``NOT NULL`` ``xmin`` value propagated back to the new primary. This results in ``xmin`` horizon not being moved forward and vacuum not being able to clean up dead tuples. With this fix, Patroni recreates the physical replication slots that are supposed to be inactive but have ``NOT NULL`` ``xmin`` value.

- Fix unhandled ``DCSError`` during the startup phase (Waynerv)

Ensure DCS connectivity before trying to check the uniqueness of the node name.

- Explicitly include ``CMDLINE_OPTIONS`` GUCs when querying ``pg_settings`` (Alexander Kukushkin)

Make sure all GUCs that are passed to postmaster as command line parameters are restored when Patroni is joining a running standby. This is a follow-up for the bug fixed in Patroni 3.2.2.

- Fix bug in ``synchronous_standby_names`` quotting logic (Alexander Kukushkin)

According to PostgreSQL documentation, ``ANY`` and ``FIRST`` keywords are supposed to be double-quoted, which Patroni did not do before.

- Fix keepalive connection out-of-range issue (hadizamani021)

Ensure that ``keepalive`` option value calculated based on the ``ttl`` set does not exceed the maximum allowed value for the current platform.

-------------

Released 2024-08-30

**Bugfix**

- Patroni was creating unnecessary replication slots for itself (Alexander Kukushkin)

It was happening if ``name`` contains upper-case or special characters.

-------------

Released 2024-08-29

.. warning::
- This version completes work on getting rid of the "master" term, in favor of "primary". This means a couple of breaking changes, please read the release notes carefully. Upgrading to the Patroni 4+ will work reliably only if you run Patroni 3.1.0 or newer. Upgrading from an older version directly to 4+ is possible but may lead to unexpected behavior if the primary fails while the rest of the nodes are running on other Patroni versions.


**Breaking changes**

- The following breaking changes were introduced when getting rid of the non-inclusive "master" term in the Patroni code:

- On Kubernetes, Patroni by default will set ``role`` label to ``primary``. In case if you want to keep the old behavior and avoid downtime or lengthy complex migrations, you can configure parameters ``kubernetes.leader_label_value`` and ``kubernetes.standby_leader_label_value`` to ``master``. Read more :ref:`here <kubernetes_role_values>`.
- Patroni role is written to DCS as ``primary`` instead of ``master``.
- Patroni role returned by Patroni REST API has been changed from ``master`` to ``primary``.
- Patroni REST API no longer accepts ``role=master`` in requests to ``/switchover``, ``/failover``, ``/restart`` endpoints.
- ``/metrics`` REST API endpoint will no longer report ``patroni_master`` metric.
- ``patronictl`` no longer accepts ``--master`` option for any command. ``--leader`` or ``--primary`` options should be used instead.
- ``no_master`` option in the declarative configuration of custom replica creation methods is no longer treated as a special option, please use ``no_leader`` instead.
- ``patroni_wale_restore`` script doesn't accept ``--no_master`` option anymore.
- ``patroni_barman`` script doesn't accept ``--role=master`` option anymore.
- All callback scripts are executed with ``role=primary`` option passed instead of ``role=master``.

- ``patronictl failover`` does not accept ``--leader`` option that was deprecated since Patroni 3.2.0.

- User creation functionality (``bootstrap.users`` configuration section) deprecated since Patroni 3.2.0 has been removed.


**New features**

- Quorum-based failover (Ants Aasma, Alexander Kukushkin)

The feature implements quorum-based synchronous replication (available from PostgreSQL v10) which helps to reduce worst-case latencies, even during normal operation, as a higher latency of replicating to one standby can be compensated by other standbys. Patroni implements additional safeguards to prevent any user-visible data loss by choosing a failover candidate based on the latest transaction received.

- Register Citus secondaries in ``pg_dist_node`` (Alexander Kukushkin)

Patroni now maintains the list of nodes with ``role==replica``, ``state==running`` and without ``noloadbalance`` :ref:`tag <tags_settings>` in ``pg_dist_node``.

- Configurable retention of members' replication slots (Alexander Kukushkin)

Implements support of ``member_slots_ttl`` global configuration parameter that controls for how long member replication slots should be kept around when the member key is absent.

- Make permissions of log files created by Patroni configurable (Alexander Kukushkin)

Allows to set specific permissions for log files created by Patroni. If not specified, permissions are set based on the current ``umask`` value.

- Compatibility with PostgreSQL 17 beta3 (Alexander Kukushkin)

GUC's validator rules were extended. Patroni handles all the new auxiliary backends during shutdown and sets ``dbname`` in ``primary_conninfo``, as it is required for logical replication slots synchronization.

- Implement ``--ignore-listen-port`` option for Patroni config validation (Sahil Naphade)

Make it possible to ignore already bound ports when running ``patroni --validate-config``.


**Improvements**

- Make ``wal_log_hints`` configurable (Paul_Kim)

Allows to avoid the overhead of ``wal_log_hints`` configuration being enabled in case ``use_pg_rewind`` is set to ``off``.

- Log ``pg_basebackup`` command in ``DEBUG`` level (Waynerv)

Facilitates failed initialization debugging.


**Bugfixes**

- Advance permanent slots for cascading nodes while in failsafe (Alexander Kukushkin)

Ensure that slots for cascading replicas are properly advanced on the primary when failsafe mode is activated. It is done by extending replicas response on ``POST /failsafe`` REST API request with their ``xlog_location``.

- Don't let the current node be chosen as synchronous (Alexander Kukushkin)

There may be "something" streaming from the current primary node with ``application_name`` that matches the name of the current primary. Patroni was not properly handling this situation, which could end up in the primary being declared as a synchronous node and consequently was blocking switchovers.

- Ignore ``restapi.allowlist_include_members`` for POST /failsafe (Alexander Kukushkin)

- Improve GUCs validation (Polina Bungina)

Due to additional validation through running ``postgres --describe-config`` command, it was previously not possible to set GUCs not listed there through Patroni configuration. This limitation is now removed.

- Add line with ``localhost`` to ``.pgpass`` file when unix sockets are detected (Alexander Kukushkin)

Patroni will add an additional line to ``.pgpass`` file if ``host`` parameter specified starts with ``/`` character. This allows to cover a corner case when ``host`` matches the default socket directory path.

- Fix logging issues (Waynerv)

Defined proper request URL in failsafe handling logs and fixed the order of timestamps in postmaster check log.