public inbox for [email protected]
help / color / mirror / Atom feedFrom: Hoda Salim <[email protected]>
To: Erik Wienhold <[email protected]>
Cc: [email protected]
Subject: Re: [PATCH] docs: document N'...' national character string literal syntax
Date: Mon, 2 Feb 2026 22:04:12 +0200
Message-ID: <CAAGT0i+SrExi4LVf-gQ4t9XY724pVRxEvOZft4B0uUs-gDuYHA@mail.gmail.com> (raw)
In-Reply-To: <[email protected]>
References: <CAAGT0iKc1Fq=mmK99fMd8O+QGZfCAqzx3bOWBcci6fO8SjLGtQ@mail.gmail.com>
<[email protected]>
> nchar is an alias of bpchar. There's no cast to char behind the scenes
> since that would truncate the string:
>
> select n'foo', 'foo'::character;
> bpchar | bpchar
> --------+--------
> foo | f
> (1 row)
Thank you for catching this! I verified the behavior and updated the
documentation to correctly state that N'...' is equivalent to a bpchar
literal.
> Should we also mention the nchar alias in [4]?
> [4] https://www.postgresql.org/docs/current/datatype-character.html
I'm happy to add that in a v3 if you think it belongs in this patch.
I wasn't sure if it would be preferred separately or together.
Updated patch attached.
--
Hoda Salim
On Mon, Feb 2, 2026 at 7:09 PM Erik Wienhold <[email protected]> wrote:
>
> On 2026-02-02 16:05 +0100, Hoda Salim wrote:
> > This patch documents the N'...' national character string literal
> > syntax, which has been supported by PostgreSQL but was previously
> > undocumented.
> >
> > The documentation explains:
> > - What the syntax is (N'hello')
> > - What the SQL standard specifies (implementation-defined national
> > character set)
> > - What PostgreSQL actually does (treats it as a cast to character type)
> > - Why it exists (compatibility with SQL migrated from other databases)
> >
> > I verified the documentation builds without errors.
>
> +1
>
> I brought up the missing documentation before [1], but wasn't sure at
> the time if Postgres conforms to the SQL standard (mainly because of
> [2]). Now I see that [3] already claims to support national character
> (F421). That entry was commented with "syntax accepted" until commit
> 35223af0579. I read that as "fully supported" now.
>
> > + <productname>PostgreSQL</productname> does not implement a separate
> > + national character set; it treats <literal>N'...'</literal> as
> > + equivalent to a regular string constant cast to the
> > + <type>character</type> type, that is, <literal>'...'::character</literal>,
> > + using the database's character set.
>
> nchar is an alias of bpchar. There's no cast to char behind the scenes
> since that would truncate the string:
>
> select n'foo', 'foo'::character;
> bpchar | bpchar
> --------+--------
> foo | f
> (1 row)
>
> Should we also mention the nchar alias in [4]?
>
> [1] https://www.postgresql.org/message-id/om3g7p7u3ztlrdp4tfswgulavljgn2fe6u2agk34mrr65dffuu%40cpzlzuv6f...
> [2] https://www.postgresql.org/message-id/[email protected]
> [3] https://www.postgresql.org/docs/current/features-sql-standard.html
> [4] https://www.postgresql.org/docs/current/datatype-character.html
>
> --
> Erik Wienhold
Attachments:
[application/octet-stream] v2-0001-docs-document-N-.-national-character-string-liter.patch (2.9K, ../CAAGT0i+SrExi4LVf-gQ4t9XY724pVRxEvOZft4B0uUs-gDuYHA@mail.gmail.com/2-v2-0001-docs-document-N-.-national-character-string-liter.patch)
download | inline diff:
From 826f469fe681b9875437bfb7e3c805c092cf8b0a Mon Sep 17 00:00:00 2001
From: HodaSalim <[email protected]>
Date: Mon, 2 Feb 2026 14:54:37 +0000
Subject: [PATCH v2] docs: document N'...' national character string literal
syntax
Document the N'...' string literal syntax in the Lexical Structure
section of the documentation. This SQL-standard syntax for national
character string literals has been supported by PostgreSQL but was
previously undocumented.
The documentation explains that while the SQL standard specifies this
syntax for an implementation-defined national character set, PostgreSQL
treats N'...' as equivalent to a bpchar (blank-padded character) type
literal, since PostgreSQL uses a single character set for all string
types.
---
doc/src/sgml/syntax.sgml | 41 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 41 insertions(+)
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 67482996861..b59e71a2664 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -590,6 +590,47 @@ $function$
</para>
</sect3>
+ <sect3 id="sql-syntax-strings-national">
+ <title>National Character String Constants</title>
+
+ <indexterm zone="sql-syntax-strings-national">
+ <primary>national character</primary>
+ <secondary>string constant</secondary>
+ </indexterm>
+
+ <para>
+ <productname>PostgreSQL</productname> accepts string constants
+ with a leading <literal>N</literal> (upper or lower case)
+ immediately before the opening single quote, for
+ example <literal>N'hello'</literal>. This syntax is specified by
+ the <acronym>SQL</acronym> standard for identifying string
+ literals of <quote>national character</quote> types
+ (<type>NCHAR</type> and <type>NCHAR VARYING</type>).
+ </para>
+
+ <para>
+ The <acronym>SQL</acronym> standard specifies that strings written
+ with this syntax should use an <quote>implementation-defined
+ national character set</quote>.
+ <productname>PostgreSQL</productname> does not implement a separate
+ national character set; it treats <literal>N'...'</literal> as
+ equivalent to a string constant of type <type>bpchar</type>
+ (blank-padded character), for example <literal>N'hello'</literal>
+ has the same type and value as <literal>'hello'::bpchar</literal>.
+ Note that trailing spaces are semantically insignificant
+ in <type>bpchar</type> values.
+ </para>
+
+ <para>
+ This syntax is accepted primarily for compatibility with SQL
+ migrated from other database systems. Since
+ <productname>PostgreSQL</productname> uses a single character set
+ for all string types (determined by the database encoding),
+ there is typically no advantage to using
+ <literal>N'...'</literal> over regular string constants.
+ </para>
+ </sect3>
+
<sect3 id="sql-syntax-bit-strings">
<title>Bit-String Constants</title>
--
2.43.0
view thread (6+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected]
Subject: Re: [PATCH] docs: document N'...' national character string literal syntax
In-Reply-To: <CAAGT0i+SrExi4LVf-gQ4t9XY724pVRxEvOZft4B0uUs-gDuYHA@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox