Tar-format dumps include an undocumented restore.sql script that can be run
with psql after extracting the archive and hand-editing its $$PATH$$
placeholders.  pg_restore never reads it.  This script has needed a number
of fixes over the years (e.g., commits bf0945e863, ff75219e9f, 3c5d9d914f,
and 146e03e79a), and it still fails to restore table data for dumps taken
with --inserts.  Furthermore, it is generated by a second pass over the
TOC, which forced tar-only hacks into the statistics code added by commits
7d5c83b4e9 and 9c02e3a986.  Those hacks run all the attribute statistics
queries a second time just for this file.

We could spend more time fixing restore.sql, but by all indications, it
sees minimal use, and "pg_restore -f" can generate a script from the same
archive.  IIRC this file was originally added in case users did not have
access to pg_restore, but that seems like a relatively unlikely situation
these days.  So, I think we should just remove it, as per the attached.

Thoughts?  As I've mused elsewhere, IMHO we should seriously consider
putting tar format on a path to deprecation, but I'm saving that for
another thread.

-- 
nathan
>From 9a691b3a76da979ed4bc27666e38f626004d1cd1 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <[email protected]>
Date: Thu, 19 Nov 2026 15:52:32 -0600
Subject: [PATCH v1 1/1] pg_dump: Remove restore.sql from tar format.

Tar-format dumps include an undocumented restore.sql script that
can be run with psql after extracting the archive and hand-editing
its $$PATH$$ placeholders.  pg_restore never reads it.  This script
has needed a number of fixes over the years (e.g., commits
bf0945e863, ff75219e9f, 3c5d9d914f, and 146e03e79a), and it still
fails to restore table data for dumps taken with --inserts.
Furthermore, it is generated by a second pass over the TOC, which
forced tar-only hacks into the statistics code added by commits
7d5c83b4e9 and 9c02e3a986.  Those hacks run all the attribute
statistics queries a second time just for this file.

We could spend more time fixing restore.sql, but by all
indications, it sees minimal use, and "pg_restore -f" can generate
a script from the same archive.  Therefore, let's just remove it,
along with the CustomOutPtr hook that existed only to write it, the
aforementioned statistics hacks, and the tar-format support for
--restrict-key added by commit 146e03e79a.
---
 doc/src/sgml/ref/pg_dump.sgml         |   6 +-
 src/bin/pg_dump/Makefile              |   1 -
 src/bin/pg_dump/meson.build           |   1 -
 src/bin/pg_dump/pg_backup_archiver.c  |  29 ++-----
 src/bin/pg_dump/pg_backup_archiver.h  |   4 -
 src/bin/pg_dump/pg_backup_directory.c |   5 +-
 src/bin/pg_dump/pg_backup_tar.c       | 106 +-------------------------
 src/bin/pg_dump/pg_dump.c             |  25 +-----
 src/bin/pg_dump/t/011_restore.pl      |  63 +--------------
 src/tools/pgindent/typedefs.list      |   1 -
 10 files changed, 17 insertions(+), 224 deletions(-)

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 3c97facb657..774be23b4f9 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1235,8 +1235,10 @@ PostgreSQL documentation
       <listitem>
        <para>
         Use the provided string as the <application>psql</application>
-        <command>\restrict</command> key in the dump output.  If no restrict
-        key is specified,
+        <command>\restrict</command> key in the dump output.  This can only be
+        specified for plain-text dumps, i.e., when <option>--format</option> is
+        set to <literal>plain</literal> or the <option>--format</option> option
+        is omitted.  If no restrict key is specified,
         <application>pg_dump</application> will generate a random one as
         needed.  Keys may contain only alphanumeric characters.
        </para>
diff --git a/src/bin/pg_dump/Makefile b/src/bin/pg_dump/Makefile
index 5abd17a4cc1..79073b0a0ea 100644
--- a/src/bin/pg_dump/Makefile
+++ b/src/bin/pg_dump/Makefile
@@ -18,7 +18,6 @@ include $(top_builddir)/src/Makefile.global
 
 export GZIP_PROGRAM=$(GZIP)
 export LZ4
-export TAR
 export ZSTD
 export with_icu
 
