From 3b34e98242446bcc2827f081e72342cc7af57574 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Sat, 10 Jan 2009 20:14:30 +0000 Subject: [PATCH] Modify libpq environment variable documentation to point to the relevant connection options documentation section, per idea from Magnus. --- doc/src/sgml/libpq.sgml | 181 +++++++++++++++------------------------- 1 file changed, 69 insertions(+), 112 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index dc04b00629..0a4379a76b 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -101,7 +101,7 @@ The currently recognized parameter key words are: - + host @@ -119,7 +119,7 @@ - + hostaddr @@ -160,7 +160,7 @@ - + port @@ -171,7 +171,7 @@ - + dbname @@ -180,7 +180,7 @@ - + user @@ -191,7 +191,7 @@ - + password @@ -200,7 +200,7 @@ - + connect_timeout @@ -211,16 +211,20 @@ - + options - Command-line options to be sent to the server. + Adds command-line options to send to the server at run-time. + For example, setting this to -c geqo=off sets the + session's value of the geqo parameter to + off. For a detailed discussion of the available + options, consult . - + tty @@ -229,7 +233,7 @@ - + sslmode @@ -259,7 +263,7 @@ - + sslverify @@ -295,7 +299,7 @@ - + requiressl @@ -317,7 +321,7 @@ - + sslcert @@ -327,7 +331,7 @@ - + sslkey @@ -342,7 +346,7 @@ - + sslrootcert @@ -351,7 +355,7 @@ - + sslcrl @@ -361,7 +365,7 @@ - + krbsrvname @@ -374,7 +378,7 @@ - + gsslib @@ -385,7 +389,7 @@ - + service @@ -5627,11 +5631,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGHOST - 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). + PGHOST behaves the same as connection parameter. @@ -5640,17 +5641,10 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGHOSTADDR - 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. + PGHOSTADDR behaves the same as connection parameter. + This can be set instead of or in addition to PGHOST + to avoid DNS lookup overhead. @@ -5659,9 +5653,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGPORT - PGPORT sets the TCP port number or Unix-domain socket - file extension for communicating with the - PostgreSQL server. + PGPORT behaves the same as connection parameter. @@ -5670,9 +5663,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGDATABASE - PGDATABASE sets the - PostgreSQL database name. - + PGDATABASE behaves the same as connection parameter. + @@ -5680,7 +5673,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGUSER - PGUSER sets the user name used to connect to the + PGUSER behaves the same as connection parameter. database. @@ -5690,11 +5684,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGPASSWORD - PGPASSWORD sets the password used if the server - demands password authentication. Use of this environment variable + PGPASSWORD behaves the same as connection parameter. + 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 + ps); instead consider using the ~/.pgpass file (see ). @@ -5715,10 +5710,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICE - PGSERVICE - sets the service name to be looked up in - pg_service.conf. This offers a shorthand way - of setting all the parameters. + PGSERVICE behaves the same as connection parameter. @@ -5727,12 +5720,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREALM - PGREALM sets the Kerberos realm to use with + 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 + libpq applications will attempt authentication with servers for this realm and use separate ticket - files to avoid conflicts with local ticket files. This + files to avoid conflicts with local ticket files. This environment variable is only used if Kerberos authentication is selected by the server. @@ -5743,12 +5736,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGOPTIONS - PGOPTIONS sets additional run-time options for the - PostgreSQL server. For example, setting - PGOPTIONS to -c geqo=off sets the session's - value of the geqo parameter to off. - For a detailed discussion of the available options consult . + PGOPTIONS behaves the same as connection parameter. @@ -5757,20 +5746,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLMODE - 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. + PGSSLMODE behaves the same as connection parameter. @@ -5779,14 +5756,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLVERIFY - PGSSLVERIFY controls how libpq verifies the certificate on the - server when performing an SSL connection. There are - three options: none disables verification completely - (not recommended!); cert enables verification that - the certificate chains to a known CA only; cn will - both verify that the certificate chains to a known CA and that - the cn attribute of the certificate matches the - hostname the connection is being made to (default). + PGSSLVERIFY behaves the same as connection parameter. @@ -5795,13 +5766,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL - 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. + PGREQUIRESSL behaves the same as connection parameter. @@ -5810,8 +5776,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLCERT - PGSSLCERT specifies the location for the client - certificate to use if the server requests one. + PGSSLCERT behaves the same as connection parameter. @@ -5820,13 +5786,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLKEY - PGSSLKEY specifies the location for the secret key - used for the client certificate. It can either specify a filename - that will be used instead of the default - ~/.postgresql/postgresql.key, or can specify an external - engine (engines are OpenSSL loadable modules). The - external engine specification should consist of a colon-separated - engine name and an engine-specific key identifier. + PGSSLKEY behaves the same as connection parameter. @@ -5835,8 +5796,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLROOTCERT - PGSSLROOTCERT specifies the file name where the SSL - root certificate is stored. + PGSSLROOTCERT behaves the same as connection parameter. @@ -5845,8 +5806,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLCRL - PGSSLCRL specifies the file name where the SSL certificate - revocation list is stored. + PGSSLCRL behaves the same as connection parameter. @@ -5855,8 +5816,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGKRBSRVNAME - PGKRBSRVNAME sets the Kerberos service name to use - when authenticating with Kerberos 5 or GSSAPI. + PGKRBSRVNAME behaves the same as connection parameter. @@ -5865,8 +5826,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGSSLIB - PGGSSLIB sets the GSS library to use for GSSAPI - authentication. + PGGSSLIB behaves the same as connection parameter. @@ -5875,12 +5836,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGCONNECT_TIMEOUT - 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. + PGCONNECT_TIMEOUT behaves the same as connection parameter. -- 2.40.0