summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
2024-04-24Doc: fix minor oversight in ALTER DEFAULT PRIVILEGES ref page.Tom Lane
Since schemas have more than one kind of privilege, we should use the synopsis form that shows the privilege being possibly repeated. Yugo Nagata Discussion: https://postgr.es/m/20240424155052.7ac0d0773e4ae27ab723faea@sraoss.co.jp
2024-04-24doc: Correct jsonpath string literal escapes descriptionPeter Eisentraut
The paragraph describing the JavaScript string literals allowed in jsonpath expressions unnecessarily mentions JSON by erroneously listing \v as allowed by JSON and mentioning the \xNN and \u{N...} backslash escapes as deviations from JSON when in fact both are accepted by ECMAScript/JavaScript. Fix this by only referring to JavaScript. Author: Erik Wienhold <ewie@ewie.name> Discussion: https://www.postgresql.org/message-id/flat/1EB17DF9-2636-484B-9DD0-3CAB19C4F5C4@justatheory.com
2024-04-20Doc: document cases where queryid is stableDavid Rowley
The documents were clear that queryid should not be assumed to be stable between major versions but said nothing about minor versions and left the reader to guess if that was implied by the mention of the instability of queryid between major versions. Here we give minor versions an explicit mention to indicate queryid can generally be assumed stable between minor versions. Reviewed-by: Michael Paquier Discussion: https://postgr.es/m/CAApHDvpYGE6h0cD9UO-eHySPynPj1L3J%3DHxT%2BA7Ud8_Yo6AuzA%40mail.gmail.com Backpatch-through: 12
2024-04-16Fix assorted bugs in ecpg's macro mechanism.Tom Lane
The code associated with EXEC SQL DEFINE was unreadable and full of bugs, notably: * It'd attempt to free a non-malloced string if the ecpg program tries to redefine a macro that was defined on the command line. * Possible memory stomp if user writes "-D=foo". * Undef'ing or redefining a macro defined on the command line would change the state visible to the next file, when multiple files are specified on the command line. (While possibly that could have been an intentional choice, the code clearly intends to revert to the original macro state; it's just failing to consider this interaction.) * Missing "break" in defining a new macro meant that redefinition of an existing name would cause an extra entry to be added to the definition list. While not immediately harmful, a subsequent undef would result in the prior entry becoming visible again. * The interactions with input buffering are subtle and were entirely undocumented. It's not that surprising that we hadn't noticed these bugs, because there was no test coverage at all of either the -D command line switch or multiple input files. This patch adds such coverage (in a rather hacky way I guess). In addition to the code bugs, the user documentation was confused about whether the -D switch defines a C macro or an ecpg one, and it failed to mention that you can write "-Dsymbol=value". These problems are old, so back-patch to all supported branches. Discussion: https://postgr.es/m/998011.1713217712@sss.pgh.pa.us
2024-04-11Doc: fix bogus to_date() examples.Tom Lane
November doesn't have 31 days. Remarkably, this thinko has escaped detection since commit 3f1998727. Noted by Y. Saburov. Discussion: https://postgr.es/m/171276122213.681.531905738590773705@wrigleys.postgresql.org
2024-04-10Doc: Update ulinks to RFC documents to avoid redirectDaniel Gustafsson
The tools.ietf.org site has been decommissioned and replaced by a number of sites serving various purposes. Links to RFCs and BCPs are now 301 redirected to their new respective IETF sites. Since this serves no purpose and only adds network overhead, update our links to the new locations. Backpatch to all supported versions. Discussion: https://postgr.es/m/3C1CEA99-FCED-447D-9858-5A579B4C6687@yesql.se Backpatch-through: v12
2024-04-09doc: Remove stray comma from list of psql optionsDaniel Gustafsson
Back in 7.2 the list of options had short options and long options on the same line separated by comma, but since 7.3 they are listed separate lines. The comma on -X was left behind so fix by removing and backpatching all the way. Reported-by: y.saburov@gmail.com Discussion: https://postgr.es/m/171267154345.684.7212826057932148541@wrigleys.postgresql.org Backpatch-through: v12
2024-04-07Doc: update documentation about EXCLUDE constraint elements.Tom Lane
What the documentation calls an exclude_element is an index_elem according to gram.y, and it allows all the same options that a CREATE INDEX column specification does. The COLLATE patch neglected to update the CREATE/ALTER TABLE docs about that, and later the opclass-parameters patch made the same oversight. Add those options to the syntax synopses, and polish the associated text a bit. Back-patch to v13 where opclass parameters came in. We could update v12 with just the COLLATE omission, but it doesn't quite seem worth the trouble at this point. Shihao Zhong, reviewed by Daniel Vérité, Shubham Khanna and myself Discussion: https://postgr.es/m/CAGRkXqShbVyB8E3gapfdtuwiWTiK=Q67Qb9qwxu=+-w0w46EBA@mail.gmail.com
2024-03-20Review wording on tablespaces w.r.t. partitioned tablesAlvaro Herrera
Remove a redundant comment, and document pg_class.reltablespace properly in catalogs.sgml. After commits a36c84c3e4a9, 87259588d0ab and others. Backpatch to 12. Discussion: https://postgr.es/m/202403191013.w2kr7wqlamqz@alvherre.pgsql
2024-03-11doc: add missing word "the"Bruce Momjian
Reported-by: doughale@gmail.com Discussion: https://postgr.es/m/170993253510.640.5664117187431542912@wrigleys.postgresql.org Backpatch-through: 12
2024-02-25Doc: fix minor typos in two ECPG function descriptions.Tom Lane
Noted by Aidar Imamov. Discussion: https://postgr.es/m/170869935022.643.3709087848818148291@wrigleys.postgresql.org
2024-02-20Doc: improve explanation of type interval, especially extract().Tom Lane
The explanation of interval's behavior in datatype.sgml wasn't wrong exactly, but it was unclear, partly because it buried the lede about there being three internal fields. Rearrange and wordsmith for more clarity. The discussion of extract() claimed that input of type date was handled by casting, but actually there's been a separate SQL function taking date for a very long time. Also, it was mostly silent about how interval inputs are handled, but there are several field types for which it seems useful to be specific. Improve discussion of justify_days()/justify_hours() too. In passing, remove vertical space in some groups of examples, as there was little consistency about whether to have such space or not. (I only did this within the datetime functions section; there are some related inconsistencies elsewhere.) Per discussion of bug #18348 from Michael Bondarenko. There may be some code changes coming out of that discussion too, but we likely won't back-patch them. This docs-only patch seems useful to back-patch, though I only carried it back to v13 because it didn't apply easily in v12. Discussion: https://postgr.es/m/18348-b097a3587dfde8a4@postgresql.org
2024-02-19Doc: fix typo in SECURITY LABEL synopsis.Tom Lane
One case missed its trailing "|". Reported by Tim Needham. Discussion: https://postgr.es/m/170833547220.3279712.700702770281879175@wrigleys.postgresql.org
2024-02-14doc: Remove links to further reading from pgcrypto docsDaniel Gustafsson
The pgcrypto docs contained a set of links for useful reading and technical references. These sets of links were however not actively curated and had stale content and dead links. Rather than investing time into maintining these, this removes them altogether since there are lots of resources online which are actively maintained. Backpatch to all supported versions since these links have been in the docs for a long time. Reported-by: Hanefi Onaldi <hanefi.onaldi@microsoft.com> Reviewed-by: Magnus Hagander <magnus@hagander.net> Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us> Discussion: https://postgr.es/m/170774255387.3279713.2822272755998870925@wrigleys.postgresql.org Backpatch-through: v12
2024-02-13Revert "Skip .DS_Store files in server side utils"Daniel Gustafsson
This reverts commit d3fdfdcd1c7f1b714a9a85b893d2c5afc60bea91. Per failure reports from the buildfarm.
2024-02-13Skip .DS_Store files in server side utilsDaniel Gustafsson
The macOS Finder application creates .DS_Store files in directories when opened, which creates problems for serverside utilities which expect all files to be PostgreSQL specific files. Skip these files when encountered in pg_checksums, pg_rewind and pg_basebackup. This was extracted from a larger patchset for skipping hidden files and system files, where the concencus was to just skip these. Since this is equally likely to happen in every version, backpatch to all supported versions. Reported-by: Mark Guertin <markguertin@gmail.com> Reviewed-by: Michael Paquier <michael@paquier.xyz> Reviewed-by: Tobias Bussmann <t.bussmann@gmx.net> Discussion: https://postgr.es/m/E258CE50-AB0E-455D-8AAD-BB4FE8F882FB@gmail.com Backpatch-through: v12
2024-02-05Last-minute updates for release notes.Tom Lane
Security: CVE-2024-0985 (not CVE-2023-5869 as claimed in prior commit msg)
2024-02-04Release notes for 16.2, 15.6, 14.11, 13.14, 12.18.Tom Lane
2024-02-01doc: remove incorrect grammar for ALTER EVENT TRIGGERDaniel Gustafsson
The Parameters subsection had an extra TRIGGER in the grammar for DISABLE/ENABLE which is incorrect. Backpatch down to all supported versions since it's been like this all along. Discussion: https://postgr.es/m/0AFB171E-7E78-4A90-A140-46AB270212CA@yesql.se Backpatch-through: v12
2024-01-30Doc: mention foreign keys can reference unique indexesDavid Rowley
We seem to have only documented a foreign key can reference the columns of a primary key or unique constraint. Here we adjust the documentation to mention columns in a non-partial unique index can be mentioned too. The header comment for transformFkeyCheckAttrs() also didn't mention unique indexes, so fix that too. In passing make that header comment reflect reality in the various other aspects where it deviated from it. Bug: 18295 Reported-by: Gilles PARC Author: Laurenz Albe, David Rowley Discussion: https://www.postgresql.org/message-id/18295-0ed0fac5c9f7b17b%40postgresql.org Backpatch-through: 12
2024-01-12Added literal tag for RETURNINGAlvaro Herrera
This is an old mistake (92e38182d7c8); backpatch all the way back. Author: Atsushi Torikoshi <torikoshia@oss.nttdata.com> Reviewed-by: Ashutosh Bapat <ashutosh.bapat.oss@gmail.com> Discussion: https://postgr.es/m/c0aa00b60a16c0ea2a4c5123b013acb9@oss.nttdata.com
2024-01-11Fix omission in partitioning limitation documentationMagnus Hagander
UNIQUE and PRIMARY KEY constraints can be created on ONLY the partitioned table. We already had an example demonstrating that, but forgot to mention it in the documentation of the limits of partitioning. Author: Laurenz Albe Reviewed-By: shihao zhong, Shubham Khanna, Ashutosh Bapat Backpatch-through: 12 Discussion: https://postgr.es/m/167299368731.659.16130012959616771853@wrigleys.postgresql.org
2024-01-09Doc: fix character_sets view.Tatsuo Ishii
The note regarding character encoding form in "The Information Schema" said that LATIN1 character repertoires only use one encoding form LATIN1. This is not correct because LATIN1 has another encoding form ISO-2022-JP-2. To fix this, replace LATIN1 with LATIN2, which is not supported by ISO-2022-JP-2, thus it can be said that LATIN2 only uses one encoding form. Back-patch to supported branches. Author: Tatsuo Ishii Reviewed-by: Daniel Gustafsson Discussion: https://postgr.es/m/flat/20240102.153925.1147403616414525145.t-ishii%40sranhm.sra.co.jp
2024-01-03Update copyright for 2024Bruce Momjian
Reported-by: Michael Paquier Discussion: https://postgr.es/m/ZZKTDPxBBMt3C0J9@paquier.xyz Backpatch-through: 12
2024-01-03Doc: Python's control flow construct is try/except not try/catch.Tom Lane
Very ancient thinko, dating evidently to 22690719e. Spotted by gweatherby. Discussion: https://postgr.es/m/170423637139.1288848.11840082988774620003@wrigleys.postgresql.org
2023-12-28doc: Mention AttributeRelationId in FDW validator function descriptionMichael Paquier
The documentation has been missing one value in the list of catalog OIDs that can be given to the validator function of a FDW, as of AttributeRelationId, when changing the attribute options of a foreign table. Author: Ian Lawrence Barwick Discussion: https://postgr.es/m/CAB8KJ=i16t2yJU_Pq2Z+hnNGWFhagp_bJmzxHZu3ZkOjZm-+rQ@mail.gmail.com Backpatch-through: 12
2023-12-27Doc: specify aclitem syntax more clearly.Tom Lane
The previous wording here relied solely on an example to explain aclitem output format. Add an actual syntax synopsis and explanation of the elements to make it clearer. David Johnston and Tom Lane, per gripe from Eugen Konkov. Discussion: https://postgr.es/m/170326116972.1876499.18357820037829248593@wrigleys.postgresql.org
2023-12-26Doc: Add missing pgoutput options.Amit Kapila
We forgot to update the docs while adding new options in pgoutput. Author: Emre Hasegeli Reviewed-by: Peter Smith, Amit Kapila Backpatch-through: 12 Discussion: https://postgr.es/m/CAE2gYzwdwtUbs-tPSV-QBwgTubiyGD2ZGsSnAVsDfAGGLDrGOA%40mail.gmail.com
2023-12-19doc: Fix syntax in ALTER FOREIGN DATA WRAPPER exampleDaniel Gustafsson
The example for dropping an option was incorrectly quoting the option key thus making it a value turning the command into an unqualified ADD operation. The result of dropping became adding a new key/value pair instead: d=# alter foreign data wrapper f options (drop 'b'); ALTER FOREIGN DATA WRAPPER d=# select fdwoptions from pg_foreign_data_wrapper where fdwname='f'; fdwoptions ------------ {drop=b} (1 row) This has been incorrect for a long time so backpatch to all supported branches. Author: Tim <tim.needham2@gmail.com> Discussion: https://postgr.es/m/170292280173.1876505.5204623074024041738@wrigleys.postgresql.org
2023-12-17Doc: add a bit to indices.sgml about what is an indexable clause.Tom Lane
We didn't explain this clearly until somewhere deep in the "Extending SQL" chapter, but really it ought to be mentioned in the introductory material too. Discussion: https://postgr.es/m/4097442.1694967650@sss.pgh.pa.us
2023-12-04doc: Remove reference to trigger file regarding promotionMichael Paquier
The wording changed here comes from 991bfe11d28a, when the only way to trigger a promotion was with a trigger file. There are more options to achieve this operation these days, like the SQL function pg_promote() or the command `pg_ctl promote`, so it is confusing to assume that only a trigger file is able to do the work. Note also that promote_trigger_file has been removed as of cd4329d9393f in 16~. Author: Shinya Kato Discussion: https://postgr.es/m/201b08ea29aa61f96162080e75be503c@oss.nttdata.com Backpatch-through: 12
2023-11-27Fix CREATE INDEX CONCURRENTLY exampleAlvaro Herrera
It fails to use the CONCURRENTLY keyword where it was necessary, so add it. This text was added to pg11 in commit 5efd604ec0a3; backpatch to pg12. Author: Nikolay Samokhvalov <nik@postgres.ai> Discussion: https://postgr.es/m/CAM527d9iz6+=_c7EqSKaGzjqWvSeCeRVVvHZ1v3gDgjTtvgsbw@mail.gmail.com
2023-11-26Doc: list AT TIME ZONE and COLLATE in operator precedence table.Tom Lane
These constructs have precedence, but we forgot to list them. In HEAD, mention AT LOCAL as well as AT TIME ZONE. Per gripe from Shay Rojansky. Discussion: https://postgr.es/m/CADT4RqBPdbsZW7HS1jJP319TMRHs1hzUiP=iRJYR6UqgHCrgNQ@mail.gmail.com
2023-11-21doc: FreeBSD uses camcontrol identify, not atacontrol, for cacheBruce Momjian
This is for IDE drive cache control, same as SCSI (already documented properly). Reported-by: John Ekins Discussion: https://postgr.es/m/20170808224017.8424.69170@wrigleys.postgresql.org Author: John Ekins Backpatch-through: 12
2023-11-18Fix typo in person's name.Noah Misch
Back-patch v16..v12 (all supported versions); master is unaffected.
2023-11-13doc: correct description of libpq's PQsetnonblocking() modeBruce Momjian
Reported-by: Yugo NAGATA Discussion: https://postgr.es/m/20210713115949.702986955f8ccf23fa81073c@sraoss.co.jp Backpatch-through: 12-16, master already done
2023-11-13doc: Add missing semicolon in exampleDaniel Gustafsson
One of the examples on the SELECT page was missing a semicolon from a listing which has the look and feel of being a psql session. This adds the missing semicolon and also removes the newline between the query and results to match the other examples nearby. Backpatch to all supported branches to avoid backpatching issues on this page. Reported-by: tim.needham2@gmail.com Discussion: https://postgr.es/m/169965004097.225187.12941375915673151540@wrigleys.postgresql.org Backpatch-through: v12
2023-11-06Last-minute updates for release notes.Tom Lane
Security: CVE-2023-5868, CVE-2023-5869, CVE-2023-5870
2023-11-05doc: Fix table cell overflowTom Lane
Fix one instance of a table cell overflow by adding a zero-width space. The visual impact of this is minimal, but since this is currently the only such case reported by FOP ("contents of ... exceed the available area"), it seems worth getting rid of. Back-patch of v14-era commit 74ff28197 into v13. It's not obvious to me why we were not seeing this warning in v13 before, since this file hasn't changed recently. Nonetheless, it's there now, and it's still desirable to keep v13 and up clean on this score.
2023-11-05Release notes for 16.1, 15.5, 14.10, 13.13, 12.17, 11.22.Tom Lane
2023-11-03doc: \copy can get data values \. and end-of-input confusedBruce Momjian
Reported-by: Svante Richter Discussion: https://postgr.es/m/fcd57e4-8f23-4c3e-a5db-2571d09208e2@beta.fastmail.com Backpatch-through: 11
2023-11-03doc: CREATE DATABASE doesn't copy db-level perms. from templateBruce Momjian
Reported-by: david@kapitaltrading.com Discussion: https://postgr.es/m/166007719137.995877.13951579839074751714@wrigleys.postgresql.org Backpatch-through: 11
2023-11-03Doc: update CREATE RULE ref page's hoary discussion of views.Tom Lane
This text left one with the impression that an ON SELECT rule could be attached to a plain table, which has not been true since commit 264c06820 (meaning the text was already misleading when written, evidently by me in 96bd67f61). However, it didn't get really bad until b23cd185f removed the convert-a-table-to-a-view logic, which had made it possible for scripts that thought they were attaching ON SELECTs to tables to still work. Rewrite into a form that makes it clear that an ON SELECT rule is better regarded as an implementation detail of a view. Pre-v16, point out that adding ON SELECT to a table actually converts it to a view. Per bug #18178 from Joshua Uyehara. Back-patch to all supported branches. Discussion: https://postgr.es/m/18178-05534d7064044d2d@postgresql.org
2023-11-03doc: ALTER DEFAULT PRIVILEGES does not affect inherited rolesBruce Momjian
Reported-by: Jordi Gutiérrez Hermoso Discussion: https://postgr.es/m/72652d72e1816bfc3c05d40f9e0e0373d07823c8.camel@octave.org Co-authored-by: Laurenz Albe Backpatch-through: 11
2023-11-02doc: Replace reference to ERRCODE_RAISE_EXCEPTION by "raise_exception"Michael Paquier
This part of the documentation refers to exceptions as handled by PL/pgSQL, and using the internal error code is confusing. Per thinko in 66bde49d96a9. Reported-by: Euler Taveira, Bruce Momjian Discussion: https://postgr.es/m/ZUEUnLevXyW7DlCs@momjian.us Backpatch-through: 11
2023-10-31doc: improve ALTER SYSTEM description of value list quotingBruce Momjian
Reported-by: splarv@ya.ru Discussion: https://postgr.es/m/167105927893.1897.13227723035830709578@wrigleys.postgresql.org Backpatch-through: 11
2023-10-31doc: add function argument and query parameter limitsBruce Momjian
Also reorder entries and add commas. Reported-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwYeNPxeocV3_0+Zx=_Xwvg+sNyEMdzyG5s2E2e0hZLQhg@mail.gmail.com Author: David G. Johnston (partial) Backpatch-through: 12
2023-10-31doc: 1-byte varlena headers can be used for user PLAIN storageBruce Momjian
This also updates some C comments. Reported-by: suchithjn22@gmail.com Discussion: https://postgr.es/m/167336599095.2667301.15497893107226841625@wrigleys.postgresql.org Author: Laurenz Albe (doc patch) Backpatch-through: 11
2023-10-25Doc: remove misleading info about ecpg's CONNECT/DISCONNECT DEFAULT.Tom Lane
As far as I can see, ecpg has no notion of a "default" open connection. You can do "CONNECT TO DEFAULT" but that just specifies letting libpq use all its default connection parameters --- the resulting connection is not special subsequently. In particular, SET CONNECTION = DEFAULT and DISCONNECT DEFAULT simply act on a connection named DEFAULT, if you've made one; they do not have special lookup rules. But the documentation of these commands makes it look like they do. Simplest fix, I think, is just to remove the paras suggesting that DEFAULT is special here. Also, SET CONNECTION *does* have one special lookup rule, which is that it recognizes CURRENT as an alias for the currently selected connection. SET CONNECTION = CURRENT is a no-op, so it's pretty useless, but nonetheless it does something different from selecting a connection by name; so we'd better document it. Per report from Sylvain Frandaz. Back-patch to all supported versions. Discussion: https://postgr.es/m/169824721149.1769274.1553568436817652238@wrigleys.postgresql.org
2023-10-25doc: Fix some typos and grammarMichael Paquier
Author: Ekaterina Kiryanova, Elena Indrupskaya, Oleg Sibiryakov, Maxim Yablokov Discussion: https://postgr.es/m/7aad518b-3e6d-47f3-9184-b1d69cb412e7@postgrespro.ru Backpatch-through: 11
generated by cgit v1.2.3 (git 2.46.0) at 2025-10-06 18:18:29 +0000