Re: Create a Foreign Table for PostgreSQL CSV Logs

On Fri, Aug 21, 2020 at 2:58 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Fri, Aug 21, 2020 at 09:25:20AM +0000, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/12/runtime-config-logging.html
> > Description:
> >
> > There is some imperfection in PostgreSQL doc. There are two section in
> > documentation how to import PostgreSQL log into sql space and both not
> > complete. One of them is:
> > https://www.postgresql.org/docs/current/file-fdw.html
> > Example F.1. Create a Foreign Table for PostgreSQL CSV Logs
> > Here is described how to config file-fdw to get access to the PostgreSQL
> > logs, but there is not description or a link how to config PostgreSQL log
> > for this.
> >
> > Other section is:
> >
> https://www.postgresql.org/docs/12/runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-CSVLOG
> > 19.8.4. Using CSV-Format Log Output
> > Here is described how to configure PostgreSQL log to import it into
> > previously created ordinary table by COPY command. May be this
> configuration
> > is compatible with "Example F.1. Create a Foreign Table for PostgreSQL
> CSV
> > Logs", but this method is not mentioned.
> >
> > My idea to improve documentation by adding cross link: to section
> «Example
> > F.1. Create a Foreign Table for PostgreSQL CSV Logs» add link to «19.8.4.
> > Using CSV-Format Log Output» as example of log configuration and to
> section
> > «19.8.4. Using CSV-Format Log Output» add link to «Example F.1. Create a
> > Foreign Table for PostgreSQL CSV Logs» as one more example how PostgreSQL
> > logs can be imported inside PostgreSQL.
>
> Good idea. People have been confused about this before. Attached is a
> patch.
>

+ It is also possible to access the file as a foreign data wrapper
+ using <xref linkend="file-fdw"/>.

Seems more accurate to say "It is also possible to access the file as a
foreign table, using the supplied <xref linkend="file-fdw"/> module."

The file_fdw -> config change looks good.

A bit off-topic, but since this is being touched anyway - the listing of
fields in the paragraph is not particularly readable (but maybe we want to
keep it for accessibility reasons?) while the CREATE TABLE statement is
very readable and more accurate, though it could be better. Adding CHECK
constraints and -- comments to the CREATE TABLE command would be a welcome
addition. In particular I noticed:

paragraph: client host:port number
example: connection_from text,

could become:

connection_from text check(connection_from ~ '^[^:]+:[0-9]+$) -- the host
and port of the client, colon-separated

I've been mentally playing around with the idea of having the Config
section with the CREATE TABLE somehow describe both the plain table and
foreign table variants directly and removing the example from the file_fdw
section and instead leaving the cross-references in place from file_fdw to
config to see the example and from config to file_fdw to get clarity on the
options and the SERVER syntax. As they are being written for
copy-and-paste though, and it's not like we are going to change the format,
having the table definition duplicated isn't a terrible option. But
consolidation is something to consider.

I may pick this up in the future unless someone thinks it wouldn't be a
good idea. I would be removing the paragraph of field names and make the
table specification authoritative.

David J.