summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
2022-07-14doc: clarify the behavior of identically-named savepointsBruce Momjian
Original patch by David G. Johnston. Reported-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwYQCxSSuSL18skCWG8QHFswOJ3hjovHsOZUE346i4OpVQ@mail.gmail.com Backpatch-through: 10
2022-07-14doc: clarify that "excluded" ON CONFLICT is a single rowBruce Momjian
Original patch by David G. Johnston. Reported-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwa4J0+WuO7kW1PLbjoEvzPN+Q_j+P2bXxNnCLaszY7ZdQ@mail.gmail.com Backpatch-through: 10
2022-07-14doc: mention that INSERT can block because of unique indexesBruce Momjian
Initial patch by David G. Johnston. Reported-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwZpbdzceO41VE-xt1Xh8rWRRfgopTAK1wL9EhCo0Am-Sw@mail.gmail.com Backpatch-through: 10
2022-07-14doc: mention the pg_locks lock names in parenthesesBruce Momjian
Reported-by: Troy Frericks Discussion: https://postgr.es/m/165653551130.665.8240515669521441325@wrigleys.postgresql.org Backpatch-through: 10
2022-07-11relnotes: updates "cumulative statistics system" mentionBruce Momjian
Also add "the". Reported-by: Justin Pryzby Discussion: https://postgr.es/m/20220711173923.GV13040@telsasoft.com Backpatch-through: 15 only
2022-07-11doc: Fix inconsistent quotes in some jsonb fieldsMichael Paquier
Single quotes are not allowed in json internals, double quotes are. Reported-by: Eric Mutta Discussion: https://postgr.es/m/165715362165.665.3875113264927503997@wrigleys.postgresql.org Backpatch-through: 14
2022-07-08doc: add examples for array_length() and jsonb_array_length()Bruce Momjian
The examples show the output of array_length() and jsonb_array_length() for empty arrays. Discussion: https://postgr.es/m/CAKFQuwaoBmRuWdMLzLHDCFDJDX3wvfQ7egAF0bpik_BFgG1KWg@mail.gmail.com Author: David G. Johnston Backpatch-through: 13
2022-07-08doc: add pg_prewarm exampleBruce Momjian
Discussion: https://postgr.es/m/20220618085541.ezxdaljlpo6x7msc@home-desktop Author: Dong Wook Lee Backpatch-through: 11
2022-07-05relnotes: clarify that PG 15 multi-xid is advanced moreBruce Momjian
Reported-by: Peter Geoghegan Discussion: https://postgr.es/m/CAH2-Wzk-oOpKObMKJ=Df4WBERX0ja14ymu3h5JrDt_FtmvH1yQ@mail.gmail.com Backpatch-through: 15 only
2022-07-05Rename pg_checkpointer predefined role to pg_checkpoint.Robert Haas
This is more consistent with how other predefined roles that confer specific privileges are named. Nathan Bosart Discussion: http://postgr.es/m/CA+TgmoatH7+yYe+A8uJFNogg3VUDtFE6c-77yHAY8TRWR7oqyw@mail.gmail.com
2022-07-05BRIN: improve documentation on summarizationAlvaro Herrera
The existing wording wasn't clear enough and some details weren't anywhere, such as the fact that autosummarization is off by default. Improve. Authors: Roberto Mello, Jaime Casanova, Justin Pryzby, Álvaro Herrera Discussion: https://postgr.es/m/CAKz==bK_NoJytRyQfX8K-erCW3Ff7--oGYpiB8+ePVS7dRVW_A@mail.gmail.com Discussion: https://postgr.es/m/20220224193520.GY9008@telsasoft.com
2022-07-02Default to dynamic_shared_memory_type=sysv on Solaris.Thomas Munro
POSIX shm_open() can sleep for a long time and fail spuriously because of contention on an internal lock file on Solaris (and presumably illumos). Commit 389869af fixed the main problem with this, namely that we could crash, but it's now clear that "posix" is not a good default. Therefore, choose "sysv" at initdb time on Solaris and illumos. Other choices are still available by editing the postgresql.conf file. Back-patch only to 15, because contention is much less likely further back, and it doesn't seem like a good idea to change this in released branches. This should clear up the failures on build farm animal margay. Discussion: https://postgr.es/m/CA%2BhUKGKqKrCV5xKWfh9rnm%3Do%3DDwZLTLtnsj_XpUi9g5%3DV%2B9oyg%40mail.gmail.com
2022-07-01doc: Add index entry for MERGE SQL command.Fujii Masao
Back-patch to v15, where MERGE command was supported. Author: Fujii Masao Reviewed-by: Alvaro Herrera Discussion: https://postgr.es/m/4e7a4b38-c34a-ce2c-c71e-832d2b768b29@oss.nttdata.com
2022-06-28relnotes: update item about public schema permission changeBruce Momjian
Also mention the bootstrap superuser. Reported-by: Noah Misch Discussion: https://postgr.es/m/20220628063719.GA2208244@rfd.leadboat.com
2022-06-27Remove outdated recommendation for manual VACUUMMagnus Hagander
We have had a working and tunable autovacuum for at least a decade now, so remove the recommendation to manually vacuum tables at least every night. Autovacuum is now also triggered by INSERTs, so we can also remove the recommendation to run VACUUM (ANALYZE) after lots of INSERTs or DELETEs. Instead, suggest using autovacuum by moving the respective paragraph up to where the importance of VACUUM is emphasized. Author: Laurenz Albe <laurenz.albe@cybertec.at> Reviewed-By: Magnus Hagander, Peter Geoghegan Discussion: https://postgr.es/m/6f5e3da98fec14640f389d7b84c3b413833697f4.camel@cybertec.at
2022-06-27doc: Mention attribute "inherited" in pg_stats_ext[_exprs]Michael Paquier
These have been added in 269b532, but the documentation did not reflect that. Author: Noriyoshi Shinoda Reviewed-by: Justin Pryzby Discussion: https://postgr.es/m/DM4PR84MB17349C4E7D88A68264C18AF3EED69@DM4PR84MB1734.NAMPRD84.PROD.OUTLOOK.COM
2022-06-24Doc: clarify that tablesync ignores publish operation.Amit Kapila
This patch documents that the initial data synchronization (tablesync) for logical replication does not take into account the publication 'publish' parameter when copying the existing table data. Author: Peter Smith Reviewed-by: Shi yu, Euler Taveira, Robert Haas, Amit Kapila Discussion: https://postgr.es/m/CAHut+PtbfALjFpS2MkrvQ+wWQKByP7CNh9RtFta-r=BHEU3S3w@mail.gmail.com
2022-06-23Fix two issues with HEADER MATCH in COPYMichael Paquier
072132f0 used the attnum offset to access the raw_fields array when checking that the attribute names of the header and of the relation match, leading to incorrect results or even crashes if the attribute numbers of a relation are changed, like on a dropped attribute. This fixes the logic to use the correct attribute names for the header matching requirements. Also, this commit disallows HEADER MATCH in COPY TO as there is no validation that can be done in this case. The tests are expanded for HEADER MATCH with COPY FROM and dropped columns, with cases where a relation has a dropped and re-added column, as well as a reduced set of columns. Author: Julien Rouhaud Reviewed-by: Peter Eisentraut, Michael Paquier Discussion: https://postgr.es/m/20220607154744.vvmitnqhyxrne5ms@jrouhaud
2022-06-22doc: improve wording of plpgsql RAISE format textBruce Momjian
Reported-by: pg@kirasoft.com Discussion: https://postgr.es/m/165455351426.573551.7050474465030525109@wrigleys.postgresql.org Backpatch-through: 10
2022-06-22doc: clarify wording about phantom readsBruce Momjian
Reported-by: akhilhello@gmail.com Discussion: https://postgr.es/m/165222922369.669.10475917322916060899@wrigleys.postgresql.org Backpatch-through: 10
2022-06-22doc: Clean up title case usePeter Eisentraut
2022-06-21doc: Make some synopsis punctuation consistentPeter Eisentraut
2022-06-20Fix file references inside some SGML commentsPeter Eisentraut
In some cases, the comments mentioning their own file or another file were not correct. Author: Josh Soref <jsoref@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CACZqfqCyhE-voJUrUkc3GQuDakfJKx1ViiCdY7B8tQwyL6727g%40mail.gmail.com
2022-06-19relnotes: simplify wording of pg_basebackup compression itemBruce Momjian
2022-06-19Message and documentation refinementsPeter Eisentraut
2022-06-17doc: Do s/int/integer/ to describe the type of some GUC parametersMichael Paquier
Three parameters have been using "int" rather than "integer" to describe their type: auth_delay.milliseconds max_logical_replication_workers pg_prewarm.autoprewarm_interval This is inconsistent with any other integer GUCs listed in the docs (148, as far as I can see). Author: Peter Smith Discussion: https://postgr.es/m/CAHut+Pv6X5T-veN2abUDUvBxZm+SSm-9otfi3LZPGyOc6u6hiA@mail.gmail.com
2022-06-16Revert changes in HOT handling of BRIN indexesTomas Vondra
This reverts commits 5753d4ee32 and fe60b67250 that modified HOT to ignore BRIN indexes. The commit message for 5753d4ee32 claims that: When determining whether an index update may be skipped by using HOT, we can ignore attributes indexed only by BRIN indexes. There are no index pointers to individual tuples in BRIN, and the page range summary will be updated anyway as it relies on visibility info. This is partially incorrect - it's true BRIN indexes don't point to individual tuples, so HOT chains are not an issue, but the visibitlity info is not sufficient to keep the index up to date. This can easily result in corrupted indexes, as demonstrated in the hackers thread. This does not mean relaxing the HOT restrictions for BRIN is a lost cause, but it needs to handle the two aspects (allowing HOT chains and updating the page range summaries) as separate. But that requires a major changes, and it's too late for that in the current dev cycle. Reported-by: Tomas Vondra Discussion: https://postgr.es/m/05ebcb44-f383-86e3-4f31-0a97a55634cf@enterprisedb.com
2022-06-15Link to MVCC docs in MERGE docsAlvaro Herrera
In addition, this moves the new paragraph in the MVCC page upwards, for a more consistent flow; some minor markup mistakes, style issues and typos are fixed too. Per comments from Justin Pryzby. Discussion: https://postgr.es/m/20220511163350.GL19626@telsasoft.com
2022-06-15Tweak behavior of psql --single-transaction depending on ON_ERROR_STOPMichael Paquier
This commit, in completion of 157f873, forces a ROLLBACK for --single-transaction only when ON_ERROR_STOP is used when one of the steps defined by -f/-c fails. Hence, COMMIT is always used when ON_ERROR_STOP is not set, ignoring the status code of the last action taken in the set of switches specified by -c/-f (previously ROLLBACK would have been issued even without ON_ERROR_STOP if the last step failed, while COMMIT was issued if a step in-between failed as long as the last step succeeded, leading to more inconsistency). While on it, this adds much more test coverage in this area when not using ON_ERROR_STOP with multiple switch patterns involving -c and -f for query files, single queries and slash commands. The behavior of ON_ERROR_STOP is arguably a bug, but there was no much support for a backpatch to force a ROLLBACK on a step failure, so this change is done only on HEAD for now. Per discussion with Tom Lane and Kyotaro Horiguchi. Discussion: https://postgr.es/m/Yqbc8bAdwnP02na4@paquier.xyz
2022-06-14Doc: clarify the default collation behavior of domains.Tom Lane
The previous wording was "the underlying data type's default collation is used", which is wrong or at least misleading. The domain inherits the base type's collation behavior, which if "default" actually can mean that we use some non-default collation obtained from elsewhere. Per complaint from Jian He. Discussion: https://postgr.es/m/CACJufxHMR8_4WooDPjjvEdaxB2hQ5a49qthci8fpKP0MKemVRQ@mail.gmail.com
2022-06-11relnotes: update word wrappingBruce Momjian
2022-06-11relnotes: update AS OF dateBruce Momjian
2022-06-11relnotes: add links to the release notes, indent, word wrapBruce Momjian
2022-06-10relnotes: add markup of textBruce Momjian
Doc link additions coming
2022-06-08Doc: copy-edit "jsonb Indexing" section.Tom Lane
The patch introducing jsonpath dropped a para about that between two related examples, and didn't bother updating the introductory sentences that it falsified. The grammar was pretty shaky as well.
2022-06-08Put option listing back into alphabetical orderPeter Eisentraut
2022-06-08Restructure pg_upgrade output directories for better idempotenceMichael Paquier
38bfae3 has moved the contents written to files by pg_upgrade under a new directory called pg_upgrade_output.d/ located in the new cluster's data folder, and it used a simple structure made of two subdirectories leading to a fixed structure: log/ and dump/. This design has made weaker pg_upgrade on repeated calls, as we could get failures when creating one or more of those directories, while potentially losing the logs of a previous run (logs are retained automatically on failure, and cleaned up on success unless --retain is specified). So a user would need to clean up pg_upgrade_output.d/ as an extra step for any repeated calls of pg_upgrade. The most common scenario here is --check followed by the actual upgrade, but one could see a failure when specifying an incorrect input argument value. Removing entirely the logs would have the disadvantage of removing all the past information, even if --retain was specified at some past step. This result is annoying for a lot of users and automated upgrade flows. So, rather than requiring a manual removal of pg_upgrade_output.d/, this redesigns the set of output directories in a more dynamic way, based on a suggestion from Tom Lane and Daniel Gustafsson. pg_upgrade_output.d/ is still the base path, but a second directory level is added, mostly named after an ISO-8601-formatted timestamp (in short human-readable, with milliseconds appended to the name to avoid any conflicts). The logs and dumps are saved within the same subdirectories as previously, as of log/ and dump/, but these are located inside the subdirectory named after the timestamp. The logs of a given run are removed only after a successful run if --retain is not used, and pg_upgrade_output.d/ is kept if there are any logs from a previous run. Note that previously, pg_upgrade would have kept the logs even after a successful --check but that was inconsistent compared to the case without --check when using --retain. The code in charge of the removal of the output directories is now refactored into a single routine. Two TAP tests are added with some --check commands (one failure case and one success case), to look after the issue fixed here. Note that the tests had to be tweaked a bit to fit with the new directory structure so as it can find any logs generated on failure. This is still going to require a change in the buildfarm client for the case where pg_upgrade is tested without the TAP test, though, but I'll tackle that with a separate patch where needed. Reported-by: Tushar Ahuja Author: Michael Paquier Reviewed-by: Daniel Gustafsson, Justin Pryzby Discussion: https://postgr.es/m/77e6ecaa-2785-97aa-f229-4b6e047cbd2b@enterprisedb.com
2022-06-06Fix psql's single transaction mode on client-side errors with -c/-f switchesMichael Paquier
psql --single-transaction is able to handle multiple -c and -f switches in a single transaction since d5563d7d, but this had the surprising behavior of forcing a transaction COMMIT even if psql failed with an error in the client (for example incorrect path given to \copy), which would generate an error, but still commit any changes that were already applied in the backend. This commit makes the behavior more consistent, by enforcing a transaction ROLLBACK if any commands fail, both client-side and backend-side, so as no changes are applied if one error happens in any of them. Some tests are added on HEAD to provide some coverage about all that. Backend-side errors are unreliable as IPC::Run can complain on SIGPIPE if psql quits before reading a query result, but that should work properly in the case where any errors come from psql itself, which is what the original report is about. Reported-by: Christoph Berg Author: Kyotaro Horiguchi, Michael Paquier Discussion: https://postgr.es/m/17504-76b68018e130415e@postgresql.org Backpatch-through: 10
2022-06-03Doc: improve example for intarray's uniq() function.Tom Lane
The previous entry invited confusion between what uniq() does by itself and what it does when combined with sort(). The latter usage is pretty useful so we should show it, but add an additional example to clarify the results of uniq() alone. Per suggestion from Martin Kalcher. Back-patch to v13, where we switched to formatting that supports multiple examples. Discussion: https://postgr.es/m/165407884456.573551.8779012279828726162@wrigleys.postgresql.org
2022-06-03Doc: fix incorrect bit-reversal in example of macaddr formatting.Tom Lane
Will Mortensen (minor additional copy-editing by me) Discussion: https://postgr.es/m/CAMpnoC5Y6jiZHSA82FG+e_AqkwMg-i94EYqs1C_9kXXFc3_3Yw@mail.gmail.com
2022-06-02Doc: Further fix CREATE FOREIGN TABLE synopsis.Etsuro Fujita
This patch fixes the partitioning synopsis in the Parameters section in the CREATE FOREIGN TABLE documentation. Follow-up for commit ce21a36cf. Back-patch to v11 where default partition was introduced. Reviewed by Amit Langote and Robert Haas. Discussion: https://postgr.es/m/CAPmGK17U5jEqVZuo3r38wB0VFWomEtJCBGn_h92HQzQ2sP-49Q%40mail.gmail.com
2022-06-02Prohibit combining publications with different column lists.Amit Kapila
Currently, we simply combine the column lists when publishing tables on multiple publications and that can sometimes lead to unexpected behavior. Say, if a column is published in any row-filtered publication, then the values for that column are sent to the subscriber even for rows that don't match the row filter, as long as the row matches the row filter for any other publication, even if that other publication doesn't include the column. The main purpose of introducing a column list is to have statically different shapes on publisher and subscriber or hide sensitive column data. In both cases, it doesn't seem to make sense to combine column lists. So, we disallow the cases where the column list is different for the same table when combining publications. It can be later extended to combine the column lists for selective cases where required. Reported-by: Alvaro Herrera Author: Hou Zhijie Reviewed-by: Amit Kapila Discussion: https://postgr.es/m/202204251548.mudq7jbqnh7r@alvherre.pgsql
2022-06-01Doc: fix a couple of erroneous examples.Tom Lane
The example given for anyelement <@ anymultirange didn't return true as claimed; adjust it so it does. In passing, change a couple of sample results where the modern numeric-based logic produces a different number of trailing zeroes than before. Erik Rijkers Discussion: https://postgr.es/m/cc35735d-1ec1-5bb3-9e27-cddbab7afa23@xs4all.nl
2022-06-01Doc: mention limitation of the number of resultset columnsDavid Rowley
The PostgreSQL limitations section of the documents mentioned the limit on the number of columns that can exist in a table. Users might be surprised to find that there's also a limit on the number of columns that can exist in a targetlist. Users may experience restrictions which surprise them if they happened to select a large number of columns from several tables with many columns. Here we document that there is a limitation on this and mention what that limit actually is. Wording proposal by Alvaro Herrera Reported-by: Vladimir Sitnikov Author: Dave Crammer Reviewed-by: Tom Lane Discussion: https://postgr.es/m/CAB=Je-E18aTYpNqje4mT0iEADpeGLSzwUvo3H9kRRuDdsNo4aQ@mail.gmail.com Backpatch-through: 12, where the limitations section was added
2022-05-31Recommend scram-sha-256 instead of md5 authentication in docsMagnus Hagander
PostgreSQL 14 changed the default to be scram-sha-256, so we should stop recommending the user to use md5 or even worse password. Suggested-By: Daniel Westermann Author: Jonathan S. Katz Backpatch-through: 14 Discussion: https://postgr.es/m/GV0P278MB0419A8BAC0B0B84AFA5263D9D2DC9@GV0P278MB0419.CHEP278.PROD.OUTLOOK.COM
2022-05-31Revert changes to CONCURRENTLY that "sped up" Xmin advanceAlvaro Herrera
This reverts commit d9d076222f5b "VACUUM: ignore indexing operations with CONCURRENTLY". These changes caused indexes created with the CONCURRENTLY option to miss heap tuples that were HOT-updated and HOT-pruned during the index creation. Before these changes, HOT pruning would have been prevented by the Xmin of the transaction creating the index, but because this change was precisely to allow the Xmin to move forward ignoring that backend, now other backends scanning the table can prune them. This is not a problem for VACUUM (which requires a lock that conflicts with a CREATE INDEX CONCURRENTLY operation), but HOT-prune can definitely occur. In other words, Xmin advancement was sped up, but at the cost of corrupting the resulting index. Regrettably, this means that the new feature in PG14 that RIC/CIC on very large tables no longer force VACUUM to retain very old tuples goes away. We might try to implement it again in a later release, but for now the risk of indexes missing tuples is too high and there's no easy fix. Backpatch to 14, where this change appeared. Reported-by: Peter Slavov <pet.slavov@gmail.com> Diagnosys-by: Andrey Borodin <x4mmm@yandex-team.ru> Diagnosys-by: Michael Paquier <michael@paquier.xyz> Diagnosys-by: Andres Freund <andres@anarazel.de> Discussion: https://postgr.es/m/17485-396609c6925b982d%40postgresql.org
2022-05-31Doc: fix mention of psql's minimum supported server version.Tom Lane
Commit cf0cab868 removed describe.c's support for pre-9.2 server versions, but neglected to update this documentation reference. Discussion: https://postgr.es/m/GV0P278MB041917EB3E2FE8704B5AE2C6D2DC9@GV0P278MB0419.CHEP278.PROD.OUTLOOK.COM
2022-05-31Doc: fix mention of pg_dump's minimum supported server version.Tom Lane
runtime.sgml contains a passing reference to the minimum server version that pg_dump[all] can dump from. That was 7.0 for many years, but when 64f3524e2 raised it to 8.0, we missed updating this bit. Then when 30e7c175b raised it to 9.2, we missed it again. Given that track record, I'm not too hopeful that we'll remember to fix this in future changes ... but for now, make the docs match reality in each branch. Noted by Daniel Westermann. Discussion: https://postgr.es/m/GV0P278MB041917EB3E2FE8704B5AE2C6D2DC9@GV0P278MB0419.CHEP278.PROD.OUTLOOK.COM
2022-05-30doc: Reword description of roles able to view track_activities's infoMichael Paquier
The information generated when track_activities is accessible to superusers, roles with the privileges of pg_read_all_stats, as well as roles one has the privileges of. The original text did not outline the last point, while the change done in ac1ae47 was unclear about the second point. Per discussion with Nathan Bossart. Discussion: https://postgr.es/m/20220521185743.GA886636@nathanxps13 Backpatch-through: 10
2022-05-29Doc: fix missing/bogus documentation of range_intersect_agg().Tom Lane
The form taking anymultirange had not been documented. This was fixed in HEAD in b21c4cf95, but that should have been back-patched to v14 since the function was added there. Do so now. Also, the form taking anyrange was incorrectly documented as returning anymultirange, when it returns anyrange. Remove b21c4cf95 from the v15 release notes, since it no longer qualifies as new-in-v15. Noted by Shay Rojansky. Discussion: https://postgr.es/m/CADT4RqAktzP7t6SFf0Xqm9YhahzvsmxFbzXe-gFOd=+_CHm0JA@mail.gmail.com