Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtp (Exim 4.84_2)
	(envelope-from <pgsql-bugs-owner+archive@lists.postgresql.org>)
	id 1ee2ND-0002oF-M5
	for pgsql-bugs@arkaria.postgresql.org; Tue, 23 Jan 2018 17:28:39 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.84_2)
	(envelope-from <pgsql-bugs-owner+archive@lists.postgresql.org>)
	id 1ee2NC-0003w0-L0
	for pgsql-bugs@arkaria.postgresql.org; Tue, 23 Jan 2018 17:28:38 +0000
Received: from makus.postgresql.org ([2001:4800:1501:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256)
	(Exim 4.84_2)
	(envelope-from <bruce@momjian.us>)
	id 1ee2NC-0003vk-Br
	for pgsql-bugs@lists.postgresql.org; Tue, 23 Jan 2018 17:28:38 +0000
Received: from momjian.us ([72.94.173.45])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <bruce@momjian.us>)
	id 1ee2N5-00023Z-6L
	for pgsql-bugs@postgresql.org; Tue, 23 Jan 2018 17:28:37 +0000
Received: from bruce by momjian.us with local (Exim 4.84_2)
	(envelope-from <bruce@momjian.us>)
	id 1ee2N4-0001AI-Bc; Tue, 23 Jan 2018 12:28:30 -0500
Date: Tue, 23 Jan 2018 12:28:30 -0500
From: Bruce Momjian <bruce@momjian.us>
To: yves.goergen@gmail.com
Cc: pgsql-bugs@postgresql.org
Subject: Re: [BUGS] BUG #14898: pg_upgrade documentation is misleading
Message-ID: <20180123172830.GA31548@momjian.us>
References: <20171110220912.31513.13322@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="sdtB3X0nJg68CQEu"
Content-Disposition: inline
In-Reply-To: <20171110220912.31513.13322@wrigleys.postgresql.org>
User-Agent: Mutt/1.5.23 (2014-03-12)
List-Id: <pgsql-bugs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-bugs@lists.postgresql.org>
List-Owner: <mailto:pgsql-bugs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-bugs>
Precedence: bulk


--sdtB3X0nJg68CQEu
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Fri, Nov 10, 2017 at 10:09:12PM +0000, yves.goergen@gmail.com wrote:
> The following bug has been logged on the website:
> 
> Bug reference:      14898
> Logged by:          Yves Goergen
> Email address:      yves.goergen@gmail.com
> PostgreSQL version: 10.0
> Operating system:   Ubuntu
> Description:        
> 
> The documentation of pg_upgrade suggests that -d and -D are the data
> directories. But actually they expect the config directories. In a default
> installation from the official packages for Ubuntu (from PostgreSQL, not
> from Ubuntu), this is a difference between /var/lib/postgresql/10/main and
> /etc/postgresql/10/main. See also https://dba.stackexchange.com/q/190469

I think you are correct.  We have tried to adjust our documentation to
show the most common implementation locations, but at the same time to
be accurate.  For example, in the the 'postgres' manual page, we kept -D
(signifying datadir) but describe it as the location of the
configuration files, e.g.

       -D datadir
           Specifies the file system location of the database
           configuration files.

This was not done with pg_upgrade, and the attached patch fixes that.  I
am thinking of applying this to PG 10 and head (PG 11)  but not
backpatching it further.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

--sdtB3X0nJg68CQEu
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="datadir.diff"

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
new file mode 100644
index 055eac3..62f5cb3
*** a/doc/src/sgml/ref/pgupgrade.sgml
--- b/doc/src/sgml/ref/pgupgrade.sgml
***************
*** 24,32 ****
     <arg choice="plain"><option>-B</option></arg>
     <arg choice="plain"><replaceable>newbindir</replaceable></arg>
     <arg choice="plain"><option>-d</option></arg>
!    <arg choice="plain"><replaceable>olddatadir</replaceable></arg>
     <arg choice="plain"><option>-D</option></arg>
!    <arg choice="plain"><replaceable>newdatadir</replaceable></arg>
     <arg rep="repeat"><replaceable>option</replaceable></arg>
    </cmdsynopsis>
   </refsynopsisdiv>
--- 24,32 ----
     <arg choice="plain"><option>-B</option></arg>
     <arg choice="plain"><replaceable>newbindir</replaceable></arg>
     <arg choice="plain"><option>-d</option></arg>
!    <arg choice="plain"><replaceable>oldconfigdir</replaceable></arg>
     <arg choice="plain"><option>-D</option></arg>
!    <arg choice="plain"><replaceable>newconfigdir</replaceable></arg>
     <arg rep="repeat"><replaceable>option</replaceable></arg>
    </cmdsynopsis>
   </refsynopsisdiv>
***************
*** 99,114 ****
       </varlistentry>
  
       <varlistentry>
!       <term><option>-d</option> <replaceable>datadir</replaceable></term>
!       <term><option>--old-datadir=</option><replaceable>datadir</replaceable></term>
!       <listitem><para>the old cluster data directory; environment
        variable <envar>PGDATAOLD</envar></para></listitem>
       </varlistentry>
  
       <varlistentry>
!       <term><option>-D</option> <replaceable>datadir</replaceable></term>
!       <term><option>--new-datadir=</option><replaceable>datadir</replaceable></term>
!       <listitem><para>the new cluster data directory; environment
        variable <envar>PGDATANEW</envar></para></listitem>
       </varlistentry>
  
--- 99,114 ----
       </varlistentry>
  
       <varlistentry>
!       <term><option>-d</option> <replaceable>configdir</replaceable></term>
!       <term><option>--old-datadir=</option><replaceable>configdir</replaceable></term>
!       <listitem><para>the old database cluster configuration directory; environment
        variable <envar>PGDATAOLD</envar></para></listitem>
       </varlistentry>
  
       <varlistentry>
!       <term><option>-D</option> <replaceable>configdir</replaceable></term>
!       <term><option>--new-datadir=</option><replaceable>configdir</replaceable></term>
!       <listitem><para>the new database cluster configuration directory; environment
        variable <envar>PGDATANEW</envar></para></listitem>
       </varlistentry>
  
*************** pg_upgrade.exe
*** 476,482 ****
        <title>Save configuration files</title>
  
        <para>
!        Save any configuration files from the old standbys' data
         directories you need to keep, e.g.  <filename>postgresql.conf</filename>,
         <literal>recovery.conf</literal>, because these will be overwritten or
         removed in the next step.
--- 476,482 ----
        <title>Save configuration files</title>
  
        <para>
!        Save any configuration files from the old standbys' configuration
         directories you need to keep, e.g.  <filename>postgresql.conf</filename>,
         <literal>recovery.conf</literal>, because these will be overwritten or
         removed in the next step.

--sdtB3X0nJg68CQEu--