Connection Service File

A configuration file which enables the association of a "service" name with a set of libpq conninfo parameters

A connection service file (commonly referred to by its default filename, pg_service.conf) is a configuration file which enables the association of a "service" name with a set of libpq conninfo parameters.

This makes it possible to create aliases for different PostgreSQL servers, which are specified by providing the conninfo "service" parameter with the name of the defined service, for example: psql -d 'service=foo'.

Connection parameters defined in the connection service file can be overridden by specifying them explictly, for example: psql -d 'service=foo user=bar'.


The connection service file is a simple .ini-file format with the section name serving as the user-defined connection name, followed by a list of key/value pairs representing libpq conninfo parameters, e.g.:



The connection service file will be searched for in the following locations:

  • Per-user file at ~/.pg_service.conf or the location specified by the environment variable PGSERVICEFILE
  • System-wide file at `pg_config --sysconfdir`/pg_service.conf or in the directory specified by the environment variable PGSYSCONFDIR

Services defined in per-user files override services defined in system-wide files.

File locations specified by the environment variables PGSERVICEFILE and PGSYSCONFDIR will override the respective defaults. There is no fallback to the default file if the file is not found in the specified location.


  • There is no way to define a setting which applies to more than one section
  • Cannot be used by JDBC

Change history


A very minimal annotated pg_service.conf sample file is provided in the source code at src/interfaces/libpq/pg_service.conf.sample.


Configuration, Database connections