Re: PGDATA confusion - Mailing list pgsql-docs

On 15 October 2011 03:24, Thom Brown <thom@linux.com> wrote:
> Hi,
>
> I notice that in the man page and the page for pg_ctl in the
> documentation (http://www.postgresql.org/docs/current/static/app-pg-ctl.html)
> it states that the -D parameter should point to the directory which
> contains the database files:
>
> "Specifies the file system location of the database files. If this is
> omitted, the environment variable PGDATA is used."
>
> This isn't necessarily true.  It will only need to know where the
> postgresql.conf file is.  In Debian and Ubuntu, for example, the
> "database files" reside in /var/lib/postgresql/x.x/main/, and the
> configuration files in /etc/postgresql/x.x/main/, so a user might
> assume they need to point it to the former as that's where the actual
> database itself can be found, when in fact it needs to be the latter.
>
> This same inaccuracy affects the "postgres" command
> (http://www.postgresql.org/docs/current/static/app-postgres.html) to a
> lesser extent:
>
> "Specifies the file system location of the data directory or
> configuration file(s)."
>
> Which is it?  This suggests it can be either, when only the latter
> matters.  If it also happens to be the data directory, that's
> unimportant.
>
> To add further confusion, the page describing PGDATA
> (http://www.postgresql.org/docs/current/static/storage-file-layout.html)
> refers to it like so:
>
> "All the data needed for a database cluster is stored within the
> cluster's data directory, commonly referred to as PGDATA...
>
> *snip*
>
> The PGDATA directory contains several subdirectories and control
> files... ...In addition to these required items, the cluster
> configuration files postgresql.conf, pg_hba.conf, and pg_ident.conf
> are traditionally stored in PGDATA (although in PostgreSQL 8.0 and
> later, it is possible to keep them elsewhere)."
>
> Traditionally but not necessarily, and not by default in Debian and
> Ubuntu.  In fact Gentoo (and therefore probably Sabayon too) has also
> elected for this separation of data files and config files as of 9.0.
>
> So if one set PGDATA to somewhere which had no database files at all,
> but just postgresql.conf, it could still work (assuming it, in turn,
> set data_directory correctly), but not vice versa.  It would make more
> sense to call it PGCONFIG, although I'm not proposing that, especially
> since PGDATA makes sense when it comes to initdb.
>
> There are probably plenty of other places in the docs which also don't
> adequately describe PGDATA or -D.
>
> Any disagreements?  If not, should I write a patch (since someone will
> probably accuse me of volunteering anyway) or would someone like to
> commit some adjustments?

No opinions on this?

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company