Subject: order of entries in admin docs

From: "Scott Marlowe" <[email-masked]>
Date: Tue, 11 Mar 2008 10:10:38 -0700

I was just looking for something in the admin docs, and it seems like
the ordering of sections is sub-optimal.

17. Operating System Environment
18. Server Configuration
19. Database Roles and Privileges
20. Managing Databases
21. Client Authentication

Seems that Client Authentication should come right after Server
Configuration.  After all, how is someone going to handle roles and
database creation before they've authenticated?  Is there some reason
for the order that I'm missing?  Is it an easy change?  I'd be happy
to try and make a patch for something like that if there's a chance of
it getting through / my figuring out how to do it in the docs.

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 11 Mar 2008 14:21:47 -0300

> it getting through / my figuring out how to do it in the docs.

Yeah, see postgres.sgml -- changing the order is just a matter of moving
where the entries appear.

The current order is probably just historical.

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

---

From: Tom Lane <[email-masked]>
Date: Tue, 11 Mar 2008 13:36:59 -0400

> database creation before they've authenticated?

Well, until you know what a role is, the client auth discussion might
not make too much sense to you...

I'm not wedded to the current ordering but I'm not sure it's silly
either.

Something else that ought to be considered here is that now that we have
CONNECT privilege for databases, manipulating privileges is a lot saner
way to control who-can-connect-where than setting up fancy combinations
of user and database entries in pg_hba.conf.  AFAIR there is no mention
of this alternative in Chapter 21, but it seems like there ought to be.
With your proposed reorganization, that would become a forward
reference; is that OK?

			regards, tom lane

---

From: "Scott Marlowe" <[email-masked]>
Date: Tue, 11 Mar 2008 11:18:44 -0700

>  With your proposed reorganization, that would become a forward

I've deleted and rewritten this email like 4 times...

The more I read the docs, the more moving client authentication seems
to make sense.  In fact, the authentication problems section is
probably the perfect final bit to the Connections and Authentication
section.  I'd move it up a level, so that it looked something like
this:

18.3. Connections and Authentication

    18.3.1. Connection Settings
    18.3.2. Security and Authentication
    18.3.3. The pg_hba.conf file
    18.3.4. Authentication methods
    18.3.5. Authentication problems

Unless a different level of indentation makes more sense, which I
could totally understand.

It definitely follows the flow of setting up a pg server better for
me.  I might even move the pg_hba.conf file to 18.3.1 up there.  It is
pretty much a firewall.

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 7 May 2008 12:34:06 -0400 (EDT)

> With your proposed reorganization, that would become a forward

We do have a "Tip" about this in the pg_hba.conf section:

	http://developer.postgresql.org/pgdocs/postgres/auth-pg-hba-conf.html
	
	Tip:  To connect to a particular database, a user must not only pass the
	pg_hba.conf checks, but must have the CONNECT privilege for the
	database. If you wish to restrict which users can connect to which
	databases, it's usually easier to control this by granting/revoking
	CONNECT privilege than to put the rules into pg_hba.conf entries.

Do we need more?

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 7 May 2008 12:38:09 -0400 (EDT)

> it getting through / my figuring out how to do it in the docs.

Agreed, section moved by attached patch.  The new ordering makes more
sense because you can't do much database management until you have
client authentication setup properly.

I bet this will reduce the number of people who don't realize they need
to modify pg_hba.conf.

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/postgres.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v
retrieving revision 1.85
diff -c -c -r1.85 postgres.sgml
*** doc/src/sgml/postgres.sgml	14 Nov 2007 02:36:43 -0000	1.85
--- doc/src/sgml/postgres.sgml	7 May 2008 16:35:20 -0000
***************
*** 146,154 ****
    &installw;
    &runtime;
    &config;
    &user-manag;
    &manage-ag;
-   &client-auth;
    &charset;
    &maintenance;
    &backup;
--- 146,154 ----
    &installw;
    &runtime;
    &config;
+   &client-auth;
    &user-manag;
    &manage-ag;
    &charset;
    &maintenance;
    &backup;

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 7 May 2008 12:39:15 -0400 (EDT)

> me.  I might even move the pg_hba.conf file to 18.3.1 up there.  It is

I don't think this change makes sense --- All the "Connection Settings"
stuff is in postgresql.conf. Pulling authentication in there will be too
complex, I am afraid.

---

From: "Scott Marlowe" <[email-masked]>
Date: Wed, 7 May 2008 12:01:12 -0600

>  stuff is in postgresql.conf. Pulling authentication in there will be too

Well, if you say so.  It seems like a natural part of it to me, but
the modifications required to move things like that are pretty big,
and I really don't feel comfortable enough in sgml to get it right.
The other move still makes more sense to me than the way it was
originally though.

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 7 May 2008 14:27:04 -0400 (EDT)

> and I really don't feel comfortable enough in sgml to get it right.

Right now we have all postgresql.conf documentation in the same chapter.
To move it would split that up, which I think is confusing.

> The other move still makes more sense to me than the way it was

I did move the Authentication chapter up to after Configuration
Settings so the order now is:

	17. Operating System Environment
	18. Server Configuration
	19. Client Authentication
	20. Database Roles and Privileges
	21. Managing Databases
	22. Localization

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 7 May 2008 15:27:17 -0400

> To move it would split that up, which I think is confusing.

Perhaps it would be better to have prose explaining all the stuff
structured like Scott proposes, and make the postgresql.conf be just a
reference linking to that.  I don't think making postgresql.conf be the
primary documentation is very nice.

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 7 May 2008 15:36:54 -0400 (EDT)

Alvaro Herrera wrote:
> Bruce Momjian escribi?:

So you are suggesting splitting out the postgresql.conf content into its
relevant sections and just linking to it?  That would work.

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 7 May 2008 17:02:11 -0400

> relevant sections and just linking to it?  That would work.

Yes, or something like that.  I don't think leaving _just_ the links on
the postgresql.conf would be enough.  But a comprehensive, verbose
explanation should be elsewhere; a short blurb and the link would remain
on the postgresql.conf reference.

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 7 May 2008 17:34:47 -0400 (EDT)

> on the postgresql.conf reference.

Yea, that's certainly possible, though right now we pretty much have
_all_ the information about each configuration value in one place.  We
would lose that.  Looking at the connection postgresql.conf docs:

	http://developer.postgresql.org/pgdocs/postgres/runtime-config-connection.html

There isn't much additional text except a description of each item.

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 7 May 2008 23:58:22 +0200

> There isn't much additional text except a description of each item.

That's the way it should be: Each parameter explains what it does.  There can 
be more extensive documentation about how they all fit together elsewhere.

What I would like to see is getting rid of the sections the parameters are 
grouped in and put them all in alphabetical order.  I find the current 
arrangement completely unusable; nine times out of ten I cannot find the 
right section.  The topical grouping of the options would be the job of the 
more extensive documentation elsewhere I mentioned above.

I think Postfix has arranged this nicely: 
http://www.postfix.org/documentation.html -- You have various sections 
explaining how to configure for various jobs, and one big list of all 
parameters explained.

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 7 May 2008 18:17:25 -0400

> more extensive documentation elsewhere I mentioned above.

+1.  That's what I was imagining.

---

From: "Ian Barwick" <[email-masked]>
Date: Fri, 9 May 2008 10:28:04 +0900

2008/5/8 Peter Eisentraut <[email-masked]>:
> Sent via pgsql-docs mailing list ([email-masked])
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs
>

-- 
http://sql-info.de/index.html

---

From: "Ian Barwick" <[email-masked]>
Date: Fri, 9 May 2008 10:29:41 +0900

(Whoops, apologies for the blank mail, I clicked on "send" by accident)

Ian Barwick