From: khushi-git-7 (@khushi-git-7) <noreply+khushi-git-7@github.com>
To: patroni/patroni <noreply+patroni-patroni@github.com>
Subject: [patroni/patroni] PR #3787: Accept a Windows drive-letter path as a unix socket directory
Date: Mon, 16 Nov 2026 15:44:05 +0000
Message-ID: <gh-patroni-patroni-3787@github.com> (raw)
Part of #3759: the Windows unix socket half, so that `use_unix_socket` and `use_unix_socket_repl` work there as @CyberDem0n suggested.
**The problem.** On Windows, a socket directory in `unix_socket_directories` is a drive-letter path such as `C:/pgsock`. libpq accepts that as a socket directory (PostgreSQL 13+). But `_get_unix_local_address()` only took a directory starting with `/`, so Patroni silently fell back to TCP. With `sslmode: verify-full`, that brings back the `localhost` certificate error from #3759.
**The change** (`patroni/postgresql/config.py`):
- A small helper, `is_unix_socket_path(host)`, returns `host.startswith('/') or os.path.isabs(host)`. On POSIX that's the same as before. On Windows it also accepts a drive-letter path. The `/` check stays because Python 3.13+ on Windows no longer treats `/x` as absolute, while libpq still does.
- It's used in the three places that decide whether a host is a socket directory:
- `_get_unix_local_address()`;
- the `.pgpass` rule that adds a `localhost` line for a socket. It now checks the hosts before they're escaped, since `C:` becomes `C\:` there.
- the custom-bootstrap `pg_hba` guard, which would otherwise call `getaddrinfo('C:/pgsock')`.
- A relative path, or `C:pgsock` (relative to drive C's current directory), still isn't a socket directory, so it falls back to TCP as before.
- `docs/yaml_configuration.rst`: the `use_unix_socket`/`use_unix_socket_repl` entries say what a suitable directory is, with `C:/pgsock` as the example.
**Tests** (`tests/test_postgresql.py`), with `os.path.isabs` patched to `ntpath.isabs` for the Windows cases:
- a new `test__get_unix_local_address`, covering `/` paths, a relative path, drive-letter paths with `/` and `\`, and `C:pgsock`;
- a Windows case in `test__pgpass_content` and in `test_resolve_connection_addresses`.
On my fork, `tests/test_postgresql.py` and `tests/test_config.py` pass on ubuntu-24.04 and windows-latest, with Python 3.8 and 3.12, and flake8 is clean on the changed files. With master's `config.py`, the three changed tests fail. I haven't run it against a real PostgreSQL on Windows.
The other half of #3759, relaxing `verify-full` to `verify-ca` for localhost connections, isn't in this PR.
inline patch 1: docs/yaml_configuration.rst, patroni/postgresql/config.py, tests/test_postgresql.py (+45/-7 lines) download inline-1.patchdiff --git a/docs/yaml_configuration.rst b/docs/yaml_configuration.rstindex 8751e4b3a..c61559676 100644--- a/docs/yaml_configuration.rst+++ b/docs/yaml_configuration.rst@@ -319,8 +319,8 @@ PostgreSQL
- **pg\_isready**: (optional) Custom name for ``pg_isready`` binary.
- **pg\_rewind**: (optional) Custom name for ``pg_rewind`` binary.
- **listen**: IP address + port that Postgres listens to; must be accessible from other nodes in the cluster, if you're using streaming replication. Multiple comma-separated addresses are permitted, as long as the port component is appended after to the last one with a colon, i.e. ``listen: 127.0.0.1,127.0.0.2:5432``. Patroni will use the first address from this list to establish local connections to the PostgreSQL node.
- - **use\_unix\_socket**: specifies that Patroni should prefer to use unix sockets to connect to the cluster. Default value is ``false``. If ``unix_socket_directories`` is defined, Patroni will use the first suitable value from it to connect to the cluster and fallback to tcp if nothing is suitable. If ``unix_socket_directories`` is not specified in ``postgresql.parameters``, Patroni will assume that the default value should be used and omit ``host`` from the connection parameters.- - **use\_unix\_socket\_repl**: specifies that Patroni should prefer to use unix sockets for replication user cluster connection. Default value is ``false``. If ``unix_socket_directories`` is defined, Patroni will use the first suitable value from it to connect to the cluster and fallback to tcp if nothing is suitable. If ``unix_socket_directories`` is not specified in ``postgresql.parameters``, Patroni will assume that the default value should be used and omit ``host`` from the connection parameters.+ - **use\_unix\_socket**: specifies that Patroni should prefer to use unix sockets to connect to the cluster. Default value is ``false``. If ``unix_socket_directories`` is defined, Patroni will use the first suitable value from it (an absolute path, which on Windows includes one starting with a drive letter, such as ``C:/pgsock``) to connect to the cluster and fallback to tcp if nothing is suitable. If ``unix_socket_directories`` is not specified in ``postgresql.parameters``, Patroni will assume that the default value should be used and omit ``host`` from the connection parameters.+ - **use\_unix\_socket\_repl**: specifies that Patroni should prefer to use unix sockets for replication user cluster connection. Default value is ``false``. If ``unix_socket_directories`` is defined, Patroni will use the first suitable value from it (an absolute path, which on Windows includes one starting with a drive letter, such as ``C:/pgsock``) to connect to the cluster and fallback to tcp if nothing is suitable. If ``unix_socket_directories`` is not specified in ``postgresql.parameters``, Patroni will assume that the default value should be used and omit ``host`` from the connection parameters.
- **pgpass**: path to the `.pgpass <https://www.postgresql.org/docs/current/static/libpq-pgpass.html;`__ password file. Patroni creates this file before executing pg\_basebackup, the post_init script and under some other circumstances. The location must be writable by Patroni.
- **recovery\_conf**: additional configuration settings written to recovery.conf when configuring follower.
- **custom\_conf** : path to an optional custom ``postgresql.conf`` file, that will be used in place of ``postgresql.base.conf``. The file must exist on all cluster nodes, be readable by PostgreSQL and will be included from its location on the real ``postgresql.conf``. Note that Patroni will not monitor this file for changes, nor backup it. However, its settings can still be overridden by Patroni's own configuration facilities - see :ref:`dynamic configuration <patroni_configuration>` for details.
diff --git a/patroni/postgresql/config.py b/patroni/postgresql/config.pyindex 2f562269f..a68f988bd 100644--- a/patroni/postgresql/config.py+++ b/patroni/postgresql/config.py@@ -277,6 +277,19 @@ def mtime(filename: str) -> Optional[float]:
return None
+def is_unix_socket_path(host: str) -> bool:+ """Check whether *host* is a unix socket directory rather than a host name or an IP address.++ ``libpq`` treats an absolute path as a unix socket directory. On Windows that includes a path that starts with a+ drive letter, such as ``C:/pgsock``, which unix sockets support there since PostgreSQL 13.++ :param host: value of the ``host`` connection parameter or one item of ``unix_socket_directories``.++ :returns: ``True`` if *host* is an absolute path on this platform.+ """+ return host.startswith('/') or os.path.isabs(host)++
class ConfigWriter(object):
"""Write a configuration file atomically.
@@ -662,7 +675,8 @@ def replace_pg_hba(self) -> Optional[bool]:
# and in order to be able to change it, we are opening trust access from a certain address
if self._postgresql.bootstrap.running_custom_bootstrap:
addresses = {} if os.name == 'nt' else {'': 'local'} # windows doesn't yet support unix-domain sockets
- if 'host' in self.local_replication_address and not self.local_replication_address['host'].startswith('/'):+ if 'host' in self.local_replication_address \+ and not is_unix_socket_path(self.local_replication_address['host']):
addresses.update({sa[0] + '/32': 'host' for _, _, _, _, sa in getaddrinfo(
self.local_replication_address['host'], self.local_replication_address['port'],
0, socket.SOCK_STREAM, socket.IPPROTO_TCP)})
@@ -1046,9 +1060,11 @@ def escape(value: Any) -> str:
return re.sub(r'([:\\])', r'\\\1', str(value))
# 'host' could be several comma-separated hostnames, in this case we need to write on pgpass line per host
- hosts = [escape(host) for host in filter(None, map(str.strip,- (record.get('host', '') or '*').split(',')))] # pyright: ignore [reportUnknownArgumentType]- if any(host.startswith('/') for host in hosts) and 'localhost' not in hosts:+ raw_hosts = [host for host in filter(None, map(str.strip,+ (record.get('host', '') or '*').split(',')))] # pyright: ignore [reportUnknownArgumentType]+ hosts = [escape(host) for host in raw_hosts]+ # libpq looks up a connection via a unix socket under "localhost"+ if any(is_unix_socket_path(host) for host in raw_hosts) and 'localhost' not in hosts:
hosts.append('localhost')
record = {n: escape(record.get(n) or '*') for n in ('port', 'user', 'password')}
return ''.join('{host}:{port}:*:{user}:{password}\n'.format(**record, host=host) for host in hosts)
@@ -1192,7 +1208,7 @@ def get_server_parameters(self, config: Dict[str, Any]) -> CaseInsensitiveDict:
def _get_unix_local_address(unix_socket_directories: str) -> str:
for d in unix_socket_directories.split(','):
d = d.strip()
- if d.startswith('/'): # Only absolute path can be used to connect via unix-socket+ if is_unix_socket_path(d): # Only absolute path can be used to connect via unix-socket
return d
return ''
diff --git a/tests/test_postgresql.py b/tests/test_postgresql.pyindex dfced2f85..08879cb44 100644--- a/tests/test_postgresql.py+++ b/tests/test_postgresql.py@@ -1,5 +1,6 @@
import datetime
import logging
+import ntpath
import os
import re
import stat
@@ -291,6 +292,11 @@ def test_write_pgpass(self):
def test__pgpass_content(self):
pgpass = self.p.config._pgpass_content({'host': '/tmp', 'port': '5432', 'user': 'foo', 'password': 'bar'})
self.assertEqual(pgpass, "/tmp:5432:*:foo:bar\nlocalhost:5432:*:foo:bar\n")
+ # a Windows socket directory with a drive letter is looked up under "localhost" too+ with patch('os.path.isabs', ntpath.isabs):+ pgpass = self.p.config._pgpass_content({'host': 'C:/pgsock', 'port': '5432', 'user': 'foo',+ 'password': 'bar'})+ self.assertEqual(pgpass, "C\\:/pgsock:5432:*:foo:bar\nlocalhost:5432:*:foo:bar\n")
def test_checkpoint(self):
with patch.object(MockCursor, 'fetchone', Mock(return_value=(True, ))):
@@ -898,6 +904,11 @@ def test_resolve_connection_addresses(self):
self.p.config._config['use_unix_socket'] = self.p.config._config['use_unix_socket_repl'] = True
self.p.config.resolve_connection_addresses()
self.assertEqual(self.p.config.local_replication_address, {'host': '/tmp', 'port': '5432'})
+ # a Windows socket directory with a drive letter, as libpq accepts it there+ with patch('os.path.isabs', ntpath.isabs):+ self.p.config._server_parameters['unix_socket_directories'] = 'C:/pgsock'+ self.p.config.resolve_connection_addresses()+ self.assertEqual(self.p.config.local_replication_address, {'host': 'C:/pgsock', 'port': '5432'})
self.p.config._server_parameters.pop('unix_socket_directories')
self.p.config.resolve_connection_addresses()
self.assertEqual(self.p.connection_pool.conn_kwargs,
@@ -905,6 +916,17 @@ def test_resolve_connection_addresses(self):
'options': '-c statement_timeout=2000 -c pg_stat_statements.track=none',
'password': 'test', 'port': '5432', 'user': 'foo'})
+ def test__get_unix_local_address(self):+ get = self.p.config._get_unix_local_address+ self.assertEqual(get('/tmp'), '/tmp')+ self.assertEqual(get('relative, /var/run/postgresql'), '/var/run/postgresql')+ self.assertEqual(get('relative'), '') # only an absolute path can be used, so fall back to TCP+ with patch('os.path.isabs', ntpath.isabs): # what Windows accepts as an absolute path+ self.assertEqual(get('C:/pgsock'), 'C:/pgsock')+ self.assertEqual(get('relative, C:\\pgsock'), 'C:\\pgsock')+ self.assertEqual(get('/tmp'), '/tmp')+ self.assertEqual(get('C:pgsock'), '') # relative to the current directory of drive C:+
@patch.object(Postgresql, '_version_file_exists', Mock(return_value=True))
def test_get_major_version(self):
with patch('builtins.open', mock_open(read_data='9.4')):