public inbox for [email protected]help / color / mirror / Atom feed
[PATCH] docs: document N'...' national character string literal syntax 6+ messages / 4 participants [nested] [flat]
* [PATCH] docs: document N'...' national character string literal syntax @ 2026-02-02 15:05 Hoda Salim <[email protected]> 2026-02-02 17:09 ` Re: [PATCH] docs: document N'...' national character string literal syntax Erik Wienhold <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Hoda Salim @ 2026-02-02 15:05 UTC (permalink / raw) To: [email protected] Hi, 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. -- Hoda Salim Attachments: [application/octet-stream] 0001-docs-document-N-national-character-string-literal.patch (3.1K, ../../CAAGT0iKc1Fq=mmK99fMd8O+QGZfCAqzx3bOWBcci6fO8SjLGtQ@mail.gmail.com/2-0001-docs-document-N-national-character-string-literal.patch) download | inline diff: From aecb9e6fdacb92cc96099afd89ad0a628b97e916 Mon Sep 17 00:00:00 2001 From: HodaSalim <[email protected]> Date: Mon, 2 Feb 2026 14:54:37 +0000 Subject: [PATCH] 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 cast to the character type using the database's encoding, since PostgreSQL uses a single character set for all string types. --- doc/src/sgml/syntax.sgml | 43 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 67482996861..85e1f9c436f 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -590,6 +590,49 @@ $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 regular string constant cast to the + <type>character</type> type, that is, <literal>'...'::character</literal>, + using the database's character set. + Since <type>character</type> without a length specifier accepts strings + of any size, the result is a value of type <type>character</type> + with the length of the given string. Note that trailing spaces + are semantically insignificant in <type>character</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 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: [PATCH] docs: document N'...' national character string literal syntax 2026-02-02 15:05 [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> @ 2026-02-02 17:09 ` Erik Wienhold <[email protected]> 2026-02-02 20:04 ` Re: [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Erik Wienhold @ 2026-02-02 17:09 UTC (permalink / raw) To: Hoda Salim <[email protected]>; +Cc: [email protected] 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 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: [PATCH] docs: document N'...' national character string literal syntax 2026-02-02 15:05 [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> 2026-02-02 17:09 ` Re: [PATCH] docs: document N'...' national character string literal syntax Erik Wienhold <[email protected]> @ 2026-02-02 20:04 ` Hoda Salim <[email protected]> 2026-02-04 00:24 ` Re: [PATCH] docs: document N'...' national character string literal syntax Erik Wienhold <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Hoda Salim @ 2026-02-02 20:04 UTC (permalink / raw) To: Erik Wienhold <[email protected]>; +Cc: [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 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: [PATCH] docs: document N'...' national character string literal syntax 2026-02-02 15:05 [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> 2026-02-02 17:09 ` Re: [PATCH] docs: document N'...' national character string literal syntax Erik Wienhold <[email protected]> 2026-02-02 20:04 ` Re: [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> @ 2026-02-04 00:24 ` Erik Wienhold <[email protected]> 2026-02-04 01:31 ` Re: [PATCH] docs: document N'...' national character string literal syntax David G. Johnston <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Erik Wienhold @ 2026-02-04 00:24 UTC (permalink / raw) To: Hoda Salim <[email protected]>; +Cc: [email protected] On 2026-02-02 21:04 +0100, Hoda Salim wrote: > > 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. Thanks! The text looks good now. But please fix the indentation of the second paragraph (should be one space per level). Your first patch was correct in that regard. > > 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. I'd prefer a single patch with both changes to have an atomic change. But in the end it's up to the committer, not me. -- Erik Wienhold ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: [PATCH] docs: document N'...' national character string literal syntax 2026-02-02 15:05 [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> 2026-02-02 17:09 ` Re: [PATCH] docs: document N'...' national character string literal syntax Erik Wienhold <[email protected]> 2026-02-02 20:04 ` Re: [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> 2026-02-04 00:24 ` Re: [PATCH] docs: document N'...' national character string literal syntax Erik Wienhold <[email protected]> @ 2026-02-04 01:31 ` David G. Johnston <[email protected]> 2026-02-04 05:22 ` Re: [PATCH] docs: document N'...' national character string literal syntax Tom Lane <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: David G. Johnston @ 2026-02-04 01:31 UTC (permalink / raw) To: Erik Wienhold <[email protected]>; +Cc: Hoda Salim <[email protected]>; [email protected] On Tue, Feb 3, 2026 at 5:24 PM Erik Wienhold <[email protected]> wrote: > On 2026-02-02 21:04 +0100, Hoda Salim wrote: > > > nchar is an alias of bpchar. There's no cast to char behind the scenes > > > since that would truncate the string: > I'm seeing things differently: postgres=# select '123 '::nchar, '123 '::bpchar; bpchar | bpchar --------+-------- 1 | 123 (1 row) Not a huge fan of the proposed wording but partly because the rest of the section doesn't mention data types at all so this is going to move the bar forward, leaving the others behind. nit: I don't like saying N'...' is equivalent to a data type; something more like N'...' produces a value of type bpchar. Also, any reason not to just say: "This syntax is accepted for compatibility with the SQL standard." and move on? Repeating "uses a single character set/does not implement a separate national character set" seems unnecessary. If there is at least one secondary consideration for accepting this syntax we should state what it is. I'd copy the E'...' wording in the first paragraph: ... just before the opening single quote, e.g., N'foo'. I'd suggest going even further in the emulation by leading with the title of the thing being described, then the syntax. i.e., flip the ordering of the first two sentences and rework for flow. My thought: For compatibility with the SQL standard, PostgreSQL accepts national character string constants. A national character string constant is specified by writing the letter N (upper or lower case) just before the opening single quote, e.g., N'foo'. (When continuing a national character string constant across lines, write N only before the first opening quote.) PostgreSQL's implementation requires that characters comprising the literal be encoded using the database encoding, just like all other string constants. In fact, the concept of national character strings is implemented purely at the SQL syntax layer (including data type names nchar and nchar varying). Within the database, the bpchar and bpchar(n) data types are used. A similar note would be added to Data Types. I'd add after Example 8.1: The SQL standard defines two additional data types pertaining to national character strings. PostgreSQL only accommodates a single, database-wide, character set via its database encoding, and so gains no practical benefit from these distinct data types. However, as a compatibility shim, PostgreSQL does implement SQL syntax to accept the nchar and nchar varying data types. These get mapped onto bpchar and bpchar(n) (and thus character) data types respectively. David J. ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: [PATCH] docs: document N'...' national character string literal syntax 2026-02-02 15:05 [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> 2026-02-02 17:09 ` Re: [PATCH] docs: document N'...' national character string literal syntax Erik Wienhold <[email protected]> 2026-02-02 20:04 ` Re: [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> 2026-02-04 00:24 ` Re: [PATCH] docs: document N'...' national character string literal syntax Erik Wienhold <[email protected]> 2026-02-04 01:31 ` Re: [PATCH] docs: document N'...' national character string literal syntax David G. Johnston <[email protected]> @ 2026-02-04 05:22 ` Tom Lane <[email protected]> 0 siblings, 0 replies; 6+ messages in thread From: Tom Lane @ 2026-02-04 05:22 UTC (permalink / raw) To: David G. Johnston <[email protected]>; +Cc: Erik Wienhold <[email protected]>; Hoda Salim <[email protected]>; [email protected] "David G. Johnston" <[email protected]> writes: > Also, any reason not to just say: > "This syntax is accepted for compatibility with the SQL standard." and > move on? +1. The syntax does not in fact do anything that anyone would call useful. And I'm also unsure that it really satisfies what the standard suggests it should do. On the whole, leaving it in undocumented obscurity seems fine to me. But if we must mention it, the less said the better. Nobody will read a paragraph about this and think their time was well spent. regards, tom lane ^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2026-02-04 05:22 UTC | newest] Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-02-02 15:05 [PATCH] docs: document N'...' national character string literal syntax Hoda Salim <[email protected]> 2026-02-02 17:09 ` Erik Wienhold <[email protected]> 2026-02-02 20:04 ` Hoda Salim <[email protected]> 2026-02-04 00:24 ` Erik Wienhold <[email protected]> 2026-02-04 01:31 ` David G. Johnston <[email protected]> 2026-02-04 05:22 ` Tom Lane <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox