Improve description for quote_ident()

From: Erwin Brandstetter <brsaweda(at)gmail(dot)com>
To: pgsql-docs(at)lists(dot)postgresql(dot)org
Subject: Improve description for quote_ident()
Date: 2021-03-17 01:44:41
Message-ID: CAGHENJ70R4zxsSS9odXvtB7oVqOXA630eMTMdndqtBPdeYXGpA@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

In the current manual, Table 9.10
<https://www.postgresql.org/docs/13/functions-string.html#FUNCTIONS-STRING-OTHER>
has this to say about quote_ident():

> Returns the given string suitably quoted to be used as an identifier in
an SQL statement string. Quotes are added only if necessary (i.e., if the
string contains non-identifier characters or would be case-folded).
Embedded quotes are properly doubled. See also Example 42.1
<https://www.postgresql.org/docs/13/plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE>
.

No mention of SQL key words which are also double-quoted. There was a
related question on stackoverflow today:

https://stackoverflow.com/questions/66662580/quote-ident-does-not-add-quotes-to-column-name-first

I suggest to at least mention key words:

* Returns the given string suitably quoted to be used as an identifier in
an SQL statement string. Quotes are added only if necessary (i.e., if the
string contains non-identifier characters, would be case-folded, or is a
reserved key word). *Embedded quotes are properly doubled. See also
Example 42.1
<https://www.postgresql.org/docs/13/plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE>
.

To be precise: key words marked *"reserved"* or *"(cannot be function or
type)"* in the column "PostgreSQL" of the *SQL Key Words*
<https://www.postgresql.org/docs/current/sql-keywords-appendix.html#KEYWORDS-TABLE>
table are quoted. And if the GUC quote_all_identifiers
<https://www.postgresql.org/docs/current/runtime-config-compatible.html#GUC-QUOTE-ALL-IDENTIFIERS>
is set, then all strings are quoted. If that's not too much information, we
might make it:

*Returns the given string suitably quoted to be used as an identifier in an
SQL statement string. Quotes are added only if necessary: if the string
contains non-identifier characters, would be case-folded, or is a reserved
word (marked "reserved" or "(cannot be function or type)" in Table C.1
<https://www.postgresql.org/docs/current/sql-keywords-appendix.html#KEYWORDS-TABLE>).
Embedded quotes are properly doubled. See also Example 42.1
<https://www.postgresql.org/docs/13/plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE>
and quote_all_identifiers
<https://www.postgresql.org/docs/current/runtime-config-compatible.html#GUC-QUOTE-ALL-IDENTIFIERS>.*

Regards
Erwin

Browse pgsql-docs by date

  From Date Subject
Next Message PG Doc comments form 2021-03-17 06:51:03 A very confusing line...
Previous Message PG Doc comments form 2021-03-16 17:56:46 Duplicate "SELECT current_user;"