diff --git a/src/bin/pg_dump/meson.build b/src/bin/pg_dump/meson.build
index e8a9e5fde93..a23046b4e90 100644
--- a/src/bin/pg_dump/meson.build
+++ b/src/bin/pg_dump/meson.build
@@ -92,7 +92,6 @@ tests += {
   'tap': {
     'env': {
       'GZIP_PROGRAM': gzip.found() ? gzip.full_path() : '',
-      'TAR': tar.found() ? tar.full_path() : '',
       'LZ4': program_lz4.found() ? program_lz4.full_path() : '',
       'ZSTD': program_zstd.found() ? program_zstd.full_path() : '',
       'with_icu': icu.found() ? 'yes' : 'no',
diff --git a/src/bin/pg_dump/pg_backup_archiver.c 
b/src/bin/pg_dump/pg_backup_archiver.c
index d3e0006fa07..7068b184f09 100644
--- a/src/bin/pg_dump/pg_backup_archiver.c
+++ b/src/bin/pg_dump/pg_backup_archiver.c
@@ -1842,9 +1842,7 @@ dump_lo_buf(ArchiveHandle *AH)
 
 /*
  *     Write buffer to the output file (usually stdout). This is used for
- *     outputting 'restore' scripts etc. It is even possible for an archive
- *     format to create a custom output routine to 'fake' a restore if it
- *     wants to generate a script (see TAR output).
+ *     outputting 'restore' scripts etc.
  */
 void
 ahwrite(const void *ptr, size_t size, size_t nmemb, ArchiveHandle *AH)
@@ -1871,8 +1869,6 @@ ahwrite(const void *ptr, size_t size, size_t nmemb, 
ArchiveHandle *AH)
 
                bytes_written = size * nmemb;
        }
-       else if (AH->CustomOutPtr)
-               bytes_written = AH->CustomOutPtr(AH, ptr, size * nmemb);
 
        /*
         * If we're doing a restore, and it's direct to DB, and we're connected
@@ -4051,28 +4047,13 @@ _printTocEntry(ArchiveHandle *AH, TocEntry *te, const 
char *pfx)
        {
                IssueACLPerBlob(AH, te);
        }
-       else if (te->defnLen && AH->format != archTar)
+       else if (te->defnLen)
        {
                /*
                 * If defnLen is set, the defnDumper has already been called 
for this
-                * TOC entry.  We don't normally expect a defnDumper to be 
called for
-                * a TOC entry a second time in _printTocEntry(), but there's an
-                * exception.  The tar format first calls WriteToc(), which 
scans the
-                * entire TOC, and then it later calls RestoreArchive() to 
generate
-                * restore.sql, which scans the TOC again.  There doesn't 
appear to be
-                * a good way to prevent a second defnDumper call in this case 
without
-                * storing the definition in memory, which defeats the purpose. 
 This
-                * second defnDumper invocation should generate the same output 
as the
-                * first, but even if it doesn't, the worst-case scenario is 
that
-                * restore.sql might have different statistics data than the 
archive.
-                *
-                * In all other cases, encountering a TOC entry a second time in
-                * _printTocEntry() is unexpected, so we fail because one of our
-                * assumptions must no longer hold true.
-                *
-                * XXX This is a layering violation, but the alternative is an 
awkward
-                * and complicated callback infrastructure for this special 
case. This
-                * might be worth revisiting in the future.
+                * TOC entry.  We don't expect a defnDumper to be called for a 
TOC
+                * entry a second time in _printTocEntry(), so we fail because 
one of
+                * our assumptions must no longer hold true.
                 */
                pg_fatal("unexpected TOC entry in _printTocEntry(): %d %s %s",
                                 te->dumpId, te->desc, te->tag);
diff --git a/src/bin/pg_dump/pg_backup_archiver.h 
b/src/bin/pg_dump/pg_backup_archiver.h
index c1528d78853..b506c352f04 100644
--- a/src/bin/pg_dump/pg_backup_archiver.h
+++ b/src/bin/pg_dump/pg_backup_archiver.h
@@ -148,8 +148,6 @@ typedef void (*DeClonePtrType) (ArchiveHandle *AH);
 typedef int (*WorkerJobDumpPtrType) (ArchiveHandle *AH, TocEntry *te);
 typedef int (*WorkerJobRestorePtrType) (ArchiveHandle *AH, TocEntry *te);
 
-typedef size_t (*CustomOutPtrType) (ArchiveHandle *AH, const void *buf, size_t 
len);
-
 typedef enum
 {
        SQL_SCAN = 0,                           /* normal */
@@ -281,8 +279,6 @@ struct _archiveHandle
        ClonePtrType ClonePtr;          /* Clone format-specific fields */
        DeClonePtrType DeClonePtr;      /* Clean up cloned fields */
 
-       CustomOutPtrType CustomOutPtr;  /* Alternative script output routine */
-
        /* Stuff for direct DB connection */
        char       *archdbname;         /* DB name *read* from archive */
        char       *savedPassword;      /* password for ropt->username, if 
known */
diff --git a/src/bin/pg_dump/pg_backup_directory.c 
b/src/bin/pg_dump/pg_backup_directory.c
index 34b3b6ba7d7..98fd40d68ed 100644
--- a/src/bin/pg_dump/pg_backup_directory.c
+++ b/src/bin/pg_dump/pg_backup_directory.c
@@ -14,9 +14,8 @@
  *     in case the user has manually compressed them with 'gzip'.
  *
  *     NOTE: This format is identical to the files written in the tar file in
- *     the 'tar' format, except that we don't write the restore.sql file 
(TODO),
- *     and the tar format doesn't support compression. Please keep the formats 
in
- *     sync.
+ *     the 'tar' format, except that the tar format doesn't support 
compression.
+ *     Please keep the formats in sync.
  *
  *
  *     Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
diff --git a/src/bin/pg_dump/pg_backup_tar.c b/src/bin/pg_dump/pg_backup_tar.c
index 204ee6619fb..2dfb7fa1c3c 100644
--- a/src/bin/pg_dump/pg_backup_tar.c
+++ b/src/bin/pg_dump/pg_backup_tar.c
@@ -5,9 +5,6 @@
  *     This file is copied from the 'files' format file, but dumps data into
  *     one temp file then sends it to the output TAR archive.
  *
- *     The tar format also includes a 'restore.sql' script which is there for
- *     the benefit of humans. This script is never used by pg_restore.
- *
  *     NOTE: If you untar the created 'tar' file, the resulting files are
  *     compatible with the 'directory' format. Please keep the two formats in
  *     sync.
@@ -84,8 +81,6 @@ typedef struct
        pgoff_t         tarFHpos;
        pgoff_t         tarNextMember;
        TAR_MEMBER *FH;
-       int                     isSpecialScript;
-       TAR_MEMBER *scriptTH;
 } lclContext;
 
 typedef struct
@@ -112,8 +107,6 @@ static void _tarWriteHeader(TAR_MEMBER *th);
 static int     _tarGetHeader(ArchiveHandle *AH, TAR_MEMBER *th);
 static size_t _tarReadRaw(ArchiveHandle *AH, void *buf, size_t len, TAR_MEMBER 
*th, FILE *fh);
 
-static size_t _scriptOut(ArchiveHandle *AH, const void *buf, size_t len);
-
 /*
  *     Initializer
  */
@@ -154,7 +147,6 @@ InitArchiveFmt_Tar(ArchiveHandle *AH)
        ctx = pg_malloc0_object(lclContext);
        AH->formatData = ctx;
        ctx->filePos = 0;
-       ctx->isSpecialScript = 0;
 
        /*
         * Now open the tar file, and load the TOC if we're in read mode.
@@ -588,51 +580,11 @@ _PrintFileData(ArchiveHandle *AH, char *filename)
 static void
 _PrintTocData(ArchiveHandle *AH, TocEntry *te)
 {
-       lclContext *ctx = (lclContext *) AH->formatData;
        lclTocEntry *tctx = (lclTocEntry *) te->formatData;
-       int                     pos1;
 
        if (!tctx->filename)
                return;
 
-       /*
-        * If we're writing the special restore.sql script, emit a suitable
-        * command to include each table's data from the corresponding file.
-        *
-        * In the COPY case this is a bit klugy because the regular COPY command
-        * was already printed before we get control.
-        */
-       if (ctx->isSpecialScript)
-       {
-               if (te->copyStmt)
-               {
-                       /* Abort the COPY FROM stdin */
-                       ahprintf(AH, "\\.\n");
-
-                       /*
-                        * The COPY statement should look like "COPY ... FROM 
stdin;\n",
-                        * see dumpTableData().
-                        */
-                       pos1 = (int) strlen(te->copyStmt) - 13;
-                       if (pos1 < 6 || strncmp(te->copyStmt, "COPY ", 5) != 0 
||
-                               strcmp(te->copyStmt + pos1, " FROM stdin;\n") 
!= 0)
-                               pg_fatal("unexpected COPY statement syntax: 
\"%s\"",
-                                                te->copyStmt);
-
-                       /* Emit all but the FROM part ... */
-                       ahwrite(te->copyStmt, 1, pos1, AH);
-                       /* ... and insert modified FROM */
-                       ahprintf(AH, " FROM '$$PATH$$/%s';\n\n", 
tctx->filename);
-               }
-               else
-               {
-                       /* --inserts mode, no worries, just include the data 
file */
-                       ahprintf(AH, "\\i $$PATH$$/%s\n\n", tctx->filename);
-               }
-
-               return;
-       }
-
        if (strcmp(te->desc, "BLOBS") == 0)
                _LoadLOs(AH, te);
        else
@@ -770,11 +722,7 @@ _CloseArchive(ArchiveHandle *AH)
 {
        lclContext *ctx = (lclContext *) AH->formatData;
        TAR_MEMBER *th;
-       RestoreOptions *ropt;
-       RestoreOptions *savRopt;
-       DumpOptions *savDopt;
-       int                     savVerbose,
-                               i;
+       int                     i;
 
        if (AH->mode == archModeWrite)
        {
@@ -792,50 +740,6 @@ _CloseArchive(ArchiveHandle *AH)
                 */
                WriteDataChunks(AH, NULL);
 
-               /*
-                * Now this format wants to append a script which does a full 
restore
-                * if the files have been extracted.
-                */
-               th = tarOpen(AH, "restore.sql", 'w');
-
-               tarPrintf(th, "--\n"
-                                 "-- NOTE:\n"
-                                 "--\n"
-                                 "-- File paths need to be edited. Search for 
$$PATH$$ and\n"
-                                 "-- replace it with the path to the directory 
containing\n"
-                                 "-- the extracted data files.\n"
-                                 "--\n");
-
-               AH->CustomOutPtr = _scriptOut;
-
-               ctx->isSpecialScript = 1;
-               ctx->scriptTH = th;
-
-               ropt = NewRestoreOptions();
-               memcpy(ropt, AH->public.ropt, sizeof(RestoreOptions));
-               ropt->filename = NULL;
-               ropt->dropSchema = 1;
-               ropt->superuser = NULL;
-               ropt->suppressDumpWarnings = true;
-
-               savDopt = AH->public.dopt;
-               savRopt = AH->public.ropt;
-
-               SetArchiveOptions((Archive *) AH, NULL, ropt);
-
-               savVerbose = AH->public.verbose;
-               AH->public.verbose = 0;
-
-               RestoreArchive((Archive *) AH);
-
-               SetArchiveOptions((Archive *) AH, savDopt, savRopt);
-
-               AH->public.verbose = savVerbose;
-
-               tarClose(AH, th);
-
-               ctx->isSpecialScript = 0;
-
                /*
                 * EOF marker for tar files is two blocks of NULLs.
                 */
@@ -853,14 +757,6 @@ _CloseArchive(ArchiveHandle *AH)
        AH->FH = NULL;
 }
 
-static size_t
-_scriptOut(ArchiveHandle *AH, const void *buf, size_t len)
-{
-       lclContext *ctx = (lclContext *) AH->formatData;
-
-       return tarWrite(buf, len, ctx->scriptTH);
-}
-
 /*
  * Large Object support
  */
diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c
index a3f38f3b886..9424c5e1652 100644
--- a/src/bin/pg_dump/pg_dump.c
+++ b/src/bin/pg_dump/pg_dump.c
@@ -896,13 +896,11 @@ main(int argc, char **argv)
 
        /* archiveFormat specific setup */
        if (archiveFormat == archNull)
-               plainText = 1;
-       if (archiveFormat == archNull ||
-               archiveFormat == archTar)
        {
+               plainText = 1;
+
                /*
                 * If you don't provide a restrict key, one will be appointed 
for you.
-                * tar format uses this for its undocumented restore.sql file.
                 */
                if (!dopt.restrict_key)
                        dopt.restrict_key = generate_restrict_key();
@@ -912,8 +910,8 @@ main(int argc, char **argv)
                        pg_fatal("invalid restrict key");
        }
        else if (dopt.restrict_key)
-               pg_fatal("option %s can only be used with %s or %s",
-                                "--restrict-key", "--format=plain", 
"--format=tar");
+               pg_fatal("option %s can only be used with %s",
+                                "--restrict-key", "--format=plain");
 
        /*
         * Custom and directory formats are compressed by default with gzip when
@@ -11031,27 +11029,12 @@ fetchAttributeStats(Archive *fout)
        int                     count = 0;
        PGresult   *res = NULL;
        static TocEntry *te;
-       static bool restarted;
        int                     max_rels = MAX_ATTR_STATS_RELS;
 
        /* If we're just starting, set our TOC pointer. */
        if (!te)
                te = AH->toc->next;
 
-       /*
-        * We can't easily avoid a second TOC scan for the tar format because it
-        * writes restore.sql separately, which means we must execute the 
queries
-        * twice.  This feels risky, but there is no known reason it should
-        * generate different output than the first pass.  Even if it does, the
-        * worst-case scenario is that restore.sql might have different 
statistics
-        * data than the archive.
-        */
-       if (!restarted && te == AH->toc && AH->format == archTar)
-       {
-               te = AH->toc->next;
-               restarted = true;
-       }
-
        appendPQExpBufferChar(relids, '{');
        appendPQExpBufferChar(nspnames, '{');
        appendPQExpBufferChar(relnames, '{');
diff --git a/src/bin/pg_dump/t/011_restore.pl b/src/bin/pg_dump/t/011_restore.pl
index 9ce275ee8da..c02cfc64955 100644
--- a/src/bin/pg_dump/t/011_restore.pl
+++ b/src/bin/pg_dump/t/011_restore.pl
@@ -5,7 +5,6 @@
 use strict;
 use warnings FATAL => 'all';
 
-use Carp;
 use PostgreSQL::Test::Cluster;
 use PostgreSQL::Test::Utils;
 use Test::More;
@@ -21,9 +20,7 @@ $node->safe_psql(
                TEMPLATE template0 ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 
'C'});
 
 # Verify that pg_restore can restore a small database from each dump format,
-# with or without each option that has format-specific code.  Currently,
-# --inserts is the option having format-specific code.  (Search pg_backup*.c
-# for "--inserts".)  Test more --inserts variants while here.
+# with and without --inserts and its variants.
 my $setup = <<'EOSQL';
 CREATE ROLE pubowner;
 ALTER SCHEMA public OWNER TO pubowner;
@@ -169,64 +166,6 @@ foreach my $case (@fmt_cases)
        );
        is($stderr, '',
                "restore$space_rextra via $fmt$space_dextra => plain: no 
stderr");
-
-       # tar fmt: test restore.sql
-       next unless $fmt eq 'tar';
-  SKIP:
-       {
-               my $unpacked = $dump_file . '.unpacked';
-               my $tar = $ENV{TAR};
-               skip "no tar program available", 1
-                 if (!defined $tar || $tar eq '');
-
-               # Unpack tar; fetch and transform restore.sql from its root.  
$$PATH$$
-               # will appear in a line like:
-               #
-               #       -- default settings
-               #       COPY public.t (c) FROM '$$PATH$$/4162.dat';
-               #       -- inserts
-               #       \i $$PATH$$/4162.dat
-               #
-               # We don't support a build directory containing a single quote.
-               # Hence, the former needs no escaping, and plain single quotes 
suffice
-               # for the latter.
-               mkdir($unpacked) || croak "mkdir $unpacked: $!";
-               system_or_bail($tar, 'xf' => $dump_file, '-C' => $unpacked);
-               my $restore_dot_sql = slurp_file("$unpacked/restore.sql");
-               $restore_dot_sql =~ s/'\$\$PATH\$\$/'$unpacked/g;
-               $restore_dot_sql =~ s/\\i \$\$PATH\$\$/\\i '$unpacked'/g;
-
-               Test::More->builder->todo_start(
-                       "--inserts restore.sql not updated for CVE-2025-8714 
fix: data rows not restored"
-               ) if $space_dextra =~ /inserts/;
-
-               # restore.sql drops and creates the database like "pg_dump 
--clean
-               # --create", so connect to some other database.
-               ($result, $stdout, $stderr) =
-                 $node->psql('postgres', $restore_dot_sql);
-               is($result, 0, "restore.sql$space_dextra: succeeds");
-               like($stdout, $want_psql_stdout,
-                       "restore.sql$space_dextra: expected stdout");
-               is($stderr, '', "restore.sql$space_dextra: no stderr");
-
-               # compare round trip
-               $result = run_log [
-                       'pg_dump', '--clean',
-                       '--restrict-key' => 'test',
-                       $node->connstr('regression_utf8')
-                 ],
-                 '>' => \$stdout,
-                 '2>' => \$stderr;
-               ok($result,
-                       "comparison dump after restore.sql$space_dextra: 
succeeds");
-               is($stdout, $want_dump_sql,
-                       "comparison dump after restore.sql$space_dextra: 
expected stdout"
-               );
-               is($stderr, '',
-                       "comparison dump after restore.sql$space_dextra: no 
stderr");
-
-               Test::More->builder->todo_end if $space_dextra =~ /inserts/;
-       }
 }
 
 # Confirm that a "pg_dumpall --clean" can be restored cleanly.
diff --git a/src/tools/pgindent/typedefs.list b/src/tools/pgindent/typedefs.list
index f10eb469266..ef3929f2101 100644
--- a/src/tools/pgindent/typedefs.list
+++ b/src/tools/pgindent/typedefs.list
@@ -608,7 +608,6 @@ CtlCommand
 CtxtHandle
 CurrentOfExpr
 CustomExecMethods
-CustomOutPtrType
 CustomPath
 CustomScan
 CustomScanMethods
-- 
2.55.0

Reply via email to