Received: from makus.postgresql.org ([98.129.198.125])
	by malur.postgresql.org with esmtp (Exim 4.72)
	(envelope-from <bruce@momjian.us>) id 1T1qJr-000510-KX
	for pgsql-docs@postgresql.org; Thu, 16 Aug 2012 03:00:23 +0000
Received: from momjian.us ([72.94.173.45])
	by makus.postgresql.org with esmtp (Exim 4.72)
	(envelope-from <bruce@momjian.us>) id 1T1qJq-0006vv-7B
	for pgsql-docs@postgresql.org; Thu, 16 Aug 2012 03:00:23 +0000
Received: from bruce by momjian.us with local (Exim 4.72)
	(envelope-from <bruce@momjian.us>)
	id 1T1qJp-0003VC-Ci; Wed, 15 Aug 2012 23:00:21 -0400
Date: Wed, 15 Aug 2012 23:00:21 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Thom Brown <thom@linux.com>
Cc: pgsql-docs <pgsql-docs@postgresql.org>
Subject: Re: PGDATA confusion
Message-ID: <20120816030021.GI8353@momjian.us>
References: 
 <CAA-aLv6KYbPa3FgH6_shVXrxQto86+QDJHQgj1isbeQngiBBGw@mail.gmail.com>
	<201111041632.pA4GWDH15361@momjian.us>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="FN+gV9K+162wdwwF"
Content-Disposition: inline
In-Reply-To: <201111041632.pA4GWDH15361@momjian.us>
User-Agent: Mutt/1.5.20 (2009-06-14)
X-Pg-Spam-Score: -1.9 (-)
X-Archive-Number: 201208/27
X-Sequence-Number: 7420


--FN+gV9K+162wdwwF
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Fri, Nov  4, 2011 at 12:32:13PM -0400, Bruce Momjian wrote:
> Thom Brown wrote:
> > > 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?
> 
> Yes.  I had kept it to deal with later.  Please work on a doc patch to
> try to clean this up.  pg_upgrade just went through this confusion and I
> also was unhappy at how vague things are in this area.
> 
> Things got very confusing with pg_upgrade when PGDATA pointed to the
> configuration directory and the data_directory GUC pointed to the data
> directory.

I have applied the attached doc patch for PG 9.3 to clarify PGDATA.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

--FN+gV9K+162wdwwF
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="pgdata.diff"

diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
new file mode 100644
index 90725d9..7a4c2be
*** a/doc/src/sgml/ref/pg_ctl-ref.sgml
--- b/doc/src/sgml/ref/pg_ctl-ref.sgml
*************** PostgreSQL documentation
*** 261,267 ****
        <term><option>--pgdata <replaceable class="parameter">datadir</replaceable></option></term>
        <listitem>
         <para>
!         Specifies the file system location of the database files.  If
          this is omitted, the environment variable
          <envar>PGDATA</envar> is used.
         </para>
--- 261,267 ----
        <term><option>--pgdata <replaceable class="parameter">datadir</replaceable></option></term>
        <listitem>
         <para>
!         Specifies the file system location of the database configuration files.  If
          this is omitted, the environment variable
          <envar>PGDATA</envar> is used.
         </para>
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
new file mode 100644
index a1f36e1..41745fb
*** a/doc/src/sgml/ref/postgres-ref.sgml
--- b/doc/src/sgml/ref/postgres-ref.sgml
*************** PostgreSQL documentation
*** 179,186 ****
        <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
        <listitem>
         <para>
!         Specifies the file system location of the data directory or
!         configuration file(s).  See
          <xref linkend="runtime-config-file-locations"> for details.
         </para>
        </listitem>
--- 179,186 ----
        <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
        <listitem>
         <para>
!         Specifies the file system location of the database
!         configuration files.  See
          <xref linkend="runtime-config-file-locations"> for details.
         </para>
        </listitem>
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
new file mode 100644
index bd2dca3..e0a93c1
*** a/doc/src/sgml/storage.sgml
--- b/doc/src/sgml/storage.sgml
*************** directories.
*** 19,25 ****
  </para>
  
  <para>
! All the data needed for a database cluster is stored within the cluster's data
  directory, commonly referred to as <varname>PGDATA</> (after the name of the
  environment variable that can be used to define it).  A common location for
  <varname>PGDATA</> is <filename>/var/lib/pgsql/data</>.  Multiple clusters,
--- 19,26 ----
  </para>
  
  <para>
! Traditionally, the configuration and data files used by a database
! cluster are stored together within the cluster's data
  directory, commonly referred to as <varname>PGDATA</> (after the name of the
  environment variable that can be used to define it).  A common location for
  <varname>PGDATA</> is <filename>/var/lib/pgsql/data</>.  Multiple clusters,
*************** these required items, the cluster config
*** 33,39 ****
  <filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>, and
  <filename>pg_ident.conf</filename> are traditionally stored in
  <varname>PGDATA</> (although in <productname>PostgreSQL</productname> 8.0 and
! later, it is possible to keep them elsewhere).
  </para>
  
  <table tocentry="1" id="pgdata-contents-table">
--- 34,40 ----
  <filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>, and
  <filename>pg_ident.conf</filename> are traditionally stored in
  <varname>PGDATA</> (although in <productname>PostgreSQL</productname> 8.0 and
! later, it is possible to place them elsewhere).
  </para>
  
  <table tocentry="1" id="pgdata-contents-table">

--FN+gV9K+162wdwwF--