[doc] clarify behaviour of pg_dump's -t/--table option with non-tables

Started by Ian Lawrence Barwickover 5 years ago5 messages

barwick@gmail.com

over 5 years ago

1 attachment(s)

Recently I ran into a case where someone was wondering why it was not
possible to dump the contents of a view, even though the documentation [1]https://www.postgresql.org/docs/current/app-pgdump.html
seems to imply this is possible.

Currently it says:

Dump only tables with names matching pattern. For this purpose, "table"
includes views, materialized views, sequences, and foreign tables.

The attached patch attempts to clarify that only definitions of those objects
will be dumped, and also mentions that dumping foreign table data requires the
--include-foreign-data option.

I suggest backpatching any changes to Pg13 where the --include-foreign-data
option was added.

[1]: https://www.postgresql.org/docs/current/app-pgdump.html

Regards

Ian Barwick

--
EnterpriseDB: https://www.enterprisedb.com

Attachments:

doc-pg_dump-clarify-table-option.patchtext/x-patch; charset=US-ASCII; name=doc-pg_dump-clarify-table-option.patchDownload

commit 7240af7e6b7168ff1ad1790c6537b29f93fb6891
Author: Ian Barwick <barwick@gmail.com>
Date:   Tue Oct 6 21:40:37 2020 +0900

    doc: clarify behaviour of pg_dump's -t/--table option
    
    The existing wording gives the impression it might be possible to
    dump the contents of views, which is not possible. Also, from PostgreSQL
    13 it is possible to dump the contents of foreign tables, but this
    requires the --include-foreign-data option.

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index f99dc3f31e..4e2c80983e 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -517,9 +517,7 @@ PostgreSQL documentation
       <listitem>
        <para>
         Dump only tables with names matching
-        <replaceable class="parameter">pattern</replaceable>.
-        For this purpose, <quote>table</quote> includes views, materialized views,
-        sequences, and foreign tables.  Multiple tables
+        <replaceable class="parameter">pattern</replaceable>. Multiple tables
         can be selected by writing multiple <option>-t</option> switches.  The
         <replaceable class="parameter">pattern</replaceable> parameter is
         interpreted as a pattern according to the same rules used by
@@ -531,6 +529,14 @@ PostgreSQL documentation
         <xref linkend="pg-dump-examples"/> below.
        </para>
 
+       <para>
+        As well as tables, this option can be used to dump views, materialized views,
+        foreign tables, and sequence definitions.  However it will not dump the contents
+        of views or materialized views, and the contents of foreign tables will only be
+        dumped if the corresponding foreign server is specified with
+        <option>--include-foreign-data</option>.
+       </para>
+
        <para>
         The <option>-n</option> and <option>-N</option> switches have no effect when
         <option>-t</option> is used, because tables selected by <option>-t</option> will

Ian Lawrence Barwick

barwick@gmail.com

over 5 years ago

