Re: [HACKERS] pg_service.conf - Mailing list pgsql-patches

I have added the attached pg_service.conf documentation to CVS HEAD and
8.1.X.

---------------------------------------------------------------------------

Mark Woodward wrote:
> > On Fri, Feb 03, 2006 at 08:05:48AM -0500, Mark Woodward wrote:
> >> Like I said, in this thread of posts, yes there are ways of doing this,
> >> and I've been doing it for years. It is just one of the rough eges that
> >> I
> >> think could be smoother.
> >>
> >> (in php)
> >> pg_connect("dbname=geo host=dbserver");
> >>
> >> Could connect and query the dbserver, if the db is not on it, connect to
> >> a
> >> database of known servers, find geo, and use that information to
> >> connect.
> >> It sounds like a simple thing, for sure, but to be useful, there needs
> >> to
> >> be buy in from the group otherwise it is just some esoteric hack.
> >
> > It turns out what you like actually exists, lookup the "service"
> > parameter in the connectdb string. It will read the values for the
> > server, port, etc from a pg_service.conf file.
> >
> > There is an example in the tree but it looks something like the following:
> >
> > [servicename]
> > dbname=blah
> > user=blah
> > pass=blah
> >
> > So all you need to specify is "service=servicename" and it will grab
> > the parameters. This allows you to change the connection without
> > changeing the code.
> >
>
> This is a great feature!!
>
> It doesn't seem to be documented in the administrators guide. Its
> mentioned in the libpq section, and only a reference to
> pg_service.conf.sample
>
> IMHO we should push for this to be the mainstream connection
> methodology!!! The variables: host, port, and dbname are very problematic
> for admins and developers who often live in different worlds.
>
> The developers "should" just use the "servicename" of a database, and the
> admins should maintain pg_service.conf. This moves the responsibility of
> the wheres and hows of connecting to the database to the admin away from
> the developer.
>
> Should there be a section of the administration manual for this?
>
> ---------------------------(end of broadcast)---------------------------
> TIP 2: Don't 'kill -9' the postmaster
>

--
  Bruce Momjian   http://candle.pha.pa.us
  SRA OSS, Inc.   http://www.sraoss.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.203
diff -c -c -r1.203 libpq.sgml
*** doc/src/sgml/libpq.sgml    28 Feb 2006 22:35:35 -0000    1.203
--- doc/src/sgml/libpq.sgml    1 Mar 2006 00:12:46 -0000
***************
*** 298,306 ****
        Service name to use for additional parameters.  It specifies a service
        name in <filename>pg_service.conf</filename> that holds additional connection parameters.
        This allows applications to specify only a service name so connection parameters
!       can be centrally maintained.  See
!       <filename>share/pg_service.conf.sample</> in the installation
!       directory for information on how to set up the file.
       </para>
       </listitem>
      </varlistentry>
--- 298,304 ----
        Service name to use for additional parameters.  It specifies a service
        name in <filename>pg_service.conf</filename> that holds additional connection parameters.
        This allows applications to specify only a service name so connection parameters
!       can be centrally maintained. See <xref linkend="libpq-pgservice">.
       </para>
       </listitem>
      </varlistentry>
***************
*** 4031,4036 ****
--- 4029,4063 ----
  </sect1>


+ <sect1 id="libpq-pgservice">
+ <title>The Connection Service File</title>
+
+ <indexterm zone="libpq-pgservice">
+  <primary>connection service file</primary>
+ </indexterm>
+ <indexterm zone="libpq-pgservice">
+  <primary>pg_service.conf</primary>
+ </indexterm>
+
+ <para>
+ The connection service file allows libpq connection parameters to be
+ associated with a single service name. That service name can then be
+ specified by a libpq connection, and the associated settings will be
+ used. This allows connection parameters to be modified without requiring
+ a recompile of the libpq application. The service name can also be
+ specified using the <envar>PGSERVICE</envar> environment variable.
+ </para>
+ <para>
+ To use this feature, copy
+ <filename>share/pg_service.conf.sample</filename> to
+ <filename>etc/pg_service.conf</filename> and edit the file to add
+ service names and parameters. This file can be used for client-only
+ installs too. The file's location can also be specified by the
+ <envar>PGSYSCONFDIR</envar> environment variable.
+ </para>
+ </sect1>
+
+
  <sect1 id="libpq-ssl">
  <title>SSL Support</title>