summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
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-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: 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-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-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-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-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-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-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-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-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-23Use correct spelling of statistics kindTomas Vondra
A couple error messages and comments used 'statistic kind', not the correct 'statistics kind'. Fix and backpack all the way back to 10, where extended statistics were introduced. Backpatch-through: 10
2021-03-17Prevent buffer overrun in read_tablespace_map().Tom Lane
Robert Foggia of Trustwave reported that read_tablespace_map() fails to prevent an overrun of its on-stack input buffer. Since the tablespace map file is presumed trustworthy, this does not seem like an interesting security vulnerability, but still we should fix it just in the name of robustness. While here, document that pg_basebackup's --tablespace-mapping option doesn't work with tar-format output, because it doesn't. To make it work, we'd have to modify the tablespace_map file within the tarball sent by the server, which might be possible but I'm not volunteering. (Less-painful solutions would require changing the basebackup protocol so that the source server could adjust the map. That's not very appetizing either.)
2021-03-12Forbid marking an identity column as nullable.Tom Lane
GENERATED ALWAYS AS IDENTITY implies NOT NULL, but the code failed to complain if you overrode that with "GENERATED ALWAYS AS IDENTITY NULL". One might think the old behavior was a feature, but it was inconsistent because the outcome varied depending on the order of the clauses, so it seems to have been just an oversight. Per bug #16913 from Pavel Boev. Back-patch to v10 where identity columns were introduced. Vik Fearing (minor tweaks by me) Discussion: https://postgr.es/m/16913-3b5198410f67d8c6@postgresql.org
2021-03-03Clarify the usage of max_replication_slots on the subscriber side.Amit Kapila
It was not clear in the docs that the max_replication_slots is also used to track replication origins on the subscriber side. Author: Paul Martinez Reviewed-by: Amit Kapila Backpatch-through: 10 where logical replication was introduced Discussion: https://postgr.es/m/CACqFVBZgwCN_pHnW6dMNCrOS7tiHCw6Retf_=U2Vvj3aUSeATw@mail.gmail.com
2021-02-26Doc: further clarify libpq's description of connection string URIs.Tom Lane
Break the synopsis into named parts to make it less confusing. Make more than zero effort at applying SGML markup. Do a bit of copy-editing of nearby text. The synopsis revision is by Alvaro Herrera and Paul Förster, the rest is my fault. Back-patch to v10 where multi-host connection strings appeared. Discussion: https://postgr.es/m/6E752D6B-487C-463E-B6E2-C32E7FB007EA@gmail.com
2021-02-24Fix some typos, grammar and style in docs and commentsMichael Paquier
The portions fixing the documentation are backpatched where needed. Author: Justin Pryzby Discussion: https://postgr.es/m/20210210235557.GQ20012@telsasoft.com backpatch-through: 9.6
2021-02-15Default to wal_sync_method=fdatasync on FreeBSD.Thomas Munro
FreeBSD 13 gained O_DSYNC, which would normally cause wal_sync_method to choose open_datasync as its default value. That may not be a good choice for all systems, and performs worse than fdatasync in some scenarios. Let's preserve the existing default behavior for now. Like commit 576477e73c4, which did the same for Linux, back-patch to all supported releases. Discussion: https://postgr.es/m/CA%2BhUKGLsAMXBQrCxCXoW-JsUYmdOL8ALYvaX%3DCrHqWxm-nWbGA%40mail.gmail.com
2021-02-07Release notes for 13.2, 12.6, 11.11, 10.16, 9.6.21, 9.5.25.Tom Lane
2021-01-22Doc: improve directions for building on macOS.Tom Lane
In light of recent discussions, we should instruct people to install Apple's command line tools; installing Xcode is secondary. Also, fix sample command for finding out the default sysroot, as we now know that the command originally recommended can give a result that doesn't match your OS version. Also document the workaround to use if you really don't want configure to select a sysroot at all. Discussion: https://postgr.es/m/20210119111625.20435-1-james.hilliard1@gmail.com
2021-01-22Doc: remove misleading claim in documentation of PQreset().Tom Lane
This text claimed that the reconnection would occur "to the same server", but there is no such guarantee in the code, nor would insisting on that be an improvement. Back-patch to v10 where multi-host connection strings were added. Discussion: https://postgr.es/m/1095901.1611268376@sss.pgh.pa.us
2021-01-18doc: adjust alignment of doc file list for "pg_waldump.sgml"Bruce Momjian
Backpatch-through: 10
2021-01-13Doc: clarify behavior of back-half options in pg_dump.Tom Lane
Options that change how the archive data is converted to SQL text are ignored when dumping to archive formats. The documentation previously said "not meaningful", which is not helpful. Discussion: https://postgr.es/m/161052021249.12228.9598689907884726185@wrigleys.postgresql.org
2021-01-12Doc: fix description of privileges needed for ALTER PUBLICATION.Tom Lane
Adding a table to a publication requires ownership of the table (in addition to ownership of the publication). This was mentioned nowhere.
2021-01-09doc: expand description of how non-SELECT queries are processedBruce Momjian
The previous description of how the executor processes non-SELECT queries was very dense, causing lack of clarity. This expanded text spells it out more simply. Reported-by: fotis.koutoupas@gmail.com Discussion: https://postgr.es/m/160912275508.676.17469511338925622905@wrigleys.postgresql.org Backpatch-through: 9.5
2021-01-07doc: Remove reference to recovery params for divergence lookup in pg_rewindMichael Paquier
The documentation of pg_rewind mentioned the use of restore_command and primary_conninfo as options available at startup to fetch missing WAL segments that could be used to find the point of divergence for the rewind. This is confusing because when finding the point of divergence the target cluster is offline, so this option is not available. Issue introduced by 878bd9a, so backpatch down to 9.6. The documentation of 13 and HEAD was already right as this sentence has been changed by a7e8ece when introducing -c/--restore-target-wal. Reported-by: Amine Tengilimoglu Discussion: https://postgr.es/m/CADTdw-w_0MP=iQrfizeU4QU5fcZb+w8P_oPeLL+WznWf0kbn3w@mail.gmail.com Backpatch-through: 9.6
2021-01-05doc: improve NLS instruction wordingBruce Momjian
Reported-by: "Tang, Haiying" Discussion: https://postgr.es/m/bbbccf7a3c2d436e85d45869d612fd6b@G08CNEXMBPEKD05.g08.fujitsu.local Author: "Tang, Haiying" Backpatch-through: 9.5
generated by cgit v1.2.3 (git 2.46.0) at 2025-09-19 13:28:39 +0000