summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
2020-12-08Doc: explain that the string types can't store \0 (ASCII NUL).Tom Lane
This restriction was mentioned in connection with string literals, but it wasn't made clear that it's a general restriction not just a syntactic limitation in query strings. Per unsigned documentation comment. Discussion: https://postgr.es/m/160720552914.710.16625261471128631268@wrigleys.postgresql.org
2020-12-03doc: remove unnecessary blank before command option textBruce Momjian
Backpatch-through: 11
2020-12-03docs: list single-letter options first in command-line summaryBruce Momjian
In a few places, the long-version options were listed before the single-letter ones in the command summary of a few commands. This didn't match other commands, and didn't match the option ordering later in the same reference page. Backpatch-through: 9.5
2020-11-30Document concurrent indexes waiting on each otherAlvaro Herrera
Because regular CREATE INDEX commands are independent, and there's no logical data dependency, it's not immediately obvious that transactions held by concurrent index builds on one table will block the second phase of concurrent index creation on an unrelated table, so document this caveat. Backpatch this all the way back. In branch master, mention that only some indexes are involved. Author: James Coleman <jtc331@gmail.com> Reviewed-by: David Johnston <david.g.johnston@gmail.com> Discussion: https://postgr.es/m/CAAaqYe994=PUrn8CJZ4UEo_S-FfRr_3ogERyhtdgHAb2WG_Ufg@mail.gmail.com
2020-11-30Remove configure-time probe for DocBook DTD.Tom Lane
Checking for DocBook being installed was valuable when we were on the OpenSP docs toolchain, because that was rather hard to get installed fully. Nowadays, as long as you have xmllint and xsltproc installed, you're good, because those programs will fetch the DocBook files off the net at need. Moreover, testing this at configure time means that a network access may well occur whether or not you have any interest in building the docs later. That can be slow (typically 2 or 3 seconds, though much higher delays have been reported), and it seems not very nice to be doing an off-machine access without warning, too. Hence, drop the PGAC_CHECK_DOCBOOK probe, and adjust related documentation. Without that macro, there's not much left of config/docbook.m4 at all, so I just removed it. Back-patch to v11, where we started to use xmllint in the PGAC_CHECK_DOCBOOK probe. Discussion: https://postgr.es/m/E2EE6B76-2D96-408A-B961-CAE47D1A86F0@yesql.se Discussion: https://postgr.es/m/A55A7FC9-FA60-47FE-98B5-139CDC57CE6E@gmail.com
2020-11-29Fix recently-introduced breakage in psql's \connect command.Tom Lane
Through my misreading of what the existing code actually did, commits 85c54287a et al. broke psql's behavior for the case where "\c connstring" provides a password in the connstring. We should use that password in such a case, but as of 85c54287a we ignored it (and instead, prompted for a password). Commit 94929f1cf fixed that in HEAD, but since I thought it was cleaning up a longstanding misbehavior and not one I'd just created, I didn't back-patch it. Hence, back-patch the portions of 94929f1cf having to do with password management. In addition to fixing the introduced bug, this means that "\c -reuse-previous=on connstring" will allow re-use of an existing connection's password if the connstring doesn't change user/host/port. That didn't happen before, but it seems like a bug fix, and anyway I'm loath to have significant differences in this code across versions. Also fix an error with the same root cause about whether or not to override a connstring's setting of client_encoding. As of 85c54287a we always did so; restore the previous behavior of overriding only when stdin/stdout are a terminal and there's no environment setting of PGCLIENTENCODING. (I find that definition a bit surprising, but right now doesn't seem like the time to revisit it.) Per bug #16746 from Krzysztof Gradek. As with the previous patch, back-patch to all supported branches. Discussion: https://postgr.es/m/16746-44b30e2edf4335d4@postgresql.org
2020-11-29Doc: clarify behavior of PQconnectdbParams().Tom Lane
The documentation omitted the critical tidbit that a keyword-array entry is simply ignored if its corresponding value-array entry is NULL or an empty string; it will *not* override any previously-obtained value for the parameter. (See conninfo_array_parse().) I'd supposed that would force the setting back to default, which is what led me into bug #16746; but it doesn't. While here, I couldn't resist the temptation to do some copy-editing, both in the description of PQconnectdbParams() and in the section about connection URI syntax. Discussion: https://postgr.es/m/931505.1606618746@sss.pgh.pa.us
2020-11-25doc: Fix typosPeter Eisentraut
Author: Justin Pryzby <pryzby@telsasoft.com> Discussion: https://www.postgresql.org/message-id/20201121194105.GO24784@telsasoft.com
2020-11-16doc: update bgwriter descriptionBruce Momjian
This clarifies exactly what the bgwriter does, which should help with tuning. Reported-by: Chris Wilson Discussion: https://postgr.es/m/160399562040.7809.7335281028960123489@wrigleys.postgresql.org Backpatch-through: 9.5
2020-11-16doc: clarify how to find pg_type_d.h in the install treeBruce Momjian
Followup to patch 152ed04799. Reported-by: Alvaro Herrera Discussion: https://postgr.es/m/20201112202900.GA28098@alvherre.pgsql Backpatch-through: 9.5
2020-11-16doc: improve wording of the need for analyze of exp. indexesBruce Momjian
This is a followup commit on 3370207986. Reported-by: Justin Pryzby Discussion: https://postgr.es/m/20201112211143.GL30691@telsasoft.com Backpatch-through: 9.5
2020-11-16Fix typoAlvaro Herrera
Introduced in 90fdc259866e; backpatch to 12. Author: Erik Rijkers <er@xs4all.nl> Discussion: https://postgr.es/m/e92b3fba98a0c0f7afc0a2a37e765954@xs4all.nl
2020-11-15Fix fuzzy thinking about amcanmulticol versus amcaninclude.Tom Lane
These flags should be independent: in particular an index AM should be able to say that it supports include columns without necessarily supporting multiple key columns. The included-columns patch got this wrong, possibly aided by the fact that it didn't bother to update the documentation. While here, clarify some text about amcanreturn, which was a little vague about what should happen when amcanreturn reports that only some of the index columns are returnable. Noted while reviewing the SP-GiST included-columns patch, which quite incorrectly (and unsafely) changed SP-GiST to claim amcanmulticol = true as a workaround for this bug. Backpatch to v11 where included columns were introduced.
2020-11-14Doc: improve partitioning discussion in ddl.sgml.Tom Lane
This started with the intent to explain that range upper bounds are exclusive, which previously you could only find out by reading the CREATE TABLE man page. But I soon found that section 5.11 really could stand a fair amount of editorial attention. It's apparently been revised several times without much concern for overall flow, nor careful copy-editing. Back-patch to v11, which is as far as the patch goes easily. Per gripe from Edson Richter. Thanks to David Johnston for review. Discussion: https://postgr.es/m/DM6PR13MB3988736CF8F5DC5720440231CFE60@DM6PR13MB3988.namprd13.prod.outlook.com
2020-11-12doc: clarify where to find pg_type_d.h (PG 11+) and pg_type.hBruce Momjian
These files are in compiled directories and install directories. Reported-by: e.indrupskaya@postgrespro.ru Discussion: https://postgr.es/m/160379609706.24746.7506163279454026608@wrigleys.postgresql.org Backpatch-through: 9.5
2020-11-12docs: mention that expression indexes need analyzeBruce Momjian
Expression indexes can't benefit from pre-computed statistics on columns. Reported-by: Nikolay Samokhvalov Discussion: https://postgr.es/m/CANNMO++5rw9RDA=p40iMVbMNPaW6O=S0AFzTU=KpYHRpCd1voA@mail.gmail.com Author: Nikolay Samokhvalov, modified Backpatch-through: 9.5
2020-11-12doc: wire protocol data type for history file content is byteaBruce Momjian
Document that though the history file content is marked as bytea, it is the same a text, and neither is btyea-escaped or encoding converted. Reported-by: Brar Piening Discussion: https://postgr.es/m/6a1b9cd9-17e3-df67-be55-86102af6bdf5@gmx.de Backpatch-through: 13 - 9.5 (not master)
2020-11-10doc: fix spelling "connction" to "connection"Bruce Momjian
Was wrong in commit 1a9388bd0f. Reported-by: Tom Lane, Justin Pryzby Discussion: https://postgr.es/m/20201102063333.GE22691@telsasoft.com Backpatch-through: 9.5
2020-11-09Last-minute updates for release notes.Tom Lane
Security: CVE-2020-25694, CVE-2020-25695, CVE-2020-25696
2020-11-09Doc: clarify data type behavior of COALESCE and NULLIF.Tom Lane
After studying the code, NULLIF is a lot more subtle than you might have guessed. Discussion: https://postgr.es/m/160486028730.25500.15740897403028593550@wrigleys.postgresql.org
2020-11-08Release notes for 13.1, 12.5, 11.10, 10.15, 9.6.20, 9.5.24.Tom Lane
2020-11-07Doc: small release note updates.Tom Lane
Add items committed in the last 24 hours. Also correct my failure to credit Nikita Glukhov for 52ad1e659, which did all the heavy lifting for 3db322eaa.
2020-11-06First-draft release notes for 13.1.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. Also as usual for a .1 release, there are some entries here that are not really relevant for v13 because they already appeared in 13.0. Those'll be removed later.
2020-11-06Revert "Accept relations of any kind in LOCK TABLE".Tom Lane
Revert 59ab4ac32, as well as the followup fix 33862cb9c, in all branches. We need to think a bit harder about what the behavior of LOCK TABLE on views should be, and there's no time for that before next week's releases. We'll take another crack at this later. Discussion: https://postgr.es/m/16703-e348f58aab3cf6cc@postgresql.org
2020-11-03Allow users with BYPASSRLS to alter their own passwords.Tom Lane
The intention in commit 491c029db was to require superuserness to change the BYPASSRLS property, but the actual effect of the coding in AlterRole() was to require superuserness to change anything at all about a BYPASSRLS role. Other properties of a BYPASSRLS role should be changeable under the same rules as for a normal role, though. Fix that, and also take care of some documentation omissions related to BYPASSRLS and REPLICATION role properties. Tom Lane and Stephen Frost, per bug report from Wolfgang Walther. Back-patch to all supported branches. Discussion: https://postgr.es/m/a5548a9f-89ee-3167-129d-162b5985fcf8@technowledgy.de
2020-11-02Add missing comma in list of SSL versionsMagnus Hagander
2020-11-02Fix some grammar and typos in comments and docsMichael Paquier
The documentation fixes are backpatched down to where they apply. Author: Justin Pryzby Discussion: https://postgr.es/m/20201031020801.GD3080@telsasoft.com Backpatch-through: 9.6
2020-10-27Accept relations of any kind in LOCK TABLEAlvaro Herrera
The restriction that only tables and views can be locked by LOCK TABLE is quite arbitrary, since the underlying mechanism can lock any relation type. Drop the restriction so that programs such as pg_dump can lock all relations they're interested in, preventing schema changes that could cause a dump to fail after expending much effort. Backpatch to 9.5. Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us> Reported-by: Wells Oliver <wells.oliver@gmail.com> Discussion: https://postgr.es/m/20201021200659.GA32358@alvherre.pgsql
2020-10-27docs: remove reference to src/tools/threadBruce Momjian
This directory and the ability to build the thread test independently were removed in commit 8a2121185b. Reported-by: e.indrupskaya@postgrespro.ru Discussion: https://postgr.es/m/160379609706.24746.7506163279454026608@wrigleys.postgresql.org Backpatch-through: 9.5
2020-10-26doc: simplify wording of function error affectsBruce Momjian
Reported-by: bob.henkel@gmail.com Discussion: https://postgr.es/m/160324449781.693.8298142858847611071@wrigleys.postgresql.org Backpatch-through: 9.5
2020-10-26doc: make blooms docs match realityBruce Momjian
Parallel execution changed the way bloom queries are executed, so update the EXPLAIN output, and restructure the docs to be clearer and more accurate. Reported-by: Daniel Westermann Discussion: https://postgr.es/m/ZR0P278MB0122119FAE78721A694C30C8D2340@ZR0P278MB0122.CHEP278.PROD.OUTLOOK.COM Author: Daniel Westermann and me Backpatch-through: 9.6
2020-10-21Fix connection string handling in psql's \connect command.Tom Lane
psql's \connect claims to be able to re-use previous connection parameters, but in fact it only re-uses the database name, user name, host name (and possibly hostaddr, depending on version), and port. This is problematic for assorted use cases. Notably, pg_dump[all] emits "\connect databasename" commands which we would like to have re-use all other parameters. If such a script is loaded in a psql run that initially had "-d connstring" with some non-default parameters, those other parameters would be lost, potentially causing connection failure. (Thus, this is the same kind of bug addressed in commits a45bc8a4f and 8e5793ab6, although the details are much different.) To fix, redesign do_connect() so that it pulls out all properties of the old PGconn using PQconninfo(), and then replaces individual properties in that array. In the case where we don't wish to re-use anything, get libpq's default settings using PQconndefaults() and replace entries in that, so that we don't need different code paths for the two cases. This does result in an additional behavioral change for cases where the original connection parameters allowed multiple hosts, say "psql -h host1,host2", and the \connect request allows re-use of the host setting. Because the previous coding relied on PQhost(), it would only permit reconnection to the same host originally selected. Although one can think of scenarios where that's a good thing, there are others where it is not. Moreover, that behavior doesn't seem to meet the principle of least surprise, nor was it documented; nor is it even clear it was intended, since that coding long pre-dates the addition of multi-host support to libpq. Hence, this patch is content to drop it and re-use the host list as given. Per Peter Eisentraut's comments on bug #16604. Back-patch to all supported branches. Discussion: https://postgr.es/m/16604-933f4b8791227b15@postgresql.org
2020-10-20Fix typo in commit 99ae342fc4.Amit Kapila
In v13, the id for max_parallel_maintenance_workers is defined differently as compared to HEAD in docs, so adjust the docs accordingly. Reported-by: Magnus Hagander and Tom Lane Discussion: https://postgr.es/m/CABUevEyAFQZ_jvjY_KtRUWbci4YMyQC1QAMzDQAbLs=XCo3m5Q@mail.gmail.com
2020-10-19Fix connection string handling in src/bin/scripts/ programs.Tom Lane
When told to process all databases, clusterdb, reindexdb, and vacuumdb would reconnect by replacing their --maintenance-db parameter with the name of the target database. If that parameter is a connstring (which has been allowed for a long time, though we failed to document that before this patch), we'd lose any other options it might specify, for example SSL or GSS parameters, possibly resulting in failure to connect. Thus, this is the same bug as commit a45bc8a4f fixed in pg_dump and pg_restore. We can fix it in the same way, by using libpq's rules for handling multiple "dbname" parameters to add the target database name separately. I chose to apply the same refactoring approach as in that patch, with a struct to handle the command line parameters that need to be passed through to connectDatabase. (Maybe someday we can unify the very similar functions here and in pg_dump/pg_restore.) Per Peter Eisentraut's comments on bug #16604. Back-patch to all supported branches. Discussion: https://postgr.es/m/16604-933f4b8791227b15@postgresql.org
2020-10-19Misc documentation fixes.Heikki Linnakangas
- Misc grammar and punctuation fixes. - Stylistic cleanup: use spaces between function arguments and JSON fields in examples. For example "foo(a,b)" -> "foo(a, b)". Add semicolon after last END in a few PL/pgSQL examples that were missing them. - Make sentence that talked about "..." and ".." operators more clear, by avoiding to end the sentence with "..". That makes it look the same as "..." - Fix syntax description for HAVING: HAVING conditions cannot be repeated Patch by Justin Pryzby, per Yaroslav Schekin's report. Backpatch to all supported versions, to the extent that the patch applies easily. Discussion: https://www.postgresql.org/message-id/20201005191922.GE17626%40telsasoft.com
2020-10-19Fix TRUNCATE doc: ALTER SEQUENCE RESTART is now transactional.Heikki Linnakangas
ALTER SEQUENCE RESTART was made transactional in commit 3d79013b97. Backpatch to v10, where that was introduced. Patch by Justin Pryzby, per Yaroslav Schekin's report. Discussion: https://www.postgresql.org/message-id/20201005191922.GE17626%40telsasoft.com
2020-10-19Fix output of tsquery example in docs.Heikki Linnakangas
The output for this query changed in commit 4e2477b7b8. Backport to 9.6 like that commit. Patch by Justin Pryzby, per Yaroslav Schekin's report. Discussion: https://www.postgresql.org/message-id/20201005191922.GE17626%40telsasoft.com
2020-10-19In libpq for Windows, call WSAStartup once and WSACleanup not at all.Tom Lane
The Windows documentation insists that every WSAStartup call should have a matching WSACleanup call. However, if that ever had actual relevance, it wasn't in this century. Every remotely-modern Windows kernel is capable of cleaning up when a process exits without doing that, and must be so to avoid resource leaks in case of a process crash. Moreover, Postgres backends have done WSAStartup without WSACleanup since commit 4cdf51e64 in 2004, and we've never seen any indication of a problem with that. libpq's habit of doing WSAStartup during connection start and WSACleanup during shutdown is also rather inefficient, since a series of non-overlapping connection requests leads to repeated, quite expensive DLL unload/reload cycles. We document a workaround for that (having the application call WSAStartup for itself), but that's just a kluge. It's also worth noting that it's far from uncommon for applications to exit without doing PQfinish, and we've not heard reports of trouble from that either. However, the real reason for acting on this is that recent experiments by Alexander Lakhin show that calling WSACleanup during PQfinish is triggering the symptom we occasionally see that a process using libpq fails to emit expected stdio output. Therefore, let's change libpq so that it calls WSAStartup only once per process, during the first connection attempt, and never calls WSACleanup at all. While at it, get rid of the only other WSACleanup call in our code tree, in pg_dump/parallel.c; that presumably is equally useless. Back-patch of HEAD commit 7d00a6b2d. Discussion: https://postgr.es/m/ac976d8c-03df-d6b8-025c-15a2de8d9af1@postgrespro.ru
2020-10-19Fix doc for full text search distance operator.Heikki Linnakangas
Commit 028350f619 changed its behavior from "at most" to "exactly", but forgot to update the documentation. Backpatch to 9.6. Patch by Justin Pryzby, per Yaroslav Schekin's report. Discussion: https://www.postgresql.org/message-id/20201005191922.GE17626%40telsasoft.com
2020-10-19Update link for plluaMagnus Hagander
Author: Daniel Gustafsson <daniel@yesql.se> Discussion: https://postgr.es/m/A05874AE-8771-4C61-A24E-0B6249B8F3C2@yesql.se
2020-10-19Change the docs for PARALLEL option of Vacuum.Amit Kapila
The rules to choose the number of parallel workers to perform parallel vacuum operation were not clearly specified. Reported-by: Peter Eisentraut Author: Amit Kapila Backpatch-through: 13, where it was introduced Discussion: https://postgr.es/m/36aa8aea-61b7-eb3c-263b-648e0cb117b7@2ndquadrant.com
2020-10-17Doc: caution against misuse of 'now' and related datetime literals.Tom Lane
Section 8.5.1.4, which defines these literals, made only a vague reference to the fact that they might be evaluated too soon to be safe in non-interactive contexts. Provide a more explicit caution against misuse. Also, generalize the wording in the related tip in section 9.9.4: while it clearly described this problem, it implied (or really, stated outright) that the problem only applies to table DEFAULT clauses. Per gripe from Tijs van Dam. Back-patch to all supported branches. Discussion: https://postgr.es/m/c2LuRv9BiRT3bqIo5mMQiVraEXey_25B4vUn0kDqVqilwOEu_iVF1tbtvLnyQK7yDG3PFaz_GxLLPil2SDkj1MCObNRVaac-7j1dVdFERk8=@thalex.com
2020-10-16Doc: tweak column widths in synchronous-commit-matrix table.Tom Lane
Commit a97e85f2b caused "exceed the available area" warnings in PDF builds. Fine-tune colwidth values to avoid that. Back-patch to 9.6, like the prior patch. (This is of dubious value before v13, since we were far from free of such warnings in older branches. But we might as well keep the SGML looking the same in all branches.) Per buildfarm.
2020-10-15doc: improve description of synchronous_commit modesBruce Momjian
Previously it wasn't clear exactly what each of the synchronous_commit modes accomplished. This clarifies that, and adds a table describing it. Only backpatched through 9.6 since 9.5 doesn't have all the options. Reported-by: kghost0@gmail.com Discussion: https://postgr.es/m/159741195522.14321.13812604195366728976@wrigleys.postgresql.org Backpatch-through: 9.6
2020-10-15doc: Mention that toast_tuple_target affects also column marked as Main.Fujii Masao
Previously it was documented that toast_tuple_target affected column marked as only External or Extended. But this description is not correct and toast_tuple_target affects also column marked as Main. Back-patch to v11 where toast_tuple_target reloption was introduced. Author: Shinya Okano Reviewed-by: Tatsuhito Kasahara, Fujii Masao Discussion: https://postgr.es/m/93f46e311a67422e89e770d236059817@oss.nttdata.com
2020-10-14Restore replication protocol's duplicate command tagsAlvaro Herrera
I removed the duplicate command tags for START_REPLICATION inadvertently in commit 07082b08cc5d, but the replication protocol requires them. The fact that the replication protocol was broken was not noticed because all our test cases use an optimized code path that exits early, failing to verify that the behavior is correct for non-optimized cases. Put them back. Also document this protocol quirk. Add a test case that shows the failure. It might still succeed even without the patch when run on a fast enough server, but it suffices to show the bug in enough cases that it would be noticed in buildfarm. Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Reported-by: Henry Hinze <henry.hinze@gmail.com> Reviewed-by: Petr Jelínek <petr.jelinek@2ndquadrant.com> Discussion: https://postgr.es/m/16643-eaadeb2a1a58d28c@postgresql.org
2020-10-06Further improvements on documentation for pg_dump -tMagnus Hagander
Ian submitted an updated patch just as I was pushing the previous one, so use this newer wording instead. Author: Ian Barwick
2020-10-06Clarify documentation around pg_dump -t optionMagnus Hagander
The behavior is different for different types of objects, so make that more clear. Author: Ian Barwick
2020-10-05doc: show functions returning record types and use of ROWS FROMBruce Momjian
Previously it was unclear exactly how ROWS FROM behaved and how to cast the data types of columns returned by FROM functions. Also document that only non-OUT record functions can have their columns cast to data types. Reported-by: guyren@gmail.com Discussion: https://postgr.es/m/158638264419.662.2482095087061084020@wrigleys.postgresql.org Backpatch-through: 9.5
2020-10-05docs: clarify the interaction of clientcert and cert auth.Bruce Momjian
This is the first paragraph change of master-only commit 253f1025da. Backpatch-through: PG 12-13 only
generated by cgit v1.2.3 (git 2.46.0) at 2025-10-29 20:38:40 +0000