summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
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
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 backpatch 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-10Doc: B-Tree only has one additional parameter.Peter Geoghegan
Oversight in commit 9f3665fb. Backpatch: 13-, just like commit 9f3665fb.
2021-03-10Don't consider newly inserted tuples in nbtree VACUUM.Peter Geoghegan
Remove the entire idea of "stale stats" within nbtree VACUUM (stop caring about stats involving the number of inserted tuples). Also remove the vacuum_cleanup_index_scale_factor GUC/param on the master branch (though just disable them on postgres 13). The vacuum_cleanup_index_scale_factor/stats interface made the nbtree AM partially responsible for deciding when pg_class.reltuples stats needed to be updated. This seems contrary to the spirit of the index AM API, though -- it is not actually necessary for an index AM's bulk delete and cleanup callbacks to provide accurate stats when it happens to be inconvenient. The core code owns that. (Index AMs have the authority to perform or not perform certain kinds of deferred cleanup based on their own considerations, such as page deletion and recycling, but that has little to do with pg_class.reltuples/num_index_tuples.) This issue was fairly harmless until the introduction of the autovacuum_vacuum_insert_threshold feature by commit b07642db, which had an undesirable interaction with the vacuum_cleanup_index_scale_factor mechanism: it made insert-driven autovacuums perform full index scans, even though there is no real benefit to doing so. This has been tied to a regression with an append-only insert benchmark [1]. Also have remaining cases that perform a full scan of an index during a cleanup-only nbtree VACUUM indicate that the final tuple count is only an estimate. This prevents vacuumlazy.c from setting the index's pg_class.reltuples in those cases (it will now only update pg_class when vacuumlazy.c had TIDs for nbtree to bulk delete). This arguably fixes an oversight in deduplication-related bugfix commit 48e12913. [1] https://smalldatum.blogspot.com/2021/01/insert-benchmark-postgres-is-still.html Author: Peter Geoghegan <pg@bowt.ie> Reviewed-By: Masahiko Sawada <sawada.mshk@gmail.com> Discussion: https://postgr.es/m/CAD21AoA4WHthN5uU6+WScZ7+J_RcEjmcuH94qcoUPuB42ShXzg@mail.gmail.com Backpatch: 13-, where autovacuum_vacuum_insert_threshold was added.
2021-03-10Doc: improve introductory information about procedures.Tom Lane
Clarify the discussion in "User-Defined Procedures", by laying out the key differences between functions and procedures in a bulleted list. Notably, this avoids burying the lede about procedures being able to do transaction control. Make the back-link in the CREATE FUNCTION reference page more prominent, and add one in CREATE PROCEDURE. Per gripe from Guyren Howe. Thanks to David Johnston for discussion. Discussion: https://postgr.es/m/BYAPR03MB4903C53A8BB7EFF5EA289674A6949@BYAPR03MB4903.namprd03.prod.outlook.com
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-25doc: Mention PGDATABASE as supported by pgbenchMichael Paquier
PGHOST, PGPORT and PGUSER were already mentioned, but not PGDATABASE. Like 5aaa584, backpatch down to 12. Reported-by: Christophe Courtois Discussion: https://postgr.es/m/161399398648.21711.15387267201764682579@wrigleys.postgresql.org Backpatch-through: 12
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-22Fix docs build for website stylesMagnus Hagander
Building the docs with STYLE=website referenced a stylesheet that long longer exists on the website, since we changed it to use versioned references. To make it less likely for this to happen again, point to a single stylesheet on the website which will in turn import the required one. That puts the process entirely within the scope of the website repository, so next time a version is switched that's the only place changes have to be made, making them less likely to be missed. Per (off-list) discussion with Peter Geoghegan and Jonathan Katz.
2021-02-17Fix typoMagnus Hagander
Author: Daniel Gustafsson <daniel@yesql.se> Discussion: https://postgr.es/m/0CF087FC-BEAD-4010-8BB9-3CDD74DC9060@yesql.se
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-13doc: Mention NO DEPENDS ON EXTENSION in its supported ALTER commandsMichael Paquier
This grammar flavor has been added by 5fc7039. Author: Ian Lawrence Barwick Discussion: https://postgr.es/m/CAB8KJ=ii6JScodxkA6-DO8bjatsMYU3OcewnL0mdN9geR+tTaw@mail.gmail.com Backpatch-through: 13
2021-02-08Last-minute updates for release notes.Tom Lane
Security: CVE-2021-3393, CVE-2021-20229
2021-02-07Release notes for 13.2, 12.6, 11.11, 10.16, 9.6.21, 9.5.25.Tom Lane
2021-02-07Docs: fix pg_wal_lsn_diff manual.Tatsuo Ishii
The manual did not mention whether its return value is (first arg - second arg) or (second arg - first arg). The order matters because the return value could have a sign. Fix the manual so that it mentions the function returns (first arg - second arg). Patch reviewed by Tom Lane. Back-patch through v13. Older version's doc format is difficult to add more description. Discussion: https://postgr.es/m/flat/20210206.151125.960423226279810864.t-ishii%40sraoss.co.jp
2021-02-05First-draft release notes for 13.2.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.
2021-02-01Doc: work a little harder on the initial examples for regex matching.Tom Lane
Writing unnecessary '.*' at start and end of a POSIX regex doesn't do much except confuse the reader about whether that might be necessary after all. Make the examples in table 9.16 a tad more realistic, and try to turn the next group of examples into something self-contained. Per gripe from rmzgrimes. Back-patch to v13 because it's easy. Discussion: https://postgr.es/m/161215841824.14653.8969016349304314299@wrigleys.postgresql.org
2021-01-29Doc: improve cross-references for SET/SHOW.Tom Lane
The corresponding functions set_config and current_setting were mostly not hyperlinked. Clarify their descriptions a tad, too. Discussion: https://postgr.es/m/161183356250.4077.687338658090583892@wrigleys.postgresql.org
2021-01-29Document behavior of the .** jsonpath accessor in the lax modeAlexander Korotkov
When the .** jsonpath accessor handles the array, it selects both array and each of its elements. When using lax mode, subsequent accessors automatically unwrap arrays. So, the content of each array element may be selected twice. Even though this behavior is counterintuitive, it's correct because everything works as designed. This commit documents it. Backpatch to 12 where the jsonpath language was introduced. Reported-by: Thomas Kellerer Bug: #16828 Discussion: https://postgr.es/m/16828-2b0229babfad2d8c%40postgresql.org Discussion: https://postgr.es/m/CAPpHfdtS-nNidT%3DEqZbAYOPcnNOWh_sd6skVdu2CAQUGdvpT8Q%40mail.gmail.com Author: Alexandex Korotkov, revised by Tom Lane Reviewed-by: Alvaro Herrera, Thomas Kellerer, Tom Lane Backpatch-through: 12
2021-01-28Remove bogus restriction from BEFORE UPDATE triggersAlvaro Herrera
In trying to protect the user from inconsistent behavior, commit 487e9861d0cf "Enable BEFORE row-level triggers for partitioned tables" tried to prevent BEFORE UPDATE FOR EACH ROW triggers from moving the row from one partition to another. However, it turns out that the restriction is wrong in two ways: first, it fails spuriously, preventing valid situations from working, as in bug #16794; and second, they don't protect from any misbehavior, because tuple routing would cope anyway. Fix by removing that restriction. We keep the same restriction on BEFORE INSERT FOR EACH ROW triggers, though. It is valid and useful there. In the future we could remove it by having tuple reroute work for inserts as it does for updates. Backpatch to 13. Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Reported-by: Phillip Menke <pg@pmenke.de> Discussion: https://postgr.es/m/16794-350a655580fbb9ae@postgresql.org
2021-01-27Doc: improve documentation for UNNEST().Tom Lane
Per a user question, spell out that UNNEST() returns array elements in storage order; also provide an example to clarify the behavior for multi-dimensional arrays. While here, also clarify the SELECT reference page's description of WITH ORDINALITY. These details were already given in 7.2.1.4, but a reference page should not omit details. Back-patch to v13; there's not room in the table in older versions. Discussion: https://postgr.es/m/FF1FB31F-0507-4F18-9559-2DE6E07E3B43@gmail.com
2021-01-27doc: Remove reference to views for TRUNCATE privilegeMichael Paquier
The page about privilege rights mentioned that TRUNCATE could be applied to views or even other relation types. This is confusing as this command can be used only on tables and on partitioned tables. Oversight in afc4a78. Reported-by: Harisai Hari Reviewed-by: Laurenz Albe Discussion: https://postgr.es/m/161157636877.14625.15340884663716426087@wrigleys.postgresql.org Backpatch-through: 12
2021-01-25Doc: improve documentation of pg_proc.protrftypes.Tom Lane
Add a "references" link pointing to pg_type, as we have for other arrays of type OIDs. Wordsmith the explanation a bit. Joel Jacobson, additional editing by me Discussion: https://postgr.es/m/d1cc628c-3953-4209-957b-29427acc38c8@www.fastmail.com
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-14Prevent drop of tablespaces used by partitioned relationsAlvaro Herrera
When a tablespace is used in a partitioned relation (per commits ca4103025dfe in pg12 for tables and 33e6c34c3267 in pg11 for indexes), it is possible to drop the tablespace, potentially causing various problems. One such was reported in bug #16577, where a rewriting ALTER TABLE causes a server crash. Protect against this by using pg_shdepend to keep track of tablespaces when used for relations that don't keep physical files; we now abort a tablespace if we see that the tablespace is referenced from any partitioned relations. Backpatch this to 11, where this problem has been latent all along. We don't try to create pg_shdepend entries for existing partitioned indexes/tables, but any ones that are modified going forward will be protected. Note slight behavior change: when trying to drop a tablespace that contains both regular tables as well as partitioned ones, you'd previously get ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE and now you'll get ERRCODE_DEPENDENT_OBJECTS_STILL_EXIST. Arguably, the latter is more correct. It is possible to add protecting pg_shdepend entries for existing tables/indexes, by doing ALTER TABLE ONLY some_partitioned_table SET TABLESPACE pg_default; ALTER TABLE ONLY some_partitioned_table SET TABLESPACE original_tablespace; for each partitioned table/index that is not in the database default tablespace. Because these partitioned objects do not have storage, no file needs to be actually moved, so it shouldn't take more time than what's required to acquire locks. This query can be used to search for such relations: SELECT ... FROM pg_class WHERE relkind IN ('p', 'I') AND reltablespace <> 0 Reported-by: Alexander Lakhin <exclusion@gmail.com> Discussion: https://postgr.es/m/16577-881633a9f9894fd5@postgresql.org Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Reviewed-by: Michael Paquier <michael@paquier.xyz>
2021-01-13Call out vacuum considerations in create index docsAlvaro Herrera
Backpatch to pg12, which is as far as it goes without conflicts. Author: James Coleman <jtc331@gmail.com> Reviewed-by: "David G. Johnston" <david.g.johnston@gmail.com> Discussion: https://postgr.es/m/CAAaqYe9oEfbz7AxXq7OX+FFVi5w5p1e_Of8ON8ZnKO9QqBfmjg@mail.gmail.com
2021-01-13Disallow a digit as the first character of a variable name in pgbench.Tom Lane
The point of this restriction is to avoid trying to substitute variables into timestamp literal values, which may contain strings like '12:34'. There is a good deal more that should be done to reduce pgbench's tendency to substitute where it shouldn't. But this is sufficient to solve the case complained of by Jaime Soler, and it's simple enough to back-patch. Back-patch to v11; before commit 9d36a3866, pgbench had a slightly different definition of what a variable name is, and anyway it seems unwise to change long-stable branches for this. Fabien Coelho Discussion: https://postgr.es/m/alpine.DEB.2.22.394.2006291740420.805678@pseudo
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-13Remove incorrect markupMagnus Hagander
Seems 737d69ffc3c made a copy/paste or automation error resulting in two extra right-parenthesis. Reported-By: Michael Vastola Backpatch-through: 13 Discussion: https://postgr.es/m/161051035421.12224.1741822783166533529@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-06doc: Fix description about default behavior of recovery_target_timeline.Fujii Masao
The default value of recovery_target_timeline was changed in v12, but the description about the default behavior of that was not updated. Back-patch to v12 where the default behavior of recovery_target_timeline was changed. Author: Benoit Lobréau Reviewed-by: Fujii Masao Discussion: https://postgr.es/m/CAPE8EZ7c3aruEmM24GYkj8y8WmHKD1m9TtPtgCF0nQ3zw4LCkQ@mail.gmail.com
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
2021-01-02Update copyright for 2021Bruce Momjian
Backpatch-through: 9.5
2021-01-01Doc: improve explanation of EXTRACT(EPOCH) for timestamp without tz.Tom Lane
Try to be clearer about what computation is actually happening here. Per bug #16797 from Dana Burd. Discussion: https://postgr.es/m/16797-f264b0b980b53b8b@postgresql.org
2020-12-30Doc: spell out comparison behaviors for the date/time types.Tom Lane
The behavior of cross-type comparisons among date/time data types was not really explained anywhere. You could probably infer it if you recognized the applicability of comments elsewhere about datatype conversions, but it seems worthy of explicit documentation. Per bug #16797 from Dana Burd. Discussion: https://postgr.es/m/16797-f264b0b980b53b8b@postgresql.org
2020-12-30Fix up usage of krb_server_keyfile GUC parameter.Tom Lane
secure_open_gssapi() installed the krb_server_keyfile setting as KRB5_KTNAME unconditionally, so long as it's not empty. However, pg_GSS_recvauth() only installed it if KRB5_KTNAME wasn't set already, leading to a troubling inconsistency: in theory, clients could see different sets of server principal names depending on whether they use GSSAPI encryption. Always using krb_server_keyfile seems like the right thing, so make both places do that. Also fix up secure_open_gssapi()'s lack of a check for setenv() failure --- it's unlikely, surely, but security-critical actions are no place to be sloppy. Also improve the associated documentation. This patch does nothing about secure_open_gssapi()'s use of setenv(), and indeed causes pg_GSS_recvauth() to use it too. That's nominally against project portability rules, but since this code is only built with --with-gssapi, I do not feel a need to do something about this in the back branches. A fix will be forthcoming for HEAD though. Back-patch to v12 where GSSAPI encryption was introduced. The dubious behavior in pg_GSS_recvauth() goes back further, but it didn't have anything to be inconsistent with, so let it be. Discussion: https://postgr.es/m/2187460.1609263156@sss.pgh.pa.us
generated by cgit v1.2.3 (git 2.46.0) at 2025-10-26 11:24:15 +0000