upstream/postgresql
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2026-04-15 22:10:45 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
postgresql/doc/src/sgml
History
David Rowley c2a4078eba Enable BUFFERS with EXPLAIN ANALYZE by default 
The topic of turning EXPLAIN's BUFFERS option on with the ANALYZE option
has come up a few times over the past few years.  In many ways, doing this
seems like a good idea as it may be more obvious to users why a given
query is running more slowly than they might expect.  Also, from my own
(David's) personal experience, I've seen users posting to the mailing
lists with two identical plans, one slow and one fast asking why their
query is sometimes slow.  In many cases, this is due to additional reads.
Having BUFFERS on by default may help reduce some of these questions, and
if not, make it more obvious to the user before they post, or save a
round-trip to the mailing list when additional I/O effort is the cause of
the slowness.

The general consensus is that we want BUFFERS on by default with
ANALYZE.  However, there were more than zero concerns raised with doing
so.  The primary reason against is the additional verbosity, making it
harder to read large plans.  Another concern was that buffer information
isn't always useful so may not make sense to have it on by default.

It's currently December, so let's commit this to see if anyone comes
forward with a strong objection against making this change.  We have over
half a year remaining in the v18 cycle where we could still easily consider
reverting this if someone were to come forward with a convincing enough
reason as to why doing this is a bad idea.

There were two patches independently submitted to achieve this goal, one
by me and the other by Guillaume.  This commit is a mix of both of these
patches with some additional work done by me to adjust various
additional places in the documentation which include EXPLAIN ANALYZE
output.

Author: Guillaume Lelarge, David Rowley
Reviewed-by: Robert Haas, Greg Sabino Mullane, Michael Christofides
Discussion: https://postgr.es/m/CANNMO++W7MM8T0KyXN3ZheXXt-uLVM3aEtZd+WNfZ=obxffUiA@mail.gmail.com
2024-12-11 22:35:11 +13:00
..
images Fix commit 641a5b7a14 for "nbsp" output in SVG files 2024-11-26 13:08:13 -05:00
keywords doc: Update SQL keywords list to SQL:2023 2023-04-05 07:55:28 +02:00
ref Enable BUFFERS with EXPLAIN ANALYZE by default 2024-12-11 22:35:11 +13:00
.gitignore Stop generating plain-text INSTALL instructions. 2023-12-22 13:32:15 -05:00
acronyms.sgml Doc: update some HTTP links to point to canonical URLs. 2024-07-25 16:38:28 -04:00
advanced.sgml Remove trailing whitespace from *.sgml files. 2022-04-20 11:04:49 -04:00
amcheck.sgml Fix search_path to a safe value during maintenance operations. 2024-03-04 17:31:38 -08:00
appendix-obsolete-default-roles.sgml Fix file references inside some SGML comments 2022-06-20 14:33:41 +02:00
appendix-obsolete-pgreceivexlog.sgml Fix file references inside some SGML comments 2022-06-20 14:33:41 +02:00
appendix-obsolete-pgresetxlog.sgml Fix file references inside some SGML comments 2022-06-20 14:33:41 +02:00
appendix-obsolete-pgxlogdump.sgml Fix file references inside some SGML comments 2022-06-20 14:33:41 +02:00
appendix-obsolete-recovery-config.sgml Remove promote_trigger_file. 2022-11-29 12:08:38 +13:00
appendix-obsolete.sgml Revert "Rename contrib module basic_archive to basic_wal_module" 2023-01-26 09:13:39 +09:00
arch-dev.sgml Doc: Miscellaneous doc updates for MERGE. 2023-02-26 09:06:04 +00:00
archive-modules.sgml Add built-in ERROR handling for archive callbacks. 2024-04-02 22:28:11 -05:00
array.sgml Improve readability and error detection of array_in(). 2023-11-13 13:01:51 -05:00
auth-delay.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
auto-explain.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
backup-manifest.sgml doc: Standardize use of dashes in references to CRC and SHA. 2024-08-09 13:16:33 -05:00
backup.sgml Document restrictions regarding incremental backups and standbys. 2024-07-25 15:45:06 -04:00
basebackup-to-shell.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
basic-archive.sgml Revert "Rename contrib module basic_archive to basic_wal_module" 2023-01-26 09:13:39 +09:00
bgworker.sgml Add option to bgworkers to allow the bypass of role login check 2023-10-12 09:24:17 +09:00
biblio.sgml Doc: minor improvements for our "Brief History" chapter. 2024-07-05 13:12:34 -04:00
bki.sgml Catalog changes preparing for builtin collation provider. 2024-03-09 14:48:18 -08:00
bloom.sgml Enable BUFFERS with EXPLAIN ANALYZE by default 2024-12-11 22:35:11 +13:00
brin.sgml docs: Merge separate chapters on built-in index AMs into one. 2024-04-05 10:34:04 -04:00
btree-gin.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
btree-gist.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
btree.sgml docs: Merge separate chapters on built-in index AMs into one. 2024-04-05 10:34:04 -04:00
catalogs.sgml Deprecate MD5 passwords. 2024-12-02 13:30:07 -06:00
charset.sgml Now that we have non-Latin1 SGML detection, restore Latin1 chars 2024-12-03 17:09:49 -05:00
citext.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
client-auth.sgml Deprecate MD5 passwords. 2024-12-02 13:30:07 -06:00
color.sgml Add color support for new frontend detail/hint messages 2022-04-11 17:36:44 +02:00
config.sgml Deprecate MD5 passwords. 2024-12-02 13:30:07 -06:00
contrib-spi.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
contrib.sgml Add contrib/pg_logicalinspect. 2024-10-14 17:22:02 -07:00
cube.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
custom-rmgr.sgml docs: Consolidate into new "WAL for Extensions" chapter. 2024-04-15 15:57:13 -04:00
custom-scan.sgml Doc: Improve documentation for creating custom scan paths. 2023-08-30 17:45:00 +09:00
datatype.sgml Doc: small improvements in discussion of geometric data types. 2024-07-04 13:23:32 -04:00
datetime.sgml doc: add missing word to sentence about Paris 2023-10-31 13:18:42 -04:00
dblink.sgml Make dblink interruptible, via new libpqsrv APIs. 2024-01-08 11:39:56 -08:00
ddl.sgml doc: Fix typo 2024-11-30 08:43:46 +01:00
dfunc.sgml Remove AIX support 2024-02-28 15:17:23 +04:00
dict-int.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
dict-xsyn.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
dml.sgml Add RETURNING support to MERGE. 2024-03-17 13:58:59 +00:00
docguide.sgml Stop generating plain-text INSTALL instructions. 2023-12-22 13:32:15 -05:00
earthdistance.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
ecpg.sgml Fix assorted bugs in ecpg's macro mechanism. 2024-04-16 12:31:42 -04:00
errcodes.sgml Doc: remove now-redundant align specifications in colspecs. 2020-05-06 15:58:23 -04:00
event-trigger.sgml doc: Remove event trigger firing matrix 2024-11-06 13:43:17 +01:00
extend.sgml Add @extschema:name@ and no_relocate options to extensions. 2023-03-20 18:37:11 -04:00
external-projects.sgml doc: Replace list of drivers and PLs with wiki link 2023-08-23 14:13:07 +02:00
fdwhandler.sgml doc: Mention AttributeRelationId in FDW validator function description 2023-12-28 20:09:12 +09:00
features.sgml Add XMLText function (SQL/XML X038) 2023-11-06 09:38:29 +01:00
file-fdw.sgml file_fdw: Add REJECT_LIMIT option to file_fdw. 2024-11-20 23:53:19 +09:00
filelist.sgml Add contrib/pg_logicalinspect. 2024-10-14 17:22:02 -07:00
func.sgml Use in-place updates for pg_restore_relation_stats(). 2024-12-10 16:30:37 -08:00
fuzzystrmatch.sgml Add support for Daitch-Mokotoff Soundex in contrib/fuzzystrmatch. 2023-04-07 17:32:26 -04:00
generate-errcodes-table.pl Update copyright for 2024 2024-01-03 20:49:05 -05:00
generate-keywords-table.pl Update copyright for 2024 2024-01-03 20:49:05 -05:00
generate-targets-meson.pl Update copyright for 2024 2024-01-03 20:49:05 -05:00
generic-wal.sgml docs: Consolidate into new "WAL for Extensions" chapter. 2024-04-15 15:57:13 -04:00
geqo.sgml Doc: add XML ID attributes to <sectN> and <varlistentry> tags. 2023-01-09 15:08:24 -05:00
gin.sgml docs: Merge separate chapters on built-in index AMs into one. 2024-04-05 10:34:04 -04:00
gist.sgml Add temporal PRIMARY KEY and UNIQUE constraints 2024-09-17 11:29:30 +02:00
glossary.sgml Doc: Add the steps for upgrading the logical replication cluster. 2024-09-25 10:06:10 +05:30
hash.sgml docs: Merge separate chapters on built-in index AMs into one. 2024-04-05 10:34:04 -04:00
high-availability.sgml Doc: Add the new section "Logical Replication Failover". 2024-06-07 11:59:27 +05:30
history.sgml Doc: minor improvements for our "Brief History" chapter. 2024-07-05 13:12:34 -04:00
hstore.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
indexam.sgml Add amgettreeheight index AM API routine 2024-09-10 10:03:23 +02:00
indextypes.sgml docs: Merge separate chapters on built-in index AMs into one. 2024-04-05 10:34:04 -04:00
indices.sgml Doc: add a bit to indices.sgml about what is an indexable clause. 2023-12-17 16:49:44 -05:00
info.sgml Don't use SGML empty tags 2017-10-17 15:10:33 -04:00
information_schema.sgml doc: Fix copy-and-paste mistake 2024-06-07 08:02:15 +02:00
install-binaries.sgml Expand installation documentation to cover binary installations 2020-10-06 14:15:32 +02:00
installation.sgml Require ucrt if using MinGW. 2024-11-27 23:13:45 +13:00
intagg.sgml doc, intagg: fix one-to-many mention to many-to-many 2023-12-07 19:36:52 -05:00
intarray.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
intro.sgml doc: add links to Postgres features intro 2023-10-28 14:02:46 -04:00
isn.sgml Doc: update some HTTP links to point to canonical URLs. 2024-07-25 16:38:28 -04:00
jit.sgml Enable BUFFERS with EXPLAIN ANALYZE by default 2024-12-11 22:35:11 +13:00
json.sgml doc: Correct jsonpath string literal escapes description 2024-04-24 11:31:47 +02:00
keywords.sgml Allow most keywords to be used as column labels without requiring AS. 2020-09-18 16:46:36 -04:00
legal.sgml Update copyright for 2024 2024-01-03 20:49:05 -05:00
libpq.sgml Deprecate MD5 passwords. 2024-12-02 13:30:07 -06:00
limits.sgml Document limit on the number of out-of-line values per table 2024-08-20 13:36:33 +07:00
lo.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
lobj.sgml Update copyright for 2024 2024-01-03 20:49:05 -05:00
logical-replication.sgml doc: clarify how logical replication takes its initial snapshot 2024-11-21 17:14:33 -05:00
logicaldecoding.sgml Rename standby_slot_names to synchronized_standby_slots. 2024-07-01 11:36:56 +05:30
ltree.sgml Add hash support functions and hash opclass for contrib/ltree. 2024-03-21 18:27:49 -04:00
maintenance.sgml Fix typos and duplicate words 2024-04-18 21:28:07 +02:00
Makefile Return actual error code from FOP failure in PDF build 2024-12-04 14:37:24 -05:00
manage-ag.sgml doc: improve tablespace example query and link to helper funcs. 2024-11-01 15:54:16 -04:00
meson.build Fix typos and duplicate words 2024-04-18 21:28:07 +02:00
mk_feature_tables.pl Make all Perl warnings fatal 2023-12-29 18:20:00 +01:00
monitoring.sgml Add two attributes to pg_stat_database for parallel workers activity 2024-11-11 10:40:48 +09:00
mvcc.sgml doc: fix typo in mvcc clarification in commit 2fa255ce9b 2024-11-04 09:24:58 -05:00
nls.sgml doc: Fix some typos and grammar 2023-10-25 09:40:55 +09:00
notation.sgml doc: clarify syntax notation, particularly parentheses 2022-02-02 21:53:52 -05:00
oid2name.sgml |--- gitweb subject length limit ----------------|-email limit-| 2023-10-27 11:06:10 -04:00
pageinspect.sgml doc: gin_page_opaque_info() must be a _compressed_ GIN page 2023-11-24 22:02:07 -05:00
parallel.sgml Doc: InitPlans aren't parallel-restricted any more. 2024-09-26 10:37:51 -04:00
passwordcheck.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
perform.sgml Enable BUFFERS with EXPLAIN ANALYZE by default 2024-12-11 22:35:11 +13:00
pgbuffercache.sgml Add pg_buffercache_evict() function for testing. 2024-04-08 16:23:40 +12:00
pgcrypto.sgml doc: Standardize use of dashes in references to CRC and SHA. 2024-08-09 13:16:33 -05:00
pgfreespacemap.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
pglogicalinspect.sgml Add contrib/pg_logicalinspect. 2024-10-14 17:22:02 -07:00
pgprewarm.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
pgrowlocks.sgml pgrowlocks: change lock mode output labels for consistency 2023-09-26 17:41:48 -04:00
pgstatstatements.sgml pg_stat_statements: Add columns to track parallel worker activity 2024-10-09 08:30:45 +09:00
pgstattuple.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
pgsurgery.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
pgtrgm.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
pgvisibility.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
pgwalinspect.sgml doc: Fix some typos and grammar 2023-10-25 09:40:55 +09:00
planstats.sgml Enable BUFFERS with EXPLAIN ANALYZE by default 2024-12-11 22:35:11 +13:00
plhandler.sgml doc: use wording "restore" instead of "reload" of dumps 2022-07-21 14:55:23 -04:00
plperl.sgml Block environment variable mutations from trusted PL/Perl. 2024-11-11 06:23:43 -08:00
plpgsql.sgml docs: fix incorrect plpgsql error message 2024-08-16 22:50:54 -04:00
plpython.sgml doc: Fix example with __next__() in PL/Python function 2024-11-25 09:15:25 +09:00
pltcl.sgml Improve PL/Tcl's method for choosing Tcl names of procedures. 2024-07-05 14:14:42 -04:00
postgres-fdw.sgml doc: explain how the home directory is found on Unix-like syst. 2024-11-01 13:32:21 -04:00
postgres.sgml doc PG relnotes: fix SGML markup for new commit links 2024-09-16 14:23:39 -04:00
problems.sgml doc: use more accurate URL for bug reporting 2024-11-04 15:08:01 -05:00
protocol.sgml Deprecate MD5 passwords. 2024-12-02 13:30:07 -06:00
queries.sgml Add RETURNING support to MERGE. 2024-03-17 13:58:59 +00:00
query.sgml Doc: improve tutorial section about grouped aggregates. 2022-11-08 18:25:03 -05:00
rangetypes.sgml Revert 29854ee8d1 due to buildfarm failures 2021-06-15 21:44:40 +03:00
README.links doc: mention <link> can be inside of <command>, but not <xref> 2021-04-22 16:01:17 -04:00
README.non-ASCII doc: improve build for non-Latin1 characters 2024-11-01 12:46:51 -04:00
reference.sgml pg_createsubscriber: creates a new logical replica from a standby server 2024-03-25 12:42:47 +01:00
regress.sgml Run regression tests with timezone America/Los_Angeles. 2024-09-14 17:55:02 -04:00
release-18.sgml Stamp HEAD as 18devel. 2024-07-01 07:56:10 +09:00
release.sgml doc: improve build for non-Latin1 characters 2024-11-01 12:46:51 -04:00
replication-origins.sgml Refer to replication origin roident as "ID" in user facing messages and docs 2022-08-18 08:57:13 +07:00
rowtypes.sgml Add RETURNING support to MERGE. 2024-03-17 13:58:59 +00:00
rules.sgml Fix doc omission for MERGE into updatable views. 2024-03-04 10:48:40 +00:00
runtime.sgml Deprecate MD5 passwords. 2024-12-02 13:30:07 -06:00
seg.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
sepgsql.sgml doc: Missing markup, punctuation and wordsmithing 2024-10-02 14:50:56 +02:00
sourcerepo.sgml Remove distprep 2023-11-06 15:18:04 +01:00
sources.sgml Revise GUC names quoting in messages again 2024-05-17 11:44:26 +02:00
spgist.sgml docs: Merge separate chapters on built-in index AMs into one. 2024-04-05 10:34:04 -04:00
spi.sgml Don't bother checking the result of SPI_connect[_ext] anymore. 2024-09-09 12:18:34 -04:00
sslinfo.sgml Revert "Add notBefore and notAfter to SSL cert info display" 2024-03-22 22:58:41 +01:00
start.sgml doc: clarify create database in start docs uses command line 2024-08-19 19:22:10 -04:00
storage.sgml docs: Make claims about the benefits of HOT updates more precise. 2024-03-21 12:54:58 -04:00
stylesheet-common.xsl Fix documentation build with older docbook-xsl 2024-02-08 11:38:46 +01:00
stylesheet-fo.xsl doc PG relnotes: remove warning about commit links in PDF build 2024-09-19 18:05:22 -04:00
stylesheet-html-common.xsl Fix documentation build with older docbook-xsl 2024-02-08 11:38:46 +01:00
stylesheet-html-nochunk.xsl docs: html: load stylesheet via custom.css.source 2023-04-04 21:29:45 -07:00
stylesheet-man.xsl Now that we have non-Latin1 SGML detection, restore Latin1 chars 2024-12-03 17:09:49 -05:00
stylesheet-speedup-common.xsl doc: Further speed improvements for HTML XSLT build 2016-12-22 15:41:44 -05:00
stylesheet-speedup-xhtml.xsl doc: Further speed improvements for HTML XSLT build 2016-12-22 15:41:44 -05:00
stylesheet-text.xsl Fix XML namespace declarations 2022-02-15 11:13:49 +01:00
stylesheet.css doc: Make HTML ids discoverable 2023-04-13 10:16:33 +02:00
stylesheet.css.xml docs: html: load stylesheet via custom.css.source 2023-04-04 21:29:45 -07:00
stylesheet.xsl docs: html: load stylesheet via custom.css.source 2023-04-04 21:29:45 -07:00
syntax.sgml doc: Missing markup, punctuation and wordsmithing 2024-10-02 14:50:56 +02:00
system-views.sgml Doc: Clarify the inactive_since field description. 2024-11-25 11:12:32 +05:30
tableam.sgml doc: Add minimal C and SQL example to add a custom table AM handler 2024-10-07 15:47:40 +09:00
tablefunc.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
tablesample-method.sgml Use the correct article for abbreviations 2021-06-11 13:38:04 +12:00
targets-meson.txt Fix an assortment of typos 2024-05-04 02:33:25 +12:00
tcn.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
test-decoding.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
textsearch.sgml Doc: Update ulinks to RFC documents to avoid redirect 2024-04-10 13:53:25 +02:00
trigger.sgml doc: Missing markup, punctuation and wordsmithing 2024-10-02 14:50:56 +02:00
tsm-system-rows.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
tsm-system-time.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
typeconv.sgml Use the correct article for abbreviations 2021-06-11 13:38:04 +12:00
unaccent.sgml unaccent: Add support for quoted translated characters 2023-09-20 12:29:36 +09:00
user-manag.sgml doc: Missing markup, punctuation and wordsmithing 2024-10-02 14:50:56 +02:00
uuid-ossp.sgml Doc: Update ulinks to RFC documents to avoid redirect 2024-04-10 13:53:25 +02:00
vacuumlo.sgml doc: remove xreflabels from commits 75fcdd2ae2 and 85af628da5 2020-06-11 18:19:25 -04:00
version.sgml.in meson: Add initial version of meson based build system 2022-09-21 22:37:17 -07:00
wal-for-extensions.sgml docs: Consolidate into new "WAL for Extensions" chapter. 2024-04-15 15:57:13 -04:00
wal.sgml doc: Missing markup, punctuation and wordsmithing 2024-10-02 14:50:56 +02:00
xact.sgml Replace BackendIds with 0-based ProcNumbers 2024-03-03 19:38:22 +02:00
xaggr.sgml Remove trailing whitespace from *.sgml files. 2022-04-20 11:04:49 -04:00
xfunc.sgml Fix typos and grammar in code comments and docs 2024-09-03 14:49:04 +09:00
xindex.sgml Add stratnum GiST support function 2024-09-17 11:29:29 +02:00
xml2.sgml Describe each contrib module in its SGML section title 2023-01-20 20:01:59 +01:00
xmltools_dep_wrapper meson: docs: Add xml{lint,proc} wrapper to collect dependencies 2022-10-05 09:56:05 -07:00
xoper.sgml Extend ALTER OPERATOR to allow setting more optimization attributes. 2023-10-20 12:28:46 -04:00
xplang.sgml Improve <xref> vs. <command> formatting in the documentation 2020-10-03 16:40:02 +02:00
xtypes.sgml doc: Clean up title case use 2019-09-08 10:27:29 +02:00

README.non-ASCII 

<!-- doc/src/sgml/README.non-ASCII -->

Representation of non-ASCII characters
--------------------------------------

Find non-ASCII characters using:

        grep --recursive --color='auto' -P '[\x80-\xFF]' .

Convert to HTML4 named entity (&) escapes
-----------------------------------------

We support several output formats:

*  html (supports all Unicode characters)
*  man (supports all Unicode characters)
*  pdf (supports only Latin-1 characters)
*  info

While some output formatting tools support all Unicode characters,
others only support Latin-1 characters.  Specifically, the PDF rendering
engine can only display Latin-1 characters;  non-Latin-1 Unicode
characters are displayed as "###".

Therefore, in the SGML files, we only use Latin-1 characters.  We
typically encode these characters as HTML entities, e.g., &Aacute;lvaro.
It is also possible to safely represent Latin-1 characters in UTF8
encoding for all output formats.

Do not use UTF numeric character escapes (&#nnn;).

HTML entities
        official:      http://www.w3.org/TR/html4/sgml/entities.html
        one page:      http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
        other lists:   http://www.zipcon.net/~swhite/docs/computers/browsers/entities.html
                       http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
                       https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references