summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
2021-07-30Fix range check in ECPG numeric to int conversionJohn Naylor
The previous coding guarded against -INT_MAX instead of INT_MIN, leading to -2147483648 being rejected as out of range. Per bug #17128 from Kevin Sweet Discussion: https://www.postgresql.org/message-id/flat/17128-55a8a879727a3e3a%40postgresql.org Reviewed-by: Tom Lane Backpatch to all supported branches
2021-07-28Doc: Clarify lock levels taken during ATTACH PARTITIONDavid Rowley
It wasn't all that clear which lock levels, if any, would be held on the DEFAULT partition during an ATTACH PARTITION operation. Also, clarify which locks will be taken if the DEFAULT partition or the table being attached are themselves partitioned tables. Here I'm only backpatching to v12 as before then we obtained an ACCESS EXCLUSIVE lock on the partitioned table. It seems much less relevant to mention which locks are taken on other tables when the partitioned table itself is locked with an ACCESS EXCLUSIVE lock. Author: Matthias van de Meent, David Rowley Discussion: https://postgr.es/m/CAEze2WiTB6iwrV8W_J=fnrnZ7fowW3qu-8iQ8zCHP3FiQ6+o-A@mail.gmail.com Backpatch-through: 12
2021-07-28Avoid using ambiguous word "non-negative" in error messages.Fujii Masao
The error messages using the word "non-negative" are confusing because it's ambiguous about whether it accepts zero or not. This commit improves those error messages by replacing it with less ambiguous word like "greater than zero" or "greater than or equal to zero". Also this commit added the note about the word "non-negative" to the error message style guide, to help writing the new error messages. When postgres_fdw option fetch_size was set to zero, previously the error message "fetch_size requires a non-negative integer value" was reported. This error message was outright buggy. Therefore back-patch to all supported versions where such buggy error message could be thrown. Reported-by: Hou Zhijie Author: Bharath Rupireddy Reviewed-by: Kyotaro Horiguchi, Fujii Masao Discussion: https://postgr.es/m/OS0PR01MB5716415335A06B489F1B3A8194569@OS0PR01MB5716.jpnprd01.prod.outlook.com
2021-07-26doc: for various substring funcs, document if only first matchBruce Momjian
Reported-by: troy@frericks.us Discussion: https://postgr.es/m/162614304115.701.2392941350859387646@wrigleys.postgresql.org Backpatch-through: 13
2021-07-26pg_resetxlog: add option to set oldest xid & use by pg_upgradeBruce Momjian
Add pg_resetxlog -u option to set the oldest xid in pg_control. Previously -x set this value be -2 billion less than the -x value. However, this causes the server to immediately scan all relation's relfrozenxid so it can advance pg_control's oldest xid to be inside the autovacuum_freeze_max_age range, which is inefficient and might disrupt diagnostic recovery. pg_upgrade will use this option to better create the new cluster to match the old cluster. Reported-by: Jason Harvey, Floris Van Nee Discussion: https://postgr.es/m/20190615183759.GB239428@rfd.leadboat.com, 87da83168c644fd9aae38f546cc70295@opammb0562.comp.optiver.com Author: Bertrand Drouvot Backpatch-through: 9.6
2021-07-21Doc: improve documentation about exponentiation operator.Tom Lane
Now that we're not having to wedge this into the straitjacket of the old operator table format, we can add another example to clarify the point about left-to-right associativity. Per suggestion from mdione at grulic.org.ar. https://postgr.es/m/162661954599.693.13700316547731859171@wrigleys.postgresql.org
2021-07-21doc: Document that only superusers can use pg_import_system_collations().Fujii Masao
Back-patch to v10 where pg_import_system_collations() was added. Author: Atsushi Torikoshi Reviewed-by: Fujii Masao Discussion: https://postgr.es/m/b7f484692a3e283710032e68b7f40617@oss.nttdata.com
2021-07-19doc: Mention CASCADE/RESTRICT for DROP STATISTICSMichael Paquier
This grammar has no effect as there are no dependencies on statistics, but it is supported by the parser. This is more consistent with the other DROP commands. Author: Vignesh C Discussion: https://postgr.es/m/CALDaNm1LA=yNmzcSfy+0oe6CEAgsxXRf_-UutE3ZncFi8QkFNQ@mail.gmail.com Backpatch-through: 10
2021-07-17Doc: document the current-transaction-modes GUCs.Tom Lane
We had documentation of default_transaction_isolation et al, but for some reason not of transaction_isolation et al. AFAICS this is just an ancient oversight, so repair. Per bug #17077 from Yanliang Lei. Discussion: https://postgr.es/m/17077-ade8e166a01e1374@postgresql.org
2021-07-12doc: Fix typo in function prototypePeter Eisentraut
2021-07-07doc: Fix description about pg_stat_statements.track_planning.Fujii Masao
This commit fixes wrong wording like "a fewer kinds" in the description about track_planning option. Back-patch to v13 where pg_stat_statements.track_planning was added. Author: Justin Pryzby Reviewed-by: Julien Rouhaud, Fujii Masao Discussion: https://postgr.es/m/20210418233615.GB7256@telsasoft.com
2021-07-06Doc: add info about timestamps with fractional-minute UTC offsets.Tom Lane
Our code has supported fractional-minute UTC offsets for ages, but there was no mention of the possibility in the main docs, and only a very indirect reference in Appendix B. Improve that. Discussion: https://postgr.es/m/162543102827.697.5755498651217979813@wrigleys.postgresql.org
2021-07-05Doc: Hash Indexes.Amit Kapila
A new chapter for Hash Indexes, designed to help users understand how they work and when to use them. Backpatch-through 10 where we have made hash indexes durable. Author: Simon Riggs Reviewed-By: Justin Pryzby, Amit Kapila Discussion: https://postgr.es/m/CANbhV-HRjNPYgHo--P1ewBrFJ-GpZPb9_25P7=Wgu7s7hy_sLQ@mail.gmail.com
2021-07-04doc: Mention requirement to --enable-tap-tests on section for TAP testsMichael Paquier
Author: Greg Sabino Mullane Discussion: https://postgr.es/m/CAKAnmmJYH2FBn_+Vwd2FD5SaKn8hjhAXOCHpZc6n4wXaUaW_SA@mail.gmail.com Backpatch-through: 9.6
2021-07-04Doc: mention that VACUUM can't utilize over 1GB of RAMDavid Rowley
Document that setting maintenance_work_mem to values over 1GB has no effect on VACUUM. Reported-by: Martín Marqués Author: Laurenz Albe Discussion: https://postgr.es/m/CABeG9LsZ2ozUMcqtqWu_-GiFKB17ih3p8wBHXcpfnHqhCnsc7A%40mail.gmail.com Backpatch-through: 9.6, oldest supported release
2021-07-02doc: adjust "cities" example to be consistent with other SQLBruce Momjian
Reported-by: tom@crystae.net Discussion: https://postgr.es/m/162345756191.14472.9754568432103008703@wrigleys.postgresql.org Backpatch-through: 9.6
2021-07-01add missing tag from commit b8c4261e5eAndrew Dunstan
2021-07-01Add new make targets world-bin and install-world-binAndrew Dunstan
These are the same as world and install-world respectively, but without building or installing the documentation. There are many reasons for wanting to be able to do this, including speed, lack of documentation building tools, and wanting to build other formats of the documentation. Plans for simplifying the buildfarm client code include using these targets. Backpatch to all live branches. Discussion: https://postgr.es/m/6a421136-d462-b043-a8eb-e75b2861f3df@dunslane.net
2021-06-25doc: Change reloption data type spelling for consistencyPeter Eisentraut
Use "floating point" rather than "float4", like everywhere else in this context. Author: Shinya11.Kato@nttdata.com Discussion: https://www.postgresql.org/message-id/flat/TYAPR01MB28965989AF84B57FC351B97BC40F9@TYAPR01MB2896.jpnprd01.prod.outlook.com
2021-06-24Doc: Update caveats in synchronous logical replication.Amit Kapila
Reported-by: Simon Riggs Author: Takamichi Osumi Reviewed-by: Amit Kapila Backpatch-through: 9.6 Discussion: https://www.postgresql.org/message-id/20210222222847.tpnb6eg3yiykzpky@alap3.anarazel.de
2021-06-23Doc: fix confusion about LEAKPROOF in syntax summaries.Tom Lane
The syntax summaries for CREATE FUNCTION and allied commands made it look like LEAKPROOF is an alternative to IMMUTABLE/STABLE/VOLATILE, when of course it is an orthogonal option. Improve that. Per gripe from aazamrafeeque0. Thanks to David Johnston for suggestions. Discussion: https://postgr.es/m/162444349581.694.5818572718530259025@wrigleys.postgresql.org
2021-06-17Document a few caveats in synchronous logical replication.Amit Kapila
In a synchronous logical setup, locking [user] catalog tables can cause deadlock. This is because logical decoding of transactions can lock catalog tables to access them so exclusively locking those in transactions can lead to deadlock. To avoid this users must refrain from having exclusive locks on catalog tables. Author: Takamichi Osumi Reviewed-by: Vignesh C, Amit Kapila Backpatch-through: 9.6 Discussion: https://www.postgresql.org/message-id/20210222222847.tpnb6eg3yiykzpky%40alap3.anarazel.de
2021-06-08Avoid misbehavior when persisting a non-stable cursor.Tom Lane
PersistHoldablePortal has long assumed that it should store the entire output of the query-to-be-persisted, which requires rewinding and re-reading the output. This is problematic if the query is not stable: we might get different row contents, or even a different number of rows, which'd confuse the cursor state mightily. In the case where the cursor is NO SCROLL, this is very easy to solve: just store the remaining query output, without any rewinding, and tweak the portal's cursor state to match. Aside from removing the semantic problem, this could be significantly more efficient than storing the whole output. If the cursor is scrollable, there's not much we can do, but it was already the case that scrolling a volatile query's result was pretty unsafe. We can just document more clearly that getting correct results from that is not guaranteed. There are already prohibitions in place on using SCROLL with FOR UPDATE/SHARE, which is one way for a SELECT query to have non-stable results. We could imagine prohibiting SCROLL when the query contains volatile functions, but that would be expensive to enforce. Moreover, it could break applications that work just fine, if they have functions that are in fact stable but the user neglected to mark them so. So settle for documenting the hazard. While this problem has existed in some guise for a long time, it got a lot worse in v11, which introduced the possibility of persisting plpgsql cursors (perhaps implicit ones) even when they violate the rules for what can be marked WITH HOLD. Hence, I've chosen to back-patch to v11 but not further. Per bug #17050 from Алексей Булгаков. Discussion: https://postgr.es/m/17050-f77aa827dc85247c@postgresql.org
2021-06-03Doc: fix bogus intarray index example.Tom Lane
The siglen parameter is provided by gist__intbig_ops not gist__int_ops. Simon Norris Discussion: https://postgr.es/m/11BF2AA9-17AE-432A-AFE1-584FB9FB079D@hillcrestgeo.ca
2021-06-04doc: Fix link reference for PGSSLMAXPROTOCOLVERSIONMichael Paquier
The link was pointing to the minimum protocol version. Incorrect as of ff8ca5f. Author: Daniel Gustafsson Discussion: https://postgr.es/m/F893F184-C645-4C21-A2BA-583441B7288F@yesql.se Backpatch-through: 13
2021-05-27doc: Fix description of some GUCs in docs and postgresql.conf.sampleMichael Paquier
The following parameters have been imprecise, or incorrect, about their description (PGC_POSTMASTER or PGC_SIGHUP): - autovacuum_work_mem (docs, as of 9.6~) - huge_page_size (docs, as of 14~) - max_logical_replication_workers (docs, as of 10~) - max_sync_workers_per_subscription (docs, as of 10~) - min_dynamic_shared_memory (docs, as of 14~) - recovery_init_sync_method (postgresql.conf.sample, as of 14~) - remove_temp_files_after_crash (docs, as of 14~) - restart_after_crash (docs, as of 9.6~) - ssl_min_protocol_version (docs, as of 12~) - ssl_max_protocol_version (docs, as of 12~) This commit adjusts the description of all these parameters to be more consistent with the practice used for the others. Revewed-by: Justin Pryzby Discussion: https://postgr.es/m/YK2ltuLpe+FbRXzA@paquier.xyz Backpatch-through: 9.6
2021-05-25Improve docs and error messages for parallel vacuum.Amit Kapila
The error messages, docs, and one of the options were using 'parallel degree' to indicate parallelism used by vacuum command. We normally use 'parallel workers' at other places so change it for parallel vacuum accordingly. Author: Bharath Rupireddy Reviewed-by: Dilip Kumar, Amit Kapila Backpatch-through: 13 Discussion: https://postgr.es/m/CALj2ACWz=PYrrFXVsEKb9J1aiX4raA+UBe02hdRp_zqDkrWUiw@mail.gmail.com
2021-05-14Doc: correct erroneous entry in this week's minor release notes.Tom Lane
The patch to disallow a NULL specification in combination with GENERATED ... AS IDENTITY applied to both ALWAYS and BY DEFAULT variants of that clause, not only the former. Noted by Shay Rojansky. Discussion: https://postgr.es/m/CADT4RqAwD3A=RvGiQU9AiTK-6VeuXcycwPHmJPv_OBCJFYOEww@mail.gmail.com
2021-05-14Prevent infinite insertion loops in spgdoinsert().Tom Lane
Formerly we just relied on operator classes that assert longValuesOK to eventually shorten the leaf value enough to fit on an index page. That fails since the introduction of INCLUDE-column support (commit 09c1c6ab4), because the INCLUDE columns might alone take up more than a page, meaning no amount of leaf-datum compaction will get the job done. At least with spgtextproc.c, that leads to an infinite loop, since spgtextproc.c won't throw an error for not being able to shorten the leaf datum anymore. To fix without breaking cases that would otherwise work, add logic to spgdoinsert() to verify that the leaf tuple size is decreasing after each "choose" step. Some opclasses might not decrease the size on every single cycle, and in any case, alignment roundoff of the tuple size could obscure small gains. Therefore, allow up to 10 cycles without additional savings before throwing an error. (Perhaps this number will need adjustment, but it seems quite generous right now.) As long as we've developed this logic, let's back-patch it. The back branches don't have INCLUDE columns to worry about, but this seems like a good defense against possible bugs in operator classes. We already know that an infinite loop here is pretty unpleasant, so having a defense seems to outweigh the risk of breaking things. (Note that spgtextproc.c is actually the only known opclass with longValuesOK support, so that this is all moot for known non-core opclasses anyway.) Per report from Dilip Kumar. Discussion: https://postgr.es/m/CAFiTN-uxP_soPhVG840tRMQTBmtA_f_Y8N51G7DKYYqDh7XN-A@mail.gmail.com
2021-05-13Improve documentation example for jsonpath like_regex operatorAlexander Korotkov
Make sample like_regex match string values of the root object instead of the whole document. The corrected example seems to represent a more relevant use case. Backpatch to 12, when jsonpath was introduced. Discussion: https://postgr.es/m/13440f8b-4c1f-5875-c8e3-f3f65606af2f%40xs4all.nl Author: Erik Rijkers Reviewed-by: Michael Paquier, Alexander Korotkov Backpatch-through: 12
2021-05-10Last-minute updates for release notes.Tom Lane
Security: CVE-2021-32027, CVE-2021-32028, CVE-2021-32029
2021-05-09Release notes for 13.3, 12.7, 11.12, 10.17, 9.6.22.Tom Lane
2021-05-07First-draft release notes for 13.3.Tom Lane
As usual, the release notes for older branches will be made by cutting these down, but put them up for community review first.
2021-05-06Document lock level used by ALTER TABLE VALIDATE CONSTRAINTAlvaro Herrera
Backpatch all the way back to 9.6. Author: Simon Riggs <simon.riggs@enterprisedb.com> Discussion: https://postgr.es/m/CANbhV-EwxvdhHuOLdfG2ciYrHOHXV=mm6=fD5aMhqcH09Li3Tg@mail.gmail.com
2021-04-30Doc: add an example of a self-referential foreign key to ddl.sgml.Tom Lane
While we've always allowed such cases, the documentation didn't say you could do it. Discussion: https://postgr.es/m/161969805833.690.13680986983883602407@wrigleys.postgresql.org
2021-04-30Doc: update libpq's documentation for PQfn().Tom Lane
Mention specifically that you can't call aggregates, window functions, or procedures this way (the inability to call SRFs was already mentioned). Also, the claim that PQfn doesn't support NULL arguments or results has been a lie since we invented protocol 3.0. Not sure why this text was never updated for that, but do it now. Discussion: https://postgr.es/m/2039442.1615317309@sss.pgh.pa.us
2021-04-29Improve documentation for default_tablespace on partitioned tablesAlvaro Herrera
Backpatch to 12, where 87259588d0ab introduced the current behavior. Per note from Justin Pryzby. Co-authored-by: Justin Pryzby <pryzby@telsasoft.com> Discussion: https://postgr.es/m/20210416143135.GI3315@telsasoft.com
2021-04-28Doc: fix discussion of how to get real Julian Dates.Tom Lane
Somehow I'd convinced myself that rotating to UTC-12 was the way to do this, but upon further review, it's definitely UTC+12. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation.Tom Lane
For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-23doc: Fix obsolete description about pg_basebackup.Fujii Masao
Previously it was documented that if using "-X none" option there was no guarantee that all required WAL files were archived at the end of pg_basebackup when taking a backup from the standby. But this limitation was removed by commit 52f8a59dd9. Now, even when taking a backup from the standby, pg_basebackup can wait for all required WAL files to be archived. Therefore this commit removes such obsolete description from the docs. Also this commit adds new description about the limitation when taking a backup from the standby, into the docs. The limitation is that pg_basebackup cannot force the standbfy to switch to a new WAL file at the end of backup, which may cause pg_basebackup to wait a long time for the last required WAL file to be switched and archived, especially when write activity on the primary is low. Back-patch to v10 where the issue was introduced. Reported-by: Kyotaro Horiguchi Author: Kyotaro Horiguchi, Fujii Masao Reviewed-by: Kyotaro Horiguchi, Fujii Masao Discussion: https://postgr.es/m/20210420.133235.1342729068750553399.horikyota.ntt@gmail.com
2021-04-22Doc: document the tie-breaking behavior of the round() function.Tom Lane
Back-patch to v13; the table layout in older branches is unfriendly to adding such details. Laurenz Albe Discussion: https://postgr.es/m/161881920775.685.12293798764864559341@wrigleys.postgresql.org
2021-04-16doc: Fix typo in example query of SQL/JSONMichael Paquier
Author: Erik Rijkers Discussion: https://postgr.es/m/1219476687.20432.1617452918468@webmailclassic.xs4all.nl Backpatch-through: 12
2021-04-09Fix typos and grammar in documentation and code commentsMichael Paquier
Comment fixes are applied on HEAD, and documentation improvements are applied on back-branches where needed. Author: Justin Pryzby Discussion: https://postgr.es/m/20210408164008.GJ6592@telsasoft.com Backpatch-through: 9.6
2021-04-02Clarify documentation of RESET ROLEJoe Conway
Command-line options, or previous "ALTER (ROLE|DATABASE) ... SET ROLE ..." commands, can change the value of the default role for a session. In the presence of one of these, RESET ROLE will change the current user identifier to the default role rather than the session user identifier. Fix the documentation to reflect this reality. Backpatch to all supported versions. Author: Nathan Bossart Reviewed-By: Laurenz Albe, David G. Johnston, Joe Conway Reported by: Nathan Bossart Discussion: https://postgr.es/m/flat/925134DB-8212-4F60-8AB1-B1231D750CB4%40amazon.com Backpatch-through: 9.6
2021-04-02doc: Clarify how to generate backup files with non-exclusive backupsMichael Paquier
The current instructions describing how to write the backup_label and tablespace_map files are confusing. For example, opening a file in text mode on Windows and copy-pasting the file's contents would result in a failure at recovery because of the extra CRLF characters generated. The documentation was not stating that clearly, and per discussion this is not considered as a supported scenario. This commit extends a bit the documentation to mention that it may be required to open the file in binary mode before writing its data. Reported-by: Wang Shenhao Author: David Steele Reviewed-by: Andrew Dunstan, Magnus Hagander Discussion: https://postgr.es/m/8373f61426074f2cb6be92e02f838389@G08CNEXMBPEKD06.g08.fujitsu.local Backpatch-through: 9.6
2021-04-01doc: mention that intervening major releases can be skippedBruce Momjian
Also mention that you should read the intervening major releases notes. This change was also applied to the website. Discussion: https://postgr.es/m/20210330144949.GA8259@momjian.us Backpatch-through: 9.6
2021-04-01doc: Clarify use of ACCESS EXCLUSIVE lock in various sectionsMichael Paquier
Some sections of the documentation used "exclusive lock" to describe that an ACCESS EXCLUSIVE lock is taken during a given operation. This can be confusing to the reader as ACCESS SHARE is allowed with an EXCLUSIVE lock is used, but that would not be the case with what is described on those parts of the documentation. Author: Greg Rychlewski Discussion: https://postgr.es/m/CAKemG7VptD=7fNWckFMsMVZL_zzvgDO6v2yVmQ+ZiBfc_06kCQ@mail.gmail.com Backpatch-through: 9.6
2021-03-31Add a docs section for obsoleted and renamed functions and settingsStephen Frost
The new appendix groups information on renamed or removed settings, commands, etc into an out-of-the-way part of the docs. The original id elements are retained in each subsection to ensure that the same filenames are produced for HTML docs. This prevents /current/ links on the web from breaking, and allows users of the web docs to follow links from old version pages to info on the changes in the new version. Prior to this change, a link to /current/ for renamed sections like the recovery.conf docs would just 404. Similarly if someone searched for recovery.conf they would find the pg11 docs, but there would be no /12/ or /current/ link, so they couldn't easily find out that it was removed in pg12 or how to adapt. Index entries are also added so that there's a breadcrumb trail for users to follow when they know the old name, but not what we changed it to. So a user who is trying to find out how to set standby_mode in PostgreSQL 12+, or where pg_resetxlog went, now has more chance of finding that information. Craig Ringer and Stephen Frost Reviewed-by: Euler Taveira Discussion: https://postgr.es/m/CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg%40mail.gmail.com Backpatch-through: 10
2021-03-28doc: Define TLS as an acronymStephen Frost
Commit c6763156589 added an acronym reference for "TLS" but the definition was never added. Author: Daniel Gustafsson Reviewed-by: Michael Paquier Backpatch-through: 9.6 Discussion: https://postgr.es/m/27109504-82DB-41A8-8E63-C0498314F5B0@yesql.se
2021-03-25Document lock obtained during partition detachAlvaro Herrera
On partition detach, we acquire a SHARE lock on all tables that reference the partitioned table that we're detaching a partition from, but failed to document this fact. My oversight in commit f56f8f8da6af. Repair. Backpatch to 12. Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Discussion: https://postgr.es/m/20210325180244.GA12738@alvherre.pgsql
generated by cgit v1.2.3 (git 2.46.0) at 2025-10-28 16:32:45 +0000