Re: Inconsistent information on default ordering for ORDER BY clause
On Fri, 8 Dec 2023 at 22:49, PG Doc comments form wrote: > Page: https://www.postgresql.org/docs/16/sql-select.html > Description: > > At the top of the sql-select page it says > > "If ORDER BY is not given, the rows are returned in whatever order the > system finds fastest to produce." > > but later it says > > "Optionally one can add the key word ASC (ascending) or DESC (descending) > after any expression in the ORDER BY clause. If not specified, ASC is > assumed by default." > > The first statement implies that you cannot rely on the default ordering, > but the second implies that you can (and it will be ASC). Perhaps you're going wrong in the last sentence in the latter fragment where it says "If not specified". This is talking about ASC/DESC rather than the ORDER BY. Maybe that could be made more clear. Something like "If ASC or DESC is not specified, ASC is assumed by default". Would that make it more clear? David
Re: Monetary Data Types Improvement
On Tue, 19 Mar 2024 at 07:43, Erik Wienhold wrote: > Maybe add a note like: > > "Money does not implement all operators that one might expect of a > numeric type. For example, use (-amount::money::numeric)::money to > negate amount." > > That would also fit nicely with the existing examples on casting to > numeric and float8. The attached patch does that. My vote would go to adding a deprecation notice to that section of the docs. There's some talk [1] about how we discourage the usage of the money type and that goes on to discuss the possibilities of moving it into a contrib module. My hope would be that deprecation notice would steer most people away from using it and therefore reduce the number of questions about it due to fewer new use cases of it. David [1] https://www.postgresql.org/message-id/[email protected]
Re: Need a PostgreSQL 16 developer edition for enabling vector support
On Thu, 4 Apr 2024 at 19:48, PG Doc comments form wrote: > We want to compile a vector extension in the postgres 16 dev edition and > use > the vector feature in the PostgreSQL You'll be better joining the pgsql-general [1] mailing list to ask this sort of question. The tool you've used is for reporting issues with the documentation, which this is not. David [1] https://www.postgresql.org/list/
Re: nchar is undocumented
On Sun, 5 May 2024 at 12:41, Erik Wienhold wrote: > So, I think we should either remove that one nchar instance (because it > doesn't add any real value) or document it properly. The attached patch > does the latter. It seems easier to do the former, that way we don't need to reconsider Peter's concerns about not having enough confidence that it matches the standard. I've included Alvaro and Peter to see what they think. David
Re: Missing examples for hash partitioning
On Sun, 5 May 2024 at 08:13, PG Doc comments form wrote: > Page: https://www.postgresql.org/docs/16/ddl-partitioning.html > Description: > > There is no example showing the syntax of Hash Partitioning in this section > of the documentation, it's missing. There are examples of hash partitioning in [1]. Maybe we should add a link so those can be more easily found. David [1] https://www.postgresql.org/docs/current/sql-createtable.html
Re: Missing examples for hash partitioning
On Sun, 5 May 2024 at 19:27, David Rowley wrote: > There are examples of hash partitioning in [1]. Maybe we should add a > link so those can be more easily found. I see the link is already there, per: "See CREATE TABLE for more details on creating partitioned tables and partitions." David > [1] https://www.postgresql.org/docs/current/sql-createtable.html
Re: Minor accuracy issue
On Wed, 5 Jun 2024 at 20:23, PG Doc comments form wrote: > Under page "https://www.postgresql.org/docs/current/limits.html";, it is > mentioned: > > relation size - 32TB > rows per table - limited by the number of tuples that can fit onto > 4,294,967,295 pages > > > 32 TB is 35,184,372,088,832 bytes (32*1024*1024*1024*1024). > When we divide this by 8192, we get 4,294,967,296. > > So why limit is mentioned 4,294,967,295 pages, instead of 4,294,967,296 > pages ? Because that's the limit. It might be more accurate to say the relation size limit is 34359738360 kB, but do you think it's going to be better to write that? David
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Thu, 18 Jul 2024 at 16:55, Muhammad Ikram wrote: > 5.1. Table Basics # > > when we hover over Table Basics, it shows # sign postfixed. I think it needs > to be removed Those are meant to be there. They allow you to copy a URL directly to that doc section. In [1], there was some talk about using another more suitable character. If the purpose of the '#' isn't obvious, then maybe we should use something else. David https://www.postgresql.org/message-id/caakru_z1xsjmv3b-jagg2e1jle2gcze3+zx7c7wgbrajbfv...@mail.gmail.com
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Thu, 18 Jul 2024 at 17:18, Tom Lane wrote: > Yeah. I've found this new feature useful multiple times already, > but the '#' icon is as non-mnemonic and unobvious as could possibly > be. OTOH, I don't know of a standard icon for this feature. I also find it useful and certainly don't want it to disappear. There's a unicode character for it. https://www.unicodepedia.com/unicode/miscellaneous-symbols-and-pictographs/1f517/link-symbol/ David
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Thu, 18 Jul 2024 at 19:46, Daniel Gustafsson wrote: > There is a lot of variability though so > whichever we choose it will be wrong one for someone. I think the tooltip would help reduce the chances of someone being confused. For an example, see [1]. David [1] https://devblogs.microsoft.com/cppblog/accelerating-compute-intensive-workloads-with-intel-avx-512/#test-system-configuration
Re: wrong field in example
On Thu, 25 Jul 2024, 12:57 am David G. Johnston, wrote: > I think you mis-copied the query - the one on the page has “select x”, not > “select *”. > That text exists as it was quoted. What the report is lacking is an indication of what is wrong with the text. David >
Re: incorrect PostgreSQL documentation for pg_type
On Sat, 3 Aug 2024 at 02:54, PG Doc comments form wrote: > Table 51.63. pg_type Columns > NameTypeReferences > --- > typinputregproc pg_proc.oid > typoutput regproc pg_proc.oid > typreceive regproc pg_proc.oid > typsend regproc pg_proc.oid > typmodinregproc pg_proc.oid > typmodout regproc pg_proc.oid > typanalyze regproc pg_proc.oid > > The correct reference is pg_proc.proname The following query disagrees: # select count(*) from pg_type t inner join pg_proc p on t.typinput = p.proname; ERROR: operator does not exist: regproc = name The following two should hopefully be enough to convince you it's fine as is. # select count(*) from pg_type t inner join pg_proc p on t.typinput = p.oid; count --- 627 (1 row) # select count(*) from pg_type; count --- 627 (1 row) Where you might be getting confused is the regproc type. Its output function converts the Oid to text. David
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Fri, 19 Jul 2024 at 06:03, Jonathan S. Katz wrote:
>
> On 7/18/24 1:59 PM, Daniel Gustafsson wrote:
> > Looking a bit closer, the Python documentation does just this, a pilcrow
> > with a
> > tool-tip ("Link to this heading") when hovering over it
>
> I forgot why we went with the "#" and not the (TIL the name) pilcrow
> symbol, but I'm generally used to seeing the pilcrow when I browse docs
> and may have voiced that at the time (though the record may show
> otherwise). So +1 to that.
I'm not really a web developer, but I did have a go at adjusting the
.css file so we show some relevant tooltip text. I was reminded about
this when looking at [1] this morning. That page is using '#' but the
purpose of it seems quite obvious when combined with the tooltip.
I've attached a small patch to adjust the CSS with hopes that it might
inspire someone who actually knows what they're doing with CSS to make
it better.
David
[1]
https://stackoverflow.blog/2024/07/24/developers-want-more-more-more-the-2024-results-from-stack-overflow-s-annual-developer-survey/
add_tooltip_to_heading_links.patch
Description: Binary data
Re: Re: Supplements and suggestions and about postgresql sequence setval function in the documents
On Thu, 22 Aug 2024 at 11:41, yanliang lei wrote: > What I want to express is： >There is no description in the document that the schema name can be > included before the sequence name I'm not to sure there is any problem here. If you look at the final paragraph in: https://www.postgresql.org/docs/current/functions-sequence.html you'll see: "The sequence to be operated on by a sequence function is specified by a regclass argument, which is simply the OID of the sequence in the pg_class system catalog. You do not have to look up the OID by hand, however, since the regclass data type's input converter will do the work for you. See Section 8.19 for details." If you navigate to Section 8.19, you'll see: "All of the OID alias types for objects that are grouped by namespace accept schema-qualified names, and will display schema-qualified names on output if the object would not be found in the current search path without being qualified. For example, myschema.mytable is acceptable input for regclass (if there is such a table)." I don't think it would be a good idea to repeat this information each time we document a function which has a regclass parameter, (or any other reg* type). Doing so would bloat the documentation quite a lot. In any case, if we were to do that, why would we limit it to reg* types? Could someone come along and argue that we didn't reiterate what an INT type was each time we document a function with an INT parameter? I think once the reader learns what a regclass type is, they'll be quite irritated if we repeatedly tell them what it is again and again. David
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Thu, 17 Oct 2024 at 11:19, Bruce Momjian wrote: > Where are we on this? I still see "#". I was hoping for some voting for or against my patch or the general idea of it. Also, my web skills in this area amount to trial and error, so it would also be good to have someone who knows what they're doing have a look at it. David
Re: Limitation relates to memory allocation
On Mon, 14 Oct 2024 at 19:03, Ekaterina Kiryanova
wrote:
> Our research showed that the limit is imposed by the palloc() function,
> regardless of whether it is a tuple or not, and if the data is
> serialized or dumped, the effective limit can be even lower, typically
> around 512MB per row. So for allocations exceeding 1GB, the
> palloc_extended() function can be used. Please correct me if I'm wrong.
I think it would be nice to document the row length limitation and
also add a caveat to the "field size" row to mention that outputting
bytea columns larger than 512MB can be problematic and storing values
that size or above is best avoided.
I don't think wording like: "The practical limit is less than 1 GB" is
going to be good enough as it's just not specific enough. The other
places that talk about practical limits on that page are mostly there
because it's likely impossible that anyone could actually reach the
actual limit. For example, 2^32 databases is likely a limit that
nobody would be able to get close. It's pretty easy to hit the bytea
limit, however:
postgres=# create table b (a bytea);
CREATE TABLE
Time: 2.634 ms
postgres=# insert into b values(repeat('a',600*1024*1024)::bytea);
INSERT 0 1
Time: 9725.320 ms (00:09.725)
postgres=# \o out.txt
postgres=# select * from b;
ERROR: invalid memory alloc request size 1258291203
Time: 209.082 ms
that took me about 10 seconds, so I disagree storing larger bytea
values is impractical.
David
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Thu, 17 Oct 2024 at 20:20, Daniel Gustafsson wrote: > My main concern is that the relative positioning will push it off screen with > a > break on smaller viewports (like phones). I can recreate what you sent in the screenshot, but I have to make my browser window as small as it will go and adjust the browser scaling to at least 150%. I don't know how to hover over a link on my phone to get tooltips to appear. Is it even possible? I tried hovering over it with my left finger, but it didn't work ;) > I was trying to improve on it but didn't succeed, my web-skills amount to very > little so it might be a case of a blind leading a blind here =) Maybe if it's > placed in a Z position where it's rendered on top of the other content (to > keep > it from adding vertical scroll) and using absolute positioning anchored on the > tag? That would require the h2 to use a position: attribute though. I don't know. I've attached the CSS and an example HTML file if that makes it easier for someone with the knowledge to play around with it. For anyone who wants to try it, the CSS class of interest starts at line 181 of the .css file. I tried using the overflow property [0], but it didn't seem to behave like I wanted it to. Setting it to "hidden" only seems to work sometimes on Chrome. Not sure if that's a browser or user problem. I tried to recreate the same wrapping issue you demonstrated with [1], but their tooltip text does not enlarge with browser scaling, and using browser scaling is the only way I can recreate the wrapping issue you mentioned. I'm not sure how to make the CSS class's text size immune to the effects of browser scaling. One other difference in [1] vs what we have is that they put the # on the left of the heading. There's less chance of having horizontal wrapping issues when the mouse cursor is over on the left side. However, we don't seem to have much of a margin for doing that. David [0] https://www.w3schools.com/css/css_overflow.asp [1] https://stackoverflow.blog/2024/07/24/developers-want-more-more-more-the-2024-results-from-stack-overflow-s-annual-developer-survey/ Title: 14.1. Using EXPLAIN 14.1. Using EXPLAINPrev UpChapter 14. Performance TipsHome Next14.1. Using EXPLAIN #14.1.1. EXPLAIN Basics14.1.2. EXPLAIN ANALYZE14.1.3. Caveats PostgreSQL devises a query plan for each query it receives. Choosing the right plan to match the query structure and the properties of the data is absolutely critical for good performance, so the system includes a complex planner that tries to choose good plans. You can use the EXPLAIN command to see what query plan the planner creates for any query. Plan-reading is an art that requires some experience to master, but this section attempts to cover the basics. Examples in this section are drawn from the regression test database after doing a VACUUM ANALYZE, using v17 development sources. You should be able to get similar results if you try the examples yourself, but your estimated costs and row counts might vary slightly because ANALYZE's statistics are random samples rather than exact, and because costs are inherently somewhat platform-dependent. The examples use EXPLAIN's default “text” output format, which is compact and convenient for humans to read. If you want to feed EXPLAIN's output to a program for further analysis, you should use one of its machine-readable output formats (XML, JSON, or YAML) instead. 14.1.1. EXPLAIN Basics # The structure of a query plan is a tree of plan nodes. Nodes at the bottom level of the tree are scan nodes: they return raw rows from a table. There are different types of scan nodes for different table access methods: sequential scans, index scans, and bitmap index scans. There are also non-table row sources, such as VALUES clauses and set-returning functions in FROM, which have their own scan node types. If the query requires joining, aggregation, sorting, or other operations on the raw rows, then there will be additional nodes above the scan nodes to perform these operations. Again, there is usually more than one possible way to do these operations, so different node types can appear here too. The output of EXPLAIN has one line for each node in the plan tree, showing the basic node type plus the cost estimates that the planner made for the execution of that plan node. Additional lines might appear, indented from the node's summary line, to show additional properties of the node. The very first line (the summary line for the topmost node) has the estimated total execution cost for the plan; it is this number that the planner seeks to minimize. Here is a trivial example, just to show what the output looks like: EXPLAIN SELECT * FROM tenk1; QUERY PLAN -
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Wed, 30 Oct 2024 at 03:46, Daniel Gustafsson wrote: > On the whole I wonder if we shouldn't just go with the proposal since it > improves the status quo, optimizing for users who hover to get link anchors on > mobile probably isn't worth the investment in time. My primary motivation for hacking on this was to try to reduce the confusion and reports about the mysterious #. I imagine the patch will improve that situation, but it does risk us getting new reports if there's something off with these changes. My thoughts are that it doesn't seem excessively critical that this is perfect on the first attempt. I'd be happy to see us try to improve this. Maybe if there's some better way, someone will appear and tell us how to do it properly. I am hopeful that we're not just swapping one problem for another. Do you have access to make this change? I think it needs to go into https://www.postgresql.org/media/css/main.css David
Re: Tip box on Adding a Column
On Fri, 1 Nov 2024 at 22:06, Marcelo Fernandes wrote: > - > https://www.postgresql.org/docs/current/ddl-alter.html#DDL-ALTER-ADDING-A-COLUMN > > That says: > > > From PostgreSQL 11, adding a column with a constant default value no longer > > means that each row of the table needs to be updated when the ALTER TABLE > > statement is executed. Instead, the default value will be returned the next > > time the row is accessed, and applied when the table is rewritten, making > > the > > ALTER TABLE very fast even on large tables. > > I'm just seeking clarification if this advice is true **even for** new columns > declared with NOT NULL? Yes, providing the default expression is immutable. > Historically, I've had to add new fields on existing big tables with a NULL to > avoid downtime, but it may be different when a DEFAULT is provided? We have the ability to store immutable defaults in the catalogue tables and "fill in the blanks" from there for any tuples that don't have the new column. Since we only can store 1 value per column, it must be a constant, i.e. the same for all rows. > I have used perf to profile the call-chain for adding a NOT NULL column with > a default versus just an ordinary NULL with a default, and they are fairly > similar. > > However, I see these functions being called in both cases: > > - ATRewriteTables > find_composite_type_dependencies > systable_beginscan > index_rescan > btrescan > > And the names raised my eyebrow... I don't have a deep understanding of the > internals here, so it would be great if someone could clarify this for me. I think you're better off staying in userland here and just doing some experiments and using the performance numbers to help give you an idea of what's going on. Using psql: \timing on create table t1 as select a from generate_Series(1,100)a; alter table t1 add column b int null; -- Time: 1.721 ms alter table t1 add column c int not null default 1234; -- Time: 5.450 ms alter table t1 add column d int not null default random(1,10); -- Time: 436.735 ms!! only adding column d required a rewrite, that's because the default expression isn't immutable. If timing isn't confirmation enough, try doing the above with: SET client_min_messages=debug1; Only adding column "d" gives you: DEBUG: rewriting table "t1" David
Re: No details on how to use Hash partitions: no example, no syntax
On Thu, 19 Sept 2024 at 02:17, Laurenz Albe wrote: > > On Tue, 2024-09-17 at 22:32 +, PG Doc comments form wrote: > > I would like the documentation to explain how to use Hash partitions. It > > says one needs to provide a modulus and remainder, but the exact syntax is > > not stated in the relevant documentation page 5.11 > > All that is documented with CREATE TABLE: > https://www.postgresql.org/docs/current/sql-createtable.html > > "How to use" is material for a tutorial rather than for the documentation. I see we also had a similar complaint back in May [1]. >From the v16 docs, "See CREATE TABLE for more details on creating partitioned tables and partitions." is mentioned in 5.11.2. Declarative Partitioning, but I wonder if it's worth adding "There are further examples on how to create partitioned tables in the examples section of CREATE TABLE" at the end of the examples section in "5.11.2.1. Example". Would people be more likely to see the link if we put it in the place where they might expect the missing examples to be? David [1] https://www.postgresql.org/message-id/[email protected]
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Thu, 7 Nov 2024 at 02:33, Daniel Gustafsson wrote: > Committed, and with some help from Magnus, the docs site has been reloaded > with > the new CSS. Everything seems to behave as expected when testing in Firefox, > Safari, Chrome and Edge. Great. Thank you to you both. David
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Thu, 7 Nov 2024 at 03:58, Daniel Gustafsson wrote: > > > On 6 Nov 2024, at 15:51, Alvaro Herrera wrote: > > Ah, but we kept the #? I thought it was going to be changed to ¶ ... > > was there any voice against that? > > You're right, I mistakenly remembered there being no concensus and didn't > re-read the thread when it was revived with the patch in question. Re-reading > it now I see multiple +1's for using a ¶ instead so will fix that. Thanks for > the heads-up. I see in the release notes we're using §. I'm not advocating for any particular one, but would it make sense to be consistent on which character we use for this? David
Re: A minor bug in doc. Hovering over heading shows # besides it.
On Wed, 30 Oct 2024 at 11:39, Daniel Gustafsson wrote:
>
> > On 29 Oct 2024, at 23:36, David Rowley wrote:
> > Do you have access to make this change? I think it needs to go into
> > https://www.postgresql.org/media/css/main.css
>
> I have a pgweb commitbit so if you roll a patch for it I can take care of the
> rest.
Thanks. Patch attached.
David
From 6b26501e43b4acb6f4c60f03f3194ad0403b88cf Mon Sep 17 00:00:00 2001
From: David Rowley
Date: Wed, 6 Nov 2024 19:07:27 +1300
Subject: [PATCH] Adjust CSS to have tooltips in the H2 headings in the docs
There's been at least one complaint about a stray # that appears in the
manual. Add a tooltip to this to make it more clear why this appears
and what it's for.
---
media/css/main.css | 14 ++
1 file changed, 14 insertions(+)
diff --git a/media/css/main.css b/media/css/main.css
index cbfea862..71364f19 100644
--- a/media/css/main.css
+++ b/media/css/main.css
@@ -1183,6 +1183,20 @@ code,
#docContent a.id_link {
color: inherit;
visibility: hidden;
+ text-decoration: none;
+}
+
+#docContent a.id_link:hover:after {
+ content: "Permalink to this heading";
+ font-size: 10px;
+ font-weight: normal;
+ text-decoration: none;
+ border: 1px solid #44;
+ text-align: center;
+ border-radius: 5px 5px 5px 5px;
+ padding: 5px 5px 5px 5px;
+ position: relative;
+ top: 20px;
}
#docContent *:hover > a.id_link {
--
2.40.1.windows.1
Re: Possible documentation inaccuracy in optimizer README
On Wed, 9 Apr 2025 at 14:33, Tom Lane wrote: > Maybe better: > > Other possibilities will be excluded for lack of join clauses. > (In reality, use of EquivalenceClasses would allow us to > deduce additional join clauses that allow more join > combinations, but here we ignore that to preserve the > simplicity of this example.) Looks good to me. David
Re: Possible documentation inaccuracy in optimizer README
On Tue, 8 Apr 2025 at 16:28, Tom Lane wrote:
> We could possibly avoid the inaccuracy by making the examples use
> some other operators that are not equijoins. But I wonder if that
> would not be more confusing rather than less so.
I don't think it'd hurt to mention that we're just ignoring the
existence of ECs for this example. Something like:
--- a/src/backend/optimizer/README
+++ b/src/backend/optimizer/README
@@ -143,7 +143,10 @@ For example:
{1 2},{2 3},{3 4}
{1 2 3},{2 3 4}
{1 2 3 4}
-(other possibilities will be excluded for lack of join clauses)
+(other possibilities will be excluded for lack of join clauses
+(technically, EquivalenceClasses do allow us to determine derived join
+clauses for this case, but we ignore that for the simplicity of this
+example))
SELECT *
FROMtab1, tab2, tab3, tab4
If it'll stop a future question or someone from being confused, it
seems worthwhile.
David
Re: Lets prohibit predicting the future in the documentation.
On Thu, 31 Jul 2025 at 14:17, David G. Johnston wrote: > > Came across this again today...we added, way back in v11: > > "This limitation will likely be removed in a future version of > PostgreSQL." > > https://www.postgresql.org/docs/18/sql-createstatistics.html This sort of thing doesn't particularly upset me. I don't believe we should hide the fact that certain features might need more work. If it inspires someone to work on making improvements, wouldn't it be worthwhile keeping these? A huge amount of stuff gets done around here because people find some inspiration to make things better. I don't believe all those people need to experience the problems first-hand to be able to fix them. Plenty of people arrive here just looking to get involved and make a difference. I presume that something like this being mentioned in the docs likely has a much better "we actually want this feature" ratio than the TODO list does. I also imagine it's more likely to inspire users of PostgreSQL to get involved in developing than the TODO list is. -1 from me. David
Re: Anchors to options are missing for pgchecksums
On Sat, 27 Sept 2025 at 21:03, PG Doc comments form wrote: > On https://www.postgresql.org/docs/current/app-pgchecksums.html the anchor > links like > https://www.postgresql.org/docs/18/app-initdb.html#APP-INITDB-DATA-CHECKSUMS > are missing. It would be nice to add those. Seems like a fair request to me. Do you have any interest in creating a patch to do this yourself? It seems to be a matter of copying what was done in [1]. If you look there and see what was done for initdb.sgml. It would be quite good if the patch did this to all of the command line arguments for all the client tools had these, not just pg_checksums. I see for example [2] doesn't have it either. David [1] https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=78ee60ed84bb3a1cf0b6bd9a715dcbcf252a90f5;hp=38d81760c4d7e22b95252e3545596602c9e38806 [2] https://www.postgresql.org/docs/18/pgarchivecleanup.html
Re: DDL Partitionion Inheritance -- improved trigger function
On Wed, 24 Sept 2025 at 04:25, Kirk Parker wrote:
> I'm a big fan of maintenance-free functions. What would you think about
> adding the following as an alternative trigger function, or as a replacement
> for the current function, to
> https://www.postgresql.org/docs/current/ddl-partitioning.html#DDL-PARTITIONING-INHERITANCE-EXAMPLE
> , item #5?
>
> CREATE OR REPLACE FUNCTION measurement_insert_trigger()
> RETURNS TRIGGER AS $$
> BEGIN
> EXECUTE format('INSERT INTO measurement_%s VALUES (NEW.*)', to_char(
> NEW.logdate, 'MM'));
> RETURN NULL;
> END;
> $$
> LANGUAGE plpgsql;
I've somewhat mixed feelings about that. While I do agree that it
might be a good way to code things to help prevent a DBA from a
midnight callout, I'm just not sure I'm that onboard with adding the
example. About 10 years ago, I'd likely just have agreed, but since
then we've got declarative partitioning and the legitimate use cases
for using inheritance partitioning over the newer method are very
limited. Today when I look at that page in the documents, I wonder how
we could write less about inheritance partitioning or if we could move
the inheritance section out into another page rather than having it
mixed up with the declarative partitioning sections, perhaps headed up
with a note to redirect people to the declarative partitioning
section. I fear adding your proposed example might increase the
chances of someone landing on that section if they're skimming the
page.
Overall, I'm about -0.01 on your idea. I might be in favour of it if
the inheritance section had a dedicated page.
David
Re: Confusion in section 8.7.3. Type Safety
On Tue, 23 Sept 2025 at 20:59, PG Doc comments form wrote: > Page: https://www.postgresql.org/docs/17/datatype-enum.html > Description: > > In section 8.7.3. Type Safety one can observe a the following statement in > the examples. > > INSERT INTO holidays(num_weeks,happiness) VALUES (2, 'sad'); > > This is somewhat confusing since type happiness doesn't contain 'sad'. I > would suggest to remove the statement or to add an enum 'sad' in type > happiness. Thank you for the report. I think you might have missed that this section is demonstrating that the statement does not work due to the column's type not containing an enum value for 'sad' and that enum values are specific to the particular enum, rather than global to all enum types, as one *could* have assumed. Your proposed modification would make the bogus INSERT statement work, which would defeat the purpose of the section demonstrating that it doesn't work. David
Re: Use uppercase keywords in foreign key tutorial
On Thu, 6 Nov 2025 at 07:09, Erik Wienhold wrote: > > On 2025-11-04 03:09 +0100, David Rowley wrote: > > I think just the keyword upper casing is a good idea for now. I'm > > starting to lose hope that there's enough merit and consistency to the > > proposed whitespace changes. Maybe there's a subset of it that does > > make sense to do. > > Done in the attached v6. But I kept the few whitespace changes on lines > where I change keywords to uppercase. It's mostly a single space after > commas in column and parameter lists which I think also enhances > readability. I reviewed this and double checked you left "uPDaTE" in [1]. Found no issues, so pushed. Thank you. David [1] https://www.postgresql.org/docs/current/sql-syntax-lexical.html
Re: Use uppercase keywords in foreign key tutorial
On Tue, 4 Nov 2025 at 09:06, Erik Wienhold wrote:
> Fixed in the attached v4. Except for one match in dblink.sgml that is
> the sample output of dblink_build_sql_insert which actually omits the
> space after the table name and VALUES keyword.
I went through all these and I think it's mostly good. However...
It seems strange to me that you've made so many changes to transform
"CREATE TABLE foo(" into "CREATE TABLE foo (", but you've done the
opposite for CREATE FUNCTION and CREATE PROCEDURE. Did you go with the
majority rules here? It just seems a bit hard to follow what the
standard is being enforced here and if that's hard to understand now,
what hope is there of people following that in the future?
I'm starting to wonder if adjusting the spacing here is a worthwhile change.
David
Re: Use uppercase keywords in foreign key tutorial
On Tue, 4 Nov 2025 at 13:04, Erik Wienhold wrote: > > On 2025-11-03 23:37 +0100, David Rowley wrote: > > I'm starting to wonder if adjusting the spacing here is a worthwhile > > change. > > I think it's worth to have that consistency. If the patch is too broad > I can of course limit it to the listings with inconsistent keyword > casing which is more less patch v2 plus some changes from v3 and later. > > Or just fix the keywords for now to get that out of the way and deal > with the spacing in a separate patch/thread. I think just the keyword upper casing is a good idea for now. I'm starting to lose hope that there's enough merit and consistency to the proposed whitespace changes. Maybe there's a subset of it that does make sense to do. David
Re: Use uppercase keywords in foreign key tutorial
On Thu, 30 Oct 2025 at 09:48, Tom Lane wrote: > > Bruce Momjian writes: > > On Tue, Oct 28, 2025 at 04:34:45PM -0500, Nathan Bossart wrote: > >> I noticed the patch also changes some column types to lowercase: > >> ... > >> -category_N TEXT > >> +category_N text > >> > >> FWIW I tend to use uppercase for those, too, but I'm not sure there is a > >> preferred style for the docs. > > > Agreed, uppercase is better for type names. > > "text" is not a keyword according to either us or the SQL standard. > I agree that there's some reason to capitalize things that are > grammar keywords, such as INTEGER or VARCHAR, but it's a big stretch > to go from that to capitalizing everything that is a type name. > Would you capitalize user-defined type names? Going by: git grep -i "\btext\b," we're fairly consistently using lower case, so FWIW, when I looked, I thought Eric's change made sense. How about if Eric just drops the portion of the patch that alters the casing of the types and leaves all the keyword uppercasing stuff in. Any objections to that part? David
Re: Use uppercase keywords in foreign key tutorial
On Fri, 31 Oct 2025 at 13:53, Erik Wienhold wrote:
> But I also agree with Tom that keeping a consistent style is impossible
> in the long run. But it also shows that the docs are still written by
> humans. As long as we can keep a consistent style within a single
> listing (or even an entire page) I'm satisfied as a reader.
For me, I don't see this as a reason not to try. If we do get things
to a consistent point, then anyone making changes that reference
existing portions of the documentation for inspiration should maintain
consistency. If we're entirely random, then there's no hope for anyone
to figure out what the best practice or perfected casing is.
> Besides that I've fixed a couple of more places that had lowercase
> keywords or were missing some whitespace that I had missed before.
A couple of things.
1) I see you've added a space after "INSERT INTO table" and before the
column list, but not consistently, per:
git grep -E "INSERT INTO \w+\("
2) An identifier casing has been changed here:
-SELECT sub_part, SUM(quantity) as total_quantity
+SELECT sub_part, sum(quantity) AS total_quantity
You could also look at the results of the SQL command that's returned
by the following SQL to see if there's anything else. I do see some
"ROLLUP(", "EXISTS(", "GROUPING(" and "VALUES(" in there. You have
been changing "VALUES(" to "VALUES (", so I assume those ones have
been missed:
select 'git grep -E "\b(' || string_agg(UPPER(word),'|') || ')\("'
from pg_get_keywords();
David
Re: Use uppercase keywords in foreign key tutorial
On Mon, 10 Nov 2025 at 16:40, Erik Wienhold wrote:
> > in doc/src/sgml/func/func-matching.sgml
> > key word: "similar", "escape", "from", "for" within the above synopsis
> > section need uppercase too?
>
> Thanks, good catch. Not surprised that I've missed those because it
> already took me a couple of rounds to find everything that's in the
> previous patch. Here's another patch.
I've pushed this after doing a manual scan the command that the
following outputs:
select 'git grep -E "\b(' || string_agg(word,'|') || ')\("' from
pg_get_keywords();
I didn't see any other ones that are all lowercase. I also tried with
initcap(word). I didn't go as far as writing a regex that searched for
other mixed case but not all upper case.
David
Re: MERGE command is not mentioned in the list of commands for variable substitution
On Tue, 11 Nov 2025 at 05:52, PG Doc comments form wrote: > "Variable substitution currently works only in SELECT, INSERT, UPDATE, > DELETE, and commands containing one of these..." > https://www.postgresql.org/docs/current/plpgsql-implementation.html#PLPGSQL-VAR-SUBST > But experiments showed that variable substitution works for MERGE command > too. Thanks for the report. You're right that this has been overlooked. The attached patch fixes it. I can take care of this once the back branches are open again after the minor releases are out. David v1-0001-Doc-include-MERGE-in-variable-substitution-comman.patch Description: Binary data
Re: Use uppercase keywords in foreign key tutorial
On Fri, 24 Oct 2025 at 09:39, Erik Wienhold wrote: > This of course produces a lot of noise, but I managed to find and fix a > couple more places with the attached v2 (including the ones you've > listed) that I've missed previously. I've searched for "primary key" > across the docs previously but did not spot the matches between the > false-positive ones from the running text. I've not reviewed in detail, but on a first-pass read, I think this is worth doing. I personally find queries with upper-case keywords and lowercase identifiers much easier on the eyes. I'm not so sure about the "Should be pushed to all stable branches" part as it seems more of a general improvement than fixing a mistake. I imagine there will be varying opinions on that, however. David
Re: MERGE command is not mentioned in the list of commands for variable substitution
On Tue, 11 Nov 2025 at 10:44, David Rowley wrote: > The attached patch fixes it. I can take care of this once the back > branches are open again after the minor releases are out. Pushed. David
