Re: 'value' has special behaviour in alter system
"Jonathan S. Katz" writes:
> On 12/15/22 10:50 AM, David G. Johnston wrote:
>> I suggest changing it to:
>> SET configuration_parameter { TO | = } { value [, ...] | DEFAULT }
> +1 in general. I would also suggest we add an example in the Examples
> section to show what the output is when you add single-quotes.
I think the core problem here is that the syntax diagram and discussion
don't clearly discuss the behavior for list values. David's version of
the syntax diagram looks fine, but not sure about the text. There likely
needs to be some explicit acknowledgement of the fact that some GUCs
act differently than others (cf GUC_LIST_INPUT and GUC_LIST_QUOTE flags).
+1 for examples, for sure.
regards, tom lane
Re: There is no command pg_ctl reload in Postgresql 13 clusters
PG Doc comments form writes: > Could you provide additional information about pg_ctlcluster command? pg_ctlcluster is not part of the community Postgres code. It is (I believe) added by the Debian packagers, so you'd have to discuss the state of their documentation with them. regards, tom lane
Re: 8.5.2 "integral" - "integer"
PG Doc comments form writes: > I think, the "integer" will be good choice instead "integral'": > 8.5.2 > ... > "The offset will be shown as hh (hours only) if it is an integral number of > hours, else as hh:mm if it is an integral number of minutes, else as > hh:mm:ss. (The third case is not possible with any modern" "Integral" seems like perfectly good English to me here. regards, tom lane
Re: The documentation for storage type 'plain' actually allows single byte header
Laurenz Albe writes:
> On Tue, 2023-01-10 at 15:53 +, PG Doc comments form wrote:
>>> PLAIN prevents either compression or out-of-line storage; furthermore it
>>> disables use of single-byte headers for varlena types. This is the only
>>> possible strategy for columns of non-TOAST-able data types.
>> However, it does allow "single byte" headers. How to verify this?
>> CREATE EXTENSION pageinspect;
>> CREATE TABLE test(a VARCHAR(1) STORAGE PLAIN);
>> INSERT INTO test VALUES (repeat('A',10));
>>
>> Now peek into the page with pageinspect functions
>>
>> SELECT left(encode(t_data, 'hex'), 40) FROM
>> heap_page_items(get_raw_page('test', 0));
>>
>> This returned value of "1741414141414141414141".
> I think that the documentation is wrong. The attached patch removes the
> offending half-sentence.
The documentation is correct, what is broken is the code. I'm not
sure when we broke it, but what I see in tracing through the INSERT
is that we are forming the tuple using a tupdesc with the wrong
value of attstorage. It looks like the tupdesc belongs to the
virtual slot representing the output of the INSERT statement,
which is not identical to the target relation's tupdesc.
(The virtual slot's tupdesc is probably reverse-engineered from
just the data types of the columns, so it'll have whatever is the
default attstorage for the data type. It's blind luck that this
attstorage value isn't used for anything more consequential,
like TOAST decisions.)
regards, tom lane
Re: The documentation for storage type 'plain' actually allows single byte header
Andres Freund writes:
> On 2023-01-15 16:40:27 -0500, Tom Lane wrote:
>> The documentation is correct, what is broken is the code. I'm not
>> sure when we broke it
> I've not thought through this fully. But after a first look, this might be
> hard to fix without incuring a lot of overhead / complexity.
It appeared to me that it was failing at this step in
ExecGetInsertNewTuple:
if (relinfo->ri_newTupleSlot->tts_ops != planSlot->tts_ops)
{
ExecCopySlot(relinfo->ri_newTupleSlot, planSlot);
return relinfo->ri_newTupleSlot;
}
ri_newTupleSlot has the tupdesc we want, planSlot is a virtual slot
that has the bogus tupdesc, and for some reason heap_form_tuple is
getting called with planSlot's tupdesc not ri_newTupleSlot's. I'm
not quite sure if this is just a thinko somewhere or there's a
deficiency in the design of the slot APIs.
The UPDATE path seems to work fine, btw.
regards, tom lane
Re: The documentation for storage type 'plain' actually allows single byte header
Andres Freund writes: > On 2023-01-15 18:08:21 -0500, Tom Lane wrote: >> ri_newTupleSlot has the tupdesc we want, planSlot is a virtual slot >> that has the bogus tupdesc, and for some reason heap_form_tuple is >> getting called with planSlot's tupdesc not ri_newTupleSlot's. > The way we copy a slot into a heap slot is to materialize the source slot and > copy the heap tuple into target slot. Which is also what happened before the > slot type abstraction (hence the problem also existing before that was > introduced). Hmm. For the case of virtual->physical slot, that doesn't sound terribly efficient. > I think it's fairly fundamental that copying between two slots assumes a > compatible tupdescs. We could possibly make some effort to inject the desired attstorage properties into the planSlot's tupdesc. Not sure where would be a good place. regards, tom lane
Re: The documentation for storage type 'plain' actually allows single byte header
Laurenz Albe writes: > On Sun, 2023-01-15 at 16:40 -0500, Tom Lane wrote: >> The documentation is correct, what is broken is the code. > I see. But what is the reason for that anyway? Why not allow short varlena > headers if TOAST storage is set to PLAIN? The original motivation for that whole mechanism was to protect data types for which the C functions haven't been upgraded to support non-traditional varlena headers. So I was worried that this behavior would somehow break those cases (which still exist, eg oidvector and int2vector). However, the thing that actually marks such a datatype is that pg_type.typstorage is PLAIN, and as far as I can find we do still honor that case in full. If that's the case then every tupdesc we ever create for such a column will say PLAIN, so there's no opportunity for the wrong thing to happen. So maybe it's okay to move the goalposts and acknowledge that setting attstorage to PLAIN isn't a complete block on applying toast-related transformations. I wonder though whether short-header is the only case that can slide through. In particular, for "INSERT ... SELECT FROM othertable", I suspect it's possible for a compressed-in-line datum to slide through without decompression. (We certainly must fix out-of-line datums, but that doesn't necessarily mean we undo compression.) So I'm not convinced that the proposed wording is fully correct yet. regards, tom lane
Re: Typo in 2.7 Aggregate Functions
PG Doc comments form writes: > Near the end of Chapter 2.7 Aggregate Functions of the documentation, the > command FILTER is introduced. The full query is > SELECT city, max(temp_lo), count(*) FILTER (WHERE temp_lo < 30) > FROM weather > GROUP BY city > HAVING max(temp_lo) < 40; > and the output shows a count value of 5. This is an error. Yeah :-(. This is already fixed in our source tree [1], as you can see on the website if you look at the "devel" branch. But the released-version docs won't update till our next releases, in February. Thanks for the report, anyway! regards, tom lane [1] https://git.postgresql.org/gitweb/?p=postgresql.git&a=commitdiff&h=f05a5e0003edfec027ee10d09082667036862e1c
Re: gen_random_uuid is only available with pgcrypto enabled
PG Doc comments form writes:
> Regarding the documentation on this page:
> https://www.postgresql.org/docs/15/functions-uuid.html
> It think the documentation should state clearly, that postgres natively does
> not have any UUID generation functions.
That hasn't been true since we added gen_random_uuid() to the
core code in v13. pgcrypto's version is now just a deprecated
wrapper for that.
regards, tom lane
Re: Naming of network_ops vs. inet_ops for SP-GIST
PG Doc comments form writes: > I wanted to add an SP-GIST index for an inet field ip_address > In https://www.postgresql.org/docs/14/spgist-builtin-opclasses.html > network_ops is stated as the built-in opclass for (inet, inet) > I entered the following command: > # create index concurrently ip_address_spgist_ban_by_ip on ban_by_ip using > spgist (ip_address network_ops); > ERROR: operator class "network_ops" does not exist for access method > "spgist" Hmm. There's some confusion here, because network_ops is the name of the operator *family*: =# \dAf spgist List of operator families AM | Operator family | Applicable types +-+-- spgist | box_ops | box spgist | kd_point_ops| point spgist | network_ops | inet spgist | poly_ops| polygon spgist | quad_point_ops | point spgist | range_ops | anyrange spgist | text_ops| text (7 rows) but inet_ops is the name of the operator *class*: n=# \dAc spgist List of operator classes AM | Input type | Storage type | Operator class | Default? ++--++-- spgist | anyrange | | range_ops | yes spgist | box| | box_ops| yes spgist | inet | | inet_ops | yes spgist | point | | kd_point_ops | no spgist | point | | quad_point_ops | yes spgist | polygon| box | poly_ops | yes spgist | text | | text_ops | yes (7 rows) This naming was evidently chosen to match btree, which has both inet_ops and cidr_ops opclasses within its network_ops family. spgist only supports inet_ops (and there's not really a reason to change that, since it will in fact work for cidr too). But you have to use the class name not the family name when explicitly selecting an index's opclass. > I notice inet_ops, not network_ops, is mentioned in the docs for 13. Perhaps > it was renamed to network_ops in 15 but not 14? Hmm, apparently somebody decided that the family name was more appropriate to show here, since the operators are tied to an opfamily not just an opclass. But the table header still says "operator classes", so that's incorrect. We could change the table header, but I'm not sure that that is a useful direction to take, because people need to use the class name for index creation but there are few cases where non-developers need be concerned with family names. I wonder whether we shouldn't just revert this table to showing opclass names, and avert our eyes from the theoretical inconsistency. Michael, looks like it was your 7a1cd5260 that changed it; what do you think? regards, tom lane
Re: Naming of network_ops vs. inet_ops for SP-GIST
Michael Paquier writes:
> I don't have a strong opinion about the naming inconsistency between
> the opclass name and the opfamily name in this case, though, couldn't
> it create more problems than actually fix something?
Well, it's been like that from day one and people haven't complained.
I think changing it now would add more confusion than it subtracts.
> Anyway, attached is a patch for the docs. Thoughts?
Works for me.
regards, tom lane
Re: Not an error but a difficult wording
Laurenz Albe writes: > On Wed, 2023-01-25 at 08:22 +, PG Doc comments form wrote: >> Maybe this would be better? (I don't know the comma rules) >> "because the files(,?) that are generated/processed by these tools(,?) are >> already included in the tarball" > +1 > Correct English would be: > These tools are not needed to build from a distribution tarball, because > the files generated by these tools are included in the tarball. The existing wording is not incorrect AFAICS, but I agree it's a bit awkward. I'd modify one word in your version: These tools are not needed to build from a distribution tarball, because the files generated using these tools are included in the tarball. Or possibly "with" instead of "using"? regards, tom lane
Re: Not an error but a difficult wording
Laurenz Albe writes: > On Wed, 2023-01-25 at 20:39 -0500, Tom Lane wrote: >> I'd modify one word in your version: >> >> These tools are not needed to build from a distribution tarball, because >> the files generated using these tools are included in the tarball. >> >> Or possibly "with" instead of "using"? > Both are better; I'd lean towards "with". Done that way then, thanks. regards, tom lane
Re: Suggestion for deprecated spellings
Bruce Momjian writes: > On Thu, Jan 26, 2023 at 12:19:29PM +, PG Doc comments form wrote: >> From time to time some spelling for given command gets obsolete, yet it is >> shown in the syntax on "equal rights" as other valid clauses. > We don't need to show all _supported_ syntaxes in the "Synopsis" > section, so we could just remove them. IIRC, there is precedent in COPY for moving obsolete alternatives to a separate part of the man page. I'd prefer that to just removing them, because then there is no documentation to help someone understand what an old SQL script is doing. regards, tom lane
Re: Modifying Arrays
PG Doc comments form writes:
> According to the official document of PostgreSQL 15, in the section 8.15.4.
> Modifying Arrays there is a statement like:
> The slice syntaxes with omitted lower-bound and/or upper-bound can be used
> too, but only when updating an array value that is not NULL or
> zero-dimensional (otherwise, there is no existing subscript limit to
> substitute).
> This statement is not true for the following statements or I am missing
> something?
Your example doesn't use a slice with omitted bound, so I'm not quite sure
what you are trying to show? Using your test data, a slice with omitted
bound does fail with Pam's null schedule:
=> UPDATE sal_emp SET schedule[:2] = '{"w", "x", "y", "z"}' WHERE name = 'Pam';
ERROR: array slice subscript must provide both boundaries
DETAIL: When assigning to a slice of an empty array value, slice boundaries
must be fully specified.
but it works for the other entries:
=> UPDATE sal_emp SET schedule[:2] = '{"w", "x", "y", "z"}' WHERE name != 'Pam';
UPDATE 3
=> table sal_emp;
name | pay_by_quarter |schedule
+---+-
Pam| {2,25001,25002,25003} |
Bill | {1,1,1,1} | {{w,x},{y,z}}
Carol | {2,25000,25000,25000} | {{w,x},{y,z}}
Carolx | {2,25001,25002,25003} | {{w,x},{y,z},{meetingy,lunchy}}
(4 rows)
regards, tom lane
Re: Mistake in statement example
PG Doc comments form writes:
> I believe there is a mistake in an example on
> https://www.postgresql.org/docs/current/transaction-iso.html section
> 13.2.1:
> BEGIN;
> UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 12345;
> UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 7534;
> COMMIT;
> The acctnum is expected to be 12345 in both cases.
No, I think that's intentional: the example depicts transferring
$100 from account 7534 to account 12345.
regards, tom lane
Re: bytea documentation error
PG Doc comments form writes: > I believe there is a documentation error in the example for "8.4.1 bytea Hex > Format" > (https://www.postgresql.org/docs/current/datatype-binary.html#id-1.5.7.12.9). > The example is > `SELECT '\xDEADBEEF';` > However, when I try that on my system [psql (13.9 (Ubuntu > 13.9-1.pgdg20.04+1), server 13.10 (Ubuntu 13.10-1.pgdg20.04+1))], it works > *but* the result is type `text` per `pg_typeof()`. I believe the example > needs to be corrected with an explicit cast to `bytea`. Yeah, that's not really right. Also, this example is pretty shoddy compared to the one for escape format a little further down. Will fix, thanks for the report! regards, tom lane
Re: Publishing Postgres Manual as a book
Erik Wienhold writes: > On 23/03/2023 04:34 CET Ian Lawrence Barwick wrote: >> Also not a lawyer, but the full sentence is: >>> Permission to use, copy, modify, and distribute this software and its >>> documentation for any purpose, without fee, and without a written agreement >>> is >>> hereby granted >> which in my non-lawyerly interpretation means anyone copying, modifying and >> distributing the documentation may do so without paying a fee. A distributor >> could charge what they like. > I know the fee clause from licenses such as Zero-Clause BSD, ISC License, and > GPLv3. They state "with or without fee" or "gratis or for a fee" pertaining > to > the distribution. That's also how I interpret the fee clause in the > PostgreSQL > license with the difference that it does not permit taking a fee. No, I agree with Ian: our license says that the Postgres project does not require a fee. It does not say that someone redistributing the material can't charge for their efforts. It would obviously be ridiculous to expect someone to print a multi-thousand-page book and then give it away for free. I do question the practicality and environmental cost of putting such short-lived material on dead trees, though ... regards, tom lane
Re: Seeming contradiction in 22.1
"David G. Johnston" writes:
> The root issue, IMO, is that all packagers have settled on the convention
> of using Postgres for the superuser name, so if one only ever sees that, it
> is easy to assume it is some kind of default of the software itself. In
> the face of consistent evidence, people not reading the documentation is my
> supposed assumption for their ignorance of this point. But reading the
> docs, it is clear how the system really works (I.e., the name of the
> bootstrap superuser comes is derived at initdb time from the environment
> executing initdb).
I agree that the docs are not incorrect as they stand, but maybe they
could be phrased a little more clearly. The "Customarily," bit is perhaps
too terse. I'm thinking about wording like
This role is always a “superuser”, and by default it will have the
same name as the operating system user that initialized the database
cluster, unless another name is specified while running initdb.
It is common, but not required, to arrange for this role to be named
postgres.
regards, tom lane
Re: Publishing Postgres Manual as a book
Siddharth Jain writes:
> to follow up, does Postgres have any official legal contact person / email
> address? i can't find any on the website.
Typically, legal questions should be sent to the core team.
(To clarify: although I am a core team member, my previous response
was not speaking for core, just myself.)
regards, tom lane
Re: Split_Part w/negative integer does not work
PG Doc comments form writes:
> Page: https://www.postgresql.org/docs/15/functions-string.html
> Documentation
> split_part ( string text, delimiter text, n integer ) → text
> Splits string at occurrences of delimiter and returns the n'th field
> (counting from one), or when n is negative, returns the |n|'th-from-last
> field.
> split_part('abc~@~def~@~ghi', '~@~', 2) → def
> split_part('abc,def,ghi,jkl', ',', -2) → ghi
> Observation
> SELECT split_part('abc,def,ghi,jkl', ',', -1);
> generates
> ERROR: field position must be greater than zero
> SQL state: 22023
Apparently, you are reading the v15 documentation and expecting it
to be exactly correct for some older server version. The described
behavior came in in v14.
regards, tom lane
Re: Minor typo in 13.3.5. Advisory Locks
PG Doc comments form writes: > Page: https://www.postgresql.org/docs/15/explicit-locking.html > After the code snippet in the 6th paragraph of 13.3.5. Advisory Locks > (https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS) > I believe there is a mistake in this sentence (I've surrounded it with > asterisks): > "In the above queries, the second *form* is dangerous because the > LIMIT...". > I believe that "form" in the above sentence is actually meant to be "from", > referencing the second line of code and its FROM clause in the snippet. No, I think "form" is exactly what was meant. Maybe we should have said "second query" or something like that, though. regards, tom lane
Re: Minor typo in 13.3.5. Advisory Locks
Daniel Gustafsson writes: > Reading this section I agree that the mix of ok/danger in the same example can > be tad misleading though. Something like the attached is what I would prefer > as a reader. I think in your rewrite, "this query" is dangling a bit because there's several sentences more before the query actually appears. I suggest ordering things more like: expressions are evaluated. For example, this query is dangerous because the LIMIT is not guaranteed to be applied before the locking function is executed: SELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger! This might cause some locks to be acquired that the application was not expecting, and hence would fail to ... On the other hand, these queries are safe: SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok ... Separately from that: now that I look at this example, it's really quite safe for any plausible plan shape. It used to be dangerous if you had an ORDER BY, but there's no ORDER BY, and even if there were we fixed that in 9118d03a8. Do we want to choose another example, and if so what? The "not guaranteed" wording isn't really wrong, but an example that doesn't do what we're saying it does isn't good either. regards, tom lane
Re: doc build error on Fedora 38
Devrim =?ISO-8859-1?Q?G=FCnd=FCz?= writes: > On Thu, 2023-04-06 at 20:18 +0800, Julien Rouhaud wrote: >> have >> you installed the required packages for that now that those files are >> available only via https, which isn't supported by any tool? > :-( Indeed, that is the problem. Apparently my script failed to install > docbook-dtds adn docbook-style-xsl while building Fedora 38 box. See also this recent change: https://git.postgresql.org/gitweb/?p=postgresql.git&a=commitdiff&h=969509c3f Those doc changes haven't shipped yet, but the it-doesn't-work situation has been true for awhile. regards, tom lane
Re: Should 'sum(mvf)' read 'sum(mcv)'...?
Daniel Gustafsson writes:
> I was inclined to spell it out as mcv_frequencies but we use xxx_freqs
> elsewhere on the same page so keeping it consistent seems better. The
> attached
> does this as well as adding mcf/mcv as acronyms as previously mentioned (since
> they are both tagged as ).
mcv_freqs looks good. I'd write the glossary entries as singular
(Most Common Frequency, Most Common Value) since our typical usage
is to pluralize them at the point of use ("MCVs"). Also, just
expanding the acronym doesn't seem that helpful. Maybe more like
MCF
Most Common Frequency, that is the frequency associated
with some Most Common Value
MCV
Most Common Value, one of the values appearing most often
within a particular table column
regards, tom lane
Re: Incorrect link tohttps://www.postgresql.org/docs/current/indexes-functional.html ?
PG Doc comments form writes:
> I found incorrect link to
> https://www.postgresql.org/docs/current/indexes-functional.html on this page
> https://www.postgresql.org/docs/7.3/indexes-functional.html.
PG 7.3 has been out of support for more than fifteen years. Nobody
is going to correct any errors that may exist in those doc pages.
They're just there for historical reference.
regards, tom lane
Re: Incorrect link tohttps://www.postgresql.org/docs/current/indexes-functional.html ?
Daniel Gustafsson writes: > This is actually not an error in the 7.3 docs (which we clearly wouldn't > address) but an error in pgweb in the warning for unsupported versions; it > assumes it can link to the same page in /current. Ah, good point. And it does know that the page doesn't exist in /current, because the "same page in other versions" list just above doesn't include that. Maybe we could have the link to "current" point to the docs top level instead of the specific page in such cases? Or simpler, just omit the "You may want to view the same page..." sentence altogether. regards, tom lane
Re: tables on pgbench man page look garbled
Daniel Gustafsson writes:
> I took a look at this using macOS as the initial testbed; the TLDR is that
> mandoc doesn't support macros in tables, and our single-column function
> signature tables rely on that. macOS switched to mandoc in v11 I think, but I
> don't have an older box handy to doublecheck.
Hmm, any chance of addressing this by expanding out the relevant macros?
regards, tom lane
Re: Typo
Laurenz Albe writes: > On Wed, 2023-05-24 at 07:32 +0900, Michael Paquier wrote: >> This is the current sentence, and it sounds kind of OK to me, FWIW: >> "Postgres95 code was completely ANSI C and trimmed in size by 25%. > That uses "ANSI C" as an adjective, which I think is sloppy wording > (even though English is somewhat relaxed about the distinction between > classes of words). Yeah, it's not great English, but it's not awful English either; just a rather telegraphic (abbreviated) style. Here's the thing: at this point, this documentation is itself a historical artifact. git excavation dates the current wording to 8baa8fcf4 of 1999-06-21, and that was just a small adjustment of c8cfb0cea of 1998-03-01, and it seems likely that that was pulled verbatim from some older source. So I'm disinclined to change it on grounds of "I think the grammar is a bit shaky". It is what it is. regards, tom lane
Re: Sequence Dependency
"David G. Johnston" writes:
> On Saturday, June 10, 2023, Umut TEKİN wrote:
>> it does not create any pg_depend entry for this sequence and table pair. So,
>> it is not possible to track down to find the pairs. Is there any other way
>> to find the sequence and the table pairs created using method 2?
> You can alter a manually created sequence to be owned by a table and thus
> get the dependency added even in the second case.
Yeah, that would be the way to match what SERIAL does (see [1]).
In the quoted example, there is a dependency from the column's default
expression to the sequence, so you could still detect the connection
without the ownership dependency; it's just harder. You have
regression=# select pg_describe_object(classid,objid,objsubid) as obj,
pg_describe_object(refclassid,refobjid,refobjsubid) as ref, deptype from
pg_depend where objid >= 'public.actor_actor_id_seq'::regclass order by objid,
refobjid;
obj |
ref | deptype
-+-+-
sequence actor_actor_id_seq | schema public
| n
table actor | schema public
| n
type actor[]| type actor
| i
type actor | table actor
| i
default value for column actor_id of table actor| sequence
actor_actor_id_seq | n
default value for column actor_id of table actor| column actor_id of table
actor | a
default value for column last_update of table actor | column last_update of
table actor | a
toast table pg_toast.pg_toast_89174 | table actor
| i
index pg_toast.pg_toast_89174_index | column chunk_id of toast
table pg_toast.pg_toast_89174 | a
index pg_toast.pg_toast_89174_index | column chunk_seq of
toast table pg_toast.pg_toast_89174 | a
(10 rows)
versus
obj | ref
| deptype
-+-+-
sequence fruits_id_seq | schema public
| n
sequence fruits_id_seq | column id of table fruits
| a
table fruits| schema public
| n
type fruits[] | type fruits
| i
type fruits | table fruits
| i
default value for column id of table fruits | sequence fruits_id_seq
| n
default value for column id of table fruits | column id of table fruits
| a
toast table pg_toast.pg_toast_89182 | table fruits
| i
index pg_toast.pg_toast_89182_index | column chunk_seq of toast table
pg_toast.pg_toast_89182 | a
index pg_toast.pg_toast_89182_index | column chunk_id of toast table
pg_toast.pg_toast_89182 | a
index fruits_pkey | constraint fruits_pkey on table
fruits | i
constraint fruits_pkey on table fruits | column id of table fruits
| a
(12 rows)
regards, tom lane
[1]
https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL
Re: Change "two" to "three" for decades of development in history
Michael Paquier writes:
> "With multiple decades of development behind it, PostgreSQL.."
+1. It sure seems silly trying to automate changing this.
regards, tom lane
Re: bad choice of the word in sentence
Bruce Momjian writes: > On Thu, Jun 22, 2023 at 06:38:37PM +, PG Doc comments form wrote: >> Quote: >> "<...>When a transaction uses this isolation level, a SELECT query (without >> a FOR UPDATE/SHARE clause) sees only data committed before the query began; >> it never sees either uncommitted data or changes committed during query >> execution by concurrent transactions. <...>" >> Don't you think this is bad choice of the word, especially while speaking >> about "commiting transactions" in very same sentence? > No, the issue is only for committed transactions, not aborted ones. I think this sentence is formally correct, but it is not very hard to misparse. Maybe a bit of re-ordering would help? Like ... it never sees either uncommitted data or changes committed by concurrent transactions during the query's execution. regards, tom lane
Re: bad choice of the word in sentence
Bruce Momjian writes:
> On Fri, Jun 23, 2023 at 09:16:39PM -0400, Tom Lane wrote:
>> I think this sentence is formally correct, but it is not very hard to
>> misparse. Maybe a bit of re-ordering would help? Like
>> ... it never sees either uncommitted data or changes committed by
>> concurrent transactions during the query's execution.
> Sure.
Done that way.
regards, tom lane
Re: Bug in documentation: https://www.postgresql.org/docs/current/spi-examples.html
"David G. Johnston" writes: > On Mon, Jul 17, 2023 at 4:53 PM Curt Kolovson wrote: >> The actual results (shown below) are different than shown on this doc >> page. > SPI_exec sees "INSERT 0 2" as the command tag from the SQL command you > passed and so 2 is the output of the execq function call. > No INFO messages appear because you did not include a returning clause. > The 1 you passed to the call is immaterial if the query you supply doesn't > produce a result set. I think his point is that this example does not behave as the documentation claims. Which it does not, according to my tests here. I find this a bit disturbing --- did we intentionally change the behavior of SPI_exec somewhere along the line? regards, tom lane
Re: Bug in documentation: https://www.postgresql.org/docs/current/spi-examples.html
"David G. Johnston" writes: > On Mon, Jul 17, 2023 at 6:22 PM Tom Lane wrote: >> I think his point is that this example does not behave as the >> documentation claims. Which it does not, according to my >> tests here. I find this a bit disturbing --- did we intentionally >> change the behavior of SPI_exec somewhere along the line? > Appears to be a documentation fix oversight back in v9.0 > https://github.com/postgres/postgres/commit/2ddc600f8f0252a0864e85d5cc1eeb3b9687d7e9 Ah, thanks for the pointer. I'd just been trying to bisect where between 8.4 and 9.0 it changed, but failed because early-9.0 versions don't build at all with current bison :-( Anyway, given that the example needs updating, how should we do that exactly? Is it worth demonstrating both the behavior with RETURNING and that without? If not, which one to show? regards, tom lane
Re: Bug in documentation: https://www.postgresql.org/docs/current/spi-examples.html
"David G. Johnston" writes:
> On Mon, Jul 17, 2023 at 7:45 PM Curt Kolovson wrote:
>> I’d vote for showing both (with RETURNING and without), since without it
>> the second argument to SPI_exec has no effect in this example, which may
>> not be obvious. That seems to be one of the subtle points illustrated by
>> this example.
> I concur:
Agreed. Done at 137b131d6.
regards, tom lane
Re: IN for records
PG Doc comments form writes:
> In section #FUNCTIONS-COMPARISONS-IN-SCALAR operator IN is described as a
> expression for scalars, and as a shorthand notation for a combination of
> operators || and =
> In section #COMPOSITE-TYPE-COMPARISON described extension, to use operators
> with a records, like "record operator record" for uncertain set of
> operators, and noted "Composite type comparisons are allowed when the
> operator is =, <>, <, <=, > or >=, or has semantics similar to one of
> these." and with a some difficult to understand note about B-trees.
> And as result, I can't see a direct description for allowance to use a
> syntax like a "(key_part_1, key_part_2) IN ( ('B',1), ('C',2) )"
I think perhaps you are reading too much into the word "scalar" in
the description of IN (and NOT IN). In this context I believe it
just means "not a set-returning expression". IN works fine on
container types such as records and arrays.
I'm inclined to propose that we simply drop the word "scalar" in
those two paragraphs. It's adding more confusion than clarity.
> So I propose to mention record types in section
> #FUNCTIONS-COMPARISONS-IN-SCALAR. Phrase "The right-hand side is a
> parenthesized list of scalar expressions." can be replaced to phrases "The
> right-hand side is a parenthesized list of scalar or record expressions.
> About records [see further](#COMPOSITE-TYPE-COMPARISON)"
> Also I propose make similar adjustments in other sections of this page, and
> make cross-links here and in a
> https://www.postgresql.org/docs/current/functions-subquery.html page near
> the text mentions of each others.
I think this approach would end in a spaghetti mess of cross-references,
again adding more confusion than clarity.
I do agree that "9.24.5. Row Constructor Comparison" could use some work.
For starters, I think we should drop both of the existing items.
The one about pre-8.2 bugs is surely long past its sell-by date. As for
the other one, I have no idea what it's even talking about: we do resolve
all the comparison operators at parse time, and did so for years before
this note came in. It's certainly too vague to be useful as it stands.
I don't much like "Every row element must be of a type which has a default
B-tree operator class or the attempted comparison may generate an error"
either, as it's confusing and not very accurate. Looking at the code,
I think a better initial paragraph might be like
Each side is a row constructor,
as described in .
The two row values must have the same number of fields.
Each side is evaluated and they are compared row-wise.
The named operator is applied to each pair of corresponding row fields.
(Since the fields could be of different types, this means that a
different specific operator could be selected for each pair.)
All the selected operators must be members of some B-tree operator
class, or be the negator of the = member of a B-tree operator
class, meaning that row constructor comparison is only possible
when the operator is
=,
<>,
<,
<=,
> or
>=,
or has semantics similar to one of these.
after which we can go on with the bit about "The = and <> cases work
slightly differently..."
regards, tom lane
Re: CREATEROLE Inheritance
PG Doc comments form writes: > I have checked this for CREATEROLE and this role attribute is definitely > inheritable. Does not look like that to me: regression=# create user alice createrole; CREATE ROLE regression=# create user bob; CREATE ROLE regression=# \c - alice You are now connected to database "regression" as user "alice". regression=> create user charlie; -- should succeed CREATE ROLE regression=> \c - bob You are now connected to database "regression" as user "bob". regression=> create user delta;-- should fail ERROR: permission denied to create role DETAIL: Only roles with the CREATEROLE attribute may create roles. regression=> \c - postgres You are now connected to database "regression" as user "postgres". regression=# grant alice to bob; GRANT ROLE regression=# \c - bob You are now connected to database "regression" as user "bob". regression=> create user delta;-- still fails ERROR: permission denied to create role DETAIL: Only roles with the CREATEROLE attribute may create roles. regression=> set role alice; SET regression=> create user delta;-- now it works CREATE ROLE (Those DETAIL messages are fairly new, but the behavior is the same in older branches.) The point is precisely that bob can't make use of alice's CREATEROLE bit without having done SET ROLE. It's not too clear to me what you did that led you to conclude otherwise, but going through additional layers like an IDE could well be confusing matters. regards, tom lane
Re: IN for records
Ilya Nenashev writes: > I totally agree. > Who and when will put these changes into the documentation pages? Done at https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=15c68cd84a2c80eed9b67ed6746ed5b91baea587 regards, tom lane
Re: U+200B ZERO WIDTH SPACE (0xe2 0x80 0x8b) in PostgreSQL documentation
PG Doc comments form writes:
> In official html documentation there are issue U+200B ZERO WIDTH SPACE (0xe2
> 0x80 0x8b) in text of some keywords, some identificators and some literals.
> When copy-pasting to the SQL command, an error occurs because of this.
> For example in page infoschema-administrable-role-authorizations.html on
> site
> (https://www.postgresql.org/account/comments/new/15/infoschema-administrable-role-authorizations.html/)
Yeah. Those are there to allow line breaks in the PDF output, which
would otherwise be too wide in those places. If you know a way to get
the XML toolchain to allow line breaks in PDF without putting
invisible characters into other formats, let us know.
regards, tom lane
Re: group by can use alias from select list
Bruce Momjian writes: > On Tue, Jul 11, 2023 at 07:31:26AM -0700, David G. Johnston wrote: >> I think the complaint is that someone seeing the behavior in the wild comes >> to >> this order-of-operations and doesn't see that the observed behavior is >> documented. > How is the attached patch? Maybe better "Although query output columns are nominally computed in the next step, they can also be referenced (by name or by ordinal number) as GROUP BY elements". You could go further and add "Such references cannot be parts of GROUP BY expressions, however." Not sure if we cover that explicitly anywhere else. regards, tom lane
Re: Incorrect/confusing information about timetz
Bruce Momjian writes: > Uh, yes to the storage part, no to the output part. ;-) Postgres does > store the timetz time zone offset, but it doesn't adust it once it is > stored so doesn't adjust for the session time zone: Right, it just stores a numeric UTC offset. > Do we want to document this? Section 8.5.1.2. Times already says "The appropriate time zone offset is recorded in the time with time zone value." Maybe that could be made a little more precise, say "The resolved numeric offset from UTC is recorded in the time with time zone value." regards, tom lane
Re: Typo/wording on https://www.postgresql.org/docs/current/catalog-pg-class.html
Daniel Gustafsson writes: >> On 20 Sep 2023, at 07:23, PG Doc comments form >> wrote: >> I've just read this: >> "catalogs tables and most everything else that has columns or is otherwise >> similar to a table" >> It seems that it should be: >> "catalogs tables and almost everything else that has columns or is otherwise >> similar to a table" > While I'm not a native english speaker I do believe this wording is correct > (although I guess your version would be semantically the same or very close to > it). It was done in commit 83501ef4ca some 20+ years ago. "Most" here is good English, although I concede it's a slightly old-fashioned usage. Maybe it'd be clearer to just remove the word altogether. If we were going to touch this sentence I'd worry about some other things too. Use of "catalogs" as a verb is probably not the greatest choice right here, since one could easily think that the verb is missing and what was meant was "pg_class lists catalogs, [user] tables, and ...". Also, I think that the reference to special relations is obsolete --- we don't list any relkind for that anymore. What probably does deserve to be called out in place of those is composite types, since their appearance in pg_class might be pretty surprising to newbies. regards, tom lane
Re: Typo/wording on https://www.postgresql.org/docs/current/catalog-pg-class.html
I wrote: > "Most" here is good English, although I concede it's a slightly > old-fashioned usage. Maybe it'd be clearer to just remove the > word altogether. > If we were going to touch this sentence I'd worry about some other > things too. Use of "catalogs" as a verb is probably not the greatest > choice right here, since one could easily think that the verb is > missing and what was meant was "pg_class lists catalogs, [user] > tables, and ...". Also, I think that the reference to special > relations is obsolete --- we don't list any relkind for that anymore. > What probably does deserve to be called out in place of those is > composite types, since their appearance in pg_class might be pretty > surprising to newbies. Hmm, I must have been looking at some old version of the docs, because when I went to prepare a draft patch I found that those last couple of points were addressed some time ago. I think we just need some slightly better wording here rather than any change of technical content. I propose the attached. (I also modified the para's last sentence to speak of "kind" not "type", for consistency with the relkind field name and the rest of the para.) regards, tom lane diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index d17ff51e28..e09adb45e4 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1893,8 +1893,8 @@ SCRAM-SHA-256$<iteration count>:&l - The catalog pg_class catalogs tables and most - everything else that has columns or is otherwise similar to a + The catalog pg_class describes tables and + other objects that have columns or are otherwise similar to a table. This includes indexes (but see also pg_index), sequences (but see also <iteration count>:&l views, materialized views, composite types, and TOAST tables; see relkind. Below, when we mean all of these kinds of objects we speak of - relations. Not all columns are meaningful for all relation - types. + relations. Not all of pg_class's + columns are meaningful for all relation kinds.
Re: Typo/wording on https://www.postgresql.org/docs/current/catalog-pg-class.html
Daniel Gustafsson writes: >> On 22 Sep 2023, at 19:04, Tom Lane wrote: >> I propose the attached. (I also modified the para's last sentence to >> speak of "kind" not "type", for consistency with the relkind field name >> and the rest of the para.) > LGTM. Pushed, thanks for looking. regards, tom lane
Re: JSON type unsupported
Vik Fearing writes: > Thank you for pointing this out. Peter's blog is slightly misleading in > that we do have the JSON data type, but the T801 feature is far from > complete. > For example, we do not have the JSON_SERIALIZE(), JSON()[1], > JSON_SCALAR() functions. We don't have the IS JSON predicate, or a few > other things hiding behind T801. > All in all, I would not say we support the JSON data type the way the > standard intends, and therefore we should not claim to support T801. Agreed, but should we say "partial support", as we do for some other feature identifiers? regards, tom lane
Re: Is CREATE INDEX dependent on the session?
Laurenz Albe writes: > On Wed, 2023-09-27 at 11:23 -0400, Ilya Priven wrote: >> Would it warrant a clarification in the documentation: >> - Whether CREATE INDEX is aborted if the session is disconnected, assuming >> it's not in a transaction? > It is aborted as soon as the server realizes that the client is gone, which > may > take a while (see the keepalive parameters and > "client_connection_check_interval"). Note that unless you change client_connection_check_interval to a nondefault value, the server will not notice that the client is gone until it tries to send or receive data. So a command like CREATE INDEX will typically run to completion even if the client drops the connection. I don't think keepalive settings affect this --- they might cause the kernel to realize that the connection is lost earlier than it otherwise would, but that doesn't result in an automatic kill of the server process. > Do you want to propose a patch? There are enough environmental dependencies involved here that any simple description is likely to contain lies. So I'm hesitant to try to put anything about it into the docs. regards, tom lane
Re: `pg_restore --if-exists` clarification
"David G. Johnston" writes: >>> .. But pragmatically it doesn't matter, so why not >>> reclassify this as a "warning" or a "notice"? > Because pg_restore is just a client and it is repeating back what the > server tells it. And for the server it is an error to drop an object that > doesn’t exist. > psql and pg_restore, as clients, can choose to ignore the errors they see, > regardless of what kind of error it is, but they don’t take on the added > burden of trying to reclassify errors into something else. If you actually try this, you'll get output like ... pg_restore: error: could not execute query: ERROR: schema "fkpart6" does not exist Command was: DROP SCHEMA fkpart6; pg_restore: error: could not execute query: ERROR: schema "fkpart5" does not exist Command was: DROP SCHEMA fkpart5; pg_restore: error: could not execute query: ERROR: schema "fkpart4" does not exist Command was: DROP SCHEMA fkpart4; pg_restore: error: could not execute query: ERROR: schema "fkpart3" does not exist Command was: DROP SCHEMA fkpart3; ... pg_restore: warning: errors ignored on restore: 1488 so the only real problem is that there are (typically) enough of these to obscure any errors that might be of greater significance. Still, genuine restore errors would come out after the blizzard of failed DROPs, so I don't think there's a big problem in practice. If we actually wanted to change any behavior here, I think what would be most profitable to discuss is making --if-exists the default. Not sure if we want to go there, but if we'd had the DROP IF EXISTS option all along I bet it would have been done that way. In any case, it's fair to complain about the documentation. How about --clean Before restoring database objects, issue commands to DROP all the objects that will be restored. This option is useful for overwriting an existing database. If any of the objects do not exist in the destination database, ignorable error messages will be reported, unless --if-exists is also specified. --if-exists Use DROP ... IF EXISTS commands to drop objects in --clean mode. This suppresses "does not exist" errors that might otherwise be reported. This option is not valid unless --clean is also specified. regards, tom lane
Re: `pg_restore --if-exists` clarification
=?UTF-8?Q?Guly=C3=A1s_Attila?= writes:
> I would love to see Tom's version in the docs! It is only slightly longer
> than the current one, but absolutely clear of the purpose of both, and the
> behaviour when used in tandem.
Hearing no objections, done at
https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=75af0f401f905b947ea14401e8a51f1bae4ac265
regards, tom lane
Re: The documentation for storage type 'plain' actually allows single byte header
Laurenz Albe writes: > On Fri, 2023-09-29 at 18:19 -0400, Bruce Momjian wrote: >> Where did we end with this? Is a doc patch the solution? > I don't think this went anywhere, and a doc patch is not the solution. > Tom has argued convincingly that single-byte headers are an effect of the > TOAST > system, and that STORAGE PLAIN should disable all effects of TOAST. Well, that was the original idea: you could use STORAGE PLAIN if you had C code that wasn't yet toast-aware. However, given the lack of complaints, it seems there's no non-toast-aware code left anywhere. And that's not too surprising, because the evolutionary pressure to fix such code would be mighty strong, and a lot of time has passed. I'm now inclined to think that changing the docs is better than changing the code; we'd be more likely to create new problems than fix anything useful. I wonder though if there's really just one place claiming that that's how it works. A trawl through the code comments might be advisable. regards, tom lane
Re: examples for windows functions
Giampaolo Capelli writes:
> I'd like to propose to add some examples to the following page
> https://www.postgresql.org/docs/16/functions-window.html
> The syntax of window functions is fully covered by the page
> https://www.postgresql.org/docs/16/sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS
> but I think it would be helpful to put some examples in
> https://www.postgresql.org/docs/16/functions-window.html
That page starts out with a link to section 3.5 which is
full of examples. Seems a bit repetitive to put more here.
regards, tom lane
Re: INT4RANGE Upper bound always includes a higher number
PG Doc comments form writes: > According to your example (copied from your docs): > -- includes 3, does not include 7, and does include all points in between > SELECT '[3,7)'::int4range; > But this is not true, it shows 3 and 7 What's not true about it? postgres=# SELECT 3 <@ '[3,7)'::int4range; ?column? -- t (1 row) postgres=# SELECT 6 <@ '[3,7)'::int4range; ?column? -- t (1 row) postgres=# SELECT 7 <@ '[3,7)'::int4range; ?column? -- f (1 row) 7 is not a member of that range, only an endpoint. > And if i do: > SELECT '(3,7]'::INT4RANGE; > It shows: > [4,8) > (1 row) This is a consequence of canonicalization. There are four different ways to write the same integer range: [3,6] [3,7) (2,6] (2,7) All of these include 3,4,5,6 and no other integer. INT4RANGE has a canonicalize function that converts ranges into the "[m,n)" form so that ranges that are functionally identical look identical. If you don't like that, you can make a user-defined range type with a different canonicalize function, or none at all. See https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-DISCRETE regards, tom lane
Re: Corresponding documentation page does not mention about `spread` mode
"David G. Johnston" writes: > On Tue, Oct 3, 2023 at 2:48 PM PG Doc comments form > wrote: >> But mentioned section 26.3.3 does not describe `spread` mode: > It does, though it is phrased in terms of "fast => false" meaning "spread" > whereas "fast => true" means "immediate". > But since the CLI wanted a label instead of true/false it had to call the > default "not fast" mode something and it chose "spread". > Not saying this couldn't be made more clear/better but it is accurate and > complete. Perhaps a parenthetical remark like "(pg_basebackup refers to this as 'spread' mode)" would help? regards, tom lane
Re: Missing closing ]
PG Doc comments form writes:
> In the example session at
> https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-EXAMPLES
> there are missing closing square bracket ]
> Take a look below
> CREATE TABLE reservation (room int, during tsrange);
> INSERT INTO reservation VALUES
> (1108, '[2010-01-01 14:30, 2010-01-01 15:30)');
> there should be ] after 15:30
No, it looks correct as given: that end of the range is open not closed.
regards, tom lane
Re: Typo in PL/pgSQL trigger Example 43.4?
"David G. Johnston" writes: > On Sat, Oct 7, 2023 at 11:11 AM Kirk Parker wrote: >> INSERT INTO emp_audit SELECT 'D', now(), user, OLD.*; -- <= ARGUMENT IN >> QUESTION >> The emp_audit table has a column named 'userid', which in actual usage >> (next-to-last line quoted) is populated by 'user' which seems undefined in >> the context. Was that intended to be 'current_user', or am I missing >> something? > user is a valid pseudo-function: > https://www.postgresql.org/docs/current/functions-info.html#FUNCTIONS-INFO-SESSION Yeah, either way has the same result. However, I wonder if we should change this example to use current_user for clarity. It does look more like it's intended to be a variable or column reference than a built-in function. regards, tom lane
Re: Typo in PL/pgSQL trigger Example 43.4?
Daniel Gustafsson writes: >> On 7 Oct 2023, at 22:22, Tom Lane wrote: >> Yeah, either way has the same result. However, I wonder if we should >> change this example to use current_user for clarity. It does look >> more like it's intended to be a variable or column reference than >> a built-in function. > Agreed, and "user" is a hard search term to use for discovering what it is. > +1 > for changing to current_user. OK, I'll take care of this later today. regards, tom lane
Re: 31.7.1. Initial Snapshot
Alvaro Herrera writes:
> On 2023-Oct-11, David G. Johnston wrote:
>> Improved formatting overall for the chapter ToC has merit.
> Great ...
+1. I've been annoyed by this ambiguity too. I agree that
artificially forcing pages to have at least two subsections
isn't a good fix.
regards, tom lane
Re: Clarify: default precision on timestamps is 6
Kirk Parker writes: > On Fri, Oct 13, 2023 at 7:32 AM David G. Johnston < > david.g.johns...@gmail.com> wrote: >> That is precisely what a no default with maximum of six means. If we say >> the default is six that would imply storage of less precise values pads >> significant zeros until there are six. > Not sure that last statement is correct. In 13 (only system I have access > to at the moment) it doesn't look like casting to a precision greater than > the value originally had causes any padding: The timestamp types don't have any explicit notion of precision (unlike, say, numeric). The stored value is an integer number of microseconds, nothing else. I've not checked the output function recently but it makes sense to me that it'd just drop trailing zeroes from the display, independently of any claimed precision for the column. Meanwhile, when casting a timestamp value to a declared precision, we handle that by just rounding off the microseconds count. This doesn't buy any space savings or anything like that, it's just for pro-forma compliance with the spec. I don't see anything particularly wrong with the existing docs. The limitation to 1-microsecond precision is spelled out in the table just above the para you quote. regards, tom lane
Re: "20.16. Customized Options" – cannot be set by `ALTER SYSTEM`
PG Doc comments form writes: > As far as I can tell, the following statement: >> PostgreSQL will accept a setting for any two-part parameter name > does not hold when creating a *new* setting with `ALTER SYSTEM`, e.g. > ALTER SYSTEM SET foo.bar TO 'baz'; > will elicit an error. ALTER SYSTEM requires the variable to be known, so that (a) it can figure out whether you have permissions to set it at system level, and (b) it can check the validity of the value. It does not seem like a good idea to allow unchecked values to be pushed into the config file, because a mistake would prevent future server restarts from succeeding. If you just do "SET foo.bar = whatever", the action is transiently allowed because nothing very interesting will happen until/unless some extension loads a definition of the variable into your session, and we can figure out at that point whether your setting should be accepted. It would be too much of a mess to make that work for ALTER SYSTEM though, not least because the config files don't record who set the variable. I do see an issue here: regression=# ALTER SYSTEM SET foo.bar TO 'baz'; ERROR: unrecognized configuration parameter "foo.bar" regression=# SET foo.bar TO 'baz'; SET regression=# ALTER SYSTEM SET foo.bar TO 'baz'; ALTER SYSTEM and now we have $ cat $PGDATA/postgresql.auto.conf # Do not edit this file manually! # It will be overwritten by the ALTER SYSTEM command. foo.bar = 'baz' So that feels like a bug: we should not allow ALTER SYSTEM to execute against a placeholder GUC definition, because the placeholder can't tell us whether the value is valid. I wonder though if forbidding this would break any legitimate usage patterns. regards, tom lane
Re: "20.16. Customized Options" – cannot be set by `ALTER SYSTEM`
Laurenz Albe writes: > On Mon, 2023-10-16 at 12:29 -0400, Tom Lane wrote: >> So that feels like a bug: we should not allow ALTER SYSTEM to execute >> against a placeholder GUC definition, because the placeholder can't >> tell us whether the value is valid. I wonder though if forbidding >> this would break any legitimate usage patterns. > I feel the same. However, the lack of any "variables" in SQL (as proposed > in [1]) leads a lot of people to abuse placeholder parameters as variables > to hold application state. I am sure that that is where this complaint > comes from. We maintain that doing so is not a valid use case, but that claim > sounds increasingly like a grammarian declaring that sentences should not > end with a preposition, when everybody does it all the time. Yeah, and we have been slowly removing the issues that made us not want to recommend using them like that. Anyway, I realized that I was wrong to claim that we need ALTER SYSTEM to defend us against bogus values of extension parameters in the config file. Checking is an important thing to do for core parameters, but a faulty extension parameter doesn't stop the system from booting. That's because we'll apply all the config file entries before we load any extensions, even ones listed in shared_preload_libraries. When we do load an extension, if it doesn't like what it finds in a placeholder then you get a WARNING and the parameter's default value is substituted. So there's no risk of an unstartable system. So maybe we should allow ALTER SYSTEM for unrecognized parameters, as long as the parameter name is syntactically legit and you're a superuser. regards, tom lane
Re: 'value' has special behaviour in alter system
Bruce Momjian writes:
> I have developed the attached patch to document this.
This seems a little imprecise:
+ Values with non-alphanumeric characters must be quoted.
I think accurate is more like "Values that are neither a number
nor a valid identifier must be quoted."
Also, that para already mentions that the input can be a
comma-separated list when appropriate, so your add-on para seems
partially repetitive. I think you could just drop the first
sentence of it.
regards, tom lane
Re: Discrepancy between the documentation and the implementation
PG Doc comments form writes: > In the documentation for Postgres 15, on page > https://www.postgresql.org/docs/15/ecpg-sql-set-connection.html, it states > that one can write: > SET CONNECTION connection_name > And under that, it talks about "connection_name" and DEFAULT, which is > supposed to be used in order to use the "default connection". > However, "SET CONNECTION DEFAULT" is treated by ECPG as a normal connection > name (looking for a connection named "DEFAULT"), not as a special keyword > meaning to go back to using the "default" connection. > Is there something I'm missing there ? I don't see it either. Both that and EXEC SQL DISCONNECT claim that DEFAULT is a specially treated name, but I don't see anything in the underlying code that treats it differently. Perhaps there was an intention to have some such feature but it never got done? Anyway, I don't see anything indicating that there's actually such a concept as "the default connection". I suggest we just remove those paragraphs. What *is* treated specially is CURRENT --- but EXEC SQL SET CONNECTION = CURRENT is effectively a no-op, so it's not very exciting. regards, tom lane
Re: Example 43.6. A PL/pgSQL Trigger Function for Maintaining a Summary Table
Daniel Gustafsson writes: > Thanks, I'll await pushing and backpatching if Tom who committed it has > insights into whether it was missed or if it indeed serves a purpose. Hey, I just pushed that for somebody else, I don't claim authorship ;-) It seems clear that the example intends to show a star-schema database where the fact table refers to various dimension tables. But it's incomplete --- there's no foreign-key constraint on time_key, and even less infrastructure for product_key or store_key. I don't have the cited book either, so I don't know how complete the original example was. Perhaps the bit in the trigger function about forbidding updates to time_key has something to do with that model. Anyway, I don't see any reason to object to this patch. The extra table isn't adding much. My only thought is would it make sense to change time_key to be a timestamp or timestamptz value? regards, tom lane
Re: "22.3. Template Databases" documentation is incomplete
Bruce Momjian writes:
> Sorry, I attached a _colorized_ diff; here is a normal one.
The new sentence is fine in isolation, but this doesn't feel like
a great spot to put it. The preceding several lines are all about
copying of objects within the database, and this isn't. In
particular, the antecedent of "it" is unclear and is different
from what "it" means in the immediately preceding sentence.
It might be best to split the thing out into its own para?
Something like
action being taken when those databases are created.
+
+ However, CREATE DATABASE does not copy
+ database-level GRANT permissions attached to the
+ source database. The new database has default permissions.
+
+
There is a second standard system database named
regards, tom lane
Re: 'pg_global' cannot be used as default_tablespace.
"David G. Johnston" writes:
> On Wednesday, November 1, 2023, Bruce Momjian wrote:
>> Did you want an error from the SET command?
> That would probably be a decent addition but the request was for us to add
> “it is not permissible to specify the pg_global tablespace for either
> default_tablespace or temp_tablespace”. In the tablespace section per the
> request but maybe also within the settings definition section.
But it *is* permissible, unless we add code to reject it during
SET as Bruce mentioned. Which seems fairly pointless to me. It's not
like there is anything unclear about the CREATE TABLE error message.
regards, tom lane
Re: 'pg_global' cannot be used as default_tablespace.
Bruce Momjian writes: > On Wed, Nov 1, 2023 at 06:32:37PM -0400, Tom Lane wrote: >> But it *is* permissible, unless we add code to reject it during >> SET as Bruce mentioned. Which seems fairly pointless to me. It's not >> like there is anything unclear about the CREATE TABLE error message. > Yeah, from the report I thought something bad happened if you tried to > use it and that is why we had to document it. By documenting it we are > just giving the user advice before they get the error. I wrote up this > minimal patch which might have the right level of detail to avoid > errors, if people think this is useful. I think this will lead to just as much confusion, because people will read it and expect that SET will fail. If we need to document any more than we have now, we should point out in the CREATE TABLE man page that you can't create a table in the pg_global tablespace. That will cover both this case and the case of trying to select pg_global explicitly in the CREATE. Another idea could be to adjust this bit in manage-ag.sgml: Two tablespaces are automatically created when the database cluster is initialized. The - pg_global tablespace is used for shared system catalogs. The + pg_global tablespace is used for shared system catalogs, + and cannot be used for user-defined tables. The pg_default tablespace is the default tablespace of the regards, tom lane
Re: 'pg_global' cannot be used as default_tablespace.
Bruce Momjian writes:
> I found a cleaner improvement, attached.
OK by me. Maybe that doesn't make the point strongly enough,
but we can hope it's enough.
regards, tom lane
Re: Incorrect mention of number of columns?
"Daniel Westermann (DWE)" writes:
> Creating a table with 1600 bigint columns does work with a 8k blocksize:
Yeah, but populating it would not (unless many of the columns were
NULL).
regards, tom lane
Re: Incorrect mention of number of columns?
"Daniel Westermann (DWE)" writes:
>> Yeah, but populating it would not (unless many of the columns were
>> NULL).
> Ok, but then should the documentation be more precise? It seems a bit odd to
> let users create such a table without at least a warning.
Given the impact of NULLs, and the fact that usually tables have some
variable-width columns, I doubt that a creation-time warning could be
accurate enough to be useful.
regards, tom lane
Re: Please make a note regarding the PL/pgSQL FOUND variable
PG Doc comments form writes:
> Since I was recently bitten by the fact that CREATE TABLE AS doesn't set the
> PL/pgSQL variable FOUND, it would be nice if that were explicitly noted in
> the documentation. Alternatively, if it COULD set the FOUND variable, that
> would be great, although I realize the difficulty of that when coupled with
> IF NOT EXISTS.
The documentation of FOUND is already quite explicit about which kinds
of statements set it:
https://www.postgresql.org/docs/current/plpgsql-statements.html#PLPGSQL-STATEMENTS-DIAGNOSTICS
I'm disinclined to put notes about PL/pgSQL features into command
reference pages that have nothing to do with PL/pgSQL.
regards, tom lane
Re: Example for Unique Partial Indexes
"David G. Johnston" writes: > On Tue, Nov 7, 2023, 09:25 PG Doc comments form > wrote: >> Currently, the documentation does not provide information on how to create >> unique partial indexes. Unique partial indexes are valuable for enforcing >> uniqueness of a column's value over a subset of a table > 11.8 discusses this in detail including an example. Maybe should add a > forward reference from 11.6 though. Yeah, AFAICS 11.8's coverage of this point is perfectly adequate. I'm disinclined to add a forward reference, because 11.8 is the first section that mentions partial indexes at all. Somebody reading the chapter in order would have no idea what we were talking about. regards, tom lane
Re: User mapping security
Bruce Momjian writes:
> On Tue, Jul 16, 2019 at 02:01:00AM +, PG Doc comments form wrote:
>> I suppose it should be warned on the pages that foreign credentials with be
>> stored as simple text and will be available for viewing in pg_user_mappings.
> I know this is four years old, but the attached patch documents it. I
> don't think postgresql-fdw needs it since it relies on user mapping and
> discourages passwords in the connection string.
This is far too alarmist. It ignores the privilege restrictions that
are built into the pg_user_mappings view. Random users can't see
umoptions.
regards, tom lane
Re: T is a mandatory date time separator in RFC3339 but documentation states differently
Erik Wienhold writes: > On 2023-11-13 15:24 +0100, Erik Wienhold wrote: >> I also noticed that when people say "ISO 8601" they usually mean RFC >> 3389 or some subset of ISO 8601. > Forgot this fine visualization of the differences: > https://ijmacd.github.io/rfc3339-iso8601/ I'm inclined not to change anything here, for a couple of reasons: 1. PG accepts a fairly large number of ISO 8601 variants (not all); not only the RFC 3339 format. So s/ISO 8601/RFC 3339/g would be incorrect. Besides, I think more people know what ISO 8601 is than know what RFC 3339 is, so that change would also be confusing. 2. If ijmacd's pretty graphic is correct, then what we say about 'T' versus space is correct, even if it isn't the whole truth. I'm not quite sure that ijmacd is correct, though, because of this bit in 3339: NOTE: Per [ABNF] and ISO8601, the "T" and "Z" characters in this syntax may alternatively be lower case "t" or "z" respectively. which suggests that 8601 is also case-insensitive. I don't plan to go buy a copy of that spec to find out, though. In any case, we accept 'T', 't', '_', and most other punctuation there, so we should be able to read nearly any plausible variant. regards, tom lane
Re: T is a mandatory date time separator in RFC3339 but documentation states differently
Erik Wienhold writes: > On 2023-11-15 12:53 +0100, Peter Eisentraut wrote: >> I think we should reframe "ISO" to mean "ISO 9075" and remove all claims of >> alignment with ISO 8601 and RFC 3339. > Agree. So just list the example inputs without any reference to a > particular standard, except for ISO 9075 to show that Postgres is > SQL-standard-compliant? I think that would remove useful context without actually improving anything. (The datetime input code would be far simpler if it meant only to read the exact format mentioned in the SQL spec.) regards, tom lane
Re: Additional Notes
Daniel Rinehart writes:
> Our callout use of NOTIFY within a TRIGGER may be tangential to the root
> cause. What we wanted to call out is that neither the NOTIFY page or the
> https://www.postgresql.org/docs/16/explicit-locking.html page mention that
> NOTIFY uses an AccessExclusiveLock.
Like Laurenz, I don't see this as being tremendously important.
The lock does not conflict with any user-acquirable lock, and
since it's not a lock on a relation it doesn't wind up getting
propagated to standby servers. We only use it as a handy way
to serialize commit of transactions that are writing the NOTIFY
queue. If it were a lesser but still exclusive lock type,
it wouldn't make any difference.
explicit-locking.html is really only about locks on tables.
Maybe that should be clarified somewhere?
regards, tom lane
Re: "name" vs "alias" in datatype table
Eric Hanson writes: > The larger point being, the "name" vs "alias" paradigm presented in this > table does not accurately represent PostgreSQL, and conveys an inaccurate > picture of the relationship between type names. int4 is not an "alias". I agree that this could be improved, mainly because it's far from clear what the internal name of each type is (and there's at least one case where the internal name is not shown at all). I could see splitting this into three columns: 1. Preferred name (the standard's name, if it's a standard type) 2. Internal name (pg_type.typname), perhaps only if different from #1 3. Other aliases However, the table is already pretty wide and so adding another column might create formatting issues. AFAICS the only candidates for "other aliases" are char, int, and decimal. Maybe we could handle those another way than reserving a table column for them? We could give them their own table rows, or relegate them to footnotes. The "serial" types need a bit more reflection too, since they aren't truly types at all: there is no matching pg_type entry. I'm not sure they belong here. regards, tom lane
Re: Typo in '8.5. Date/Time Types' v16
PG Doc comments form writes:
> In the interval example outputs, for postgres and postgres_verbose.
> It says mons instead of months.
That is in fact the datatype's output format.
regression=# show intervalstyle;
IntervalStyle
---
postgres
(1 row)
regression=# select '2 month'::interval;
interval
--
2 mons
(1 row)
regards, tom lane
Re: Section 4.1.2.3 repeats information presented in section 4.1.1
PG Doc comments form writes: > The following documentation comment has been logged on the website: > Page: https://www.postgresql.org/docs/16/sql-syntax-lexical.html > Description: > it just threw me off to read the exact same thing twice in quick succession, > I'd suggest linking to section 4.1.2.3 in section 4.1.1 instead. They are *not* the same. The quoting is different and the meaning is quite different, just as "slon" and 'slon' are not equivalent in SQL. Moreover, there's little reason to assume that somebody coming to 4.1.2.3 necessarily just read 4.1.1. Perhaps it'd be better to use different example strings though? regards, tom lane
Re: Documentation does not describes format for access privileges: =Tc/user
"David G. Johnston" writes:
> We probably should write the syntax like we do everywhere else:
> [grantee]={privilege[*]}[…]/grantor
> Then define the placeholders in the subsequent paragraph.
Seems reasonable. About like this?
regards, tom lane
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index d2951cd754..664361a724 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2318,8 +2318,12 @@ REVOKE ALL ON accounts FROM PUBLIC;
aclitem
The privileges that have been granted for a particular object are
- displayed as a list of aclitem entries, where each
- aclitem describes the permissions of one grantee that
+ displayed as a list of aclitem entries, each having the
+ format:
+
+grantee=privilege-abbreviations/grantor
+
+ Each aclitem describes the permissions of one grantee that
have been granted by a particular grantor. For example,
calvin=r*w/hobbes specifies that the role
calvin has the privilege
Re: Postgres compilation instructions do not work on modern debian or ubuntu
PG Doc comments form writes: > Page: https://www.postgresql.org/docs/16/install-make.html > Description: > Thanks for all your hard work, postgres is amazing. Small suggestion for > installation instructions on debian / ubuntu boxes: > apt install -yqq build-essential libreadline-dev zlib1g-dev flex bison > libxml2-dev libxslt-dev libssl-dev libxml2-utils xsltproc ccache git > libicu-dev pkg-config > works, what is listed misses git, libicu-dev and pkg-config There is nothing in the core PG documentation, either on the page you cite or anyplace else, that tries to specify exactly what other packages you might need to build from source on any particular distribution. We aren't very interested in trying to add such lists, precisely because they'd be constantly out of date. You might have found the above list somewhere else, but in that case you should be reporting the omissions somewhere else than here. > Even with the above, make world and make world-bin and make check, do not > succeed on arm64, so I've no idea if the build is reporting success, but > silently failing (I get return code zero, so it should pass a compile in > CI) Can't help you on that when you provide no details. PG certainly does work for many other people on Debian+arm64. regards, tom lane
Re: Problems when using unaccent
PG Doc comments form writes:
> I'm trying to query a database with unaccent, but PostgreSQL gives me
> exceptions:
> ERROR: function unaccent(character varying) does not exist at character
> 139
It looks like you haven't installed the unaccent extension in that
database. See
https://www.postgresql.org/docs/current/contrib.html
regards, tom lane
Re: incorrect description of Python try / except
PG Doc comments form writes:
> On page
> https://www.postgresql.org/docs/current/plpython-subtransaction.html,
> Note that the use of try/catch is still required.
> should read
> Note that the use of try/except is still required.
Right you are. Will fix, thanks!
regards, tom lane
Re: initdb username doc bug
"David G. Johnston" writes: > Or just the bit more verbose “user running the initdb command” and don’t > bother giving it a label, which is basically the approach used in the > description for initdb anyway. Or if you want a few more words, "name of the operating-system user running initdb". I don't like "installation user", that's just about as vague as could be. regards, tom lane
Re: Grammar suggestion
"David G. Johnston" writes: > I see where you are coming from but I think the word “need” is actual > problem and it has to go. We use the phrase “escapes satisfying” in the > subsequent sentence and should use it here too. Meh. I don't like the "escapes" construction too much; I think it's more confusing than "need not". But I agree that the two sentences should use parallel constructions. > Also, we go to the trouble of accepting “match partial”. Maybe add a final > sentence in this paragraph nothing that we do so and explaining what > partial is defined to mean in the standard? I'd be inclined not to. That info would fit in the reference page that covers this, but this is introductory material and shouldn't get too deep in the weeds. (Of course, if we ever did add MATCH PARTIAL, we'd have to explain it here. But nobody's done so in twenty years so I'm not holding my breath.) regards, tom lane
Re: initdb username doc bug
Bruce Momjian writes: > Agreed, updated patch attached. WFM. regards, tom lane
Re: Question on doc for RETURNING clause
"Russell, John" writes: > Hi, I was thinking of suggesting some doc clarifications and additional > examples related to the RETURNING clause. Just a couple of questions first to > see if my understanding is correct. > I was trying to figure out what the precise “thing” is that comes back from a > RETURNING clause. A table reference? A result set? I'd say it's a result set, just like the output of SELECT. > That made me think both a RETURNING clause could work in contexts such as CTE > (yes) and subquery (seems like no). We disallow DML in subqueries because there's a lot of squishiness around when a subquery is evaluated, whether it's evaluated to completion, or indeed whether it's evaluated more than once. CTEs have tighter semantics and so it's practical to require "exactly once" evaluation for CTEs. Partly this is a matter of historical expectations, but I doubt we'd consider revisiting it. >> PostgreSQL allows INSERT, UPDATE, and DELETE to be used as WITH queries. >> This is not found in the SQL standard. > Is MERGE allowed in that ^^^ context? Not yet, as you'd find out if you tried it. I think there's a patch in the pipeline to allow it. regards, tom lane
Re: SQL command : ALTER DATABASE OWNER TO
"David G. Johnston" writes:
> On Wed, Jan 24, 2024 at 8:35 AM Laurenz Albe
> wrote:
>> The permissions are transferred to the new owner, so the old owner doesn't
>> have any privileges on the object (and, in your case, cannot connect to
>> the database any more).
> I dislike this change, ownership of an object is completely independent of
> the grant system of privileges. The granted privileges of the old row do
> not transfer to the new owner when alter ... owner to is executed. The
> separate object attribute "owner" is the only thing that changes.
Laurenz is correct, as you can easily find out by testing. For
example,
regression=# create user joe;
CREATE ROLE
regression=# create database joe owner joe;
CREATE DATABASE
regression=# grant connect on database joe to joe;
GRANT
regression=# select datacl from pg_database where datname = 'joe';
datacl
---
{=Tc/joe,joe=CTc/joe}
(1 row)
regression=# create user bob;
CREATE ROLE
regression=# alter database joe owner to bob;
ALTER DATABASE
regression=# select datacl from pg_database where datname = 'joe';
datacl
---
{=Tc/bob,bob=CTc/bob}
(1 row)
If no explicit GRANTs have ever been done, so that the ACL column
is null, then it stays null --- but that has the same effect,
because the default privileges implied by the null entry now attach
to the new owner.
For myself, I thought Laurenz's proposed patch is an improvement.
regards, tom lane
Re: SQL command : ALTER DATABASE OWNER TO
"David G. Johnston" writes: > postgres=# grant all on database newdb2 to testowner; > -- as I am logged in as davidj this grant should actually happen, with > davidj as the grantor > -- the grants that materialize from ownership has the owning role as the > grantor Yes. The FM points out somewhere that if a superuser does a GRANT, it's executed as though by the object owner. That provision predates when we supported explicit GRANTED BY clauses in GRANT. I'm not sure we'd have made it work like that if we had GRANTED BY already, but I'm afraid of the compatibility implications if we change it now. regards, tom lane
Re: text and varchar are not equivalent
"David G. Johnston" writes: > On Fri, Feb 9, 2024, 10:12 PG Doc comments form > wrote: >> The documentation implies that the data types text and varchar are >> equivalent, but this is not the case with this test in Postgresql version >> 16. > Fair point. But I'd rather further emphasize that char should just be > avoided so this and other unexpected outcomes simply do not manifest in a > real database scenario. Rather than try and document how odd it's behavior > is when dealing with intra-textual type conversions. Yeah, this is less about varchar acting oddly and more about char acting oddly. The short answer though is that text is a preferred type, varchar is not, and that makes a difference when resolving whether to apply text's or char's equality operator. You can detect how it's being handled with EXPLAIN: regression=# explain verbose SELECT vc = ch AS vc_ch FROM test; QUERY PLAN --- Seq Scan on pg_temp.test (cost=0.00..17.88 rows=630 width=1) Output: ((vc)::bpchar = ch) (2 rows) regression=# explain verbose SELECT txt = ch AS txt_ch FROM test; QUERY PLAN --- Seq Scan on pg_temp.test (cost=0.00..19.45 rows=630 width=1) Output: (txt = (ch)::text) (2 rows) regards, tom lane
Re: Broken link in pgcrypto documentation
Magnus Hagander writes: > On Tue, Feb 13, 2024 at 7:12 PM Daniel Gustafsson wrote: >> However, I wonder if we aren't better off removing the "Useful Reading" >> section >> altogether? The field of crypto is continuously advancing and keeping a >> stale >> 10+ year old list of links is unlikely to provide more insights than what >> more >> curated sites can do. > +1. I don't think it's the job of a postgres contrib module to maintain that. +1. We haven't maintained that list in the past and it seems unlikely that we'll get better at it. I'm a little dubious about the "Technical References" list right below it, too. The RFC references are probably useful and stable, and maybe the wikipedia ref is OK, but I have little faith in either the stability or the long-term relevance of the other two links. regards, tom lane
Re: Broken link in pgcrypto documentation
Daniel Gustafsson writes: > On 13 Feb 2024, at 20:42, Tom Lane wrote: >> I'm a little dubious about the "Technical References" list right below >> it, too. The RFC references are probably useful and stable, and maybe >> the wikipedia ref is OK, but I have little faith in either the >> stability or the long-term relevance of the other two links. > Not even those are all that stable, while the RFCs' in question haven't been > replaced they have all been updated with new RFC's which we don't link to. I > think we are better off removing them as well and leaving reading up on > security/crypto subject an exercise for the reader. Good point. Nuking both lists works for me. regards, tom lane
Re: Missing | ?
Laurenz Albe writes:
> On Mon, 2024-02-19 at 09:37 +, PG Doc comments form wrote:
>> Page: https://www.postgresql.org/docs/16/sql-security-label.html
>> FOREIGN TABLE object_name
>>
>> ...probably should have a following "|", I think?
> Absolutely!
Indeed. Will fix, thanks for report!
regards, tom lane
Re: Typos in dectoint() and dectolong() function's descriptions
PG Doc comments form writes: > The first sentence in dectoint() and dectolong() function's descriptions > contains part with typo: "Convert a variable to type decimal to ...". > Should use "of" preposition here: "Convert a variable of type decimal to > ...". Yup, I think you're right. Thanks for the report! regards, tom lane
Re: substring start position behavior
Bruce Momjian writes: > This web page explains the feature: > > https://stackoverflow.com/questions/33462061/sql-server-substring-position-negative-value > but also asks: > now the only question that remains is, "why would anyone need it > to behave this way?" Yeah. I believe our implementation adheres to the SQL spec, which says this for (in SQL:2021 6.3.2): a) If the character encoding form of is UTF8, UTF16, or UTF32, then, in the remainder of this General Rule, the term “character” shall be taken to mean “unit specified by ”. b) Let C be the value of the , let LC be the length in characters of C, and let S be the value of the . c) If is specified, then let L be the value of and let E be S+L. Otherwise, let E be the larger of LC+1 and S. d) If at least one of C, S, and L is the null value, then the result of the is the null value. e) If E is less than S, then an exception condition is raised: data exception — substring error (22011). [tgl note: given c), this happens if and only if a negative is provided.] f) Case: i) If S is greater than LC or if E is less than 1 (one), then the result of the is the zero-length character string. ii) Otherwise, 1) Let S1 be the larger of S and 1 (one). Let E1 be the smaller of E and LC+1. Let L1 be E1–S1. 2) The result of the is a character string containing the L1 characters of C starting at character number S1 in the same order that the characters appear in C. That's a pretty sterling example of standards-ese that is both unreadable and devoid of any justification. But if you trace through the possible effects of a negative S value, it looks like (1) if L >= 0 is specified and S+L (E) is less than one, the result is an empty string per rule f)i). (2) if L >= 0 is specified and S+L (E) is at least one but less than LC+1, then E is the substring end+1 position. (3) otherwise, a negative S is disregarded and replaced by 1 so far as the substring end calculation is concerned. (4) in any case, a negative S is disregarded and replaced by 1 so far as the substring start calculation is concerned. I'm kind of inclined to not document this weirdness. I especially don't think it's worth giving an example that neither explains the "disregarded" bit nor highlights the dependency on L being given. regards, tom lane
Re: What are the minimum required permissions for pg_isready
PG Doc comments form writes:
> The documentation does not specify what are the minimum required permissions
> for setting up pg_isready .
There are none. Per the documentation:
It is not necessary to supply correct user name, password, or
database name values to obtain the server status; however, if
incorrect values are provided, the server will log a failed
connection attempt.
If you don't want log spam about failed connections, you'd need
a user with privilege to connect to the mentioned database.
Otherwise, not.
regards, tom lane
Re: Incomplete sentence in the description for most_common_freqs
PG Doc comments form writes: > It seems the ending clarifying sentence: > "(Null when most_common_vals is.)" > should rather be: > "(Null when most_common_vals is null.)" I think it's perfectly good English as-is, if a bit terse. regards, tom lane
Re: A typo?
"David G. Johnston" writes: > On Saturday, April 6, 2024, PG Doc comments form > wrote: >> Under 43.3.1, "Notice that we omitted RETURNS real — we could have included >> it, but it would be redundant." >> Should that be "RETURNS tax" instead of "RETURNS real"? > The docs are correct. Specifically, that bit is a declaration of the data type of the function's result, not a specification of how to compute it. regards, tom lane
Re: 8.14.5 jsonb subscripting
Arne Sommerfelt writes: > I am running on AWS RDS - it says engine version 12.17 i thought that was > the postgres version. If so, the [] subscripting should be supported > according to docs. According to what docs? Generic subscripting was added in v14. regards, tom lane
Re: 8.14.5 jsonb subscripting
Arne Sommerfelt writes:
> Thank you! When googling it is easy to end up with latest docs,
> unfortunately
That's actually good news --- it used to be that Google would
tend to steer people to very ancient versions of our docs.
Sounds like the SEO work that we've done is paying off.
However, if you're running a moderately old PG version, you need
to make use of the links at the top of the page to go to the
equivalent page in the older version's docs.
regards, tom lane
Re: Mysteries of the future
PG Doc comments form writes:
> SELECT to_date('2-1131', '-MMDD');
> ERROR: 22008: date/time field value out of range: "2-1131"
What exactly do you find wrong with that? November doesn't have
31 days.
Sure, we could have a discussion about the probability of the
Gregorian calendar still being in use 18000 years from now,
but it doesn't seem very profitable. What else do you want
to use?
regards, tom lane