In reply to: Ian Lawrence Barwick (#1)

1 attachment(s)

Re: [doc] clarify behaviour of pg_dump's -t/--table option with non-tables

2020年10月6日(火) 21:58 Ian Lawrence Barwick <barwick@gmail.com>:

Hi

Recently I ran into a case where someone was wondering why it was not
possible to dump the contents of a view, even though the documentation [1]
seems to imply this is possible.

Currently it says:

Dump only tables with names matching pattern. For this purpose, "table"
includes views, materialized views, sequences, and foreign tables.

The attached patch attempts to clarify that only definitions of those objects
will be dumped, and also mentions that dumping foreign table data requires the
--include-foreign-data option.

I suggest backpatching any changes to Pg13 where the --include-foreign-data
option was added.

[1] https://www.postgresql.org/docs/current/app-pgdump.html

Better version attached.

Regards

Ian Barwick

--
EnterpriseDB: https://www.enterprisedb.com

Attachments:

doc-pg_dump-clarify-table-option.v2.patchtext/x-patch; charset=US-ASCII; name=doc-pg_dump-clarify-table-option.v2.patchDownload

commit 4344e620620fa82d89bc9838d389cc345a7763ea
Author: Ian Barwick <barwick@gmail.com>
Date:   Tue Oct 6 21:40:37 2020 +0900

    doc: clarify behaviour of pg_dump's -t/--table option
    
    The existing wording gives the impression it might be possible to
    dump the contents of views, which is not possible. Also, from PostgreSQL
    13 it is possible to dump the contents of foreign tables, but this
    requires the --include-foreign-data option.

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index f99dc3f31e..0aa35cf0c3 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -517,9 +517,7 @@ PostgreSQL documentation
       <listitem>
        <para>
         Dump only tables with names matching
-        <replaceable class="parameter">pattern</replaceable>.
-        For this purpose, <quote>table</quote> includes views, materialized views,
-        sequences, and foreign tables.  Multiple tables
+        <replaceable class="parameter">pattern</replaceable>. Multiple tables
         can be selected by writing multiple <option>-t</option> switches.  The
         <replaceable class="parameter">pattern</replaceable> parameter is
         interpreted as a pattern according to the same rules used by
@@ -531,6 +529,14 @@ PostgreSQL documentation
         <xref linkend="pg-dump-examples"/> below.
        </para>
 
+       <para>
+        As well as tables, this option can be used to dump the definition of matching
+        views, materialized views, foreign tables, and sequences.  It will not dump the
+        contents of views or materialized views, and the contents of foreign tables will
+        only be dumped if the corresponding foreign server is specified with
+        <option>--include-foreign-data</option>.
+       </para>
+
        <para>
         The <option>-n</option> and <option>-N</option> switches have no effect when
         <option>-t</option> is used, because tables selected by <option>-t</option> will

Magnus Hagander

magnus@hagander.net

over 5 years ago

In reply to: Ian Lawrence Barwick (#1)

Re: [doc] clarify behaviour of pg_dump's -t/--table option with non-tables

On Tue, Oct 6, 2020 at 2:59 PM Ian Lawrence Barwick <barwick@gmail.com>
wrote:

Hi

Recently I ran into a case where someone was wondering why it was not
possible to dump the contents of a view, even though the documentation [1]
seems to imply this is possible.

Currently it says:

Dump only tables with names matching pattern. For this purpose, "table"
includes views, materialized views, sequences, and foreign tables.

The attached patch attempts to clarify that only definitions of those
objects
will be dumped, and also mentions that dumping foreign table data requires
the
--include-foreign-data option.

I suggest backpatching any changes to Pg13 where the --include-foreign-data
option was added.

LGTM and agreed on the backpatch. Pushed.

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/>
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>

Magnus Hagander

magnus@hagander.net

over 5 years ago

In reply to: Ian Lawrence Barwick (#2)

Re: [doc] clarify behaviour of pg_dump's -t/--table option with non-tables

On Tue, Oct 6, 2020 at 3:45 PM Ian Lawrence Barwick <barwick@gmail.com>
wrote:

2020年10月6日(火) 21:58 Ian Lawrence Barwick <barwick@gmail.com>:

Hi

Recently I ran into a case where someone was wondering why it was not
possible to dump the contents of a view, even though the documentation

[1]

seems to imply this is possible.

Currently it says:

Dump only tables with names matching pattern. For this purpose, "table"
includes views, materialized views, sequences, and foreign tables.

The attached patch attempts to clarify that only definitions of those

objects

will be dumped, and also mentions that dumping foreign table data

requires the

--include-foreign-data option.

I suggest backpatching any changes to Pg13 where the

--include-foreign-data

option was added.

[1] https://www.postgresql.org/docs/current/app-pgdump.html

Better version attached.

Argh, perfect timing. I'll update with your new version :)

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/>
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>

Ian Lawrence Barwick

barwick@gmail.com

over 5 years ago

In reply to: Magnus Hagander (#4)

Re: [doc] clarify behaviour of pg_dump's -t/--table option with non-tables

2020年10月6日(火) 22:48 Magnus Hagander <magnus@hagander.net>:

On Tue, Oct 6, 2020 at 3:45 PM Ian Lawrence Barwick <barwick@gmail.com> wrote:

2020年10月6日(火) 21:58 Ian Lawrence Barwick <barwick@gmail.com>:

Hi

Recently I ran into a case where someone was wondering why it was not
possible to dump the contents of a view, even though the documentation [1]
seems to imply this is possible.

Currently it says:

Dump only tables with names matching pattern. For this purpose, "table"
includes views, materialized views, sequences, and foreign tables.

The attached patch attempts to clarify that only definitions of those objects
will be dumped, and also mentions that dumping foreign table data requires the
--include-foreign-data option.

I suggest backpatching any changes to Pg13 where the --include-foreign-data
option was added.

[1] https://www.postgresql.org/docs/current/app-pgdump.html

Better version attached.

Argh, perfect timing. I'll update with your new version :)

Whoops, wasn't expecting such a quick response. Thanks!

FWIW, I sent in another patch suggesting removal of an ancient
backwards compatibility
"Note" under the same -t/--tables option description [1]/messages/by-id/CAB8KJ=jYHgnxLLZSNJz7gBTck4TxomngCmGkw3nEMSNF0yL6wA@mail.gmail.com.

[1]: /messages/by-id/CAB8KJ=jYHgnxLLZSNJz7gBTck4TxomngCmGkw3nEMSNF0yL6wA@mail.gmail.com

Regards

Ian Barwick

--
EnterpriseDB: https://www.enterprisedb.com