summaryrefslogtreecommitdiff
path: root/doc/src
AgeCommit message (Collapse)Author
2020-12-29doc: Improve some grammar and sentencesMichael Paquier
90fbf7c has taken care of that for HEAD. This includes the portion of the fixes that applies to the documentation, where needed depending on the branch. Author: Justin Pryzby Discussion: https://postgr.es/m/20201227202604.GC26311@telsasoft.com Backpatch-through: 9.5
2020-12-28Fix assorted issues in backend's GSSAPI encryption support.Tom Lane
Unrecoverable errors detected by GSSAPI encryption can't just be reported with elog(ERROR) or elog(FATAL), because attempting to send the error report to the client is likely to lead to infinite recursion or loss of protocol sync. Instead make this code do what the SSL encryption code has long done, which is to just report any such failure to the server log (with elevel COMMERROR), then pretend we've lost the connection by returning errno = ECONNRESET. Along the way, fix confusion about whether message translation is done by pg_GSS_error() or its callers (the latter should do it), and make the backend version of that function work more like the frontend version. Avoid allocating the port->gss struct until it's needed; we surely don't need to allocate it in the postmaster. Improve logging of "connection authorized" messages with GSS enabled. (As part of this, I back-patched the code changes from dc11f31a1.) Make BackendStatusShmemSize() account for the GSS-related space that will be allocated by CreateSharedBackendStatus(). This omission could possibly cause out-of-shared-memory problems with very high max_connections settings. Remove arbitrary, pointless restriction that only GSS authentication can be used on a GSS-encrypted connection. Improve documentation; notably, document the fact that libpq now prefers GSS encryption over SSL encryption if both are possible. Per report from Mikael Gustavsson. Back-patch to v12 where this code was introduced. Discussion: https://postgr.es/m/e5b0b6ed05764324a2f3fe7acfc766d5@smhi.se
2020-12-23docs: document which server-side languages can create procsBruce Momjian
This was missed when the feature was added. Reported-by: Daniel Westermann Discussion: https://postgr.es/m/160624532969.25818.4767632047905006142@wrigleys.postgresql.org Backpatch-through: 11
2020-12-21Remove "invalid concatenation of jsonb objects" error case.Tom Lane
The jsonb || jsonb operator arbitrarily rejected certain combinations of scalar and non-scalar inputs, while being willing to concatenate other combinations. This was of course quite undocumented. Rather than trying to document it, let's just remove the restriction, creating a uniform rule that unless we are handling an object-to-object concatenation, non-array inputs are converted to one-element arrays, resulting in an array-to-array concatenation. (This does not change the behavior for any case that didn't throw an error before.) Per complaint from Joel Jacobson. Back-patch to all supported branches. Discussion: https://postgr.es/m/163099.1608312033@sss.pgh.pa.us
2020-12-20Doc: fix description of how to use src/tutorial files.Tom Lane
The separate "cd" command before invoking psql made sense (or at least I thought so) when it was added in commit ed1939332. But 4e3a61635 removed the supporting text that explained when to use it, making it just confusing. So drop it. Also switch from four-dot to three-dot filler for the unsupplied part of the path, since at least one person has read the four-dot filler as a typo for "../..". And fix these/those inconsistency. Discussion: https://postgr.es/m/160837647714.673.5195186835607800484@wrigleys.postgresql.org
2020-12-20Doc: improve description of pgbench script weights.Tom Lane
Point out the workaround to be used if you want to write a script file name that includes "@". Clean up the text a little. Fabien Coelho, additional wordsmithing by me Discussion: https://postgr.es/m/1c4e81550d214741827a03292222db8d@G08CNEXMBPEKD06.g08.fujitsu.local
2020-12-16doc: Fix explanation related to pg_shmem_allocationsMichael Paquier
Offsets are shown as NULL only for anonymous allocations. Author: Benoit Lobréau Reviewed-by: Kyotaro Horiguchi Discussion: https://postgr.es/m/CAPE8EZ5Lnoyqoz7aZpvQM0E8sW+hw+k6G2NULe+m4arFRrA1aA@mail.gmail.com Backpatch-through: 13
2020-12-15doc: clarify COPY TO for partitioning/inheritanceBruce Momjian
It was not clear how COPY TO behaved with partitioning/inheritance because the paragraphs were so far apart. Also reword to simplify. Discussion: https://postgr.es/m/20201203211723.GR24052@telsasoft.com Author: Justin Pryzby Backpatch-through: 10
2020-12-08Doc: clarify that CREATE TABLE discards redundant unique constraints.Tom Lane
The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
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
generated by cgit v1.2.3 (git 2.46.0) at 2025-10-27 12:50:57 +0000