Thread: libpq & user

Hi --

I'm trying to use libpq to read a Postgres database from C.  I use the
following command to connect to the database:

  PGconn *deep;
  deep=PQsetdb("dara",NULL,"user=deep",NULL,"deep");

("dara" is the host where postmaster is running; "deep" is the name of the
database, and the user I'm trying to connect as.)

The problem is, lots of different people will be using this, and I'm
trying to avoid having to put all of the various usernames in the Postgres
shadow file by having everybody connect as user deep.  I have not found
anywhere in the documentation how to set the user with libpq; what I've
tried here is based on analogy to the Pg Perl module (which I have been
able to get working).

Can somebody give me any suggestions?

(I've already tried setting the USER variable with putenv(), to no avail.)

Thank you,

-Rob

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
==== Rob Knop ===== rknop@lbl.gov ====== http://panisse.lbl.gov/~rknop ======

At 0:02 +0300 on 15/7/98, Robert Knop wrote:


> I'm trying to use libpq to read a Postgres database from C.  I use the
> following command to connect to the database:
>
>   PGconn *deep;
>   deep=PQsetdb("dara",NULL,"user=deep",NULL,"deep");

I didn't exactly get it from your problem description, but I take it that
putting the username in the options field doesn't work.

Well, two alternatives for solution:

In the psql source code, they set the user by setting the PGUSER
environment variable. The source of the PQsetdb function states that the
following environment variables are accepted (although this is not
documented - at least not in my old 6.2.1 version):

PGHOST, PGPORT, PGTTY, PGOPTIONS, PGUSER, PGPASSWORD, PGDATABASE

So you may set these variables from within your program or from the shell
script that calls it.

Another option: the psql source, when needing a password, uses the
undocumented function:

PQconnectdb( connection_string );

The connection string is a C character string containing pairs of names and
values. For example: "host=dara user=deep password=ocean dbname=deep".

The allowed parameters are:
host, port, tty, options, user, password, authtype, dbname

Which to use? Depends on which undocumented feature you prefer... Or maybe
the gurus who actually wrote the code can give us a hint.

Herouth

--
Herouth Maoz, Internet developer.
Open University of Israel - Telem project
http://telem.openu.ac.il/~herutma

> In the psql source code, they set the user by setting the PGUSER
> environment variable. The source of the PQsetdb function states that the
> following environment variables are accepted (although this is not
> documented - at least not in my old 6.2.1 version):

Aha!  Thank you, that was the secret.  I do not believe that these
environment variables are documented in 6.3.1 either -- at least, I didn't
find them.  I tried USER, but not PGUSER.  Setting PGUSER worked.

> Another option: the psql source, when needing a password, uses the
> undocumented function:
>
> PQconnectdb( connection_string );
>
> The connection string is a C character string containing pairs of names and
> values. For example: "host=dara user=deep password=ocean dbname=deep".

This is how the Pg.pm perl connectdb function works; that _is_ documented
in the Pg man page.  Presumably this is a "documented" feature of libpq,
but the documentation hasn't caught up yet.  (Of course, it's always scary
to assume things like that.)

Thanks again for your help.

-Rob

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
==== Rob Knop ===== rknop@lbl.gov ====== http://panisse.lbl.gov/~rknop ======

> > In the psql source code, they set the user by setting the PGUSER
> > environment variable. The source of the PQsetdb function states that the
> > following environment variables are accepted (although this is not
> > documented - at least not in my old 6.2.1 version):
>
> Aha!  Thank you, that was the secret.  I do not believe that these
> environment variables are documented in 6.3.1 either -- at least, I
> didn't find them.  I tried USER, but not PGUSER.

These environment variables are documented in the libpq section of the
new v6.3.x html/hardcopy documents. However, PGUSER was omitted. Would
someone like to add it to the sgml sources? It is in
  doc/src/sgml/libpq.sgml

Look for PGHOST, put in some text in the appropriate area, and send a
patch. It's that easy! (Wasn't that a Ross Perot quote?...)

                     - Tom

