Subject: please inform data_directory

From: PG Doc comments form <[email-masked]>
Date: Sun, 09 Sep 2018 23:41:36 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/static/functions-admin.html
Description:

It is impossible to use pg_read_file(), etc. functions without 
SHOW  data_directory

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 10 Oct 2018 15:59:59 -0400

> It is impossible to use pg_read_file(), etc. functions without 

What do you mean by that?  I can call pg_read_file() before calling
'SHOW  data_directory'.  Are you saying that pg_read_file can only read
in the data_directory?  It is designed that way.

-- 
  Bruce Momjian  <[email-masked]>        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 +

---

From: Michael Paquier <[email-masked]>
Date: Thu, 11 Oct 2018 10:04:12 +0900

> in the data_directory?  It is designed that way.

Please note that v11 has added a new default role called
pg_read_server_files, which allows a role to read files out of the data
directory which is the default.
--
Michael

---

From: Peter Krauss <[email-masked]>
Date: Thu, 11 Oct 2018 15:50:09 -0300

Hi, trying to explain again,
the "SHOW  data_directory"  is an information that *not exist in the guide
today, *but must to exist... is a suggestion to add information, a
middle-expert or non-extert reader need it.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 11 Oct 2018 14:51:36 -0400

On Thu, Oct 11, 2018 at 03:50:09PM -0300, Peter Krauss wrote:
> the "SHOW  data_directory"  is an information that not exist in the guide
> today, but must to exist... is a suggestion to add information, a middle-expert
> or non-extert reader need it.

Uh, add data_directory where?  Which guide?

---

From: Peter Krauss <[email-masked]>
Date: Thu, 11 Oct 2018 15:56:42 -0300

The page https://www.postgresql.org/docs/10/static/functions-admin.html
need this information, is like a  "pg_read_file Guide".

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 11 Oct 2018 15:24:31 -0400

>     Uh, add data_directory where?  Which guide?

How is this patch adding a mention of the data_directory setting?

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
new file mode 100644
index 5193df3..0a5b30a
*** a/doc/src/sgml/func.sgml
--- b/doc/src/sgml/func.sgml
*************** postgres=# SELECT * FROM pg_walfile_name
*** 20297,20303 ****
      The functions shown in <xref
      linkend="functions-admin-genfile-table"/> provide native access to
      files on the machine hosting the server. Only files within the
!     database cluster directory and the <varname>log_directory</varname> can be
      accessed unless the user is granted the role
      <literal>pg_read_server_files</literal>.  Use a relative path for files in
      the cluster directory, and a path matching the <varname>log_directory</varname>
--- 20297,20305 ----
      The functions shown in <xref
      linkend="functions-admin-genfile-table"/> provide native access to
      files on the machine hosting the server. Only files within the
!     database cluster directory (see <link
!     linkend="guc-data-directory"><varname>data_directory</varname></link>)
!     and the <varname>log_directory</varname> can be
      accessed unless the user is granted the role
      <literal>pg_read_server_files</literal>.  Use a relative path for files in
      the cluster directory, and a path matching the <varname>log_directory</varname>

---

From: "David G. Johnston" <[email-masked]>
Date: Thu, 11 Oct 2018 12:51:27 -0700

> need this information, is like a  "pg_read_file Guide".

Applies to all:

"The functions shown in Table 9.88 provide native access to files on the
machine hosting the server. Only files within the database cluster
directory and the log_directory can be accessed. Use a relative path for
files in the cluster directory, and a path matching the log_directory
configuration setting for log files. Use of these functions is restricted
to superusers except where stated otherwise."

Applies to pg_read_file:

"pg_read_file returns part of a text file, starting at the given offset,
returning at most length bytes (less if the end of file is reached first).
If offset is negative, it is relative to the end of the file. If offset and
length are omitted, the entire file is returned. The bytes read from the
file are interpreted as a string in the server encoding; an error is thrown
if they are not valid in that encoding."

There is nothing unclear there and by the time one gets to this part of the
documentation its reasonably assumed they understand "data directory";
being verbose on that point is not an improvement.  For the rare person
that gets confused these lists are available to obtain clarity.  But aside
from the one comment I've already made - and this is very minor in nature -
I'm not seeing anything obvious short-comings here.

David J.