public inbox for [email protected]help / color / mirror / Atom feed
BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects 3+ messages / 3 participants [nested] [flat]
* BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects @ 2026-06-19 07:17 PG Bug reporting form <[email protected]> 2026-06-20 15:55 ` Re: BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects Fujii Masao <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: PG Bug reporting form @ 2026-06-19 07:17 UTC (permalink / raw) To: [email protected]; +Cc: [email protected] The following bug has been logged on the website: Bug reference: 19529 Logged by: Igi Izumi Email address: [email protected] PostgreSQL version: 19beta1 Operating system: Rocky Linux 10.2 x86_64 Description: The PostgreSQL 19 pg_dump documentation currently states: "When --statistics is specified, pg_dump will include most optimizer statistics in the resulting dump file. This does not include all statistics, such as those created explicitly with CREATE STATISTICS, custom statistics added by an extension, or statistics collected by the cumulative statistics system. Therefore, it may still be useful to run ANALYZE after restoring from a dump file to ensure optimal performance; see Section 24.1.3 and Section 24.1.6 for more information." https://www.postgresql.org/docs/19/app-pgdump.html However, PostgreSQL 19 introduced support for restoring extended statistics with pg_restore_extended_stats(), and the following commits appear to add support for dumping and restoring CREATE STATISTICS data: ・Include extended statistics data in pg_dump https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=c32fb29e9 ・Add pg_restore_extended_stats() https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=0e80f3f88 Because of these changes, it appears that statistics created explicitly with CREATE STATISTICS are now handled by pg_dump --statistics, while the PostgreSQL 19 documentation still states that they are not included. Could you please confirm whether the documentation is correct, or whether this is a documentation bug? ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects 2026-06-19 07:17 BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects PG Bug reporting form <[email protected]> @ 2026-06-20 15:55 ` Fujii Masao <[email protected]> 2026-06-22 07:50 ` Re: BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects Michael Paquier <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: Fujii Masao @ 2026-06-20 15:55 UTC (permalink / raw) To: [email protected]; [email protected] On Sat, Jun 20, 2026 at 8:19 PM PG Bug reporting form <[email protected]> wrote: > > The following bug has been logged on the website: > > Bug reference: 19529 > Logged by: Igi Izumi > Email address: [email protected] > PostgreSQL version: 19beta1 > Operating system: Rocky Linux 10.2 x86_64 > Description: > > The PostgreSQL 19 pg_dump documentation currently states: > "When --statistics is specified, pg_dump will include most optimizer > statistics in the resulting dump file. This does not include all statistics, > such as those created explicitly with CREATE STATISTICS, custom statistics > added by an extension, or statistics collected by the cumulative statistics > system. Therefore, it may still be useful to run ANALYZE after restoring > from a dump file to ensure optimal performance; see Section 24.1.3 and > Section 24.1.6 for more information." > https://www.postgresql.org/docs/19/app-pgdump.html > > However, PostgreSQL 19 introduced support for restoring extended statistics > with pg_restore_extended_stats(), and the following commits appear to add > support for dumping and restoring CREATE STATISTICS data: > > ・Include extended statistics data in pg_dump > https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=c32fb29e9 > > ・Add pg_restore_extended_stats() > https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=0e80f3f88 > > Because of these changes, it appears that statistics created explicitly with > CREATE STATISTICS are now handled by pg_dump --statistics, while the > PostgreSQL 19 documentation still states that they are not included. > > Could you please confirm whether the documentation is correct, or whether > this is a documentation bug? This looks like a documentation oversight in (maybe) the commit that added extended statistics support to pg_dump. I say that because I confirmed that pg_dump --statistics does dump the extended statistics for table t after running: CREATE TABLE t (i int, j int); INSERT INTO t SELECT n, n FROM generate_series(1, 100) n; CREATE STATISTICS ON i, j FROM t; ANALYZE t; Regards, -- Fujii Masao ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects 2026-06-19 07:17 BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects PG Bug reporting form <[email protected]> 2026-06-20 15:55 ` Re: BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects Fujii Masao <[email protected]> @ 2026-06-22 07:50 ` Michael Paquier <[email protected]> 0 siblings, 0 replies; 3+ messages in thread From: Michael Paquier @ 2026-06-22 07:50 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: [email protected]; [email protected] On Sun, Jun 21, 2026 at 12:55:34AM +0900, Fujii Masao wrote: > This looks like a documentation oversight in (maybe) the commit that > added extended statistics support to pg_dump. This is a doc oversight. While working on the support of extstats for this release, I have looked at holes like this one in the docs, and did not consider the pattern of a linkend based on sql-createstatistics. The report mentions pg_dump, but we have the same wrong pattern in the doc pages for pg_dumpall and pg_upgrade, leading me to the attached for these three holes. Thoughts? -- Michael diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index ae1bc14d2f26..0e0d53926af6 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1703,7 +1703,6 @@ CREATE DATABASE foo WITH TEMPLATE template0; When <option>--statistics</option> is specified, <command>pg_dump</command> will include most optimizer statistics in the resulting dump file. This does not include all statistics, such as - those created explicitly with <xref linkend="sql-createstatistics"/>, custom statistics added by an extension, or statistics collected by the cumulative statistics system. Therefore, it may still be useful to run <command>ANALYZE</command> after restoring from a dump file to ensure diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 8834b7ec141e..238c87c13f5f 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -893,7 +893,6 @@ exclude database <replaceable class="parameter">PATTERN</replaceable> When <option>--statistics</option> is specified, <command>pg_dumpall</command> will include most optimizer statistics in the resulting dump file. This does not include all statistics, such as - those created explicitly with <xref linkend="sql-createstatistics"/>, custom statistics added by an extension, or statistics collected by the cumulative statistics system. Therefore, it may still be useful to run <command>ANALYZE</command> on each database after restoring from a dump diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 38ca09b423c3..cc44983a9a8d 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -834,8 +834,7 @@ psql --username=postgres --file=script.sql postgres Unless the <option>--no-statistics</option> option is specified, <command>pg_upgrade</command> will transfer most optimizer statistics from the old cluster to the new cluster. This does not transfer - all statistics, such as those created explicitly with - <xref linkend="sql-createstatistics"/>, custom statistics added by + all statistics, such as custom statistics added by an extension, or statistics collected by the cumulative statistics system. </para> Attachments: [text/plain] extstats-restore-docs.patch (2.3K, ../../[email protected]/2-extstats-restore-docs.patch) download | inline diff: diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index ae1bc14d2f26..0e0d53926af6 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1703,7 +1703,6 @@ CREATE DATABASE foo WITH TEMPLATE template0; When <option>--statistics</option> is specified, <command>pg_dump</command> will include most optimizer statistics in the resulting dump file. This does not include all statistics, such as - those created explicitly with <xref linkend="sql-createstatistics"/>, custom statistics added by an extension, or statistics collected by the cumulative statistics system. Therefore, it may still be useful to run <command>ANALYZE</command> after restoring from a dump file to ensure diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 8834b7ec141e..238c87c13f5f 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -893,7 +893,6 @@ exclude database <replaceable class="parameter">PATTERN</replaceable> When <option>--statistics</option> is specified, <command>pg_dumpall</command> will include most optimizer statistics in the resulting dump file. This does not include all statistics, such as - those created explicitly with <xref linkend="sql-createstatistics"/>, custom statistics added by an extension, or statistics collected by the cumulative statistics system. Therefore, it may still be useful to run <command>ANALYZE</command> on each database after restoring from a dump diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 38ca09b423c3..cc44983a9a8d 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -834,8 +834,7 @@ psql --username=postgres --file=script.sql postgres Unless the <option>--no-statistics</option> option is specified, <command>pg_upgrade</command> will transfer most optimizer statistics from the old cluster to the new cluster. This does not transfer - all statistics, such as those created explicitly with - <xref linkend="sql-createstatistics"/>, custom statistics added by + all statistics, such as custom statistics added by an extension, or statistics collected by the cumulative statistics system. </para> [application/pgp-signature] signature.asc (833B, ../../[email protected]/3-signature.asc) download ^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2026-06-22 07:50 UTC | newest] Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-06-19 07:17 BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects PG Bug reporting form <[email protected]> 2026-06-20 15:55 ` Fujii Masao <[email protected]> 2026-06-22 07:50 ` Michael Paquier <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox