1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>28.11.Environment Variables</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="libpq.html" title="Chapter28.libpq - C Library">
<link rel="prev" href="libpq-notice-processing.html" title="28.10.Notice Processing">
<link rel="next" href="libpq-pgpass.html" title="28.12.The Password File">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="libpq-envars"></a>28.11.Environment Variables</h2></div></div></div>
<a name="id685730"></a><p>The following environment variables can be used to select default
connection parameter values, which will be used by
<code class="function">PQconnectdb</code>, <code class="function">PQsetdbLogin</code> and
<code class="function">PQsetdb</code> 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.
</p>
<div class="itemizedlist"><ul type="disc">
<li><p><a name="id685771"></a>
<code class="envar">PGHOST</code> 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 <code class="filename">/tmp</code>).</p></li>
<li>
<p><a name="id685796"></a>
<code class="envar">PGHOSTADDR</code> specifies the numeric IP address of the database
server. This can be set instead of or in addition to <code class="envar">PGHOST</code>
to avoid DNS lookup overhead. See the documentation of
these parameters, under <code class="function">PQconnectdb</code> above, for details
on their interaction.</p>
<p>When neither <code class="envar">PGHOST</code> nor <code class="envar">PGHOSTADDR</code> is set,
the default behavior is to connect using a local Unix-domain socket; or on
machines without Unix-domain sockets, <span class="application">libpq</span> will
attempt to connect to <code class="literal">localhost</code>.</p>
</li>
<li><p><a name="id685853"></a>
<code class="envar">PGPORT</code> sets the TCP port number or Unix-domain
socket file extension for communicating with the
<span class="productname">PostgreSQL</span> server.</p></li>
<li><p><a name="id685876"></a>
<code class="envar">PGDATABASE</code> sets the
<span class="productname">PostgreSQL</span> database name.</p></li>
<li><p><a name="id685899"></a>
<code class="envar">PGUSER</code>
sets the user name used to connect to the database.</p></li>
<li><p><a name="id685915"></a>
<code class="envar">PGPASSWORD</code>
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
<span class="application">ps</span>); instead consider using the
<code class="filename">~/.pgpass</code> file (see <a href="libpq-pgpass.html" title="28.12.The Password File">Section28.12, “The Password File”</a>).</p></li>
<li><p><a name="id685954"></a>
<code class="envar">PGPASSFILE</code>
specifies the name of the password file to use for lookups.
If not set, it defaults to <code class="filename">~/.pgpass</code>
(see <a href="libpq-pgpass.html" title="28.12.The Password File">Section28.12, “The Password File”</a>).</p></li>
<li><p><a name="id685984"></a>
<code class="envar">PGSERVICE</code>
sets the service name to be looked up in <code class="filename">pg_service.conf</code>.
This offers a shorthand way of setting all the parameters.</p></li>
<li><p><a name="id686008"></a>
<code class="envar">PGREALM</code> sets the Kerberos realm to use with
<span class="productname">PostgreSQL</span>, if it is different from the local realm.
If <code class="envar">PGREALM</code> is set, <span class="application">libpq</span>
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.</p></li>
<li><p><a name="id686046"></a>
<code class="envar">PGOPTIONS</code> sets additional run-time options for
the <span class="productname">PostgreSQL</span> server.</p></li>
<li><p><a name="id686068"></a>
<code class="envar">PGSSLMODE</code> determines whether and with what priority an
<acronym class="acronym">SSL</acronym> connection will be negotiated with the server. There are
four modes: <code class="literal">disable</code> will attempt only an unencrypted
<acronym class="acronym">SSL</acronym> connection; <code class="literal">allow</code> will negotiate,
trying first a non-<acronym class="acronym">SSL</acronym> connection, then if that fails,
trying an <acronym class="acronym">SSL</acronym> connection; <code class="literal">prefer</code>
(the default) will negotiate, trying first an <acronym class="acronym">SSL</acronym>
connection, then if that fails, trying a regular non-<acronym class="acronym">SSL</acronym>
connection; <code class="literal">require</code> will try only an <acronym class="acronym">SSL</acronym>
connection. If <span class="productname">PostgreSQL</span> is compiled without SSL support,
using option <code class="literal">require</code> will cause an error, while options
<code class="literal">allow</code> and <code class="literal">prefer</code> will be accepted but
<span class="application">libpq</span> will not in fact attempt an <acronym class="acronym">SSL</acronym>
connection.</p></li>
<li><p><a name="id686182"></a>
<code class="envar">PGREQUIRESSL</code> sets whether or not the connection must be
made over <acronym class="acronym">SSL</acronym>. If set to
“<span class="quote">1</span>”, <span class="application">libpq</span>
will refuse to connect if the server does not accept
an <acronym class="acronym">SSL</acronym> connection (equivalent to <code class="literal">sslmode</code>
<code class="literal">prefer</code>).
This option is deprecated in favor of the <code class="literal">sslmode</code>
setting, and is only available if
<span class="productname">PostgreSQL</span> is compiled with SSL support.</p></li>
<li><p><a name="id686245"></a>
<code class="envar">PGKRBSRVNAME</code> sets the Kerberos service name to use when
authenticating with Kerberos 5.</p></li>
<li><p><a name="id686262"></a>
<code class="envar">PGCONNECT_TIMEOUT</code> sets the maximum number of seconds
that <span class="application">libpq</span> will wait when attempting to
connect to the <span class="productname">PostgreSQL</span> server. If unset
or set to zero, <span class="application">libpq</span> will wait indefinitely.
It is not recommended to set the timeout to less than 2 seconds.</p></li>
</ul></div>
<p>The following environment variables can be used to specify default
behavior for each <span class="productname">PostgreSQL</span> session.
(See also the
<a href="sql-alteruser.html">ALTER USER</a> and
<a href="sql-alterdatabase.html">ALTER DATABASE</a>
commands for ways to set default behavior on a per-user or per-database
basis.)
</p>
<div class="itemizedlist"><ul type="disc">
<li><p><a name="id686336"></a>
<code class="envar">PGDATESTYLE</code>
sets the default style of date/time representation.
(Equivalent to <code class="literal">SET datestyle TO ...</code>.)</p></li>
<li><p><a name="id686359"></a>
<code class="envar">PGTZ</code>
sets the default time zone.
(Equivalent to <code class="literal">SET timezone TO ...</code>.)</p></li>
<li><p><a name="id686381"></a>
<code class="envar">PGCLIENTENCODING</code>
sets the default client character set encoding.
(Equivalent to <code class="literal">SET client_encoding TO ...</code>.)</p></li>
<li><p><a name="id686405"></a>
<code class="envar">PGGEQO</code>
sets the default mode for the genetic query optimizer.
(Equivalent to <code class="literal">SET geqo TO ...</code>.)</p></li>
</ul></div>
<p>
Refer to the <acronym class="acronym">SQL</acronym> command
<a href="sql-set.html">SET</a>
for information on correct values for these environment variables.</p>
<p>The following environment variables determine internal behavior of
<span class="application">libpq</span>; they override compiled-in defaults.
</p>
<div class="itemizedlist"><ul type="disc">
<li><p><a name="id686456"></a>
<code class="envar">PGSYSCONFDIR</code>
sets the directory containing the <code class="filename">pg_service.conf</code> file.</p></li>
<li><p><a name="id686479"></a>
<code class="envar">PGLOCALEDIR</code>
sets the directory containing the <code class="literal">locale</code> files for message
internationalization.</p></li>
</ul></div>
</div></body>
</html>
|
