unix_socket_directories

Definition PG 18 manual

Specifies the directory of the Unix-domain socket(s) on which the server is to listen for connections from client applications. Multiple sockets can be created by listing multiple directories separated by commas. Whitespace between entries is ignored; surround a directory name with double quotes if you need to include whitespace or commas in the name. An empty value specifies not listening on any Unix-domain sockets, in which case only TCP/IP sockets can be used to connect to the server.

A value that starts with @ specifies that a Unix-domain socket in the abstract namespace should be created (currently supported on Linux only). In that case, this value does not specify a “directory” but a prefix from which the actual socket name is computed in the same manner as for the file-system namespace. While the abstract socket name prefix can be chosen freely, since it is not a file-system location, the convention is to nonetheless use file-system-like values such as @/tmp.

The default value is normally /tmp, but that can be changed at build time. On Windows, the default is empty, which means no Unix-domain socket is created by default. This parameter can only be set at server start.

In addition to the socket file itself, which is named .s.PGSQL.nnnn where nnnn is the server's port number, an ordinary file named .s.PGSQL.nnnn.lock will be created in each of the unix_socket_directories directories. Neither file should ever be removed manually. For sockets in the abstract namespace, no lock file is created.

How it works

unix_socket_directories sets the directories where Unix-domain sockets will be created. PostgreSQL creates one socket and lock file per listed directory at startup; a value beginning with @ selects an abstract namespace on supported systems.

unix_socket_directories is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

Unix-socket reachability combines directory existence and traversal rights, socket group and mode, the server account, and client search paths; pg_hba.conf local records still authenticate users.

Operational considerations

Expecting a reload or SET to activate unix_socket_directories, although it requires a controlled server restart.

Opening the socket mode broadly while overlooking directory traversal, group membership, and pg_hba.conf local authentication.

Adding a volatile or missing directory and preventing server startup or confusing local clients after restart.

Changing unix_socket_directories globally without a rollback plan and a client or operational compatibility test.

Workload guidance

OLAP: Use the same reviewed local-access boundary for analytical tools; add a directory or group only when its client and operating-system lifecycle are managed.

OLTP: Configure unix_socket_directories as one Unix-socket access policy: choose trusted directories, ownership, group membership, and modes, then test local poolers, monitoring, backup, and administration.

SMALL: Keep unix_socket_directories simple and least-privileged. A local socket avoids TCP overhead only marginally and should not be made world-accessible for convenience.