> > > In the psql source code, they set the user by setting the PGUSER
> > > environment variable. The source of the PQsetdb function states that the
> > > following environment variables are accepted (although this is not
> > > documented - at least not in my old 6.2.1 version):
> >
> > Aha!  Thank you, that was the secret.  I do not believe that these
> > environment variables are documented in 6.3.1 either -- at least, I
> > didn't find them.  I tried USER, but not PGUSER.
>
> These environment variables are documented in the libpq section of the
> new v6.3.x html/hardcopy documents. However, PGUSER was omitted. Would
> someone like to add it to the sgml sources? It is in
>   doc/src/sgml/libpq.sgml
>
> Look for PGHOST, put in some text in the appropriate area, and send a
> patch. It's that easy! (Wasn't that a Ross Perot quote?...)

Woh, hold on big doggy.  (western saying)

Someone is in the process of converting the 6.3.2 src/man/* pages to
sgml.

We need to continue making changes only to the src/man/* pages until
they are converted all to sgml, and then any changes made to src/man/*
from 6.3.2->current are merged into the sgml source.  At that point, we
switch over to making changes only to the sgml files, and generate
src/man/* before each release.  We need to move to sgml, but we can't
start making changes in two places.  I have added to src/man/libpq.3:

\(bu
.B PGUSER
sets the username use to connect to the database and for authentication.


Is this OK?

--
Bruce Momjian                          |  830 Blythe Avenue
maillist@candle.pha.pa.us              |  Drexel Hill, Pennsylvania 19026
  +  If your life is a hard drive,     |  (610) 353-9879(w)
  +  Christ can be your backup.        |  (610) 853-3000(h)

> We need to continue making changes only to the src/man/* pages until
> they are converted all to sgml, and then any changes made to src/man/*
> from 6.3.2->current are merged into the sgml source. At that point, we
> switch over to making changes only to the sgml files, and generate
> src/man/* before each release.  We need to move to sgml, but we can't
> start making changes in two places.

Hmm. I guess I don't see the point in asking people to stay away from
the parts of the SGML docs which are _not_ derived from the parts of the
man pages which are actually being converted, especially parts which
were converted long ago. It just makes the document conversion work
harder. I believe that there are only two people actively working on the
reference page conversion to sgml, Oliver Elphick and myself, with
Oliver doing much of the work.

Here is the documentation plan for v6.4:

1) convert the man pages covering SQL syntax and commands to SGML
reference sections. That is roughly half-way completed.

2) convert the man pages covering utility programs to SGML reference
sections.

3) rebuild the User's Guide, Reference Guide, and Administrator's Guide
(the admin guide only if we get release notes and installation
information updated in sgml; I'm hoping you are willing to look at that
Bruce).

A _lot_ of information has already been converted. The libpq
documentation is one of those; I converted it back in March for the v6.3
release, and subsequent doc updates by Tom Lane and others have been
done to the sgml source. That should continue!

In the long run, the "reference docs" will be different from the user's
guide; the reference stuff says "how", and the user's guide says "why".
There will possibly be information currently in the man pages which will
not show up in Oliver's sgml reference pages, and that will need to move
to the User's Guide. There is not a good one-to-one mapping of the man
pages to sgml sources since the man pages tried to stuff everything on
one topic into one section; "real" docs will have a logical structure.

If you have a chance you might want to look through the sgml source
directories to see what is there; it is a lot of stuff. It will _not_ be
trivial to remerge the man page updates, but we said that we would do it
since the alternative was to bring some doc updates to a halt.

At some point the SGML docs will have more and better information than
the current man pages and other available docs. Actually, I think it is
already to that point but since the man pages have been the primary docs
for so long I haven't pushed the transition.

Anyway, if information is already available in SGML then that is where
updates should happen. OK? And as soon as Oliver finishes the SQL
reference pages, we will re-merge and work from the SGML sources for
others too.

Here's an idea: I'll go in and mark the man pages (as a comment in the
top) as to whether they have been or will be converted. Would that help?

Also, if there are any questions on what should be updated, or where,
perhaps checking on the docs list would be helpful? I know I wasn't
available for quite a while (pop server woes), but I should be from here
on...

                       - Tom

> Here's an idea: I'll go in and mark the man pages (as a comment in the
> top) as to whether they have been or will be converted. Would that help?
>
> Also, if there are any questions on what should be updated, or where,
> perhaps checking on the docs list would be helpful? I know I wasn't
> available for quite a while (pop server woes), but I should be from here
> on...

That is the problem.  There is no indication what has been converted and
what has not been converted.  If you move to the sgml for some, you have
to merge the post-6.3.2 man changes into sgml.

With so many people involved, it seemed best to keep all changes in one
area until everything was moved over, then do a diff against 6.3.2 and
merge them.  We can then auto-generate the man pages from sgml.

Oliver is working from the base 6.3.2 sources, so he has a nice stable
base to do the conversions.

People are sumbiting changes from the man pages, and I install them.

Again, keep it consistent for everyone, or we will spend hours trying to
get it straight.

Merging in well-collected changes is much easier than trying to keep two
sets of sources straight.  I will do the merging of post-6.3.2 changes
myself if necessary.

--
Bruce Momjian                          |  830 Blythe Avenue
maillist@candle.pha.pa.us              |  Drexel Hill, Pennsylvania 19026
  +  If your life is a hard drive,     |  (610) 353-9879(w)
  +  Christ can be your backup.        |  (610) 853-3000(h)

> \The problem is, lots of different people will be using this, and I'm
> trying to avoid having to put all of the various usernames in the Postgres
> shadow file by having everybody connect as user deep.  I have not found
> anywhere in the documentation how to set the user with libpq; what I've
> tried here is based on analogy to the Pg Perl module (which I have been
> able to get working).
>

Try changing the owner of your C program to deep.  Then set the setuid bit.  At
that point anyone running your program will be user deep.

> That is the problem.  There is no indication what has been converted
> and what has not been converted.  If you move to the sgml for some,
> you have to merge the post-6.3.2 man changes into sgml.
> With so many people involved, it seemed best to keep all changes in
> one area until everything was moved over, then do a diff against 6.3.2
> and merge them.  We can then auto-generate the man pages from sgml.

We do not currently have the mechanism for generating man pages from
sgml, though it is theoretically possible to do. Man pages are only one
of the important information formats (and in fact the least important of
them because of the limitations in man page structure and the flat
organization). See below.

> Oliver is working from the base 6.3.2 sources, so he has a nice stable
> base to do the conversions.

Not really (though I had forgotten why). See below.

> People are submiting changes from the man pages, and I install them.

That's fine. But this person was asking what to change, and you directed
them to the man pages for something converted 4 months ago. That's why I
spoke up. Not complaining, just trying to work something out here :)

> Again, keep it consistent for everyone, or we will spend hours trying
> to get it straight.

I'm trying to. I've already spent over a hundred hours getting the sgml
docs to where they are now. Lots has been converted already. Some still
needs to be done. We don't disagree on the facts, or on the goals. But
we do have a coordination problem here, and I'd like to try addressing
that.

If I generate a list of _all_ online document resources, and their
current state (converted, unconverted, not a candidate for conversion,
etc) would the hackers and docs people be willing to look at that when
making changes? Seems like that should help coordinate things.

For example, release notes and installation instructions have been
converted. Docs on libraries and interfaces have been converted. Man
pages are not actually being converted by Oliver, now that I think about
it; Jose' Soares had written a really nice text-based new version of
_reference_ information for each of the commands, perhaps using the man
page sources as a resource. Oliver is converting those text-based docs
to sgml. But the man pages try to span two separate documents: a User's
Guide and a Reference Manual. On their own, the man pages are not
suitable for a simple conversion, but must be split. We will need to
make sure _information_ in the man pages ends up in the right place. The
replacement man pages will be from the reference information, not the
User's Guide, so will not be identical to the current man pages.

One possible outcome of the docs conversion for the v6.4 release is that
the sgml sources, the html online docs and the Postscript hardcopy are
up to date for v6.4, and the SQL command man pages are up to date for
v6.3.x only. I think that this should be acceptable, and that we can
then focus on getting a man page output from the sgml sources for v6.5.
Brandon has expressed ongoing interest in working on this, and I have
some ideas for doing a "quick and dirty" stopgap. You are asking a lot
of one or two or three people to do _all_ of the docs conversion, _and_
the re-syncing of old docs, _and_ getting 3 separate output formats in
the span of 4 months. Especially when the docs are hundreds of pages and
the people are also contributing to the code itself!

Anyway, the issue really seems to have come up over a single topic
(libpq) which has _not_ been a coordination problem since its conversion
in February. So it isn't _that_ big a problem, and a
conversion/coordination list would seem be help address the lack of
information about what the current state of things is.

We both see a problem from two different angles, so let's try to work
out a solution :) I've been working on code for v6.4 for a bit now, but
am willing to stop that (I have most of my v6.4 coding goals
accomplished) and re-focus on docs.

                        - Tom

> > That is the problem.  There is no indication what has been converted
> > and what has not been converted.  If you move to the sgml for some,
> > you have to merge the post-6.3.2 man changes into sgml.
> > With so many people involved, it seemed best to keep all changes in
> > one area until everything was moved over, then do a diff against 6.3.2
> > and merge them.  We can then auto-generate the man pages from sgml.
>
> We do not currently have the mechanism for generating man pages from
> sgml, though it is theoretically possible to do. Man pages are only one
> of the important information formats (and in fact the least important of
> them because of the limitations in man page structure and the flat
> organization). See below.

Yikes.  I did not know.  Do we have a solution for this, or are we going
to maintain multiple version of this information?

I can't imagine trying to maintain muliple versions of this information.

I did look at the libpq sgml version, and it looks identical to the man
version, though of course, I have been updating the man version and not
the sgml version.


> > Oliver is working from the base 6.3.2 sources, so he has a nice stable
> > base to do the conversions.
>
> Not really (though I had forgotten why). See below.
>
> > People are submiting changes from the man pages, and I install them.
>
> That's fine. But this person was asking what to change, and you directed
> them to the man pages for something converted 4 months ago. That's why I
> spoke up. Not complaining, just trying to work something out here :)


>
> > Again, keep it consistent for everyone, or we will spend hours trying
> > to get it straight.
>
> I'm trying to. I've already spent over a hundred hours getting the sgml
> docs to where they are now. Lots has been converted already. Some still
> needs to be done. We don't disagree on the facts, or on the goals. But
> we do have a coordination problem here, and I'd like to try addressing
> that.

Yes, I want the sgml to be kept up-to-date.

> If I generate a list of _all_ online document resources, and their
> current state (converted, unconverted, not a candidate for conversion,
> etc) would the hackers and docs people be willing to look at that when
> making changes? Seems like that should help coordinate things.
>
> For example, release notes and installation instructions have been
> converted. Docs on libraries and interfaces have been converted. Man
> pages are not actually being converted by Oliver, now that I think about
> it; Jose' Soares had written a really nice text-based new version of
> _reference_ information for each of the commands, perhaps using the man
> page sources as a resource. Oliver is converting those text-based docs
> to sgml. But the man pages try to span two separate documents: a User's
> Guide and a Reference Manual. On their own, the man pages are not
> suitable for a simple conversion, but must be split. We will need to
> make sure _information_ in the man pages ends up in the right place. The
> replacement man pages will be from the reference information, not the
> User's Guide, so will not be identical to the current man pages.

Yep, a guide to what is converted would be great.  We need to know where
to make changes for each section.  If we need to make changes in two
places, let us know.  If one file is generated from another, let us
know.

For example, I added a missing part of a query structure because we not
mention the AS part of DISTINCT.  I added it the SELECT man page and
psql help.  I probably missed something in sgml.  Maybe we should make
only changes in man pages, and before each release, we merge those
changes into the sgml?  I am afraid only a few people will know where
the sgml changes are to be placed.  I would be glad to add it to my
release checklist and make sure someone does it before each release.

>
> One possible outcome of the docs conversion for the v6.4 release is that
> the sgml sources, the html online docs and the Postscript hardcopy are
> up to date for v6.4, and the SQL command man pages are up to date for
> v6.3.x only. I think that this should be acceptable, and that we can
> then focus on getting a man page output from the sgml sources for v6.5.

Oh, this is what I was hoping not to do.  Going too long with changes
only to sgml could be a problem.  People use the man pages from the
command line.

Again, how about keeping the man pages up-to-date, and merging the diffs
before every release until we have a plan to move sgml to man.  Perhaps
we should consider moving man to sgml.  I know I can generate html and
postscript from man pages very easily.

> Brandon has expressed ongoing interest in working on this, and I have
> some ideas for doing a "quick and dirty" stopgap. You are asking a lot
> of one or two or three people to do _all_ of the docs conversion, _and_
> the re-syncing of old docs, _and_ getting 3 separate output formats in
> the span of 4 months. Especially when the docs are hundreds of pages and
> the people are also contributing to the code itself!
>
> Anyway, the issue really seems to have come up over a single topic
> (libpq) which has _not_ been a coordination problem since its conversion
> in February. So it isn't _that_ big a problem, and a
> conversion/coordination list would seem be help address the lack of
> information about what the current state of things is.
>
> We both see a problem from two different angles, so let's try to work
> out a solution :) I've been working on code for v6.4 for a bit now, but
> am willing to stop that (I have most of my v6.4 coding goals
> accomplished) and re-focus on docs.

Yes, we both see the same problem.  Let's agree on how to handle things
consistently.  Perhaps I can keep the sgml changes up-to-date with the
man pages.  However, I need to do it at fixed periods, like before each
release, so I know people are not converting old documents as I am
moving in changes from the man pages.  If they work on 6.3.2 sources up
until the 6.3.2 beta, I can then update sgml, and they can start
converting again with the 6.4 sources, which I will not touch until 6.5.

If people took the current man version of a file, converted it into
sgml, and deleted the old man file, that would be even better.  No
duplication, but then you have to have a way to generate the man file,
and currently we don't.

I just did a context diff of the man directory since 6.3.2, and I have
5k lines of diffs.  Most of them are additions of underscores in man
pages names.  This was done so the man->html could create proper links
for man pages.  The rest are small wording changes or new libpq
functions.  Not much.

Let me know how we should proceed.

--
Bruce Momjian                          |  830 Blythe Avenue
maillist@candle.pha.pa.us              |  Drexel Hill, Pennsylvania 19026
  +  If your life is a hard drive,     |  (610) 353-9879(w)
  +  Christ can be your backup.        |  (610) 853-3000(h)

On Thu, 16 Jul 1998, Thomas G. Lockhart wrote:

[snip]

> If I generate a list of _all_ online document resources, and their
> current state (converted, unconverted, not a candidate for conversion,
> etc) would the hackers and docs people be willing to look at that when
> making changes? Seems like that should help coordinate things.

As I've said before, I'm working on the JDBC doc's. As there wasn't any
before, it shouldn't cause any problems.

--
Peter T Mount peter@retep.org.uk or petermount@earthling.net
Main Homepage: http://www.retep.org.uk
************ Someday I may rebuild this signature completely ;-) ************
Work Homepage: http://www.maidstone.gov.uk Work EMail: peter@maidstone.gov.uk

> If people took the current man version of a file, converted it into
> sgml, and deleted the old man file, that would be even better.  No
> duplication, but then you have to have a way to generate the man file,
> and currently we don't.

Well, the man pages as they currently exist aren't what we want anyway.
See below.

> I just did a context diff of the man directory since 6.3.2, and I have
> 5k lines of diffs.  Most of them are additions of underscores in man
> pages names.  This was done so the man->html could create proper links
> for man pages.  The rest are small wording changes or new libpq
> functions.  Not much.

Great. That is encouraging, and matches my impression of where we are
at. As v6.4 gets closer to release, you and others will be wanting to
update docs to reflect new features, so this is a good time to get
coordinated.

> Let me know how we should proceed.

Well, I think we are still short of a common view here, but closing in
on it :)

Remember, the man pages as they exist now will not exist in the future!
The information content in a single current man page does not fit with a
well structured document of any kind. The man pages in the future will
be the same as the sgml reference pages, which summarize syntax and give
examples. If you want the "whys and wherefores" then you go to the
User's Guide, Administrator's Manual, or Reference Manual. This isn't a
bad thing; it is the best way to present information. man pages will
provide quick reminders, while the full docs are meant for teaching and
informing. The man pages have more now because there was no other place
to put new information, so we kept adding more and more to them.

I'm just now generating a list of all files in the tree (as of last
Friday) which are (or might be) documentation resources. I'll send you
the list, and if you would remove any lines which are definitely not
documentation and return the result to me then I will generate an sgml
document/table from it and put it into a section of the "docguide"
appendix, with it marked-up as to what has been converted and what has
not.

I'll update the web site doc information, and generate a new output
version of the html docs for the web site and for our use.

I will indicate which man pages have been directly used in the sgml docs
(libpq, for example) and the other man pages are fair game for continued
maintenance. However, if we already have a place for the same
information in the sgml docs, I will call that out and ask that we try
to maintain both for a short while.

If we get some preliminary work on the man page conversion software done
(so we have some pretty good examples which are close to adequate) then
we can make the "hard switch" to sgml.

OK? Let me know if these suggestions are headed in the right direction,
and if so which ones you would like to support.

Talk to you soon.

                         - Tom