From aecb9e6fdacb92cc96099afd89ad0a628b97e916 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] 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