From 826f469fe681b9875437bfb7e3c805c092cf8b0a Mon Sep 17 00:00:00 2001
From: HodaSalim <hoda.s.salim@gmail.com>
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