summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
2020-07-18doc: Fix description of \copy for psqlMichael Paquier
The WHERE clause introduced by 31f3817 was not described. While on it, split the grammar of \copy FROM and TO into two distinct parts for clarity as they support different set of options. Author: Vignesh C Discussion: https://postgr.es/m/CALDaNm3zWr=OmxeNqOqfT=uZTSdam_j-gkX94CL8eTNfgUtf6A@mail.gmail.com Backpatch-through: 12
2020-07-17Cope with data-offset-less archive files during out-of-order restores.Tom Lane
pg_dump produces custom-format archive files that lack data offsets when it is unable to seek its output. Up to now that's been a hazard for pg_restore. But if pg_restore is able to seek in the archive file, there is no reason to throw up our hands when asked to restore data blocks out of order. Instead, whenever we are searching for a data block, record the locations of the blocks we passed over (that is, fill in the missing data-offset fields in our in-memory copy of the TOC data). Then, when we hit a case that requires going backwards, we can just seek back. Also track the furthest point that we've searched to, and seek back to there when beginning a search for a new data block. This avoids possible O(N^2) time consumption, by ensuring that each data block is examined at most twice. (On Unix systems, that's at most twice per parallel-restore job; but since Windows uses threads here, the threads can share block location knowledge, reducing the amount of duplicated work.) We can also improve the code a bit by using fseeko() to skip over data blocks during the search. This is all of some use even in simple restores, but it's really significant for parallel pg_restore. In that case, we require seekability of the input already, and we will very probably need to do out-of-order restores. Back-patch to v12, as this fixes a regression introduced by commit 548e50976. Before that, parallel restore avoided requesting out-of-order restores, so it would work on a data-offset-less archive. Now it will again. Ideally this patch would include some test coverage, but there are other open bugs that need to be fixed before we can extend our coverage of parallel restore very much. Plan to revisit that later. David Gilman and Tom Lane; reviewed by Justin Pryzby Discussion: https://postgr.es/m/CALBH9DDuJ+scZc4MEvw5uO-=vRyR2=QF9+Yh=3hPEnKHWfS81A@mail.gmail.com
2020-07-15doc: Fix typoPeter Eisentraut
2020-07-13Revert "Track statistics for spilling of changes from ReorderBuffer".Amit Kapila
The stats with this commit was available only for WALSenders, however, users might want to see for backends doing logical decoding via SQL API. Then, users might want to reset and access these stats across server restart which was not possible with the current patch. List of commits reverted: caa3c4242c Don't call elog() while holding spinlock. e641b2a995 Doc: Update the documentation for spilled transaction statistics. 5883f5fe27 Fix unportable printf format introduced in commit 9290ad198. 9290ad198b Track statistics for spilling of changes from ReorderBuffer. Additionaly, remove the release notes entry for this feature. Backpatch-through: 13, where it was introduced Discussion: https://postgr.es/m/CA+fd4k5_pPAYRTDrO2PbtTOe0eHQpBvuqmCr8ic39uTNmR49Eg@mail.gmail.com
2020-07-10Doc: update or remove dead external links.Tom Lane
Re-point comp.ai.genetic FAQ link to a more stable address. Remove stale links to AIX documentation; we don't really need to tell AIX users how to use their systems. Remove stale links to HP documentation about SSL. We've had to update those twice before, making it increasingly obvious that HP does not intend them to be stable landing points. They're not particularly authoritative, either. (This change effectively reverts bbd3bdba3.) Daniel Gustafsson and Álvaro Herrera, per a gripe from Kyotaro Horiguchi. Back-patch, since these links are just as dead in the back branches. Discussion: https://postgr.es/m/20200709.161226.204639179120026914.horikyota.ntt@gmail.com
2020-07-09doc: Correct the description about the length of pg_stat_activity.query.Fujii Masao
pg_stat_activity.query text is truncated at 1024 bytes. But previously the document described that it's truncated at 1024 characters. This was not accurate when considering multibyte characters. Back-patch to v10 where this inaccurate description was added. Author: Atsushi Torikoshi Reviewed-by: Daniel Gustafsson, Fujii Masao Discussion: https://postgr.es/m/cd5b49a5a14e887542f5f569c1c6bde2@oss.nttdata.com
2020-07-08doc: Fix inconsistencies in GIN, BRIN and SP-GiST for optional opclass methodsMichael Paquier
The GIN and SP-GiST parts were out-of-sync since the changes of 14903f2, and the BRIN part was wrong since its introduction in 15cb2bd. Author: Guillaume Lelarge Reviewed-by: Daniel Gustafsson Discussion: https://postgr.es/m/CAECtzeXKvEPEr967h0PRYRi39uTmdEms=oUtc_PWGjZRNN1prw@mail.gmail.com Backpatch-through: 13
2020-07-07Morph pg_replication_slots.min_safe_lsn to safe_wal_sizeAlvaro Herrera
The previous definition of the column was almost universally disliked, so provide this updated definition which is more useful for monitoring purposes: a large positive value is good, while zero or a negative value means danger. This should be operationally more convenient. Backpatch to 13, where the new column to pg_replication_slots (and the feature it represents) were added. Author: Kyotaro Horiguchi <horikyota.ntt@gmail.com> Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Reported-by: Fujii Masao <masao.fujii@oss.nttdata.com> Discussion: https://postgr.es/m/9ddfbf8c-2f67-904d-44ed-cf8bc5916228@oss.nttdata.com
2020-07-06doc: Add note about possible performance overhead by enabling track_planning.Fujii Masao
Enabling pg_stat_statements.track_plaanning may incur a noticeable performance penalty, especially when a fewer kinds of queries are executed on many concurrent connections. This commit documents this note. Back-patch to v13 where pg_stat_statements.track_plaanning was added. Suggested-by: Pavel Stehule Author: Fujii Masao Reviewed-by: Pavel Stehule Discussion: https://postgr.es/m/CAFj8pRC9Jxa8r5i0TNBWLb8mzuaYzEoLq3QOvip0jVpHPOLbVA@mail.gmail.com
2020-07-05doc: Spell checkingPeter Eisentraut
2020-07-05doc: Fix incorrect reference to textout in plpgsql examplesMichael Paquier
This error has survived for 22 years, and has been introduced by da63386. Reported-by: Erwin Brandstetter Discussion: https://postgr.es/m/CAGHENJ57wogGOvGXo5LgWYcqswxafLck8ELqHDR+zrkTPgs_OQ@mail.gmail.com Backpatch-through: 9.5
2020-07-05Rename enable_incrementalsort for clarityPeter Eisentraut
Author: James Coleman <jtc331@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/df652910-e985-9547-152c-9d4357dc3979%402ndquadrant.com
2020-07-03Clamp total-tuples estimates for foreign tables to ensure planner sanity.Tom Lane
After running GetForeignRelSize for a foreign table, adjust rel->tuples to be at least as large as rel->rows. This prevents bizarre behavior in estimate_num_groups() and perhaps other places, especially in the scenario where rel->tuples is zero because pg_class.reltuples is (suggesting that ANALYZE has never been run for the table). As things stood, we'd end up estimating one group out of any GROUP BY on such a table, whereas the default group-count estimate is more likely to result in a sane plan. Also, clarify in the documentation that GetForeignRelSize has the option to override the rel->tuples value if it has a better idea of what to use than what is in pg_class.reltuples. Per report from Jeff Janes. Back-patch to all supported branches. Patch by me; thanks to Etsuro Fujita for review Discussion: https://postgr.es/m/CAMkU=1xNo9cnan+Npxgz0eK7394xmjmKg-QEm8wYG9P5-CcaqQ@mail.gmail.com
2020-07-03doc: Correct description of restart_lsn in pg_replication_slotsFujii Masao
Previously the document explained that restart_lsn indicates the LSN of oldest WAL won't be automatically removed during checkpoints. But since v13 this was no longer true thanks to max_slot_wal_keep_size. Back-patch to v13 where max_slot_wal_keep_size was added. Author: Fujii Masao Discussion: https://postgr.es/m/6497f1e9-3148-c5da-7e49-b2fddad9a42f@oss.nttdata.com
2020-07-03Change default of pg_stat_statements.track_planning to off.Fujii Masao
Since v13 pg_stat_statements is allowed to track the planning time of statements when track_planning option is enabled. Its default was on. But this feature could cause more terrible spinlock contentions in pg_stat_statements. As a result of this, Robins Tharakan reported that v13 beta1 showed ~45% performance drop at high DB connection counts (when compared with v12.3) during fully-cached SELECT-only test using pgbench. To avoid this performance regression by the default setting, this commit changes default of pg_stat_statements.track_planning to off. Back-patch to v13 where pg_stat_statements.track_planning was introduced. Reported-by: Robins Tharakan Author: Fujii Masao Reviewed-by: Julien Rouhaud Discussion: https://postgr.es/m/2895b53b033c47ccb22972b589050dd9@EX13D05UWC001.ant.amazon.com
2020-06-30doc: clarify that storage parameter values are optionalBruce Momjian
In a few cases, the documented syntax specified storage parameter values as required. Reported-by: galiev_mr@taximaxim.ru Discussion: https://postgr.es/m/159283163235.684.4482737698910467437@wrigleys.postgresql.org Backpatch-through: 9.5
2020-06-30doc: change pg_upgrade wal_level to be not minimalBruce Momjian
Previously it was specified to be only replica. Discussion: https://postgr.es/m/20200618180058.GK7349@momjian.us Backpatch-through: 9.5
2020-06-29Remove support for timezone "posixrules" file.Tom Lane
The IANA tzcode library has a feature to read a time zone file named "posixrules" and apply the daylight-savings transition dates and times therein, when it is given a POSIX-style time zone specification that lacks an explicit transition rule. However, there's a problem with that code: it doesn't work for dates past the Y2038 time_t rollover. (Effectively, all times beyond that point are treated as standard time.) The IANA crew regard this feature as legacy, so their plan is to remove it not fix it. The time frame in which that will happen is unclear, but presumably it'll happen well before 2038. Moreover, effective with the next IANA data update (probably this fall), the recommended default will be to not install a "posixrules" file in the first place. The time frame in which tzdata packagers might adopt that suggestion is likewise unclear, but at least some platforms will probably do it in the next year or so. While we could ignore that recommendation so far as PG-supplied tzdata trees are concerned, builds using --with-system-tzdata will be subject to whatever the platform's tzdata packager decides to do. Thus, whether or not we do anything, some increasing fraction of Postgres users will be exposed to the behavior observed when there is no "posixrules" file; and if we do nothing, we'll have essentially no control over the timing of that change. The best thing to do to ameliorate the uncertainty seems to be to proactively remove the posixrules-reading feature. If we do that in a scheduled release then at least we can release-note the behavioral change, rather than having users be surprised by it after a routine tzdata update. The change in question is fairly minor anyway: to be affected, you have to be using a POSIX-style timezone spec, it has to not have an explicit rule, and it has to not be one of the four traditional continental-USA zone names (EST5EDT, CST6CDT, MST7MDT, or PST8PDT), as those are special-cased. Since the default "posixrules" file provides USA DST rules, the number of people who are likely to find such a zone spec useful is probably quite small. Moreover, the fallback behavior with no explicit rule and no "posixrules" file is to apply current USA rules, so the only thing that really breaks is the DST transitions in years before 2007 (and you get the countervailing fix that transitions after 2038 will be applied). Now, some installations might have replaced the "posixrules" file, allowing e.g. EU rules to be applied to a POSIX-style timezone spec. That won't work anymore. But it's not exactly clear why this solution would be preferable to using a regular named zone. In any case, given the Y2038 issue, we need to be pushing users to stop depending on this. Back-patch into v13; it hasn't been released yet, so it seems OK to change its behavior. (Personally I think we ought to back-patch further, but I've been outvoted.) Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us Discussion: https://postgr.es/m/20200621211855.6211-1-eggert@cs.ucla.edu
2020-06-27Fix documentation of "must be vacuumed within" warning.Noah Misch
Warnings start 10M transactions before xidStopLimit, which is 11M transactions before wraparound. The sample WARNING output showed a value greater than 11M, and its HINT message predated commit 25ec228ef760eb91c094cc3b6dea7257cc22ffb5. Hence, the sample was impossible. Back-patch to 9.5 (all supported versions).
2020-06-27Change libpq's default ssl_min_protocol_version to TLSv1.2.Tom Lane
When we initially created this parameter, in commit ff8ca5fad, we left the default as "allow any protocol version" on grounds of backwards compatibility. However, that's inconsistent with the backend's default since b1abfec82; protocol versions prior to 1.2 are not considered very secure; and OpenSSL has had TLSv1.2 support since 2012, so the number of PG servers that need a lesser minimum is probably quite small. On top of those things, it emerges that some popular distros (including Debian and RHEL) set MinProtocol=TLSv1.2 in openssl.cnf. Thus, far from having "allow any protocol version" behavior in practice, what we actually have as things stand is a platform-dependent lower limit. So, change our minds and set the min version to TLSv1.2. Anybody wanting to connect with a new libpq to a pre-2012 server can either set ssl_min_protocol_version=TLSv1 or accept the fallback to non-SSL. Back-patch to v13 where the aforementioned patches appeared. Patch by me, reviewed by Daniel Gustafsson Discussion: https://postgr.es/m/a9408304-4381-a5af-d259-e55d349ae4ce@2ndquadrant.com
2020-06-26doc: PG 13 relnotes; remove FOREIGN keyword item and clarifyBruce Momjian
Clarify --include-foreign-data option addition. Reported-by: Masahiko Sawada, Alvaro Herrera Discussion: https://postgr.es/m/CA+fd4k62hYtce8VrEMGm6Y+1c24QBgCksXvOaH5kE8PbY+68sA@mail.gmail.com Backpatch-through: 13 only
2020-06-26Doc: explain that "timestamp - timestamp" applies justify_hours().Tom Lane
Back-patch to v13; before that, there's not really space for this kind of detail. Discussion: https://postgr.es/m/c1696f68-fa8d-7759-6a9c-eb293ab1bbc9@gmx.net
2020-06-25doc: mention trigger helper functions in CREATE TRIGGER docsBruce Momjian
Reported-by: petermpallesen@gmail.com Discussion: https://postgr.es/m/159195294959.673.5752624528747900508@wrigleys.postgresql.org Backpatch-through: 9.5
2020-06-25docs: clarify that CREATE DATABASE does not copy db permissionsBruce Momjian
That is, those database permissions set by GRANT. Diagnosed-by: Joseph Nahmias Discussion: https://postgr.es/m/20200614072613.GA21852@nahmias.net Backpatch-through: 9.5
2020-06-25Doc: correct nitpicky mistakes in array_position/array_positions examples.Tom Lane
Daniel Gustafsson and Erik Rijkers, per report from nick@cleaton Discussion: https://postgr.es/m/159275646273.679.16940709892308114570@wrigleys.postgresql.org
2020-06-24Adjust max_slot_wal_keep_size behavior per reviewAlvaro Herrera
In pg_replication_slot, change output from normal/reserved/lost to reserved/extended/unreserved/ lost, which better expresses the possible states particularly near the time where segments are no longer safe but checkpoint has not run yet. Under the new definition, reserved means the slot is consuming WAL that's still under the normal WAL size constraints; extended means it's consuming WAL that's being protected by wal_keep_segments or the slot itself, whose size is below max_slot_wal_keep_size; unreserved means the WAL is no longer safe, but checkpoint has not yet removed those files. Such as slot is in imminent danger, but can still continue for a little while and may catch up to the reserved WAL space. Also, there were some bugs in the calculations used to report the status; fixed those. Backpatch to 13. Reported-by: Fujii Masao <masao.fujii@oss.nttdata.com> Author: Kyotaro Horiguchi <horikyota.ntt@gmail.com> Reviewed-by: Fujii Masao <masao.fujii@oss.nttdata.com> Reviewed-by: Álvaro Herrera <alvherre@alvh.no-ip.org> Discussion: https://postgr.es/m/20200616.120236.1809496990963386593.horikyota.ntt@gmail.com
2020-06-22Doc fixup for hashagg_avoid_disk_plan GUC.Jeff Davis
Reported-by: Justin Pryzby Discussion: https://postgr.es/m/20200620220402.GZ17995@telsasoft.com Backport-through: 13
2020-06-21Language fixes for docs related to opclass optionsAlexander Korotkov
Discussion: https://postgr.es/m/20200620232145.GB17995%40telsasoft.com Author: Justin Pryzby Backpatch-through: 13
2020-06-20Doc: Tweak description of B-Tree duplicate tuples.Peter Geoghegan
Defining duplicates as "close by" to each other was unclear. Simplify the definition. Backpatch: 13-, where deduplication was introduced (by commit 0d861bbb)
2020-06-21Minor corrections to docs related to opclass optionsAlexander Korotkov
Reported-by: Peter Geoghegan Discussion: https://postgr.es/m/CAH2-WzmwhYbxuoL0WjTLaiCxW3gj6qadeNpBhWAo_KZsE5-FGw%40mail.gmail.com
2020-06-20Add documentation for opclass optionsAlexander Korotkov
911e7020770 added opclass options and adjusted documentation for each particular affected opclass. However, documentation for extendability was not adjusted. This commit adjusts documentation for interfaces of index AMs and opclasses. Discussion: https://postgr.es/m/CAH2-WzmQnW6%2Bz5F9AW%2BSz%2BzEcEvXofTwh_A9J3%3D_WA-FBP0wYg%40mail.gmail.com Author: Alexander Korotkov Reported-by: Peter Geoghegan Reviewed-by: Peter Geoghegan
2020-06-19Future-proof regression tests against possibly-missing posixrules file.Tom Lane
The IANA time zone folk have deprecated use of a "posixrules" file in the tz database. While for now it's our choice whether to keep supplying one in our own builds, installations built with --with-system-tzdata will soon be needing to cope with that file not being present, at least on some platforms. This causes a problem for the horology test, which expected the nonstandard POSIX zone spec "CST7CDT" to apply pre-2007 US daylight savings rules. That does happen if the posixrules file supplies such information, but otherwise the test produces undesired results. To fix, add an explicit transition date rule that matches 2005 practice. (We could alternatively have switched the test to use some real time zone, but it seems useful to have coverage of this type of zone spec.) While at it, update a documentation example that also relied on "CST7CDT"; use a real-world zone name instead. Also, document why the zone names EST5EDT, CST6CDT, MST7MDT, PST8PDT aren't subject to similar failures when "posixrules" is missing. Back-patch to all supported branches, since the hazard is the same for all. Discussion: https://postgr.es/m/1665379.1592581287@sss.pgh.pa.us
2020-06-19Adjust some glossary termsAlvaro Herrera
Mostly in response to Jürgen Purtz critique of previous definitions, though I added many other changes. Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Reviewed-by: Jürgen Purtz <juergen@purtz.de> Reviewed-by: Justin Pryzby <pryzby@telsasoft.com> Reviewed-by: Erik Rijkers <er@xs4all.nl> Discussion: https://postgr.es/m/c1e06008-2132-30f4-9b38-877e8683d418@purtz.de
2020-06-18Doc: document POSIX-style time zone specifications in full.Tom Lane
We'd glossed over most of this complexity for years, but it's hard to avoid writing it all down now, so that we can explain what happens when there's no "posixrules" file in the IANA time zone database. That was at best a tiny minority situation till now, but it's likely to become quite common in the future, so we'd better explain it. Nonetheless, we don't really encourage people to use POSIX zone specs; picking a named zone is almost always what you really want, unless perhaps you're stuck with an out-of-date zone database. Therefore, let's shove all this detail into an appendix. Patch by me; thanks to Robert Haas for help with some awkward wording. Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us
2020-06-18doc: Fix formatting typoPeter Eisentraut
2020-06-16Doc: fix copy-and-pasteo in ecpg docs.Tom Lane
The synopsis for PGTYPESinterval_free() used the wrong name. Discussion: https://postgr.es/m/159231203030.679.3061023914894071953@wrigleys.postgresql.org
2020-06-15Doc: Add references for SI and SSI.Thomas Munro
Our documentation failed to point out that REPEATABLE READ is really snapshot isolation, which might be important to some users. Point to the standard reference paper for this complicated topic. Likewise, add a reference to the VLDB paper about PostgreSQL SSI, for technical information about our SSI implementation and how it compares to S2PL. While here, add a note about catalog access using a lower isolation level, per recent user complaint. Back-patch to all releases. Reported-by: Kyle Kingsbury <aphyr@jepsen.io> Reviewed-by: Andres Freund <andres@anarazel.de> Reviewed-by: Peter Geoghegan <pg@bowt.ie> Reviewed-by: Tatsuo Ishii <ishii@sraoss.co.jp> Discussion: https://postgr.es/m/db7b729d-0226-d162-a126-8a8ab2dc4443%40jepsen.io Discussion: https://postgr.es/m/16454-9408996bb1750faf%40postgresql.org
2020-06-11doc: remove xreflabels used in PG 13 relnotesBruce Momjian
xreflabels were removed in a previous commit Discussion: https://postgr.es/m/8315c0ca-7758-8823-fcb6-f37f9413e6b6@2ndquadrant.com Backpatch-through: 13 only
2020-06-11doc: remove xreflabels from commits 75fcdd2ae2 and 85af628da5Bruce Momjian
xreflabels prevent references to the chapter numbers of sections id's. It should only be used in specific cases. Discussion: https://postgr.es/m/8315c0ca-7758-8823-fcb6-f37f9413e6b6@2ndquadrant.com Backpatch-through: 9.5
2020-06-11Fix doc build, broken by 13e0fa7a.Jeff Davis
Reported-by: Peter Geoghegan
2020-06-11Rework HashAgg GUCs.Jeff Davis
Eliminate enable_groupingsets_hash_disk, which was primarily useful for testing grouping sets that use HashAgg and spill. Instead, hack the table stats to convince the planner to choose hashed aggregation for grouping sets that will spill to disk. Suggested by Melanie Plageman. Rename enable_hashagg_disk to hashagg_avoid_disk_plan, and invert the meaning of on/off. The new name indicates more strongly that it only affects the planner. Also, the word "avoid" is less definite, which should avoid surprises when HashAgg still needs to use the disk. Change suggested by Justin Pryzby, though I chose a different GUC name. Discussion: https://postgr.es/m/CAAKRu_aisiENMsPM2gC4oUY1hHG3yrCwY-fXUg22C6_MJUwQdA%40mail.gmail.com Discussion: https://postgr.es/m/20200610021544.GA14879@telsasoft.com Backpatch-through: 13
2020-06-08Doc: Update example symptom of systemd misconfiguration.Thomas Munro
In PostgreSQL 10, we stopped using System V semaphores on Linux systems. Update the example we give of an error message from a misconfigured system to show what people are most likely to see these days. Back-patch to 10, where PREFERRED_SEMAPHORES=UNNAMED_POSIX arrived. Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us> Discussion: https://postgr.es/m/CA%2BhUKGLmJUSwybaPQv39rB8ABpqJq84im2UjZvyUY4feYhpWMw%40mail.gmail.com
2020-06-07Spelling adjustmentsPeter Eisentraut
2020-06-07doc: Fix man page whitespace issuesPeter Eisentraut
Whitespace between tags is significant, and in some cases it creates extra vertical space in man pages. The fix is either to remove some newlines or in some cases to reword slightly to avoid the awkward markup layout.
2020-06-07doc: Move options on man pages into more alphabetical orderPeter Eisentraut
2020-06-07doc: Fix up spacing around verbatim DocBook elementsPeter Eisentraut
2020-06-07doc: Language reviewPeter Eisentraut
2020-06-07doc: Trim trailing whitespacePeter Eisentraut
2020-06-07doc: Clean up title case usePeter Eisentraut
2020-06-07doc: Remove line breaks after <title>Peter Eisentraut
This creates unnecessary rendering problem risks, and it's inconsistent and gets copied around.
generated by cgit v1.2.3 (git 2.46.0) at 2025-09-09 19:31:07 +0000