Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1vaJXn-006niN-1H
	for pgsql-docs@arkaria.postgresql.org;
	Mon, 29 Dec 2025 20:08:44 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.96)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1vaJXm-000dAp-0R
	for pgsql-docs@arkaria.postgresql.org;
	Mon, 29 Dec 2025 20:08:42 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1vaJXl-000dAf-2u
	for pgsql-docs@lists.postgresql.org;
	Mon, 29 Dec 2025 20:08:42 +0000
Received: from sss.pgh.pa.us ([68.162.161.243])
	by makus.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1vaJXl-003EBu-0e
	for pgsql-docs@lists.postgresql.org;
	Mon, 29 Dec 2025 20:08:41 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 5BTK8eOV2998402
	for <pgsql-docs@lists.postgresql.org>; Mon, 29 Dec 2025 15:08:40 -0500
From: Tom Lane <tgl@sss.pgh.pa.us>
To: pgsql-docs@lists.postgresql.org
Subject: Obsolete/mangled Note about composite-value I/O syntax
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <2998400.1767038920.1@sss.pgh.pa.us>
Date: Mon, 29 Dec 2025 15:08:40 -0500
Message-ID: <2998401.1767038920@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/2998401.1767038920%40sss.pgh.pa.us>
Precedence: bulk

In section 8.16.6. Composite Type Input and Output Syntax [1]
we have this <note> text:

    Remember that what you write in an SQL command will first be
    interpreted as a string literal, and then as a composite. This
    doubles the number of backslashes you need (assuming escape string
    syntax is used). For example, to insert a text field containing a
    double quote and a backslash in a composite value, you'd need to
    write:

    INSERT ... VALUES ('("\"\\")');

    The string-literal processor removes one level of backslashes, so
    that what arrives at the composite-value parser looks like
    ("\"\\"). In turn, the string fed to the text data type's input
    routine becomes "\. (If we were working with a data type whose
    input routine also treated backslashes specially, bytea for
    example, we might need as many as eight backslashes in the command
    to get one backslash into the stored composite field.) Dollar
    quoting (see Section 4.1.2.4) can be used to avoid the need to
    double backslashes.

This is a mess.  I think that the example INSERT was originally
written assuming that standard_conforming_strings is OFF, so that
it had twice as many backslashes as now.  Then somebody removed those
extra backslashes without considering whether the example as a whole
still made any sense at all; and it doesn't.  "The string-literal
processor removes one level of backslashes" is just false given this
example.  The cross-reference to dollar quoting is pretty unhelpful
too, because all that does for you is remove the need for doubling
backslashes an extra time, which is already gone with
standard-conforming strings.

My guess is that nearly nobody uses escape string syntax anymore,
so I think that rather than trying to rewrite this <note> into
something less confused, we should just nuke it altogether.
There is no corresponding text in the preceding section about
array I/O syntax, although that's just about as gnarly.

			regards, tom lane

[1] https://www.postgresql.org/docs/devel/rowtypes.html#ROWTYPES-IO-SYNTAX