Re: Duplicated docs on libpq parameters - Mailing list pgsql-hackers
| From | Bruce Momjian |
|---|---|
| Subject | Re: Duplicated docs on libpq parameters |
| Date | |
| Msg-id | 200901102014.n0AKEmH23476@momjian.us Whole thread Raw |
| In response to | Re: Duplicated docs on libpq parameters (Magnus Hagander <magnus@hagander.net>) |
| List | pgsql-hackers |
Magnus Hagander wrote: > Tom Lane wrote: > > Magnus Hagander <magnus@hagander.net> writes: > >> Any reason not to just have the environment variable documentation refer > >> back to the connection option documentation? > > > > Well, not all of 'em are connection options. > > > > I could see documenting the connection options more like the > > GUC-variable options, ie a few words and a reference to the underlying > > option. Or is that what you meant? > > Well, I was mostly thinking like: > PGSSLMODE > This corresponds to the <link>sslmode</link> connection option. > > Then for those that aren't connection options, we'd keep the full > description. I'm not advocating we remove the whole chapter, just the > duplicated stuff. (I assume we can make the link above go directly to > the description for the option?) Done, with attached, applied patch. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: doc/src/sgml/libpq.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v retrieving revision 1.274 diff -c -c -r1.274 libpq.sgml *** doc/src/sgml/libpq.sgml 15 Dec 2008 10:28:21 -0000 1.274 --- doc/src/sgml/libpq.sgml 10 Jan 2009 20:09:58 -0000 *************** *** 101,107 **** The currently recognized parameter key words are: <variablelist> ! <varlistentry> <term><literal>host</literal></term> <listitem> <para> --- 101,107 ---- The currently recognized parameter key words are: <variablelist> ! <varlistentry id="libpq-connect-host" xreflabel="host"> <term><literal>host</literal></term> <listitem> <para> *************** *** 119,125 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>hostaddr</literal></term> <listitem> <para> --- 119,125 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-hostaddr" xreflabel="hostaddr"> <term><literal>hostaddr</literal></term> <listitem> <para> *************** *** 160,166 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>port</literal></term> <listitem> <para> --- 160,166 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-port" xreflabel="port"> <term><literal>port</literal></term> <listitem> <para> *************** *** 171,177 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>dbname</literal></term> <listitem> <para> --- 171,177 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-dbname" xreflabel="dbname"> <term><literal>dbname</literal></term> <listitem> <para> *************** *** 180,186 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>user</literal></term> <listitem> <para> --- 180,186 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-user" xreflabel="user"> <term><literal>user</literal></term> <listitem> <para> *************** *** 191,197 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>password</literal></term> <listitem> <para> --- 191,197 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-password" xreflabel="password"> <term><literal>password</literal></term> <listitem> <para> *************** *** 200,206 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>connect_timeout</literal></term> <listitem> <para> --- 200,206 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-connect-timeout" xreflabel="connect_timeout"> <term><literal>connect_timeout</literal></term> <listitem> <para> *************** *** 211,226 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>options</literal></term> <listitem> <para> ! Command-line options to be sent to the server. </para> </listitem> </varlistentry> ! <varlistentry> <term><literal>tty</literal></term> <listitem> <para> --- 211,230 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-options" xreflabel="options"> <term><literal>options</literal></term> <listitem> <para> ! Adds command-line options to send to the server at run-time. ! For example, setting this to <literal>-c geqo=off</> sets the ! session's value of the <varname>geqo</> parameter to ! <literal>off</>. For a detailed discussion of the available ! options, consult <xref linkend="runtime-config">. </para> </listitem> </varlistentry> ! <varlistentry id="libpq-connect-tty" xreflabel="tty"> <term><literal>tty</literal></term> <listitem> <para> *************** *** 229,235 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>sslmode</literal></term> <listitem> <para> --- 233,239 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-sslmode" xreflabel="sslmode"> <term><literal>sslmode</literal></term> <listitem> <para> *************** *** 259,265 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>sslverify</literal></term> <listitem> <para> --- 263,269 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-sslverify" xreflabel="sslverify"> <term><literal>sslverify</literal></term> <listitem> <para> *************** *** 295,301 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>requiressl</literal></term> <listitem> <para> --- 299,305 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-requiressl" xreflabel="requiressl"> <term><literal>requiressl</literal></term> <listitem> <para> *************** *** 317,323 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>sslcert</literal></term> <listitem> <para> --- 321,327 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-sslcert" xreflabel="sslcert"> <term><literal>sslcert</literal></term> <listitem> <para> *************** *** 327,333 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>sslkey</literal></term> <listitem> <para> --- 331,337 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-sslkey" xreflabel="sslkey"> <term><literal>sslkey</literal></term> <listitem> <para> *************** *** 342,348 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>sslrootcert</literal></term> <listitem> <para> --- 346,352 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-sslrootcert" xreflabel="sslrootcert"> <term><literal>sslrootcert</literal></term> <listitem> <para> *************** *** 351,357 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>sslcrl</literal></term> <listitem> <para> --- 355,361 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-sslcrl" xreflabel="sslcrl"> <term><literal>sslcrl</literal></term> <listitem> <para> *************** *** 361,367 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>krbsrvname</literal></term> <listitem> <para> --- 365,371 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-krbsrvname" xreflabel="krbsrvname"> <term><literal>krbsrvname</literal></term> <listitem> <para> *************** *** 374,380 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>gsslib</literal></term> <listitem> <para> --- 378,384 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-gsslib" xreflabel="gsslib"> <term><literal>gsslib</literal></term> <listitem> <para> *************** *** 385,391 **** </listitem> </varlistentry> ! <varlistentry> <term><literal>service</literal></term> <listitem> <para> --- 389,395 ---- </listitem> </varlistentry> ! <varlistentry id="libpq-connect-service" xreflabel="service"> <term><literal>service</literal></term> <listitem> <para> *************** *** 5627,5637 **** <indexterm> <primary><envar>PGHOST</envar></primary> </indexterm> ! <envar>PGHOST</envar> 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 <filename>/tmp</filename>). </para> </listitem> --- 5631,5638 ---- <indexterm> <primary><envar>PGHOST</envar></primary> </indexterm> ! <envar>PGHOST</envar> behaves the same as <xref ! linkend="libpq-connect-host"> connection parameter. </para> </listitem> *************** *** 5640,5656 **** <indexterm> <primary><envar>PGHOSTADDR</envar></primary> </indexterm> ! <envar>PGHOSTADDR</envar> specifies the numeric IP address of the database ! server. This can be set instead of or in addition to <envar>PGHOST</envar> ! to avoid DNS lookup overhead. See the documentation of ! these parameters, under <function>PQconnectdb</function> above, for details ! on their interaction. ! </para> ! <para> ! When neither <envar>PGHOST</envar> nor <envar>PGHOSTADDR</envar> is set, ! the default behavior is to connect using a local Unix-domain socket; or on ! machines without Unix-domain sockets, <application>libpq</application> will ! attempt to connect to <literal>localhost</>. </para> </listitem> --- 5641,5650 ---- <indexterm> <primary><envar>PGHOSTADDR</envar></primary> </indexterm> ! <envar>PGHOSTADDR</envar> behaves the same as <xref ! linkend="libpq-connect-hostaddr"> connection parameter. ! This can be set instead of or in addition to <envar>PGHOST</envar> ! to avoid DNS lookup overhead. </para> </listitem> *************** *** 5659,5667 **** <indexterm> <primary><envar>PGPORT</envar></primary> </indexterm> ! <envar>PGPORT</envar> sets the TCP port number or Unix-domain socket ! file extension for communicating with the ! <productname>PostgreSQL</productname> server. </para> </listitem> --- 5653,5660 ---- <indexterm> <primary><envar>PGPORT</envar></primary> </indexterm> ! <envar>PGPORT</envar> behaves the same as <xref ! linkend="libpq-connect-port"> connection parameter. </para> </listitem> *************** *** 5670,5678 **** <indexterm> <primary><envar>PGDATABASE</envar></primary> </indexterm> ! <envar>PGDATABASE</envar> sets the ! <productname>PostgreSQL</productname> database name. ! </para> </listitem> <listitem> --- 5663,5671 ---- <indexterm> <primary><envar>PGDATABASE</envar></primary> </indexterm> ! <envar>PGDATABASE</envar> behaves the same as <xref ! linkend="libpq-connect-dbname"> connection parameter. ! </para> </listitem> <listitem> *************** *** 5680,5686 **** <indexterm> <primary><envar>PGUSER</envar></primary> </indexterm> ! <envar>PGUSER</envar> sets the user name used to connect to the database. </para> </listitem> --- 5673,5680 ---- <indexterm> <primary><envar>PGUSER</envar></primary> </indexterm> ! <envar>PGUSER</envar> behaves the same as <xref ! linkend="libpq-connect-user"> connection parameter. database. </para> </listitem> *************** *** 5690,5700 **** <indexterm> <primary><envar>PGPASSWORD</envar></primary> </indexterm> ! <envar>PGPASSWORD</envar> 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 ! <application>ps</>); instead consider using the <filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">). </para> </listitem> --- 5684,5695 ---- <indexterm> <primary><envar>PGPASSWORD</envar></primary> </indexterm> ! <envar>PGPASSWORD</envar> behaves the same as <xref ! linkend="libpq-connect-password"> 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 ! <application>ps</>); instead consider using the <filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">). </para> </listitem> *************** *** 5715,5724 **** <indexterm> <primary><envar>PGSERVICE</envar></primary> </indexterm> ! <envar>PGSERVICE</envar> ! sets the service name to be looked up in ! <filename>pg_service.conf</filename>. This offers a shorthand way ! of setting all the parameters. </para> </listitem> --- 5710,5717 ---- <indexterm> <primary><envar>PGSERVICE</envar></primary> </indexterm> ! <envar>PGSERVICE</envar> behaves the same as <xref ! linkend="libpq-connect-service"> connection parameter. </para> </listitem> *************** *** 5727,5738 **** <indexterm> <primary><envar>PGREALM</envar></primary> </indexterm> ! <envar>PGREALM</envar> sets the Kerberos realm to use with <productname>PostgreSQL</productname>, if it is different from the local realm. If <envar>PGREALM</envar> is set, ! <application>libpq</application> 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. </para> --- 5720,5731 ---- <indexterm> <primary><envar>PGREALM</envar></primary> </indexterm> ! <envar>PGREALM</envar> sets the Kerberos realm to use with <productname>PostgreSQL</productname>, if it is different from the local realm. If <envar>PGREALM</envar> is set, ! <application>libpq</application> 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. </para> *************** *** 5743,5754 **** <indexterm> <primary><envar>PGOPTIONS</envar></primary> </indexterm> ! <envar>PGOPTIONS</envar> sets additional run-time options for the ! <productname>PostgreSQL</productname> server. For example, setting ! <envar>PGOPTIONS</envar> to <literal>-c geqo=off</> sets the session's ! value of the <varname>geqo</> parameter to <literal>off</>. ! For a detailed discussion of the available options consult <xref ! linkend="runtime-config">. </para> </listitem> --- 5736,5743 ---- <indexterm> <primary><envar>PGOPTIONS</envar></primary> </indexterm> ! <envar>PGOPTIONS</envar> behaves the same as <xref ! linkend="libpq-connect-options"> connection parameter. </para> </listitem> *************** *** 5757,5776 **** <indexterm> <primary><envar>PGSSLMODE</envar></primary> </indexterm> ! <envar>PGSSLMODE</envar> determines whether and with what priority ! an <acronym>SSL</> connection will be negotiated with the server. ! There are four modes: <literal>disable</> will attempt only an ! unencrypted <acronym>SSL</> connection; <literal>allow</> will ! negotiate, trying first a non-<acronym>SSL</> connection, then if ! that fails, trying an <acronym>SSL</> connection; <literal>prefer</> ! (the default) will negotiate, trying first an <acronym>SSL</> ! connection, then if that fails, trying a regular non-<acronym>SSL</> ! connection; <literal>require</> will try only an <acronym>SSL</> ! connection. If <productname>PostgreSQL</> is compiled without SSL ! support, using option <literal>require</> will cause an error, while ! options <literal>allow</> and <literal>prefer</> will be accepted ! but <application>libpq</> will not in fact attempt an <acronym>SSL</> ! connection. </para> </listitem> --- 5746,5753 ---- <indexterm> <primary><envar>PGSSLMODE</envar></primary> </indexterm> ! <envar>PGSSLMODE</envar> behaves the same as <xref ! linkend="libpq-connect-sslmode"> connection parameter. </para> </listitem> *************** *** 5779,5792 **** <indexterm> <primary><envar>PGSSLVERIFY</envar></primary> </indexterm> ! <envar>PGSSLVERIFY</envar> controls how libpq verifies the certificate on the ! server when performing an <acronym>SSL</> connection. There are ! three options: <literal>none</> disables verification completely ! (not recommended!); <literal>cert</> enables verification that ! the certificate chains to a known CA only; <literal>cn</> will ! both verify that the certificate chains to a known CA and that ! the <literal>cn</> attribute of the certificate matches the ! hostname the connection is being made to (default). </para> </listitem> --- 5756,5763 ---- <indexterm> <primary><envar>PGSSLVERIFY</envar></primary> </indexterm> ! <envar>PGSSLVERIFY</envar> behaves the same as <xref ! linkend="libpq-connect-sslverify"> connection parameter. </para> </listitem> *************** *** 5795,5807 **** <indexterm> <primary><envar>PGREQUIRESSL</envar></primary> </indexterm> ! <envar>PGREQUIRESSL</envar> sets whether or not the connection must ! be made over <acronym>SSL</acronym>. If set to <quote>1</quote>, ! <application>libpq</> will refuse to connect if the server does not ! accept an <acronym>SSL</acronym> connection (equivalent to ! <literal>sslmode</> <literal>prefer</>). This option is deprecated ! in favor of the <literal>sslmode</> setting, and is only available ! if <productname>PostgreSQL</> is compiled with SSL support. </para> </listitem> --- 5766,5773 ---- <indexterm> <primary><envar>PGREQUIRESSL</envar></primary> </indexterm> ! <envar>PGREQUIRESSL</envar> behaves the same as <xref ! linkend="libpq-connect-requiressl"> connection parameter. </para> </listitem> *************** *** 5810,5817 **** <indexterm> <primary><envar>PGSSLCERT</envar></primary> </indexterm> ! <envar>PGSSLCERT</envar> specifies the location for the client ! certificate to use if the server requests one. </para> </listitem> --- 5776,5783 ---- <indexterm> <primary><envar>PGSSLCERT</envar></primary> </indexterm> ! <envar>PGSSLCERT</envar> behaves the same as <xref ! linkend="libpq-connect-sslcert"> connection parameter. </para> </listitem> *************** *** 5820,5832 **** <indexterm> <primary><envar>PGSSLKEY</envar></primary> </indexterm> ! <envar>PGSSLKEY</envar> 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 ! <filename>~/.postgresql/postgresql.key</>, or can specify an external ! engine (engines are <productname>OpenSSL</> loadable modules). The ! external engine specification should consist of a colon-separated ! engine name and an engine-specific key identifier. </para> </listitem> --- 5786,5793 ---- <indexterm> <primary><envar>PGSSLKEY</envar></primary> </indexterm> ! <envar>PGSSLKEY</envar> behaves the same as <xref ! linkend="libpq-connect-sslkey"> connection parameter. </para> </listitem> *************** *** 5835,5842 **** <indexterm> <primary><envar>PGSSLROOTCERT</envar></primary> </indexterm> ! <envar>PGSSLROOTCERT</envar> specifies the file name where the SSL ! root certificate is stored. </para> </listitem> --- 5796,5803 ---- <indexterm> <primary><envar>PGSSLROOTCERT</envar></primary> </indexterm> ! <envar>PGSSLROOTCERT</envar> behaves the same as <xref ! linkend="libpq-connect-sslrootcert"> connection parameter. </para> </listitem> *************** *** 5845,5852 **** <indexterm> <primary><envar>PGSSLCRL</envar></primary> </indexterm> ! <envar>PGSSLCRL</envar> specifies the file name where the SSL certificate ! revocation list is stored. </para> </listitem> --- 5806,5813 ---- <indexterm> <primary><envar>PGSSLCRL</envar></primary> </indexterm> ! <envar>PGSSLCRL</envar> behaves the same as <xref ! linkend="libpq-connect-sslcrl"> connection parameter. </para> </listitem> *************** *** 5855,5862 **** <indexterm> <primary><envar>PGKRBSRVNAME</envar></primary> </indexterm> ! <envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use ! when authenticating with Kerberos 5 or GSSAPI. </para> </listitem> --- 5816,5823 ---- <indexterm> <primary><envar>PGKRBSRVNAME</envar></primary> </indexterm> ! <envar>PGKRBSRVNAME</envar> behaves the same as <xref ! linkend="libpq-connect-krbsrvname"> connection parameter. </para> </listitem> *************** *** 5865,5872 **** <indexterm> <primary><envar>PGGSSLIB</envar></primary> </indexterm> ! <envar>PGGSSLIB</envar> sets the GSS library to use for GSSAPI ! authentication. </para> </listitem> --- 5826,5833 ---- <indexterm> <primary><envar>PGGSSLIB</envar></primary> </indexterm> ! <envar>PGGSSLIB</envar> behaves the same as <xref ! linkend="libpq-connect-gsslib"> connection parameter. </para> </listitem> *************** *** 5875,5886 **** <indexterm> <primary><envar>PGCONNECT_TIMEOUT</envar></primary> </indexterm> ! <envar>PGCONNECT_TIMEOUT</envar> sets the maximum number of seconds ! that <application>libpq</application> will wait when attempting to ! connect to the <productname>PostgreSQL</productname> server. If ! unset or set to zero, <application>libpq</application> will wait ! indefinitely. It is not recommended to set the timeout to less than ! 2 seconds. </para> </listitem> </itemizedlist> --- 5836,5843 ---- <indexterm> <primary><envar>PGCONNECT_TIMEOUT</envar></primary> </indexterm> ! <envar>PGCONNECT_TIMEOUT</envar> behaves the same as <xref ! linkend="libpq-connect-connect-timeout"> connection parameter. </para> </listitem> </itemizedlist>
pgsql-hackers by date: