pg.ddx.io pgsql-committers@postgresql.org mailing list archive
help / color / mirror / Atom feedpgsql: Doc: document bpchar, clarify relationship of text and varchar.
7+ messages / 3 participants
[nested] [flat]
Commits from this thread:
2023-10-31 b69db51736 83981bcbac doc: improve bpchar and character type length details
* pgsql: Doc: document bpchar, clarify relationship of text and varchar.
@ 2022-09-28 16:31 Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 20:18 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2022-09-28 16:31 UTC (permalink / raw)
To: pgsql-committers@lists.postgresql.org
Doc: document bpchar, clarify relationship of text and varchar.
For some reason the "bpchar" type name was defined nowhere in
our SGML docs, although several places refer to it in passing.
Give it a proper mention under Character Types.
While here, also provide an explanation of how the text and varchar
types relate. The previous wording seemed to be doing its best
to sweep text under the rug, which doesn't seem very appropriate
given its prominence in other parts of the docs.
Minor rearrangements and word-smithing for clarity, too.
Laurenz Albe and Tom Lane, per gripe from Yanliang Lei
Discussion: https://postgr.es/m/120b3084.56b6.1833b5ffe4b.Coremail.msdnchina@163.com
Branch
------
master
Details
-------
https://git.postgresql.org/pg/commitdiff/0937f6d172921202e1b432e206e4c30775d564d8
Modified Files
--------------
doc/src/sgml/datatype.sgml | 59 ++++++++++++++++++++++++++++------------------
1 file changed, 36 insertions(+), 23 deletions(-)
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar.
2022-09-28 16:31 pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
@ 2022-12-02 20:18 ` Jeff Davis <pgsql@j-davis.com>
2022-12-02 20:26 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 7+ messages in thread
From: Jeff Davis @ 2022-12-02 20:18 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-committers@lists.postgresql.org
On Wed, 2022-09-28 at 16:31 +0000, Tom Lane wrote:
> Doc: document bpchar, clarify relationship of text and varchar.
BPCHAR is documented as an alias to CHARACTER, but the former can end
up with no typmod at all whereas the latter defaults to CHARACTER(1).
Should we document the case of using BPCHAR with no length?
I noticed this because there exists a hash function bug[1] that seems
to be visible with BPCHAR but not CHARACTER.
[1]
https://www.postgresql.org/message-id/7692740d4736e79032a5dac689cf2e304c03fa78.camel@j-davis.com
--
Jeff Davis
PostgreSQL Contributor Team - AWS
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar.
2022-09-28 16:31 pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 20:18 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
@ 2022-12-02 20:26 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 21:55 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2022-12-02 20:26 UTC (permalink / raw)
To: Jeff Davis <pgsql@j-davis.com>; +Cc: pgsql-committers@lists.postgresql.org
Jeff Davis <pgsql@j-davis.com> writes:
> BPCHAR is documented as an alias to CHARACTER, but the former can end
> up with no typmod at all whereas the latter defaults to CHARACTER(1).
> Should we document the case of using BPCHAR with no length?
Perhaps; you got specific wording in mind?
(I think that that difference is in fact documented somewhere,
but maybe not where you looked.)
regards, tom lane
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar.
2022-09-28 16:31 pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 20:18 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
2022-12-02 20:26 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
@ 2022-12-02 21:55 ` Jeff Davis <pgsql@j-davis.com>
2023-10-24 22:35 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: Jeff Davis @ 2022-12-02 21:55 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-committers@lists.postgresql.org
On Fri, 2022-12-02 at 15:26 -0500, Tom Lane wrote:
> Perhaps; you got specific wording in mind?
Here's what I came up with. It's kind of its own thing, because it
can't be described as blank-padded.
--
Jeff Davis
PostgreSQL Contributor Team - AWS
Attachments:
v1-0001-Document-type-BPCHAR-without-length-specifier.patch (text/x-patch, 3.1K) download
From 3fbe9c3a6acc95d67c468f1406ab816d89c601bb Mon Sep 17 00:00:00 2001
From: Jeff Davis <jeff@j-davis.com>
Date: Fri, 2 Dec 2022 13:39:13 -0800
Subject: [PATCH v1] Document type BPCHAR without length specifier.
The BPCHAR datatype with no length specifier has its own semantics; it
cannot be considered "padded" as it has no length to which it should
be padded, but trailing spaces are still ignored.
---
doc/src/sgml/datatype.sgml | 31 +++++++++++++++++++------------
1 file changed, 19 insertions(+), 12 deletions(-)
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index fdffba4442..824e2a3022 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1174,7 +1174,11 @@ SELECT '52093.89'::money::numeric::float8;
</row>
<row>
<entry><type>character(<replaceable>n</replaceable>)</type>, <type>char(<replaceable>n</replaceable>)</type>, <type>bpchar(<replaceable>n</replaceable>)</type></entry>
- <entry>fixed-length, blank padded</entry>
+ <entry>fixed-length, blank-padded</entry>
+ </row>
+ <row>
+ <entry><type>bpchar</type></entry>
+ <entry>variable unlimited length, blank-trimmed</entry>
</row>
<row>
<entry><type>text</type></entry>
@@ -1230,20 +1234,23 @@ SELECT '52093.89'::money::numeric::float8;
<para>
The type name <type>varchar</type> is an alias for <type>character
- varying</type>, while <type>char</type> and <type>bpchar</type> are
- aliases for <type>character</type>.
- The <type>varchar</type> and <type>char</type> aliases are defined in
- the <acronym>SQL</acronym> standard, but <type>bpchar</type> is
- a <productname>PostgreSQL</productname> extension.
+ varying</type>, while <type>bpchar</type> (with length specifier) and
+ <type>char</type> are aliases for <type>character</type>. The
+ <type>varchar</type> and <type>char</type> aliases are defined in the
+ <acronym>SQL</acronym> standard, but <type>bpchar</type> is a
+ <productname>PostgreSQL</productname> extension.
</para>
<para>
- If specified, the length <replaceable>n</replaceable> must be greater
- than zero and cannot exceed 10485760.
- <type>character</type> without length specifier is equivalent to
- <type>character(1)</type>. If <type>character varying</type> is used
- without length specifier, the type accepts strings of any size. The
- latter behavior is a <productname>PostgreSQL</productname> extension.
+ If specified, the length <replaceable>n</replaceable> must be greater than
+ zero and cannot exceed 10485760. <type>character</type> or
+ <type>char</type> without length specifier are equivalent to
+ <type>character(1)</type>. If <type>character varying</type> or
+ <type>varchar</type> are used without length specifier, the type accepts
+ strings of any size. The latter behavior is a
+ <productname>PostgreSQL</productname> extension. If <type>bpchar</type> is
+ used without length specifier, it accepts strings of any size, but
+ trailing spaces are semantically insignificant.
</para>
<para>
--
2.34.1
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar.
2022-09-28 16:31 pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 20:18 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
2022-12-02 20:26 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 21:55 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
@ 2023-10-24 22:35 ` Bruce Momjian <bruce@momjian.us>
2023-10-24 23:00 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2023-10-24 22:35 UTC (permalink / raw)
To: Jeff Davis <pgsql@j-davis.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-committers@lists.postgresql.org
On Fri, Dec 2, 2022 at 01:55:41PM -0800, Jeff Davis wrote:
> On Fri, 2022-12-02 at 15:26 -0500, Tom Lane wrote:
> > Perhaps; you got specific wording in mind?
>
> Here's what I came up with. It's kind of its own thing, because it
> can't be described as blank-padded.
I liked this patch and adjusted it; patch attached. I would like to
apply it to all branches since it provides useful information.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
Attachments:
bpchar.diff (text/x-diff, 2.3K) download
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 5d23765705..dcb44716f5 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1174,7 +1174,11 @@ SELECT '52093.89'::money::numeric::float8;
</row>
<row>
<entry><type>character(<replaceable>n</replaceable>)</type>, <type>char(<replaceable>n</replaceable>)</type>, <type>bpchar(<replaceable>n</replaceable>)</type></entry>
- <entry>fixed-length, blank padded</entry>
+ <entry>fixed-length, blank-padded</entry>
+ </row>
+ <row>
+ <entry><type>bpchar</type></entry>
+ <entry>variable unlimited length, blank-trimmed</entry>
</row>
<row>
<entry><type>text</type></entry>
@@ -1230,19 +1234,22 @@ SELECT '52093.89'::money::numeric::float8;
<para>
The type name <type>varchar</type> is an alias for <type>character
- varying</type>, while <type>char</type> and <type>bpchar</type> are
- aliases for <type>character</type>.
- The <type>varchar</type> and <type>char</type> aliases are defined in
- the <acronym>SQL</acronym> standard, but <type>bpchar</type> is
- a <productname>PostgreSQL</productname> extension.
+ varying</type>, while <type>bpchar</type> (with length specifier) and
+ <type>char</type> are aliases for <type>character</type>. The
+ <type>varchar</type> and <type>char</type> aliases are defined in the
+ <acronym>SQL</acronym> standard; <type>bpchar</type> is a
+ <productname>PostgreSQL</productname> extension.
</para>
<para>
If specified, the length <replaceable>n</replaceable> must be greater
- than zero and cannot exceed 10485760.
- <type>character</type> without length specifier is equivalent to
- <type>character(1)</type>. If <type>character varying</type> is used
- without length specifier, the type accepts strings of any size.
+ than zero and cannot exceed 10485760. If <type>character
+ varying</type> (or <type>varchar</type>) is used without
+ length specifier, the type accepts strings of any length. If
+ <type>bpchar</type> lacks a length specifier, it also accepts strings
+ of any length, but trailing spaces are semantically insignificant.
+ If <type>character</type> (or <type>char</type>) lacks a specifier,
+ it is equivalent to <type>character(1)</type>.
</para>
<para>
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar.
2022-09-28 16:31 pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 20:18 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
2022-12-02 20:26 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 21:55 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
2023-10-24 22:35 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Bruce Momjian <bruce@momjian.us>
@ 2023-10-24 23:00 ` Jeff Davis <pgsql@j-davis.com>
2023-10-31 14:13 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: Jeff Davis @ 2023-10-24 23:00 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-committers@lists.postgresql.org
On Tue, 2023-10-24 at 18:35 -0400, Bruce Momjian wrote:
> I liked this patch and adjusted it; patch attached. I would like to
> apply it to all branches since it provides useful information.
Looks good to me.
Regards,
Jeff Davis
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar.
2022-09-28 16:31 pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 20:18 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
2022-12-02 20:26 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 21:55 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
2023-10-24 22:35 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Bruce Momjian <bruce@momjian.us>
2023-10-24 23:00 ` Re: pgsql: Doc: document bpchar, clarify relationship of text and varchar. Jeff Davis <pgsql@j-davis.com>
@ 2023-10-31 14:13 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 7+ messages in thread
From: Bruce Momjian @ 2023-10-31 14:13 UTC (permalink / raw)
To: Jeff Davis <pgsql@j-davis.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-committers@lists.postgresql.org
On Tue, Oct 24, 2023 at 04:00:08PM -0700, Jeff Davis wrote:
> On Tue, 2023-10-24 at 18:35 -0400, Bruce Momjian wrote:
> > I liked this patch and adjusted it; patch attached. I would like to
> > apply it to all branches since it provides useful information.
>
> Looks good to me.
Patch applied back to PG 16.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2023-10-31 14:13 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-09-28 16:31 pgsql: Doc: document bpchar, clarify relationship of text and varchar. Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 20:18 ` Jeff Davis <pgsql@j-davis.com>
2022-12-02 20:26 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-12-02 21:55 ` Jeff Davis <pgsql@j-davis.com>
2023-10-24 22:35 ` Bruce Momjian <bruce@momjian.us>
2023-10-24 23:00 ` Jeff Davis <pgsql@j-davis.com>
2023-10-31 14:13 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox