summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
2023-10-12Doc: fix grammatical errors for enable_partitionwise_aggregateDavid Rowley
Author: Andrew Atkinson Reviewed-by: Ashutosh Bapat Discussion: https://postgr.es/m/CAG6XLEnC%3DEgq0YHRic2kWWDs4xwQnQ_kBA6qhhzAq1-pO_9Tfw%40mail.gmail.com Backpatch-through: 11, where enable_partitionwise_aggregate was added
2023-10-10doc: clarify that SSPI and GSSAPI are interchangeableBruce Momjian
Reported-by: tpo_deb@sourcepole.ch Discussion: https://postgr.es/m/167846222574.1803490.15815104179136215862@wrigleys.postgresql.org Backpatch-through: 11
2023-10-10doc: foreign servers with pushdown need matching collationBruce Momjian
Reported-by: Pete Storer Discussion: https://postgr.es/m/BL0PR05MB66283C57D72E321591AE4EB1F3CE9@BL0PR05MB6628.namprd05.prod.outlook.com Backpatch-through: 11
2023-10-10doc: add SSL configuration section referenceBruce Momjian
Reported-by: Steve Atkins Discussion: https://postgr.es/m/B82E80DD-1452-4175-B19C-564FE46705BA@blighty.com Backpatch-through: 11
2023-10-10doc: document the need to analyze partitioned tablesBruce Momjian
Autovacuum does not do it. Reported-by: Justin Pryzby Discussion: https://postgr.es/m/20210913035409.GA10647@telsasoft.com Backpatch-through: 11
2023-10-09Doc: use CURRENT_USER not USER in plpgsql trigger examples.Tom Lane
While these two built-in functions do exactly the same thing, CURRENT_USER seems preferable to use in documentation examples. It's easier to look up if the reader is unsure what it is. Also, this puts these examples in sync with an adjacent example that already used CURRENT_USER. Per question from Kirk Parker. Discussion: https://postgr.es/m/CANwZ8rmN_Eb0h0hoMRS8Feftaik0z89PxVsKg+cP+PctuOq=Qg@mail.gmail.com
2023-09-29Doc: improve description of dump/restore's --clean and --if-exists.Tom Lane
Try to make these option descriptions a little clearer for novices. Per gripe from Attila Gulyás. Discussion: https://postgr.es/m/169590536647.3727336.11070254203649648453@wrigleys.postgresql.org
2023-09-29doc: Change statistics function xref to the right targetDaniel Gustafsson
Commit 7d3b7011b added a link to the statistics functions, which at the time were anchored under the section for statistics views. aebe989477a added a separate section for statistics functions, but the link was not updated to point to the new anchor. Fix by changing the xref. Backpatch to all supported branches. Author: Peter Smith <peter.b.smith@fujitsu.com> Discussion: https://postgr.es/m/CAHut+Ptr0jKzNNtWnssLq+3jNhbyaBseqf6NPrWHk08mQFRoTg@mail.gmail.com Backpatch-through: 11
2023-09-26doc: clarify the effect of concurrent work_mem allocationsBruce Momjian
Reported-by: Sami Imseih Discussion: https://postgr.es/m/66590882-F48C-4A25-83E3-73792CF8C51F@amazon.com Backpatch-through: 11
2023-09-26doc: clarify handling of time zones with "time with time zone"Bruce Momjian
Reported-by: davecramer@postgres.rocks Discussion: https://postgr.es/m/168451942371.714.9173574930845904336@wrigleys.postgresql.org Backpatch-through: 11
2023-09-26doc: clarify the behavior of unopenable listen_addressesBruce Momjian
Reported-by: Gurjeet Singh Discussion: https://postgr.es/m/CABwTF4WYPD9ov-kcSq1+J+ZJ5wYDQLXquY6Lu2cvb-Y7pTpSGA@mail.gmail.com Backpatch-through: 11
2023-09-26doc: pg_upgrade, clarify standby servers must remain runningBruce Momjian
Also mention that mismatching primary/standby LSNs should never happen. Reported-by: Nikolay Samokhvalov Discussion: https://postgr.es/m/CAM527d8heqkjG5VrvjU3Xjsqxg41ufUyabD9QZccdAxnpbRH-Q@mail.gmail.com Backpatch-through: 11
2023-09-26doc: mention GROUP BY columns can reference target col numbersBruce Momjian
Reported-by: hape <postgres-hape@gmx.de> Discussion: https://postgr.es/m/168871536004.379168.9352636188330923805@wrigleys.postgresql.org Backpatch-through: 11
2023-09-26doc: Tell about "vcregress taptest" for regression tests on WindowsMichael Paquier
There was no mention of this command in the documentation, and it is useful to run the TAP tests of a target source directory. Author: Yugo Nagata Discussion: https://postgr.es/m/20230925153204.926d685d347ee1c8f527090c@sraoss.co.jp Backpatch-through: 11
2023-09-22Doc: copy-edit the introductory para for the pg_class catalog.Tom Lane
The previous wording had a faint archaic whiff to it, and more importantly used "catalogs" as a verb, which while cutely self-referential seems likely to provoke confusion in this particular context. Also consistently use "kind" not "type" to refer to the different kinds of relations distinguished by relkind. Per gripe from Martin Nash. Back-patch to supported versions. Discussion: https://postgr.es/m/169518739902.3727338.4793815593763320945@wrigleys.postgresql.org
2023-09-18Don't crash if cursor_to_xmlschema is used on a non-data-returning Portal.Tom Lane
cursor_to_xmlschema() assumed that any Portal must have a tupDesc, which is not so. Add a defensive check. It's plausible that this mistake occurred because of the rather poorly chosen name of the lookup function SPI_cursor_find(), which in such cases is returning something that isn't very much like a cursor. Add some documentation to try to forestall future errors of the same ilk. Report and patch by Boyu Yang (docs changes by me). Back-patch to all supported branches. Discussion: https://postgr.es/m/dd343010-c637-434c-a8cb-418f53bda3b8.yangboyu.yby@alibaba-inc.com
2023-09-08doc: remove mention of backslash doubling in stringsBruce Momjian
Reported-by: Laurenz Albe Discussion: https://postgr.es/m/0b03f91a875fb44182f5bed9e1d404ed6d138066.camel@cybertec.at Author: Laurenz Albe Backpatch-through: 11
2023-09-06doc: mention that to_char() values are roundedBruce Momjian
Reported-by: barsikdacat@gmail.com Diagnosed-by: Laurenz Albe Discussion: https://postgr.es/m/168991536429.626.9957835774751337210@wrigleys.postgresql.org Author: Laurenz Albe Backpatch-through: 11
2023-09-05doc: mention libpq regression testsBruce Momjian
Reported-by: Ryo Matsumura Discussion: https://postgr.es/m/TYCPR01MB11316B3FB56EE54D70BF0CEF6E8E4A@TYCPR01MB11316.jpnprd01.prod.outlook.com Backpatch-through: 11
2023-08-23doc: Replace list of drivers and PLs with wiki linkDaniel Gustafsson
The list of external language drivers and procedural languages was never complete or exhaustive, and rather than attempting to manage it the content has migrated to the wiki. This replaces the tables altogether with links to the wiki as we regularly get requests for adding various projects, which we reject without any clear policy for why or how the content should be managed. The threads linked to below are the most recent discussions about this, the archives contain many more. Backpatch to all supported branches since the list on the wiki applies to all branches. Author: Jonathan Katz <jkatz@postgresql.org> Discussion: https://postgr.es/m/169165415312.635.10247434927885764880@wrigleys.postgresql.org Discussion: https://postgr.es/m/169177958824.635.11087800083040275266@wrigleys.postgresql.org Backpatch-through: v11
2023-08-07Last-minute updates for release notes.Tom Lane
Security: CVE-2023-39417, CVE-2023-39418
2023-08-05Release notes for 15.4, 14.9, 13.12, 12.16, 11.21.Tom Lane
2023-08-03Doc: update documentation for creating custom scan paths.Etsuro Fujita
Commit f49842d1e added a new callback for custom scan paths, but missed updating the documentation. Back-patch to all supported branches. Discussion: https://postgr.es/m/CAPmGK15ODkN%2B%3DhkBCufj1HBW0x5OTb65Xuy7ryXchMdiCMpx_g%40mail.gmail.com
2023-07-19Doc: improve description of IN and row-constructor comparisons.Tom Lane
IN and NOT IN work fine on records and arrays, so just say that they accept "expressions" not "scalar expressions". I think that that phrasing was meant to say that they don't work on set-returning expressions, but that's not the common meaning of "scalar". Revise the description of row-constructor comparisons to make it perhaps a bit less confusing. (This partially reverts some dubious wording changes made by commit f56651519.) Per gripe from Ilya Nenashev. Back-patch to supported branches. In HEAD and v16, also drop a NOTE about pre-8.2 behavior, which is hopefully no longer of interest to anybody. Discussion: https://postgr.es/m/168968062460.632.14303906825812821399@wrigleys.postgresql.org
2023-07-18Doc: fix out-of-date example of SPI usage.Tom Lane
The "count" argument of SPI_exec() only limits execution when the query is actually returning rows. This was not the case before PG 9.0, so this example was correct when written; but we missed updating it in commit 2ddc600f8. Extend the example to show the behavior both with and without RETURNING. While here, improve the commentary and markup for the rest of the example. David G. Johnston and Tom Lane, per report from Curt Kolovson. Back-patch to all supported branches. Discussion: https://postgr.es/m/CANhYJV6HWtgz_qjx_APfK0PAgLUzY-2vjLuj7i_o=TZF1LAQew@mail.gmail.com
2023-07-13Handle DROP DATABASE getting interruptedAndres Freund
Until now, when DROP DATABASE got interrupted in the wrong moment, the removal of the pg_database row would also roll back, even though some irreversible steps have already been taken. E.g. DropDatabaseBuffers() might have thrown out dirty buffers, or files could have been unlinked. But we continued to allow connections to such a corrupted database. To fix this, mark databases invalid with an in-place update, just before starting to perform irreversible steps. As we can't add a new column in the back branches, we use pg_database.datconnlimit = -2 for this purpose. An invalid database cannot be connected to anymore, but can still be dropped. Unfortunately we can't easily add output to psql's \l to indicate that some database is invalid, it doesn't fit in any of the existing columns. Add tests verifying that a interrupted DROP DATABASE is handled correctly in the backend and in various tools. Reported-by: Evgeny Morozov <postgresql3@realityexists.net> Author: Andres Freund <andres@anarazel.de> Reviewed-by: Daniel Gustafsson <daniel@yesql.se> Reviewed-by: Thomas Munro <thomas.munro@gmail.com> Discussion: https://postgr.es/m/20230509004637.cgvmfwrbht7xm7p6@awork3.anarazel.de Discussion: https://postgr.es/m/20230314174521.74jl6ffqsee5mtug@awork3.anarazel.de Backpatch: 11-, bug present in all supported versions
2023-06-23doc: rename "decades" to be more genericBruce Momjian
Reported-by: Michael Paquier Discussion: https://postgr.es/m/ZJTzwD2rTbHWWQ9g@paquier.xyz Backpatch-through: 11
2023-06-22Doc: Clarify the behavior of triggers/rules in a logical subscriber.Amit Kapila
By default, triggers and rules do not fire on a logical replication subscriber based on the "session_replication_role" GUC being set to "replica". However, the docs in the logical replication section assumed that the reader understood how this GUC worked. This modifies the docs to be more explicit and links back to the GUC itself. Author: Jonathan Katz, Peter Smith Reviewed-by: Vignesh C, Euler Taveira Backpatch-through: 11 Discussion: https://postgr.es/m/5bb2c9a2-499f-e1a2-6e33-5ce96b35cc4a@postgresql.org
2023-06-22Doc: mention that extended stats aren't used for joinsDavid Rowley
Statistics defined by the CREATE STATISTICS command are only used to assist with the selectivity estimations of base relations, never for joins. Here we mention this fact in the notes section of the CREATE STATISTICS command. Discussion: https://postgr.es/m/CAApHDvrMuVgDOrmg_EtFDZ=AOovq6EsJNnHH1ddyZ8EqL4yzMw@mail.gmail.com Backpatch-through: 11
2023-06-21doc: update PG history as over "three decades"Bruce Momjian
Reported-by: Pierre <pbaumard@gmail.com> Discussion: https://postgr.es/m/168724660637.399156.7642965215720120947@wrigleys.postgresql.org Backpatch-through: 11
2023-06-21Fix the errhint message and docs for drop subscription failure.Amit Kapila
The existing errhint message and docs were missing the fact that we can't disassociate from the slot unless the subscription is disabled. Author: Robert Sjöblom, Peter Smith Reviewed-by: Peter Eisentraut, Amit Kapila Backpatch-through: 11 Discussion: https://postgr.es/m/807bdf85-61ea-88e2-5712-6d9fcd4eabff@fortnox.se
2023-06-08doc: Fix example command for ALTER FOREIGN TABLE ... OPTIONS.Fujii Masao
In the documentation, previously the example command for ALTER FOREIGN TABLE ... OPTIONS incorrectly included both the option name and value with the DROP operation. The correct syntax for the DROP operation requires only the name of the option to be specified. This commit fixes the example by removing the option value from the DROP operation. Back-patch to all supported versions. Author: Mehmet Emin KARAKAS <emin100@gmail.com> Reviewed-by: Fujii Masao Discussion: https://postgr.es/m/CANQrdXAHzbcEYhjGoe5A42OmfvdQhHFJzyKj9gJvHuDKyOF5Ng@mail.gmail.com
2023-06-01doc: add missing "the" in LATERAL sentence.Bruce Momjian
Backpatch-through: 11
2023-05-10Doc: Fix link to fillfactor reloption.Peter Geoghegan
Fix a link from the "Heap-Only Tuples" documentation section. Previously, its "fillfactor" link pointed to the "CREATE TABLE" command's documentation. Now the link directly points to the fillfactor storage parameter documentation (which is about half way into the "CREATE TABLE" sect1). Oversight in commit 115464bb. Backpatch: 12-, the first version with a usable reloption link.
2023-05-08Last-minute updates for release notes.Tom Lane
Security: CVE-2023-2454, CVE-2023-2455
2023-05-07Release notes for 15.3, 14.8, 13.11, 12.15, 11.20.Tom Lane
2023-05-02Doc: clarify behavior of row-limit arguments in the PLs' SPI wrappers.Tom Lane
plperl, plpython, and pltcl all provide query-execution functions that are thin wrappers around SPI_execute() or its variants. The SPI functions document their row-count limit arguments clearly, as "maximum number of rows to return, or 0 for no limit". However the PLs' documentation failed to explain this special behavior of zero, so that a reader might well assume it means "fetch zero rows". Improve that. Daniel Gustafsson and Tom Lane, per report from Kieran McCusker Discussion: https://postgr.es/m/CAGgUQ6H6qYScctOhktQ9HLFDDoafBKHyUgJbZ6q_dOApnzNTXg@mail.gmail.com
2023-04-23Validate ltree siglen GiST option to be int-alignedAlexander Korotkov
Unaligned siglen could lead to an unaligned access to subsequent key fields. Backpatch to 13, where opclass options were introduced. Reported-by: Alexander Lakhin Bug: 17847 Discussion: https://postgr.es/m/17847-171232970bea406b%40postgresql.org Reviewed-by: Tom Lane, Pavel Borisov, Alexander Lakhin Backpatch-through: 13
2023-04-14doc: PQinitOpenSSL and PQinitSSL are obsolete in OpenSSL 1.1.0+Daniel Gustafsson
Starting with OpenSSL 1.1.0 there is no need to call PQinitOpenSSL or PQinitSSL to avoid duplicate initialization of OpenSSL. Add a note to the documentation to explain this. Backpatch to all supported versions as older OpenSSL versions are equally likely to be used for all branches. Reported-by: Sebastien Flaesch <sebastien.flaesch@4js.com> Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us> Discussion: https://postgr.es/m/DBAP191MB12895BFFEC4B5FE0460D0F2FB0459@DBAP191MB1289.EURP191.PROD.OUTLOOK.COM Backpatch-through: 11, all supported versions
2023-04-05doc: Update error messages in RLS examplesJohn Naylor
Since 8b9e9644d, the messages for failed permissions checks report "table" where appropriate, rather than "relation". Backpatch to all supported branches
2023-04-05doc: Add more details about pg_stat_get_xact_blocks_{fetched,hit}Michael Paquier
The explanation describing the dependency to system read() calls for these two functions has been removed in ddfc2d9. And after more discussion about d69c404, we have concluded that adding more details makes them easier to understand. While on it, use the term "block read requests" (maybe found in cache) rather than "buffers fetched" and "buffer hits". Per discussion with Melanie Plageman, Kyotaro Horiguchi, Bertrand Drouvot and myself. Discussion: https://postgr.es/m/CAAKRu_ZmdiScT4q83OAbfmR5AH-L5zWya3SXjaxiJvhCob-e2A@mail.gmail.com Backpatch-through: 11
2023-03-27doc: Fix XML_CATALOG_FILES env var for Apple Silicon machinesDaniel Gustafsson
Homebrew changed the prefix for Apple Silicon based machines, so our advice for XML_CATALOG_FILES needs to mention both. More info on the Homebrew change can be found at: https://github.com/Homebrew/brew/issues/9177 This is backpatch of commits 4c8d65408 and 5a91c7975, the latter which contained a small fix based on a report from Dagfinn Ilmari Mannsåker. Author: Julien Rouhaud <julien.rouhaud@free.fr> Discussion: https://postgr.es/m/20230327082441.h7pa2vqiobbyo7rd@jrouhaud
2023-03-22doc: Add description of some missing monitoring functionsMichael Paquier
This commit adds some documentation about two monitoring functions: - pg_stat_get_xact_blocks_fetched() - pg_stat_get_xact_blocks_hit() The description of these functions has been removed in ddfc2d9, later simplified by 5f2b089, assuming that all the functions whose descriptions were removed are used in system views. Unfortunately, some of them were are not used in any system views, so they lacked documentation. This gap exists in the docs for a long time, so backpatch all the way down. Reported-by: Michael Paquier Author: Bertrand Drouvot Reviewed-by: Kyotaro Horiguchi Discussion: https://postgr.es/m/ZBeeH5UoNkTPrwHO@paquier.xyz Backpatch-through: 11
2023-03-18Doc: fix documentation example for bytea hex output format.Tom Lane
Per report from rsindlin Discussion: https://postgr.es/m/167907221210.1803488.5939223864945604536@wrigleys.postgresql.org
2023-03-17Fix pg_dump for hash partitioning on enum columns.Tom Lane
Hash partitioning on an enum is problematic because the hash codes are derived from the OIDs assigned to the enum values, which will almost certainly be different after a dump-and-reload than they were before. This means that some rows probably end up in different partitions than before, causing restore to fail because of partition constraint violations. (pg_upgrade dodges this problem by using hacks to force the enum values to keep the same OIDs, but that's not possible nor desirable for pg_dump.) Users can work around that by specifying --load-via-partition-root, but since that's a dump-time not restore-time decision, one might find out the need for it far too late. Instead, teach pg_dump to apply that option automatically when dealing with a partitioned table that has hash-on-enum partitioning. Also deal with a pre-existing issue for --load-via-partition-root mode: in a parallel restore, we try to TRUNCATE target tables just before loading them, in order to enable some backend optimizations. This is bad when using --load-via-partition-root because (a) we're likely to suffer deadlocks from restore jobs trying to restore rows into other partitions than they came from, and (b) if we miss getting a deadlock we might still lose data due to a TRUNCATE removing rows from some already-completed restore job. The fix for this is conceptually simple: just don't TRUNCATE if we're dealing with a --load-via-partition-root case. The tricky bit is for pg_restore to identify those cases. In dumps using COPY commands we can inspect each COPY command to see if it targets the nominal target table or some ancestor. However, in dumps using INSERT commands it's pretty impractical to examine the INSERTs in advance. To provide a solution for that going forward, modify pg_dump to mark TABLE DATA items that are using --load-via-partition-root with a comment. (This change also responds to a complaint from Robert Haas that the dump output for --load-via-partition-root is pretty confusing.) pg_restore checks for the special comment as well as checking the COPY command if present. This will fail to identify the combination of --load-via-partition-root and --inserts in pre-existing dump files, but that should be a pretty rare case in the field. If it does happen you will probably get a deadlock failure that you can work around by not using parallel restore, which is the same as before this bug fix. Having done this, there seems no remaining reason for the alarmism in the pg_dump man page about combining --load-via-partition-root with parallel restore, so remove that warning. Patch by me; thanks to Julien Rouhaud for review. Back-patch to v11 where hash partitioning was introduced. Discussion: https://postgr.es/m/1376149.1675268279@sss.pgh.pa.us
2023-02-08Stop recommending auto-download of DTD files, and indeed disable it.Tom Lane
It appears no longer possible to build the SGML docs without a local installation of the DocBook DTD, because sourceforge.net now only permits HTTPS access, and no common version of xsltproc supports that. Hence, remove the bits of our documentation suggesting that that's possible or useful. In fact, we might as well add the --nonet option to the build recipes automatically, for a bit of extra security. Also fix our documentation-tool-installation recipes for macOS to ensure that xmllint and xsltproc are pulled in from MacPorts or Homebrew. The previous recipes assumed you could use the Apple-supplied versions of these tools; which still works, except that you'd need to set an environment variable to ensure that they would find DTD files provided by those package managers. Simpler and easier to just recommend pulling in the additional packages. In HEAD, also document how to build docs using Meson, and adjust "ninja docs" to just build the HTML docs, for consistency with the default behavior of doc/src/sgml/Makefile. In a fit of neatnik-ism, I also made the ordering of the package lists match the order in which the tools are described at the head of the appendix. Aleksander Alekseev, Peter Eisentraut, Tom Lane Discussion: https://postgr.es/m/CAJ7c6TO8Aro2nxg=EQsVGiSDe-TstP4EsSvDHd7DSRsP40PgGA@mail.gmail.com
2023-02-06Last-minute updates for release notes.Tom Lane
Security: CVE-2022-41862
2023-02-05Release notes for 15.2, 14.7, 13.10, 12.14, 11.19.Tom Lane
2023-02-03doc: Fix XML formatting that psql cannot handlePeter Eisentraut
Breaking <phrase> over two lines is not handled by psql's create_help.pl. (It creates faulty \help output.) Undo the formatting change introduced by 9bdad1b5153e5d6b77a8f9c6e32286d6bafcd76d to fix this for now.
2023-01-31Doc: clarify use of NULL to drop comments and security labels.Tom Lane
This was only mentioned in the description of the text/label, which are marked as being in quotes in the synopsis, which can cause confusion (as witnessed on IRC). Also separate the literal and NULL cases in the parameter list, per suggestion from Tom Lane. Also add an example of dropping a security label. Dagfinn Ilmari Mannsåker, with some tweaks by me Discussion: https://postgr.es/m/87sffqk4zp.fsf@wibble.ilmari.org