Deprecating postfix and factorial operators in PostgreSQL 13
Hackers,
Over in [1] we have been discussing the deprecation of postfix operators, with the general consensus that deprecation warnings should be included in this upcoming release and postfix operator support should be removed in PostgreSQL 14. Since not all people who follow -hackers will necessarily have been following that thread, I am creating this new thread, with a patch which adds the deprecation notices, for your consideration.
The only postfix operator we ship in the standard catalogs is the factorial operator (!), which is deprecated by this patch.
The standard catalogs also include a prefix factorial operator (!!) which has been deprecated since 2011.
The deprecation warnings included in this patch warn that postfix operator support, along with both postfix ! and prefix !! factorial operators, will be removed in PostgreSQL 14.
Some of the deprecation verbiage supplied by John Naylor, some by me:
Attachments:
v1-0001-Adding-deprecation-notices.patchapplication/octet-stream; name=v1-0001-Adding-deprecation-notices.patch; x-unix-mode=0644Download
From 525663e5354feb851d38c71b34c172ebebb4b898 Mon Sep 17 00:00:00 2001
From: Mark Dilger <mark.dilger@enterprisedb.com>
Date: Thu, 27 Aug 2020 08:38:56 -0700
Subject: [PATCH v1] Adding deprecation notices.
This deprecates all three of:
Postfix factorial operator (!)
Prefix factorial operator (!!)
Unary right (postfix) operators
---
doc/src/sgml/func.sgml | 5 ++---
doc/src/sgml/ref/alter_opfamily.sgml | 7 +++++++
doc/src/sgml/ref/create_opclass.sgml | 7 +++++++
doc/src/sgml/ref/create_operator.sgml | 17 ++++++++++++++-
doc/src/sgml/ref/drop_operator.sgml | 2 +-
doc/src/sgml/typeconv.sgml | 2 +-
doc/src/sgml/xoper.sgml | 30 +++++++++++++++++++++------
src/include/catalog/pg_operator.dat | 4 ++--
src/include/catalog/pg_proc.dat | 2 +-
9 files changed, 61 insertions(+), 15 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index bbbffd9d5b..23ff6ff4c5 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1054,7 +1054,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>numeric</returnvalue>
</para>
<para>
- Factorial
+ Factorial (as a postfix operator, deprecated)
</para>
<para>
<literal>5 !</literal>
@@ -1068,14 +1068,13 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>numeric</returnvalue>
</para>
<para>
- Factorial (as a prefix operator)
+ Factorial (as a prefix operator, deprecated)
</para>
<para>
<literal>!! 5</literal>
<returnvalue>120</returnvalue>
</para></entry>
</row>
-
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>@</literal> <replaceable>numeric_type</replaceable>
diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml
index 4ac1cca95a..9b3064a5fe 100644
--- a/doc/src/sgml/ref/alter_opfamily.sgml
+++ b/doc/src/sgml/ref/alter_opfamily.sgml
@@ -146,6 +146,13 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="
must always be specified.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
In an <literal>ADD FUNCTION</literal> clause, the operand data type(s) the
function is intended to support, if different from
diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml
index f42fb6494c..e207f05132 100644
--- a/doc/src/sgml/ref/create_opclass.sgml
+++ b/doc/src/sgml/ref/create_opclass.sgml
@@ -166,6 +166,13 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL
as the operator class's data type.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
In a <literal>FUNCTION</literal> clause, the operand data type(s) the
function is intended to support, if different from
diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index d5c385c087..8374641ba4 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -87,11 +87,18 @@ CREATE OPERATOR <replaceable>name</replaceable> (
<para>
At least one of <literal>LEFTARG</literal> and <literal>RIGHTARG</literal> must be defined. For
- binary operators, both must be defined. For right unary
+ binary operators, both must be defined. For right unary
operators, only <literal>LEFTARG</literal> should be defined, while for left
unary operators only <literal>RIGHTARG</literal> should be defined.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
The <replaceable class="parameter">function_name</replaceable>
function must have been previously defined using <command>CREATE
@@ -165,6 +172,14 @@ CREATE OPERATOR <replaceable>name</replaceable> (
The data type of the operator's right operand, if any.
This option would be omitted for a right-unary operator.
</para>
+
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml
index 2dff050ecf..10d2b0b23b 100644
--- a/doc/src/sgml/ref/drop_operator.sgml
+++ b/doc/src/sgml/ref/drop_operator.sgml
@@ -121,7 +121,7 @@ DROP OPERATOR ~ (none, bit);
</para>
<para>
- Remove the right unary factorial operator <literal>x!</literal>
+ Remove the deprecated right unary factorial operator <literal>x!</literal>
for type <type>bigint</type>:
<programlisting>
DROP OPERATOR ! (bigint, none);
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index 8900d0eb38..9312f37c64 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -357,7 +357,7 @@ Some examples follow.
<title>Factorial Operator Type Resolution</title>
<para>
-There is only one factorial operator (postfix <literal>!</literal>)
+There is a deprecated factorial operator (postfix <literal>!</literal>)
defined in the standard catalog, and it takes an argument of type
<type>bigint</type>.
The scanner assigns an initial type of <type>integer</type> to the argument
diff --git a/doc/src/sgml/xoper.sgml b/doc/src/sgml/xoper.sgml
index 56b08491c9..847f8701d0 100644
--- a/doc/src/sgml/xoper.sgml
+++ b/doc/src/sgml/xoper.sgml
@@ -66,12 +66,23 @@ SELECT (a + b) AS c FROM test_complex;
<para>
We've shown how to create a binary operator here. To create unary
operators, just omit one of <literal>leftarg</literal> (for left unary) or
- <literal>rightarg</literal> (for right unary). The <literal>function</literal>
- clause and the argument clauses are the only required items in
- <command>CREATE OPERATOR</command>. The <literal>commutator</literal>
- clause shown in the example is an optional hint to the query
- optimizer. Further details about <literal>commutator</literal> and other
- optimizer hints appear in the next section.
+ <literal>rightarg</literal> (for right unary).
+ </para>
+
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
+ <para>
+ The <literal>function</literal> clause and the argument clauses are the only
+ required items in <command>CREATE OPERATOR</command>. The
+ <literal>commutator</literal> clause shown in the example is an optional
+ hint to the query optimizer. Further details about
+ <literal>commutator</literal> and other optimizer hints appear in the next
+ section.
</para>
</sect1>
@@ -205,6 +216,13 @@ SELECT (a + b) AS c FROM test_complex;
for all x, or the equivalent for right unary operators.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
An operator's negator must have the same left and/or right operand types
as the operator to be defined, so just as with <literal>COMMUTATOR</literal>, only the operator
diff --git a/src/include/catalog/pg_operator.dat b/src/include/catalog/pg_operator.dat
index 5b0e063655..0d013a7fd1 100644
--- a/src/include/catalog/pg_operator.dat
+++ b/src/include/catalog/pg_operator.dat
@@ -218,10 +218,10 @@
oprname => '>=', oprleft => 'xid8', oprright => 'xid8', oprresult => 'bool',
oprcom => '<=(xid8,xid8)', oprnegate => '<(xid8,xid8)', oprcode => 'xid8ge',
oprrest => 'scalargesel', oprjoin => 'scalargejoinsel' },
-{ oid => '388', descr => 'factorial',
+{ oid => '388', descr => 'deprecated, use factorial instead',
oprname => '!', oprkind => 'r', oprleft => 'int8', oprright => '0',
oprresult => 'numeric', oprcode => 'numeric_fac' },
-{ oid => '389', descr => 'deprecated, use ! instead',
+{ oid => '389', descr => 'deprecated, use factorial instead',
oprname => '!!', oprkind => 'l', oprleft => '0', oprright => 'int8',
oprresult => 'numeric', oprcode => 'numeric_fac' },
{ oid => '385', descr => 'equal',
diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index 27989971db..a08f4cf449 100644
--- a/src/include/catalog/pg_proc.dat
+++ b/src/include/catalog/pg_proc.dat
@@ -327,7 +327,7 @@
{ oid => '110', descr => 'I/O',
proname => 'unknownout', prorettype => 'cstring', proargtypes => 'unknown',
prosrc => 'unknownout' },
-{ oid => '111',
+{ oid => '111', descr => 'factorial',
proname => 'numeric_fac', prorettype => 'numeric', proargtypes => 'int8',
prosrc => 'numeric_fac' },
--
2.21.1 (Apple Git-122.3)
Mark Dilger <mark.dilger@enterprisedb.com> writes:
The deprecation warnings included in this patch warn that postfix operator support, along with both postfix ! and prefix !! factorial operators, will be removed in PostgreSQL 14.
The operator docs should say "use factorial() instead", or words to
that effect.
regards, tom lane
On Aug 27, 2020, at 9:16 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Mark Dilger <mark.dilger@enterprisedb.com> writes:
The deprecation warnings included in this patch warn that postfix operator support, along with both postfix ! and prefix !! factorial operators, will be removed in PostgreSQL 14.
The operator docs should say "use factorial() instead", or words to
that effect.regards, tom lane
Yes, that is better. Attached.
Attachments:
v2-0001-Adding-deprecation-notices.patchapplication/octet-stream; name=v2-0001-Adding-deprecation-notices.patch; x-unix-mode=0644Download
From f1f221312ccc282e644dd2ce93cc3b1e6ace6a40 Mon Sep 17 00:00:00 2001
From: Mark Dilger <mark.dilger@enterprisedb.com>
Date: Thu, 27 Aug 2020 08:38:56 -0700
Subject: [PATCH v2] Adding deprecation notices.
This deprecates all three of:
Postfix factorial operator (!)
Prefix factorial operator (!!)
Unary right (postfix) operators
---
doc/src/sgml/func.sgml | 7 +++----
doc/src/sgml/ref/alter_opfamily.sgml | 7 +++++++
doc/src/sgml/ref/create_opclass.sgml | 7 +++++++
doc/src/sgml/ref/create_operator.sgml | 17 ++++++++++++++-
doc/src/sgml/ref/drop_operator.sgml | 2 +-
doc/src/sgml/typeconv.sgml | 2 +-
doc/src/sgml/xoper.sgml | 30 +++++++++++++++++++++------
src/include/catalog/pg_operator.dat | 4 ++--
src/include/catalog/pg_proc.dat | 2 +-
9 files changed, 62 insertions(+), 16 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index bbbffd9d5b..b1bb6ff8f4 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1054,7 +1054,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>numeric</returnvalue>
</para>
<para>
- Factorial
+ Factorial (as a postfix operator, deprecated, use <link linkend="factorial">factorial()</link> instead)
</para>
<para>
<literal>5 !</literal>
@@ -1068,14 +1068,13 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>numeric</returnvalue>
</para>
<para>
- Factorial (as a prefix operator)
+ Factorial (as a prefix operator, deprecated, use <link linkend="factorial">factorial()</link> instead)
</para>
<para>
<literal>!! 5</literal>
<returnvalue>120</returnvalue>
</para></entry>
</row>
-
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>@</literal> <replaceable>numeric_type</replaceable>
@@ -1348,7 +1347,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
</row>
<row>
- <entry role="func_table_entry"><para role="func_signature">
+ <entry role="func_table_entry" id="factorial"><para role="func_signature">
<indexterm>
<primary>factorial</primary>
</indexterm>
diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml
index 4ac1cca95a..9b3064a5fe 100644
--- a/doc/src/sgml/ref/alter_opfamily.sgml
+++ b/doc/src/sgml/ref/alter_opfamily.sgml
@@ -146,6 +146,13 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="
must always be specified.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
In an <literal>ADD FUNCTION</literal> clause, the operand data type(s) the
function is intended to support, if different from
diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml
index f42fb6494c..e207f05132 100644
--- a/doc/src/sgml/ref/create_opclass.sgml
+++ b/doc/src/sgml/ref/create_opclass.sgml
@@ -166,6 +166,13 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL
as the operator class's data type.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
In a <literal>FUNCTION</literal> clause, the operand data type(s) the
function is intended to support, if different from
diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index d5c385c087..8374641ba4 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -87,11 +87,18 @@ CREATE OPERATOR <replaceable>name</replaceable> (
<para>
At least one of <literal>LEFTARG</literal> and <literal>RIGHTARG</literal> must be defined. For
- binary operators, both must be defined. For right unary
+ binary operators, both must be defined. For right unary
operators, only <literal>LEFTARG</literal> should be defined, while for left
unary operators only <literal>RIGHTARG</literal> should be defined.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
The <replaceable class="parameter">function_name</replaceable>
function must have been previously defined using <command>CREATE
@@ -165,6 +172,14 @@ CREATE OPERATOR <replaceable>name</replaceable> (
The data type of the operator's right operand, if any.
This option would be omitted for a right-unary operator.
</para>
+
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml
index 2dff050ecf..10d2b0b23b 100644
--- a/doc/src/sgml/ref/drop_operator.sgml
+++ b/doc/src/sgml/ref/drop_operator.sgml
@@ -121,7 +121,7 @@ DROP OPERATOR ~ (none, bit);
</para>
<para>
- Remove the right unary factorial operator <literal>x!</literal>
+ Remove the deprecated right unary factorial operator <literal>x!</literal>
for type <type>bigint</type>:
<programlisting>
DROP OPERATOR ! (bigint, none);
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index 8900d0eb38..9312f37c64 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -357,7 +357,7 @@ Some examples follow.
<title>Factorial Operator Type Resolution</title>
<para>
-There is only one factorial operator (postfix <literal>!</literal>)
+There is a deprecated factorial operator (postfix <literal>!</literal>)
defined in the standard catalog, and it takes an argument of type
<type>bigint</type>.
The scanner assigns an initial type of <type>integer</type> to the argument
diff --git a/doc/src/sgml/xoper.sgml b/doc/src/sgml/xoper.sgml
index 56b08491c9..847f8701d0 100644
--- a/doc/src/sgml/xoper.sgml
+++ b/doc/src/sgml/xoper.sgml
@@ -66,12 +66,23 @@ SELECT (a + b) AS c FROM test_complex;
<para>
We've shown how to create a binary operator here. To create unary
operators, just omit one of <literal>leftarg</literal> (for left unary) or
- <literal>rightarg</literal> (for right unary). The <literal>function</literal>
- clause and the argument clauses are the only required items in
- <command>CREATE OPERATOR</command>. The <literal>commutator</literal>
- clause shown in the example is an optional hint to the query
- optimizer. Further details about <literal>commutator</literal> and other
- optimizer hints appear in the next section.
+ <literal>rightarg</literal> (for right unary).
+ </para>
+
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
+ <para>
+ The <literal>function</literal> clause and the argument clauses are the only
+ required items in <command>CREATE OPERATOR</command>. The
+ <literal>commutator</literal> clause shown in the example is an optional
+ hint to the query optimizer. Further details about
+ <literal>commutator</literal> and other optimizer hints appear in the next
+ section.
</para>
</sect1>
@@ -205,6 +216,13 @@ SELECT (a + b) AS c FROM test_complex;
for all x, or the equivalent for right unary operators.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
An operator's negator must have the same left and/or right operand types
as the operator to be defined, so just as with <literal>COMMUTATOR</literal>, only the operator
diff --git a/src/include/catalog/pg_operator.dat b/src/include/catalog/pg_operator.dat
index 5b0e063655..0d013a7fd1 100644
--- a/src/include/catalog/pg_operator.dat
+++ b/src/include/catalog/pg_operator.dat
@@ -218,10 +218,10 @@
oprname => '>=', oprleft => 'xid8', oprright => 'xid8', oprresult => 'bool',
oprcom => '<=(xid8,xid8)', oprnegate => '<(xid8,xid8)', oprcode => 'xid8ge',
oprrest => 'scalargesel', oprjoin => 'scalargejoinsel' },
-{ oid => '388', descr => 'factorial',
+{ oid => '388', descr => 'deprecated, use factorial instead',
oprname => '!', oprkind => 'r', oprleft => 'int8', oprright => '0',
oprresult => 'numeric', oprcode => 'numeric_fac' },
-{ oid => '389', descr => 'deprecated, use ! instead',
+{ oid => '389', descr => 'deprecated, use factorial instead',
oprname => '!!', oprkind => 'l', oprleft => '0', oprright => 'int8',
oprresult => 'numeric', oprcode => 'numeric_fac' },
{ oid => '385', descr => 'equal',
diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index 27989971db..a08f4cf449 100644
--- a/src/include/catalog/pg_proc.dat
+++ b/src/include/catalog/pg_proc.dat
@@ -327,7 +327,7 @@
{ oid => '110', descr => 'I/O',
proname => 'unknownout', prorettype => 'cstring', proargtypes => 'unknown',
prosrc => 'unknownout' },
-{ oid => '111',
+{ oid => '111', descr => 'factorial',
proname => 'numeric_fac', prorettype => 'numeric', proargtypes => 'int8',
prosrc => 'numeric_fac' },
--
2.21.1 (Apple Git-122.3)
Hi Mark,
-{ oid => '111',
+{ oid => '111', descr => 'factorial',I see that opr_sanity fails without something here. We explicitly
don't have descriptions of functions that implement deprecated
operators (see setup_description() in initdb.c), but in all other
cases, there are also supported operators present. Technically, it's
not the same entry as the sql-callable function (1376), so it might be
better to try to match the other operator functions and say
"implementation of deprecated ! and !! operators".
For typeconv.sgml, it looks like in v14 we'll just have a different
operator entirely for the example, so ideally we would backpatch that
change for v13. What you have is good enough in a pinch, though.
--
John Naylor https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Thu, Aug 27, 2020 at 1:07 PM Mark Dilger
<mark.dilger@enterprisedb.com> wrote:
Yes, that is better. Attached.
So, in this version, there are six copies of the deprecation notice
John wrote, rather than just one. Maybe we need more than one, but I
doubt we need six. I don't think the CREATE OPERATOR documentation
needs to mention this both when first introducing the concept and then
again when defining right_type; the former seems sufficient. I don't
think xoper.sgml needs these changes either; they interrupt the flow
of the narrative and I don't think this is where anyone would look for
a deprecation notice. I would also argue for dropping the mentions in
the docs for ALTER OPERATOR FAMILY and CREATE OPERATOR CLASS, although
those seem less clear-cut. Really, CREATE OPERATOR where John had it
originally seems like the right place.
That being said, the changes to typeconv.sgml and drop_operator.sgml
seem like improvements, so I'd keep those.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
Robert Haas <robertmhaas@gmail.com> writes:
So, in this version, there are six copies of the deprecation notice
John wrote, rather than just one. Maybe we need more than one, but I
doubt we need six. I don't think the CREATE OPERATOR documentation
needs to mention this both when first introducing the concept and then
again when defining right_type; the former seems sufficient. I don't
think xoper.sgml needs these changes either; they interrupt the flow
of the narrative and I don't think this is where anyone would look for
a deprecation notice. I would also argue for dropping the mentions in
the docs for ALTER OPERATOR FAMILY and CREATE OPERATOR CLASS, although
those seem less clear-cut. Really, CREATE OPERATOR where John had it
originally seems like the right place.
Yeah, I agree that there are way too many copies here. CREATE OPERATOR
seems sufficient. It also seems like we should just rewrite the typeconv
and drop_operator examples to use some other operator. We'll have
to do that eventually anyway, so why not now, instead of visiting those
places twice?
regards, tom lane
On Fri, Aug 28, 2020 at 11:56 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
Yeah, I agree that there are way too many copies here. CREATE OPERATOR
seems sufficient. It also seems like we should just rewrite the typeconv
and drop_operator examples to use some other operator. We'll have
to do that eventually anyway, so why not now, instead of visiting those
places twice?
Hmm, that's an idea. I think it would be reasonable to rewrite the
typeconv.sgml one, but the one in drop_operator.sgml seems like it
could just be dropped. Its only purpose seems to be to demonstrate how
to drop a right-unary operator vs. a left-unary operator, but I
venture to guess that anyone smart enough to make any sort of
effective use of DROP OPERATOR could probably draw the necessary
inferences anyway.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
On Aug 28, 2020, at 8:56 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Robert Haas <robertmhaas@gmail.com> writes:
So, in this version, there are six copies of the deprecation notice
John wrote, rather than just one. Maybe we need more than one, but I
doubt we need six. I don't think the CREATE OPERATOR documentation
needs to mention this both when first introducing the concept and then
again when defining right_type; the former seems sufficient. I don't
think xoper.sgml needs these changes either; they interrupt the flow
of the narrative and I don't think this is where anyone would look for
a deprecation notice. I would also argue for dropping the mentions in
the docs for ALTER OPERATOR FAMILY and CREATE OPERATOR CLASS, although
those seem less clear-cut. Really, CREATE OPERATOR where John had it
originally seems like the right place.Yeah, I agree that there are way too many copies here. CREATE OPERATOR
seems sufficient. It also seems like we should just rewrite the typeconv
and drop_operator examples to use some other operator. We'll have
to do that eventually anyway, so why not now, instead of visiting those
places twice?
John's deprecation language now only appears in the create operator documentation.
The first typeconv example was based on the (int8 !) operator. I chose to replace it with and example based on the (jsonb ? text) operator, as the two operators have a relevant similarity. Both of them are singletons, with only one interpretation in the standard catalogs. In both cases, the scanner cannot know the types of the undecorated arguments and assigns default types (integer and unknown, respectively), which get resolved later to match the only types accepted by the operator ('int8' for !, and 'jsonb,text' for ?).
The drop operator example has been left, though altered to include the adjective "deprecated". Robert mentions that the entire example could simply be dropped now, and I agree with that, but it also makes sense to me to drop the example in 14, when the operation it describes is also dropped. If the committer who picks this up wants to drop that example now, that's fine, too.
Attachments:
v3-0001-Adding-deprecation-notices.patchapplication/octet-stream; name=v3-0001-Adding-deprecation-notices.patch; x-unix-mode=0644Download
From f7063a1e6556c4ac49bb98c86eda0cf62b15d087 Mon Sep 17 00:00:00 2001
From: Mark Dilger <mark.dilger@enterprisedb.com>
Date: Thu, 27 Aug 2020 08:38:56 -0700
Subject: [PATCH v3] Adding deprecation notices.
This deprecates all three of:
Postfix factorial operator (!)
Prefix factorial operator (!!)
Unary right (postfix) operators
---
doc/src/sgml/func.sgml | 6 ++---
doc/src/sgml/ref/create_operator.sgml | 9 ++++++-
doc/src/sgml/ref/drop_operator.sgml | 2 +-
doc/src/sgml/typeconv.sgml | 37 +++++++++++++++------------
src/include/catalog/pg_operator.dat | 4 +--
src/include/catalog/pg_proc.dat | 1 +
6 files changed, 36 insertions(+), 23 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index bbbffd9d5b..ef34e625af 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1054,7 +1054,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>numeric</returnvalue>
</para>
<para>
- Factorial
+ Factorial (as a postfix operator, deprecated, use <link linkend="factorial">factorial()</link> instead)
</para>
<para>
<literal>5 !</literal>
@@ -1068,7 +1068,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>numeric</returnvalue>
</para>
<para>
- Factorial (as a prefix operator)
+ Factorial (as a prefix operator, deprecated, use <link linkend="factorial">factorial()</link> instead)
</para>
<para>
<literal>!! 5</literal>
@@ -1348,7 +1348,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
</row>
<row>
- <entry role="func_table_entry"><para role="func_signature">
+ <entry role="func_table_entry" id="factorial"><para role="func_signature">
<indexterm>
<primary>factorial</primary>
</indexterm>
diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index d5c385c087..66c34e0072 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -87,11 +87,18 @@ CREATE OPERATOR <replaceable>name</replaceable> (
<para>
At least one of <literal>LEFTARG</literal> and <literal>RIGHTARG</literal> must be defined. For
- binary operators, both must be defined. For right unary
+ binary operators, both must be defined. For right unary
operators, only <literal>LEFTARG</literal> should be defined, while for left
unary operators only <literal>RIGHTARG</literal> should be defined.
</para>
+ <note>
+ <para>
+ Right unary, also called postfix, operators are deprecated and will be
+ removed in <productname>PostgreSQL</productname> version 14.
+ </para>
+ </note>
+
<para>
The <replaceable class="parameter">function_name</replaceable>
function must have been previously defined using <command>CREATE
diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml
index 2dff050ecf..10d2b0b23b 100644
--- a/doc/src/sgml/ref/drop_operator.sgml
+++ b/doc/src/sgml/ref/drop_operator.sgml
@@ -121,7 +121,7 @@ DROP OPERATOR ~ (none, bit);
</para>
<para>
- Remove the right unary factorial operator <literal>x!</literal>
+ Remove the deprecated right unary factorial operator <literal>x!</literal>
for type <type>bigint</type>:
<programlisting>
DROP OPERATOR ! (bigint, none);
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index 8900d0eb38..deba0de1c5 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -354,30 +354,35 @@ Some examples follow.
</para>
<example>
-<title>Factorial Operator Type Resolution</title>
+<title>JSONB Key Exists Operator Type Resolution</title>
<para>
-There is only one factorial operator (postfix <literal>!</literal>)
-defined in the standard catalog, and it takes an argument of type
-<type>bigint</type>.
-The scanner assigns an initial type of <type>integer</type> to the argument
-in this query expression:
+There is only one key exists operator (infix <literal>?</literal>) defined in
+the standard catalog, taking a left argument of type <type>jsonb</type> and a
+right argument of type <type>text</type>. The scanner assigns an initial type
+of <type>unknown</type> to each of the arguments in this query expression:
+</para>
<screen>
-SELECT 40 ! AS "40 factorial";
-
- 40 factorial
---------------------------------------------------
- 815915283247897734345611269596115894272000000000
+SELECT '{"poem":"Odyssey", "author":"Homer"}' ? 'author' AS "does author field exist";
+ does author field exist
+-------------------------
+ t
(1 row)
</screen>
-
-So the parser does a type conversion on the operand and the query
-is equivalent to:
+<para>
+No types are specified in the query, so the parser looks for all candidate
+operators and finds that there is only one candidate, which accepts
+<type>jsonb</type> and <type>text</type> inputs. The parser does type
+conversions on the operands and the query is equivalent to:
+</para>
<screen>
-SELECT CAST(40 AS bigint) ! AS "40 factorial";
+SELECT CAST('{"poem":"Odyssey", "author":"Homer"}' AS jsonb) ? CAST('author' AS text) AS "does author field exist";
+ does author field exist
+-------------------------
+ t
+(1 row)
</screen>
-</para>
</example>
<example>
diff --git a/src/include/catalog/pg_operator.dat b/src/include/catalog/pg_operator.dat
index 5b0e063655..0d013a7fd1 100644
--- a/src/include/catalog/pg_operator.dat
+++ b/src/include/catalog/pg_operator.dat
@@ -218,10 +218,10 @@
oprname => '>=', oprleft => 'xid8', oprright => 'xid8', oprresult => 'bool',
oprcom => '<=(xid8,xid8)', oprnegate => '<(xid8,xid8)', oprcode => 'xid8ge',
oprrest => 'scalargesel', oprjoin => 'scalargejoinsel' },
-{ oid => '388', descr => 'factorial',
+{ oid => '388', descr => 'deprecated, use factorial instead',
oprname => '!', oprkind => 'r', oprleft => 'int8', oprright => '0',
oprresult => 'numeric', oprcode => 'numeric_fac' },
-{ oid => '389', descr => 'deprecated, use ! instead',
+{ oid => '389', descr => 'deprecated, use factorial instead',
oprname => '!!', oprkind => 'l', oprleft => '0', oprright => 'int8',
oprresult => 'numeric', oprcode => 'numeric_fac' },
{ oid => '385', descr => 'equal',
diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index 27989971db..1dd325e0e6 100644
--- a/src/include/catalog/pg_proc.dat
+++ b/src/include/catalog/pg_proc.dat
@@ -328,6 +328,7 @@
proname => 'unknownout', prorettype => 'cstring', proargtypes => 'unknown',
prosrc => 'unknownout' },
{ oid => '111',
+ descr => 'implementation of deprecated ! and !! factorial operators',
proname => 'numeric_fac', prorettype => 'numeric', proargtypes => 'int8',
prosrc => 'numeric_fac' },
--
2.21.1 (Apple Git-122.3)
Mark Dilger <mark.dilger@enterprisedb.com> writes:
[ v3-0001-Adding-deprecation-notices.patch ]
Pushed with some fiddling.
We previously found that adding id tags to <entry> constructs in the
function lists didn't work in PDF output [1]/messages/by-id/32159.1586738304@sss.pgh.pa.us. Your patch did build
a PDF without warnings for me, which is odd --- apparently we changed
something since April? But the links didn't lead to quite the right
place, so the conclusion that there's something broken with that still
holds. I made it look like the existing usages for encode() and decode().
I did not like your choice of "jsonb ? text" for the typeconv example
at all, primarily because it introduces a host of distractions for anyone
who's not already quite familiar with both JSON and that operator.
After some digging around I found the |/ (square root) operator, which
likewise has just one instance, and it's something familiar enough that
most readers probably won't be slowed down by trying to figure out what
it does. Also, this more nearly covers the territory of the original
example, namely auto-casting an integer constant to something else.
There are later examples covering unknown-type literals, so we don't
need to address that scenario in this one.
I also found another example that depends on the ! operator, in the
operator precedence discussion. I concluded after study that the
particular case it's on about only arises for postfix operators,
so I just got rid of that example in favor of a generalized mention
that you should use parentheses to override operator precedence.
I concluded that there's not much point in touching drop_operator.sgml
at all yet. I don't think labeling ! as deprecated as adding anything
to that example, and besides there's another example that will also need
to be changed.
regards, tom lane
On Aug 30, 2020, at 11:50 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Mark Dilger <mark.dilger@enterprisedb.com> writes:
[ v3-0001-Adding-deprecation-notices.patch ]
Pushed with some fiddling.
Thanks!
—
Mark Dilger
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company