Re: Use uppercase keywords in foreign key tutorial
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? A concrete reason for worrying about this distinction is that the keywords will be interpreted the same regardless of search_path, but ordinary-identifier names will not. But having said that, I think 100% consistency about this sort of stylistic choice is neither achievable (for any long period) nor particularly desirable. In the worst case it could mislead novices into thinking that case is significant when it isn't. regards, tom lane
copy.sgml: add XML ID attributes to tags.
hi.
similar to what we did in
https://git.postgresql.org/cgit/postgresql.git/commit/?id=78ee60ed84bb3a1cf0b6bd9a715dcbcf252a90f5
I happened to notice COPY.sgml Parameters section is un-linkable.
The Parameters section in copy.sgml has shorter explanations compared to
create_table.sgml, but it contains a long list of options.
So I think making Each parameter linkable would improve readability.
From 3a2ffea61f42d9790ffdb2a945810739575acefc Mon Sep 17 00:00:00 2001
From: jian he
Date: Wed, 29 Oct 2025 21:25:22 +0800
Subject: [PATCH v1 1/1] make COPY.sgml Parameters linkable
doc changes:
Discussion: https://postgr.es/m/
---
doc/src/sgml/ref/copy.sgml | 50 +++---
1 file changed, 25 insertions(+), 25 deletions(-)
diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index fdc24b36bb8..27a2c418760 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -105,7 +105,7 @@ COPY { table_name [ ( Parameters
-
+
table_name
@@ -114,7 +114,7 @@ COPY { table_name [ (
-
+
column_name
@@ -125,7 +125,7 @@ COPY { table_name [ (
-
+
query
@@ -149,7 +149,7 @@ COPY { table_name [ (
-
+
filename
@@ -161,7 +161,7 @@ COPY { table_name [ (
-
+
PROGRAM
@@ -180,7 +180,7 @@ COPY { table_name [ (
-
+
STDIN
@@ -189,7 +189,7 @@ COPY { table_name [ (
-
+
STDOUT
@@ -198,7 +198,7 @@ COPY { table_name [ (
-
+
boolean
@@ -212,7 +212,7 @@ COPY { table_name [ (
-
+
integer
@@ -221,7 +221,7 @@ COPY { table_name [ (
-
+
FORMAT
@@ -235,7 +235,7 @@ COPY { table_name [ (
-
+
FREEZE
@@ -258,7 +258,7 @@ COPY { table_name [ (
-
+
DELIMITER
@@ -271,7 +271,7 @@ COPY { table_name [ (
-
+
NULL
@@ -295,7 +295,7 @@ COPY { table_name [ (
-
+
DEFAULT
@@ -308,7 +308,7 @@ COPY { table_name [ (
-
+
HEADER
@@ -335,7 +335,7 @@ COPY { table_name [ (
-
+
QUOTE
@@ -347,7 +347,7 @@ COPY { table_name [ (
-
+
ESCAPE
@@ -361,7 +361,7 @@ COPY { table_name [ (
-
+
FORCE_QUOTE
@@ -375,7 +375,7 @@ COPY { table_name [ (
-
+
FORCE_NOT_NULL
@@ -390,7 +390,7 @@ COPY { table_name [ (
-
+
FORCE_NULL
@@ -405,7 +405,7 @@ COPY { table_name [ (
-
+
ON_ERROR
@@ -433,7 +433,7 @@ COPY { table_name [ (
-
+
REJECT_LIMIT
@@ -451,7 +451,7 @@ COPY { table_name [ (
-
+
ENCODING
@@ -463,7 +463,7 @@ COPY { table_name [ (
-
+
LOG_VERBOSITY
@@ -481,7 +481,7 @@ COPY { table_name [ (
-
+
WHERE
--
2.34.1
recovery_target_time format explanation should be clarified when using UTC zone
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/18/index.html Description: We've been hitting a bug with PITR when specifying a recovery_target_time with an ISO 8601 format and UTC zone indicated with a trailing `Z`. We get an error like this ``` "msg":"waiting for server to start2025-10-28 16:40:20.324 UTC [38] LOG: invalid value for parameter \"recovery_target_time\": \"2025-10-28 16:34:15.00Z\"", ``` The documentation states > The value of this parameter is a time stamp in the same format accepted by the timestamp with time zone data type, except that you cannot use a time zone abbreviation > [-snip-] > Preferred style is to use a numeric offset from UTC, or you can write a full time zone name, e.g., Europe/Helsinki not EEST. That `Z`, if it's an abbreviation, would be an abbreviation for Zulu, I presume? I tried to use `Zulu` and not just `z` but still had the same `invalid value` error. For timestamps in UTC zone, I think the only supported format would be numeric offset, right? With `+00` instead of `Z`. I think that the documentation should clarify this explicitly. Unless there is a full name for the UTC zone which I'm unaware of... Thanks
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 Thu, Oct 30, 2025 at 10:24:30AM +1300, David Rowley wrote: > 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? Works for me. -- Bruce Momjian https://momjian.us EDB https://enterprisedb.com Do not let urgent matters crowd out time for investment in the future.
Re: Use uppercase keywords in foreign key tutorial
On Wed, Oct 29, 2025 at 05:25:43PM -0400, Bruce Momjian wrote: > On Thu, Oct 30, 2025 at 10:24:30AM +1300, David Rowley wrote: >> 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? > > Works for me. +1 -- nathan
Re: Use uppercase keywords in foreign key tutorial
On Tue, Oct 28, 2025 at 04:34:45PM -0500, Nathan Bossart wrote: > I noticed the patch also changes some column types to lowercase: > > > CREATE TYPE tablefunc_crosstab_N AS ( > -row_name TEXT, > -category_1 TEXT, > -category_2 TEXT, > +row_name text, > +category_1 text, > +category_2 text, > . > . > . > -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. -- Bruce Momjian https://momjian.us EDB https://enterprisedb.com Do not let urgent matters crowd out time for investment in the future.
