Clarify pg_dump documentation

petere · petere · commit 10f55448965f · 2019-09-03T14:25:26.000+02:00
Clarify in the help output and documentation that -n, -t etc. take a "pattern" rather than a "schema" or "table" etc. This was especially confusing now that the new pg_dumpall --exclude-database option was documented with "pattern" and the others not, even though they all behave the same. Discussion: https://www.postgresql.org/message-id/flat/b85f3fa1-b350-38d1-1893-4f7911bd7310%402ndquadrant.com
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
@@ -375,17 +375,17 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-n <replaceable class="parameter">schema</replaceable></option></term>
-      <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term>
+      <term><option>-n <replaceable class="parameter">pattern</replaceable></option></term>
+      <term><option>--schema=<replaceable class="parameter">pattern</replaceable></option></term>
       <listitem>
        <para>
         Dump only schemas matching <replaceable
-        class="parameter">schema</replaceable>; this selects both the
+        class="parameter">pattern</replaceable>; this selects both the
         schema itself, and all its contained objects.  When this option is
         not specified, all non-system schemas in the target database will be
         dumped.  Multiple schemas can be
-        selected by writing multiple <option>-n</option> switches.  Also, the
-        <replaceable class="parameter">schema</replaceable> parameter is
+        selected by writing multiple <option>-n</option> switches.  The
+        <replaceable class="parameter">pattern</replaceable> parameter is
         interpreted as a pattern according to the same rules used by
         <application>psql</application>'s <literal>\d</literal> commands (see <xref
         linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>),
@@ -417,12 +417,12 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-N <replaceable class="parameter">schema</replaceable></option></term>
-      <term><option>--exclude-schema=<replaceable class="parameter">schema</replaceable></option></term>
+      <term><option>-N <replaceable class="parameter">pattern</replaceable></option></term>
+      <term><option>--exclude-schema=<replaceable class="parameter">pattern</replaceable></option></term>
       <listitem>
        <para>
-        Do not dump any schemas matching the <replaceable
-        class="parameter">schema</replaceable> pattern.  The pattern is
+        Do not dump any schemas matching <replaceable
+        class="parameter">pattern</replaceable>.  The pattern is
         interpreted according to the same rules as for <option>-n</option>.
         <option>-N</option> can be given more than once to exclude schemas
         matching any of several patterns.
@@ -513,16 +513,16 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-t <replaceable class="parameter">table</replaceable></option></term>
-      <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
+      <term><option>-t <replaceable class="parameter">pattern</replaceable></option></term>
+      <term><option>--table=<replaceable class="parameter">pattern</replaceable></option></term>
       <listitem>
        <para>
         Dump only tables with names matching
-        <replaceable class="parameter">table</replaceable>.
+        <replaceable class="parameter">pattern</replaceable>.
         For this purpose, <quote>table</quote> includes views, materialized views,
         sequences, and foreign tables.  Multiple tables
-        can be selected by writing multiple <option>-t</option> switches.  Also, the
-        <replaceable class="parameter">table</replaceable> parameter is
+        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
         <application>psql</application>'s <literal>\d</literal> commands (see <xref
         linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>),
@@ -565,12 +565,12 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-T <replaceable class="parameter">table</replaceable></option></term>
-      <term><option>--exclude-table=<replaceable class="parameter">table</replaceable></option></term>
+      <term><option>-T <replaceable class="parameter">pattern</replaceable></option></term>
+      <term><option>--exclude-table=<replaceable class="parameter">pattern</replaceable></option></term>
       <listitem>
        <para>
-        Do not dump any tables matching the <replaceable
-        class="parameter">table</replaceable> pattern.  The pattern is
+        Do not dump any tables matching <replaceable
+        class="parameter">pattern</replaceable>.  The pattern is
         interpreted according to the same rules as for <option>-t</option>.
         <option>-T</option> can be given more than once to exclude tables
         matching any of several patterns.
@@ -728,11 +728,11 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--exclude-table-data=<replaceable class="parameter">table</replaceable></option></term>
+      <term><option>--exclude-table-data=<replaceable class="parameter">pattern</replaceable></option></term>
       <listitem>
        <para>
-        Do not dump data for any tables matching the <replaceable
-        class="parameter">table</replaceable> pattern. The pattern is
+        Do not dump data for any tables matching <replaceable
+        class="parameter">pattern</replaceable>. The pattern is
         interpreted according to the same rules as for <option>-t</option>.
         <option>--exclude-table-data</option> can be given more than once to
         exclude tables matching any of several patterns. This option is
diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c
@@ -1000,22 +1000,22 @@ help(const char *progname)
 	printf(_("  -c, --clean                  clean (drop) database objects before recreating\n"));
 	printf(_("  -C, --create                 include commands to create database in dump\n"));
 	printf(_("  -E, --encoding=ENCODING      dump the data in encoding ENCODING\n"));
-	printf(_("  -n, --schema=SCHEMA          dump the named schema(s) only\n"));
-	printf(_("  -N, --exclude-schema=SCHEMA  do NOT dump the named schema(s)\n"));
+	printf(_("  -n, --schema=PATTERN         dump the specified schema(s) only\n"));
+	printf(_("  -N, --exclude-schema=PATTERN do NOT dump the specified schema(s)\n"));
 	printf(_("  -O, --no-owner               skip restoration of object ownership in\n"
 			 "                               plain-text format\n"));
 	printf(_("  -s, --schema-only            dump only the schema, no data\n"));
 	printf(_("  -S, --superuser=NAME         superuser user name to use in plain-text format\n"));
-	printf(_("  -t, --table=TABLE            dump the named table(s) only\n"));
-	printf(_("  -T, --exclude-table=TABLE    do NOT dump the named table(s)\n"));
+	printf(_("  -t, --table=PATTERN          dump the specified table(s) only\n"));
+	printf(_("  -T, --exclude-table=PATTERN  do NOT dump the specified table(s)\n"));
 	printf(_("  -x, --no-privileges          do not dump privileges (grant/revoke)\n"));
 	printf(_("  --binary-upgrade             for use by upgrade utilities only\n"));
 	printf(_("  --column-inserts             dump data as INSERT commands with column names\n"));
 	printf(_("  --disable-dollar-quoting     disable dollar quoting, use SQL standard quoting\n"));
 	printf(_("  --disable-triggers           disable triggers during data-only restore\n"));
 	printf(_("  --enable-row-security        enable row security (dump only content user has\n"
 			 "                               access to)\n"));
-	printf(_("  --exclude-table-data=TABLE   do NOT dump data for the named table(s)\n"));
+	printf(_("  --exclude-table-data=PATTERN do NOT dump data for the specified table(s)\n"));
 	printf(_("  --extra-float-digits=NUM     override default setting for extra_float_digits\n"));
 	printf(_("  --if-exists                  use IF EXISTS when dropping objects\n"));
 	printf(_("  --inserts                    dump data as INSERT commands, rather than COPY\n"));
