The following environment variables can be used to select default
connection parameter values, which will be used by
PQconnectdb
, PQsetdbLogin
and
PQsetdb
if no value is directly specified by the calling
code. These are useful to avoid hard-coding database connection
information into simple client applications, for example.
PGHOST
sets the database server name.
If this begins with a slash, it specifies Unix-domain communication
rather than TCP/IP communication; the value is then the name of the
directory in which the socket file is stored (in a default installation
setup this would be /tmp
).
PGHOSTADDR
specifies the numeric IP address of the database
server. This can be set instead of or in addition to PGHOST
to avoid DNS lookup overhead. See the documentation of
these parameters, under PQconnectdb
above, for details
on their interaction.
When neither PGHOST
nor PGHOSTADDR
is set,
the default behavior is to connect using a local Unix-domain socket; or on
machines without Unix-domain sockets, libpq will
attempt to connect to localhost
.
PGPORT
sets the TCP port number or Unix-domain
socket file extension for communicating with the
PostgreSQL server.
PGPASSWORD
sets the password used if the server demands password
authentication. Use of this environment variable is not
recommended for security reasons (some operating systems
allow non-root users to see process environment variables via
ps); instead consider using the
~/.pgpass
file (see Section 29.13, “The Password File”).
PGPASSFILE
specifies the name of the password file to use for lookups.
If not set, it defaults to ~/.pgpass
(see Section 29.13, “The Password File”).
PGSERVICE
sets the service name to be looked up in pg_service.conf
.
This offers a shorthand way of setting all the parameters.
PGREALM
sets the Kerberos realm to use with
PostgreSQL, if it is different from the local realm.
If PGREALM
is set, libpq
applications will attempt authentication with servers for this realm and use
separate ticket files to avoid conflicts with local
ticket files. This environment variable is only
used if Kerberos authentication is selected by the server.
PGOPTIONS
sets additional run-time options for
the PostgreSQL server.
PGSSLMODE
determines whether and with what priority an
SSL connection will be negotiated with the server. There are
four modes: disable
will attempt only an unencrypted
SSL connection; allow
will negotiate,
trying first a non-SSL connection, then if that fails,
trying an SSL connection; prefer
(the default) will negotiate, trying first an SSL
connection, then if that fails, trying a regular non-SSL
connection; require
will try only an SSL
connection. If PostgreSQL is compiled without SSL support,
using option require
will cause an error, while options
allow
and prefer
will be accepted but
libpq will not in fact attempt an SSL
connection.
PGREQUIRESSL
sets whether or not the connection must be
made over SSL. If set to
“1”, libpq
will refuse to connect if the server does not accept
an SSL connection (equivalent to sslmode
prefer
).
This option is deprecated in favor of the sslmode
setting, and is only available if
PostgreSQL is compiled with SSL support.
PGKRBSRVNAME
sets the Kerberos service name to use when
authenticating with Kerberos 5.
PGCONNECT_TIMEOUT
sets the maximum number of seconds
that libpq will wait when attempting to
connect to the PostgreSQL server. If unset
or set to zero, libpq will wait indefinitely.
It is not recommended to set the timeout to less than 2 seconds.
The following environment variables can be used to specify default behavior for each PostgreSQL session. (See also the ALTER USER and ALTER DATABASE commands for ways to set default behavior on a per-user or per-database basis.)
PGDATESTYLE
sets the default style of date/time representation.
(Equivalent to SET datestyle TO ...
.)
PGTZ
sets the default time zone.
(Equivalent to SET timezone TO ...
.)
PGCLIENTENCODING
sets the default client character set encoding.
(Equivalent to SET client_encoding TO ...
.)
PGGEQO
sets the default mode for the genetic query optimizer.
(Equivalent to SET geqo TO ...
.)
Refer to the SQL command SET for information on correct values for these environment variables.
The following environment variables determine internal behavior of libpq; they override compiled-in defaults.