summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
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-08doc: Extend documentation of PG_TEST_EXTRADaniel Gustafsson
Extend the PG_TEST_EXTRA documentation to mention resource intensive tests as well. The previous wording only mentioned special software and security in the main paragraph, with resource usage listed on one of the tests in the list. Backpatch to v15 where f47ed79cc8 added wal_consistenct_checking as a PG_TEST_EXTRA target. Author: Nazir Bilal Yavuz <byavuz81@gmail.com> Discussion: https://postgr.es/m/CAN55FZ0OthTuBdiNkaX2BvxuHdK4Y1MVEb8_uEuD1yHMPmT9Og@mail.gmail.com Backpatch-through: 15
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-08-02First-draft release notes for 15.4.Tom Lane
As usual, the release notes for other branches will be made by cutting these down, but put them up for community review first.
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-07-09Doc: update old reference to "result cache"David Rowley
During the PostgreSQL 14 cycle, the Memoize executor node was briefly called "Result Cache" until it was renamed in 83f4fcc65. That commit missed one reference. Reported-by: Paul A Jungwirth Packpatch-through: 14, where Memoize was added Discussion: https://postgr.es/m/CA+renyX=40YXhsfPTzn13oNOPO3TJ12CK9GX-2P2pvnQiScefA@mail.gmail.com
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-20docs: adjust tag indenting and add MERGE mentionBruce Momjian
Discussion: https://postgr.es/m/CAMpnoC4_WsY3gsY+ud-Z0GDbafR=K7t7cXn2gatEqFnsRNY3yQ@mail.gmail.com Author: Will Mortensen Backpatch-through: 15
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-04Doc: explain about dependency tracking for new-style SQL functions.Tom Lane
5.14 Dependency Tracking was not updated when we added new-style SQL functions. Improve that. Noted by Sami Imseih. Back-patch to v14 where new-style SQL functions came in. Discussion: https://postgr.es/m/2C1933AB-C2F8-499B-9D18-4AC1882256A0@amazon.com
2023-06-01doc: add missing "the" in LATERAL sentence.Bruce Momjian
Backpatch-through: 11
2023-05-25doc: Fix example query for pg_walinspectDaniel Gustafsson
The LIMIT clause had ended up in the wrong place in the query. Backpatch to v15 where pg_walinspect was introduced. Reported-by: Jian He <jian.universality@gmail.com> Discussion: https://postgr.es/m/CACJufxHqXDr4NnmwmR6pEiVPAg54J0dgwMuYQzrH5BX6+NtF1g@mail.gmail.com Backpatch-through: 15
2023-05-19pageinspect: Fix gist_page_items() with included columnsMichael Paquier
Non-leaf pages of GiST indexes contain key attributes, leaf pages contain both key and non-key attributes, and gist_page_items() ignored the handling of non-key attributes. This caused a few problems when using gist_page_items() on a GiST index with INCLUDE: - On a non-leaf page, the function would crash. - On a leaf page, the function would work, but miss to display all the values for included attributes. This commit fixes gist_page_items() to handle such cases in a more appropriate way, and now displays the values of key and non-key attributes for each item separately in a style consistent with what ruleutils.c would generate for the attribute list, depending on the page type dealt with. In a way similar to how a record is displayed, values would be double-quoted for key or non-key attributes if required. ruleutils.c did not provide a routine able to control if non-key attributes should be displayed, so an extended() routine for index definitions is added to work around the leaf and non-leaf page differences. While on it, this commit fixes a third problem related to the amount of data reported for key attributes. The code originally relied on BuildIndexValueDescription() (used for error reports on constraints) that would not print all the data stored in the index but the index opclass's input type, so this limited the amount of information available. This switch makes gist_page_items() much cheaper as there is no need to run ACL checks for each item printed, which is not an issue anyway as superuser rights are required to execute the functions of pageinspect. Opclasses whose data cannot be displayed can rely on gist_page_items_bytea(). The documentation of this function was slightly incorrect for the output results generated on HEAD and v15, so adjust it on these branches. Author: Alexander Lakhin, Michael Paquier Discussion: https://postgr.es/m/17884-cb8c326522977acb@postgresql.org Backpatch-through: 14
2023-05-12Tighten usage of PSQL_WATCH_PAGER.Tom Lane
Don't use PSQL_WATCH_PAGER when stdin/stdout are not a terminal. This corresponds to the restrictions on when other commands will use [PSQL_]PAGER. There isn't a lot of sense in trying to use a pager in non-interactive cases, and doing so allows an environment setting to break our tests. Also, ignore PSQL_WATCH_PAGER if it is set but empty or all-blank, for the same reasons we ignore such settings of [PSQL_]PAGER (see commit 18f8f784c). No documentation change is really needed, since there is nothing suggesting that these constraints on [PSQL_]PAGER didn't already apply to PSQL_WATCH_PAGER too. But I rearranged the text a little to make it read more naturally (IMHO anyway). Per report from Pavel Stehule. Back-patch to v15 where PSQL_WATCH_PAGER was introduced. Discussion: https://postgr.es/m/CAFj8pRDTwFzmEWdA-gdAcUh0ZnxUioSfTMre71WyB_wNJy-8gw@mail.gmail.com
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-10Fix assertion failure when updating stats_fetch_consistency in a transactionMichael Paquier
An update of the GUC stats_fetch_consistency in a transaction would be able to trigger an assertion when doing cache->snapshot. In this case, when retrieving a pgstat entry after the switch, a new snapshot would be rebuilt, confusing pgstat_build_snapshot() because a snapshot is already cached with an unexpected mode ("cache"). In order to fix this problem, this commit adds a flag to force a snapshot clear each time this GUC is changed. Some tests are added to check, while on it. Some optimizations in avoiding the snapshot clear should be possible depending on what is cached and the current GUC value, I guess, but this solution is simple, and ensures that the state of the cache is updated each time a new pgstat entry is fetched, hence being consistent with the level wanted by the client that has set the GUC. Note that cache->none and snapshot->none would not cause issues, as fetching a pgstat entry would be retrieved from shared memory on the second attempt, however a snapshot would still be cached. Similarly, none->snapshot and none->cache would build a new snapshot on the second fetch attempt. Finally, snapshot->cache would cache a new snapshot on the second attempt. Reported-by: Alexander Lakhin Author: Kyotaro Horiguchi Discussion: https://postgr.es/m/17804-2a118cd046f2d0e5@postgresql.org backpatch-through: 15
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-05First-draft release notes for 15.3.Tom Lane
As usual, the release notes for other branches will be made by cutting these down, but put them up for community review first.
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-05-02doc: Fix typo in pg_amcheck for term "schema"Michael Paquier
Author: Alexander Lakhin Discussion: https://postgr.es/m/e8c38840-596a-83d6-bd8d-cebc51111572@gmail.com Backpatch-through: 14
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-20Doc: clarify NULLS NOT DISTINCT use in unique indexesDavid Rowley
indexes-unique.html mentioned nothing about the availability of NULLS NOT DISTINCT to modify the NULLs-are-not-equal behavior of unique indexes. Add this to the synopsis and clarify what it does regarding NULLs. Author: David Gilman, David Rowley Reviewed-by: Corey Huinker Discussion: https://postgr.es/m/CALBH9DDr3NLqzWop1z5uZE-M5G_GYUuAeHFHQeyzFbNd8W0d=Q@mail.gmail.com Backpatch-through: 15, where NULLS NOT DISTINCT was added
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-12Document BaseBackupSync and BaseBackupWrite wait events.Robert Haas
Commit 3500ccc39b0dadd1068a03938e4b8ff562587ccc should have done this, but I overlooked it. Per complaint from Thomas Munro. Discussion: http://postgr.es/m/CA+hUKGJixAHc860Ej9Qzd_z96Z6aoajAgJ18bYfV3Lfn6t9=+Q@mail.gmail.com
2023-04-10Doc: add missed entries in BRIN extensibility tables.Tom Lane
The tables in "71.3. Extensibility" listing the support functions for bloom and minmax-multi opclasses should include the associated options function. While this isn't quite as required as the rest, you need it for full functionality of the opclass. Back-patch to v14 where these functions were added.
2023-04-10Doc: adjust examples of EXTRACT() output to match current reality.Tom Lane
EXTRACT(EPOCH), EXTRACT(SECOND), and some related cases print more trailing zeroes than they used to. This behavior change happened with commit a2da77cdb (Change return type of EXTRACT to numeric), and it was intentional according to the commit log: - Return values when extracting fields with possibly fractional values, such as second and epoch, now have the full scale that the value has internally (so, for example, '1.000000' instead of just '1'). It's been like that for two releases now, so while I suggested changing this back, it's probably better to adjust the documentation examples. Per bug #17866 from Евгений Жужнев. Back-patch to v14 where the change came in. Discussion: https://postgr.es/m/17866-18eb70095b1594e2@postgresql.org
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
generated by cgit v1.2.3 (git 2.46.0) at 2025-11-29 10:42:07 +0000