Subject: Nit: "Immutable" should be "pure"

From: PG Doc comments form <[email-masked]>
Date: Thu, 07 Nov 2019 14:17:58 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/sql-createindex.html
Description:

The adjective "immutable" describing the functions and operators used in an
index (see two occurrences in doc snippet below) is incorrect and should be
replaced with "pure". Both "pure" and "immutable" are in popular lexicon now
because of the interest in functional programming, so conflating the two can
happen, but the word immutable applies to data and pure applies to
functions. See https://en.wikipedia.org/wiki/Pure_function. 

From the CREATE INDEX doc:
All functions and operators used in an index definition must be “immutable”,
that is, their results must depend only on their arguments and never on any
outside influence (such as the contents of another table or the current
time). This restriction ensures that the behavior of the index is
well-defined. To use a user-defined function in an index expression or WHERE
clause, remember to mark the function immutable when you create it.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 7 Nov 2019 12:28:30 -0500

> clause, remember to mark the function immutable when you create it.

Well, we use IMMUTABLE as an option to CREATE FUNCTION so I don't see
how we can realign to the new word meanings without a lot of confusion:

       CREATE [ OR REPLACE ] FUNCTION
           name ( [ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [, ...] ] )
           [ RETURNS rettype
             | RETURNS TABLE ( column_name column_type [, ...] ) ]
         { LANGUAGE lang_name
           | TRANSFORM { FOR TYPE type_name } [, ... ]
           | WINDOW
           | IMMUTABLE | STABLE | VOLATILE | [ NOT ] LEAKPROOF
             ^^^^^^^^^

I think the best we can do is to mention that IMMUTABLE functions mean
pure, but I am not sure there is even enough demand for that, vs.
confusing people.

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

---

From: Tom Lane <[email-masked]>
Date: Thu, 07 Nov 2019 12:38:11 -0500

Bruce Momjian <[email-masked]> writes:
>> replaced with "pure".

> pure, but I am not sure there is even enough demand for that, vs.

Yeah.  I don't think this terminology is nearly as universal
as the OP believes, so I don't feel a need to change anything.

If we adopt Corey's proposal to create a glossary [1], there'd be
room for a parenthetical comment like "(In some circles, "pure" is the
preferred term for this function property.)" in the glossary entry for
"immutable".  I suspect it won't be the only entry that needs
cross-references to other terminology.

			regards, tom lane

[1] https://commitfest.postgresql.org/25/2305/

---

From: Brian Williams <[email-masked]>
Date: Thu, 7 Nov 2019 13:04:28 -0500

Thanks for the feedback folks. I had not seen the IMMUTABLE argument to CREATE FUNCTION and realize this change is too expensive.

This probably will not be the last you hear on this since pureness and immutability are all the rage in development circles.   

> On Nov 7, 2019, at 12:38 PM, Tom Lane <[email-masked]> wrote:
>