v20231121_fixups.txt
text/plain
Filename: v20231121_fixups.txt
Type: text/plain
Part: 0
commit 4a3c0bdaf3fd21b75e17244691fbeb9340e960e1
Author: Daniel Gustafsson <dgustafsson@postgresql.org>
Date: Tue Nov 21 15:08:27 2023 +0100
Fixups and tweaks
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index e2f100d552..0e5ba4f712 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -873,49 +873,52 @@ PostgreSQL documentation
<itemizedlist>
<listitem>
<para>
- <literal>extension</literal>: data on foreign servers, works like
- <option>--extension</option>. This keyword can only be
+ <literal>extension</literal>: extensions, works like the
+ <option>--extension</option> option. This keyword can only be
used with the <literal>include</literal> keyword.
</para>
</listitem>
<listitem>
<para>
<literal>foreign_data</literal>: data on foreign servers, works like
- <option>--include-foreign-data</option>. This keyword can only be
- used with the <literal>include</literal> keyword.
+ the <option>--include-foreign-data</option> option. This keyword can
+ only be used with the <literal>include</literal> keyword.
</para>
</listitem>
<listitem>
<para>
- <literal>table</literal>: tables, works like
- <option>-t</option>/<option>--table</option>
+ <literal>table</literal>: tables, works like the
+ <option>-t</option>/<option>--table</option> option.
</para>
</listitem>
<listitem>
<para>
- <literal>table_and_children</literal>: tables, works like
- <option>--table-and-children</option>
+ <literal>table_and_children</literal>: tables including any partitions
+ or inheritance child tables, works like the
+ <option>--table-and-children</option> option.
</para>
</listitem>
<listitem>
<para>
- <literal>table_data</literal>: table data, works like
- <option>--exclude-table-data</option>. This keyword can only be
- used with the <literal>exclude</literal> keyword.
+ <literal>table_data</literal>: table data of any tables matching
+ <replaceable>pattern</replaceable>, works like the
+ <option>--exclude-table-data</option> option. This keyword can only
+ be used with the <literal>exclude</literal> keyword.
</para>
</listitem>
<listitem>
<para>
- <literal>table_data_and_children</literal>: table data of any
- partitions or inheritance child, works like
- <option>--exclude-table-data-and-children</option>. This keyword can only be
- used with the <literal>exclude</literal> keyword.
+ <literal>table_data_and_children</literal>: table data of any tables
+ matching <replaceable>pattern</replaceable> as well as any partitions
+ or inheritance children of the table(s), works like the
+ <option>--exclude-table-data-and-children</option> option. This
+ keyword can only be used with the <literal>exclude</literal> keyword.
</para>
</listitem>
<listitem>
<para>
- <literal>schema</literal>: schemas, works like
- <option>-n</option>/<option>--schema</option>
+ <literal>schema</literal>: schemas, works like the
+ <option>-n</option>/<option>--schema</option> option.
</para>
</listitem>
</itemizedlist>
@@ -923,9 +926,9 @@ PostgreSQL documentation
<para>
Lines starting with <literal>#</literal> are considered comments and
- ignored. Comments can be placed after filter as well. Blank lines
- are also ignored. See <xref linkend="app-psql-patterns"/> for how to
- perform quoting in patterns.
+ ignored. Comments can be placed after an object pattern row as well.
+ Blank lines are also ignored. See <xref linkend="app-psql-patterns"/>
+ for how to perform quoting in patterns.
</para>
<para>
@@ -1715,8 +1718,8 @@ CREATE DATABASE foo WITH TEMPLATE template0;
</screen></para>
<para>
- To dump all tables with names starting with mytable, except for table
- <literal>mytable2</literal>, specify a filter file
+ To dump all tables whose names start with <literal>mytable</literal>, except
+ for table <literal>mytable2</literal>, specify a filter file
<filename>filter.txt</filename> like:
<programlisting>
include table mytable*
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 75ba03f3ad..4d7c046468 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -130,20 +130,29 @@ PostgreSQL documentation
<listitem>
<para>
Specify a filename from which to read patterns for databases excluded
- from the dump. The patterns are interpretted according to the same rules
+ from the dump. The patterns are interpreted according to the same rules
as <option>--exclude-database</option>.
To read from <literal>STDIN</literal>, use <filename>-</filename> as the
filename. The <option>--filter</option> option can be specified in
- conjunction with the above listed options for excluding databases,
- and can also be specified more than once for multiple filter files.
+ conjunction with <option>--exclude-database</option> for excluding
+ databases, and can also be specified more than once for multiple filter
+ files.
</para>
<para>
The file lists one database pattern per row, with the following format:
<synopsis>
-exclude database <replaceable class="parameter">PATTERN</replaceable>
+exclude database <replaceable class="parameter">PATTERN</replaceable>
</synopsis>
</para>
+
+ <para>
+ Lines starting with <literal>#</literal> are considered comments and
+ ignored. Comments can be placed after an object pattern row as well.
+ Blank lines are also ignored. See <xref linkend="app-psql-patterns"/>
+ for how to perform quoting in patterns.
+ </para>
+
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 64f7c5dc4d..1a23874da6 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -195,10 +195,14 @@ PostgreSQL documentation
<listitem>
<para>
Specify a filename from which to read patterns for objects excluded
- or included from restore. The patterns are interpretted according to the
- same rules as <option>--schema</option>, <option>--exclude-schema</option>,
- <option>--function</option>, <option>--index</option>, <option>--table</option>
- or <option>--trigger</option>.
+ or included from restore. The patterns are interpreted according to the
+ same rules as
+ <option>-n</option>/<option>--schema</option> for including objects in schemas,
+ <option>-N</option>/<option>--exclude-schema</option>for excluding objects in schemas,
+ <option>-P</option>/<option>--function</option> for restoring named functions,
+ <option>-I</option>/<option>--index</option> for restoring named indexes,
+ <option>-t</option>/<option>--table</option> for restoring named tables
+ or <option>-T</option>/<option>--trigger</option> for restoring triggers.
To read from <literal>STDIN</literal>, use <filename>-</filename> as the
filename. The <option>--filter</option> option can be specified in
conjunction with the above listed options for including or excluding
@@ -212,6 +216,57 @@ PostgreSQL documentation
{ include | exclude } { function | index | schema | table | trigger } <replaceable class="parameter">PATTERN</replaceable>
</synopsis>
</para>
+
+ <para>
+ The first keyword specifies whether the objects matched by the pattern
+ are to be included or excluded. The second keyword specifies the type
+ of object to be filtered using the pattern:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>function</literal>: functions, works like the
+ <option>-P</option>/<option>--function</option> option. This keyword
+ can only be used with the <literal>include</literal> keyword.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>index</literal>: indexes, works like the
+ <option>-I</option>/<option>--indexes</option> option. This keyword
+ can only be used with the <literal>include</literal> keyword.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>schema</literal>: schemas, works like the
+ <option>-n</option>/<option>--schema</option> and
+ <option>-N</option>/<option>--exclude-schema</option> options.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>table</literal>: tables, works like the
+ <option>-t</option>/<option>--table</option> option. This keyword
+ can only be used with the <literal>include</literal> keyword.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>trigger</literal>: triggers, works like the
+ <option>-T</option>/<option>--trigger</option> option. This keyword
+ can only be used with the <literal>include</literal> keyword.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Lines starting with <literal>#</literal> are considered comments and
+ ignored. Comments can be placed after an object pattern row as well.
+ Blank lines are also ignored. See <xref linkend="app-psql-patterns"/>
+ for how to perform quoting in patterns.
+ </para>
+
</listitem>
</varlistentry>
diff --git a/src/bin/pg_dump/filter.c b/src/bin/pg_dump/filter.c
index 9b5e45c722..b64822b6b7 100644
--- a/src/bin/pg_dump/filter.c
+++ b/src/bin/pg_dump/filter.c
@@ -23,15 +23,13 @@
/*
* Following routines are called from pg_dump, pg_dumpall and pg_restore.
- * Unfortunately, the implementation of exit_nicely in pg_dump and pg_restore is
- * different from the one in pg_dumpall, so instead of calling exit_nicely we
- * have to return some error flag (in this case NULL), and exit_nicely will be
- * executed from caller's routine.
+ * Since the implementation of exit_nicely is application specific, each
+ * application need to pass a function pointer to the exit_nicely function to
+ * use for exiting on errors.
*/
/*
* Opens filter's file and initialize fstate structure.
- * Returns true on success.
*/
void
filter_init(FilterStateData *fstate, const char *filename, exit_function f_exit)
@@ -76,8 +74,8 @@ filter_free(FilterStateData *fstate)
}
/*
- * Translate FilterObjectType enum to string. It is designed for formatting
- * of error message in log_unsupported_filter_object_type routine.
+ * Translate FilterObjectType enum to string. The main purpose is for error
+ * message formatting.
*/
const char *
filter_object_type_name(FilterObjectType fot)
@@ -181,7 +179,7 @@ filter_get_keyword(const char **line, int *size)
const char *ptr = *line;
const char *result = NULL;
- /* Set returnlength preemptively in case no keyword is found */
+ /* Set returned length preemptively in case no keyword is found */
*size = 0;
/* Skip initial whitespace */
@@ -382,8 +380,7 @@ read_pattern(FilterStateData *fstate, const char *str, PQExpBuffer pattern)
* Returns true when one filter item was successfully read and parsed. When
* object name contains \n chars, then more than one line from input file can
* be processed. Returns false when the filter file reaches EOF. In case of
- * error, the function will emit an appropriate error message before returning
- * false.
+ * error, the function will emit an appropriate error message and exit.
*/
bool
filter_read_item(FilterStateData *fstate,
diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c
index 1e7756beba..64e2d754d1 100644
--- a/src/bin/pg_dump/pg_dump.c
+++ b/src/bin/pg_dump/pg_dump.c
@@ -436,6 +436,7 @@ main(int argc, char **argv)
{"exclude-table-data-and-children", required_argument, NULL, 14},
{"sync-method", required_argument, NULL, 15},
{"filter", required_argument, NULL, 16},
+
{NULL, 0, NULL, 0}
};
@@ -666,7 +667,7 @@ main(int argc, char **argv)
exit_nicely(1);
break;
- case 16: /* object filters from file */
+ case 16: /* read object filters from file */
read_dump_filters(optarg, &dopt);
break;
@@ -1117,8 +1118,8 @@ help(const char *progname)
" do NOT dump data for the specified table(s),\n"
" including child and partition tables\n"));
printf(_(" --extra-float-digits=NUM override default setting for extra_float_digits\n"));
- printf(_(" --filter=FILENAME dump objects and data based on the filter expressions\n"
- " in specified file\n"));
+ printf(_(" --filter=FILENAME include or exclude objects and data from dump\n"
+ " based expressions in FILENAME\n"));
printf(_(" --if-exists use IF EXISTS when dropping objects\n"));
printf(_(" --include-foreign-data=PATTERN\n"
" include data of foreign tables on foreign\n"
diff --git a/src/bin/pg_dump/pg_dumpall.c b/src/bin/pg_dump/pg_dumpall.c
index fe2a541c56..1b974cf7e8 100644
--- a/src/bin/pg_dump/pg_dumpall.c
+++ b/src/bin/pg_dump/pg_dumpall.c
@@ -160,7 +160,6 @@ main(int argc, char *argv[])
{"disable-triggers", no_argument, &disable_triggers, 1},
{"exclude-database", required_argument, NULL, 6},
{"extra-float-digits", required_argument, NULL, 5},
- {"filter", required_argument, NULL, 8},
{"if-exists", no_argument, &if_exists, 1},
{"inserts", no_argument, &inserts, 1},
{"lock-wait-timeout", required_argument, NULL, 2},
@@ -180,6 +179,7 @@ main(int argc, char *argv[])
{"no-unlogged-table-data", no_argument, &no_unlogged_table_data, 1},
{"on-conflict-do-nothing", no_argument, &on_conflict_do_nothing, 1},
{"rows-per-insert", required_argument, NULL, 7},
+ {"filter", required_argument, NULL, 8},
{NULL, 0, NULL, 0}
};
@@ -660,7 +660,7 @@ help(void)
printf(_(" --disable-triggers disable triggers during data-only restore\n"));
printf(_(" --exclude-database=PATTERN exclude databases whose name matches PATTERN\n"));
printf(_(" --extra-float-digits=NUM override default setting for extra_float_digits\n"));
- printf(_(" --filter=FILENAME exclude databases specified in filter file\n"));
+ printf(_(" --filter=FILENAME exclude databases specified in FILENAME\n"));
printf(_(" --if-exists use IF EXISTS when dropping objects\n"));
printf(_(" --inserts dump data as INSERT commands, rather than COPY\n"));
printf(_(" --load-via-partition-root load partitions via the root table\n"));
@@ -1921,6 +1921,7 @@ executeCommand(PGconn *conn, const char *query)
PQclear(res);
}
+
/*
* dumpTimestamp
*/
diff --git a/src/bin/pg_dump/pg_restore.c b/src/bin/pg_dump/pg_restore.c
index 0cca9ee612..1459e02263 100644
--- a/src/bin/pg_dump/pg_restore.c
+++ b/src/bin/pg_dump/pg_restore.c
@@ -470,7 +470,8 @@ usage(const char *progname)
printf(_(" -1, --single-transaction restore as a single transaction\n"));
printf(_(" --disable-triggers disable triggers during data-only restore\n"));
printf(_(" --enable-row-security enable row security\n"));
- printf(_(" --filter=FILE restore objects based on filter expressions\n"));
+ printf(_(" --filter=FILENAME restore or skip objects based on expressions\n"
+ " in FILENAME\n"));
printf(_(" --if-exists use IF EXISTS when dropping objects\n"));
printf(_(" --no-comments do not restore comments\n"));
printf(_(" --no-data-for-failed-tables do not restore data of tables that could not be\n"
diff --git a/src/bin/pg_dump/t/005_pg_dump_filterfile.pl b/src/bin/pg_dump/t/005_pg_dump_filterfile.pl
index 09d3262b8b..d4c2c2340d 100644
--- a/src/bin/pg_dump/t/005_pg_dump_filterfile.pl
+++ b/src/bin/pg_dump/t/005_pg_dump_filterfile.pl
@@ -1,12 +1,12 @@
-# Copyright (c) 2021, PostgreSQL Global Development Group
+# Copyright (c) 2023, PostgreSQL Global Development Group
use strict;
use warnings;
use PostgreSQL::Test::Cluster;
use PostgreSQL::Test::Utils;
-use Test::More tests => 106;
+use Test::More;
my $tempdir = PostgreSQL::Test::Utils::tempdir;;
my $inputfile;
@@ -421,7 +421,7 @@ command_ok(
"--filter=$tempdir/inputfile.txt",
'--strict-names', 'postgres'
],
- "strict names with matching mattern");
+ "strict names with matching pattern");
$dump = slurp_file($plainfile);
@@ -546,7 +546,7 @@ command_fails_like(
"--filter=$tempdir/inputfile.txt"
],
qr/include filter for "table data" is not allowed/,
- "invalid syntax: inclusion of non allowed object"
+ "invalid syntax: inclusion of unallowed object"
);
open $inputfile, '>', "$tempdir/inputfile.txt"
@@ -560,7 +560,7 @@ command_fails_like(
"--filter=$tempdir/inputfile.txt"
],
qr/include filter for "extension" is not allowed/,
- "invalid syntax: inclusion of non allowed object"
+ "invalid syntax: inclusion of unallowed object"
);
open $inputfile, '>', "$tempdir/inputfile.txt"
@@ -574,7 +574,7 @@ command_fails_like(
"--filter=$tempdir/inputfile.txt"
],
qr/exclude filter for "extension" is not allowed/,
- "invalid syntax: exclusion of non allowed object"
+ "invalid syntax: exclusion of unallowed object"
);
open $inputfile, '>', "$tempdir/inputfile.txt"
@@ -587,8 +587,8 @@ command_fails_like(
'pg_restore', '-p', $port, '-f', $plainfile,
"--filter=$tempdir/inputfile.txt"
],
- qr/xclude filter for "table data" is not allowed/,
- "invalid syntax: exclusion of non allowed object"
+ qr/exclude filter for "table data" is not allowed/,
+ "invalid syntax: exclusion of unallowed object"
);
#########################################
@@ -771,3 +771,6 @@ command_fails_like(
],
qr/pg_dump: error: no matching extensions were found/,
"dump nonexisting extension");
+
+
+done_testing();