deprecating =>, take two
By consensus, we have removed the new-to-9.0 operator text[] => text[]
and renamed the hstore => text[] operator. (The current name is "%",
but there is some discussion of "%>", some yet other name, or getting
rid of it altogether; please comment on that thread if you wish to
weigh in.) This means that the only remaining => operator in CVS is
the text => text operator which constructs a single-element hstore,
which has been around since 8.2. In lieu of providing a substitute
operator, Tom Lane proposed that we simply encourage people to use the
hstore(text, text) function which does the same thing:
http://archives.postgresql.org/pgsql-hackers/2010-06/msg00711.php
Per that email, and subsequent concurrence, here is a series of
patches which does the following:
1. In CVS HEAD, document the hstore(text, text) function and adjust
CREATE OPERATOR to throw a warning when => is used as an operator
name, using the wording previously suggested by Tom.
2. In the back branches, add an hstore(text, text) function. These
branches already have a tconvert(text, text) function which does the
same thing, but the consensus seemed to be that we do not want to go
back to the name tconvert() for this functionality, and that
back-patching the new name was preferable.
3. In 8.4 and 8.3, also add hstore(text, text) to the documentation.
8.2 appears to have no contrib documentation.
Barring vigorous objections, I will apply these tomorrow so that we
can consider deprecating => as an operator name in 9.1, for better
compliance with the SQL standard.
http://archives.postgresql.org/pgsql-hackers/2010-05/msg01501.php
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company
Attachments:
hstore_82.patchapplication/octet-stream; name=hstore_82.patchDownload
diff --git a/contrib/hstore/hstore.sql.in b/contrib/hstore/hstore.sql.in
index 95cecf1..4e7c494 100644
--- a/contrib/hstore/hstore.sql.in
+++ b/contrib/hstore/hstore.sql.in
@@ -118,6 +118,12 @@ RETURNS hstore
AS 'MODULE_PATHNAME'
LANGUAGE 'C' with (isstrict,iscachable);
+-- For forward compatibility with PostgreSQL >= 9.0
+CREATE OR REPLACE FUNCTION hstore(text,text)
+RETURNS hstore
+AS 'MODULE_PATHNAME', 'tconvert'
+LANGUAGE C IMMUTABLE; -- not STRICT
+
CREATE OPERATOR => (
LEFTARG = text,
RIGHTARG = text,
diff --git a/contrib/hstore/uninstall_hstore.sql b/contrib/hstore/uninstall_hstore.sql
index bfa2e73..f0b9fa5 100644
--- a/contrib/hstore/uninstall_hstore.sql
+++ b/contrib/hstore/uninstall_hstore.sql
@@ -21,6 +21,7 @@ DROP FUNCTION hs_concat(hstore,hstore);
DROP FUNCTION hs_contains(hstore,hstore);
DROP FUNCTION hs_contained(hstore,hstore);
DROP FUNCTION tconvert(text,text);
+DROP FUNCTION hstore(text,text);
DROP FUNCTION akeys(hstore);
DROP FUNCTION avals(hstore);
DROP FUNCTION skeys(hstore);
hstore_83.patchapplication/octet-stream; name=hstore_83.patchDownload
diff --git a/contrib/hstore/hstore.sql.in b/contrib/hstore/hstore.sql.in
index 9ce52f1..0d1cea5 100644
--- a/contrib/hstore/hstore.sql.in
+++ b/contrib/hstore/hstore.sql.in
@@ -129,6 +129,12 @@ RETURNS hstore
AS 'MODULE_PATHNAME'
LANGUAGE C IMMUTABLE;
+-- For forward compatibility with PostgreSQL >= 9.0
+CREATE OR REPLACE FUNCTION hstore(text,text)
+RETURNS hstore
+AS 'MODULE_PATHNAME', 'tconvert'
+LANGUAGE C IMMUTABLE; -- not STRICT
+
CREATE OPERATOR => (
LEFTARG = text,
RIGHTARG = text,
diff --git a/contrib/hstore/uninstall_hstore.sql b/contrib/hstore/uninstall_hstore.sql
index 78a8314..fed5fc3 100644
--- a/contrib/hstore/uninstall_hstore.sql
+++ b/contrib/hstore/uninstall_hstore.sql
@@ -26,6 +26,7 @@ DROP FUNCTION hs_concat(hstore,hstore);
DROP FUNCTION hs_contains(hstore,hstore);
DROP FUNCTION hs_contained(hstore,hstore);
DROP FUNCTION tconvert(text,text);
+DROP FUNCTION hstore(text,text);
DROP FUNCTION akeys(hstore);
DROP FUNCTION avals(hstore);
DROP FUNCTION skeys(hstore);
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index 1dde684..b6d551f 100644
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -150,6 +150,14 @@
<tbody>
<row>
+ <entry><function>hstore(text, text)</function></entry>
+ <entry><type>hstore</type></entry>
+ <entry>make single-item <type>hstore</></entry>
+ <entry><literal>hstore('a', 'b')</literal></entry>
+ <entry><literal>"a"=>"b"</literal></entry>
+ </row>
+
+ <row>
<entry><function>akeys(hstore)</function></entry>
<entry><type>text[]</type></entry>
<entry>get <type>hstore</>'s keys as array</entry>
hstore_84.patchapplication/octet-stream; name=hstore_84.patchDownload
diff --git a/contrib/hstore/hstore.sql.in b/contrib/hstore/hstore.sql.in
index 2e9b6b5..191f4b6 100644
--- a/contrib/hstore/hstore.sql.in
+++ b/contrib/hstore/hstore.sql.in
@@ -129,6 +129,12 @@ RETURNS hstore
AS 'MODULE_PATHNAME'
LANGUAGE C IMMUTABLE; -- not STRICT
+-- For forward compatibility with PostgreSQL >= 9.0
+CREATE OR REPLACE FUNCTION hstore(text,text)
+RETURNS hstore
+AS 'MODULE_PATHNAME', 'tconvert'
+LANGUAGE C IMMUTABLE; -- not STRICT
+
CREATE OPERATOR => (
LEFTARG = text,
RIGHTARG = text,
diff --git a/contrib/hstore/uninstall_hstore.sql b/contrib/hstore/uninstall_hstore.sql
index 74bc852..725b548 100644
--- a/contrib/hstore/uninstall_hstore.sql
+++ b/contrib/hstore/uninstall_hstore.sql
@@ -26,6 +26,7 @@ DROP FUNCTION hs_concat(hstore,hstore);
DROP FUNCTION hs_contains(hstore,hstore);
DROP FUNCTION hs_contained(hstore,hstore);
DROP FUNCTION tconvert(text,text);
+DROP FUNCTION hstore(text,text);
DROP FUNCTION akeys(hstore);
DROP FUNCTION avals(hstore);
DROP FUNCTION skeys(hstore);
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index 1dde684..b6d551f 100644
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -150,6 +150,14 @@
<tbody>
<row>
+ <entry><function>hstore(text, text)</function></entry>
+ <entry><type>hstore</type></entry>
+ <entry>make single-item <type>hstore</></entry>
+ <entry><literal>hstore('a', 'b')</literal></entry>
+ <entry><literal>"a"=>"b"</literal></entry>
+ </row>
+
+ <row>
<entry><function>akeys(hstore)</function></entry>
<entry><type>text[]</type></entry>
<entry>get <type>hstore</>'s keys as array</entry>
hstore_90.patchapplication/octet-stream; name=hstore_90.patchDownload
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index 76d876b..78c2e81 100644
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -225,6 +225,14 @@
</para>
</note>
+ <note>
+ <para>
+ The <literal>=></> operator is deprecated and may be removed in a
+ future release. The use of the <literal>hstore(text, text)</literal>
+ function is recommended as an alternative.
+ </para>
+ </note>
+
<table id="hstore-func-table">
<title><type>hstore</> Functions</title>
@@ -266,6 +274,14 @@
</row>
<row>
+ <entry><function>hstore(text, text)</function></entry>
+ <entry><type>hstore</type></entry>
+ <entry>make single-item <type>hstore</></entry>
+ <entry><literal>hstore('a', 'b')</literal></entry>
+ <entry><literal>"a"=>"b"</literal></entry>
+ </row>
+
+ <row>
<entry><function>akeys(hstore)</function></entry>
<entry><type>text[]</type></entry>
<entry>get <type>hstore</>'s keys as an array</entry>
diff --git a/src/backend/commands/operatorcmds.c b/src/backend/commands/operatorcmds.c
index 9c07cf3..c0dc7a2 100644
--- a/src/backend/commands/operatorcmds.c
+++ b/src/backend/commands/operatorcmds.c
@@ -88,6 +88,16 @@ DefineOperator(List *names, List *parameters)
/* Convert list of names to a name and namespace */
oprNamespace = QualifiedNameGetCreationNamespace(names, &oprName);
+ /*
+ * The SQL standard committee has decided that => should be used for
+ * named parameters; therefore, a future release of PostgreSQL may
+ * disallow it as the name of a user-defined operator.
+ */
+ if (strcmp(oprName, "=>") == 0)
+ ereport(WARNING,
+ (errmsg("=> is deprecated as an operator name"),
+ errdetail("This name may be disallowed altogether in future versions of PostgreSQL.")));
+
/* Check we have creation rights in target namespace */
aclresult = pg_namespace_aclcheck(oprNamespace, GetUserId(), ACL_CREATE);
if (aclresult != ACLCHECK_OK)
On Jun 21, 2010, at 9:20 AM, Robert Haas wrote:
Per that email, and subsequent concurrence, here is a series of
patches which does the following:1. In CVS HEAD, document the hstore(text, text) function and adjust
CREATE OPERATOR to throw a warning when => is used as an operator
name, using the wording previously suggested by Tom.
2. In the back branches, add an hstore(text, text) function. These
branches already have a tconvert(text, text) function which does the
same thing, but the consensus seemed to be that we do not want to go
back to the name tconvert() for this functionality, and that
back-patching the new name was preferable.
3. In 8.4 and 8.3, also add hstore(text, text) to the documentation.
8.2 appears to have no contrib documentation.
+1
I was just about to email asking where this was. Glad I checked for new mail first. :-)
Barring vigorous objections, I will apply these tomorrow so that we
can consider deprecating => as an operator name in 9.1, for better
compliance with the SQL standard.
So will the CREATE OPERATOR code be updated to issue the warning, rather than just for the case of hstore's => operator?
Best,
David
Excerpts from Robert Haas's message of lun jun 21 12:20:59 -0400 2010:
Barring vigorous objections, I will apply these tomorrow so that we
can consider deprecating => as an operator name in 9.1, for better
compliance with the SQL standard.
Maybe this is just a matter of semantics, but I thought we were going to
deprecate => in 9.0 so that people started to avoid its use altogether.
Why wait till 9.1 to recommend avoidance?
I had imagined that 9.1 was going to ban => altogether.
--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
On Mon, Jun 21, 2010 at 12:40 PM, Alvaro Herrera
<alvherre@commandprompt.com> wrote:
Excerpts from Robert Haas's message of lun jun 21 12:20:59 -0400 2010:
Barring vigorous objections, I will apply these tomorrow so that we
can consider deprecating => as an operator name in 9.1, for better
compliance with the SQL standard.Maybe this is just a matter of semantics, but I thought we were going to
deprecate => in 9.0 so that people started to avoid its use altogether.
Why wait till 9.1 to recommend avoidance?I had imagined that 9.1 was going to ban => altogether.
Sorry, bad phrasing on my part. Your understanding matches mine.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company
On Mon, Jun 21, 2010 at 12:37 PM, David E. Wheeler <david@kineticode.com> wrote:
Barring vigorous objections, I will apply these tomorrow so that we
can consider deprecating => as an operator name in 9.1, for better
compliance with the SQL standard.So will the CREATE OPERATOR code be updated to issue the warning, rather than just for the case of hstore's => operator?
Yes.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company
Robert Haas <robertmhaas@gmail.com> writes:
Barring vigorous objections, I will apply these tomorrow so that we
can consider deprecating => as an operator name in 9.1, for better
compliance with the SQL standard.
Two documentation comments:
1. Perhaps, rather than
+ The <literal>=></> operator is deprecated and may be removed in a + future release. The use of the <literal>hstore(text, text)</literal> + function is recommended as an alternative.
write
+ The <literal>=></> operator is deprecated and will be removed in a + future release. Use the <literal>hstore(text, text)</literal> + function instead.
in particular, s/may/will/ and avoid passive voice in the second sentence.
2. The 8.4 and 8.3 doc patches should include this same paragraph.
regards, tom lane
On Mon, Jun 21, 2010 at 1:24 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Robert Haas <robertmhaas@gmail.com> writes:
Barring vigorous objections, I will apply these tomorrow so that we
can consider deprecating => as an operator name in 9.1, for better
compliance with the SQL standard.Two documentation comments:
1. Perhaps, rather than
+ The <literal>=></> operator is deprecated and may be removed in a + future release. The use of the <literal>hstore(text, text)</literal> + function is recommended as an alternative.write
+ The <literal>=></> operator is deprecated and will be removed in a + future release. Use the <literal>hstore(text, text)</literal> + function instead.in particular, s/may/will/ and avoid passive voice in the second sentence.
Avoiding the passive voice is a good idea, and I like your suggested
phrasing. I'm reluctant to say what we "will" do in a future release
because we don't always do what we claim we'll do. For example, we're
planning to remove contrib/xml2 in 8.4.
http://developer.postgresql.org/pgdocs/postgres/xml2.html
Still, I haven't heard too many arguments against disallowing => as an
operator, so perhaps it's safe to bank on it actually happening in
this case?
2. The 8.4 and 8.3 doc patches should include this same paragraph.
OK.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company
Robert Haas <robertmhaas@gmail.com> writes:
By consensus, we have removed the new-to-9.0 operator text[] => text[]
and renamed the hstore => text[] operator. (The current name is "%",
but there is some discussion of "%>", some yet other name, or getting
rid of it altogether; please comment on that thread if you wish to
weigh in.)
Hey, you're asking for bikesheding! %> would be my choice too.
--
dim
On Mon, Jun 21, 2010 at 1:46 PM, Dimitri Fontaine
<dfontaine@hi-media.com> wrote:
Robert Haas <robertmhaas@gmail.com> writes:
By consensus, we have removed the new-to-9.0 operator text[] => text[]
and renamed the hstore => text[] operator. (The current name is "%",
but there is some discussion of "%>", some yet other name, or getting
rid of it altogether; please comment on that thread if you wish to
weigh in.)Hey, you're asking for bikesheding! %> would be my choice too.
The point was that if you want to bikeshed, please do it on the OTHER
thread, not this one. :-)
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company
Robert Haas <robertmhaas@gmail.com> writes:
On Mon, Jun 21, 2010 at 1:24 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
in particular, s/may/will/ and avoid passive voice in the second sentence.
Avoiding the passive voice is a good idea, and I like your suggested
phrasing. I'm reluctant to say what we "will" do in a future release
because we don't always do what we claim we'll do.
True.
Still, I haven't heard too many arguments against disallowing => as an
operator, so perhaps it's safe to bank on it actually happening in
this case?
AFAICS, the only way we won't do it is if the SQL committee reverses
field on the syntax they're using. I'm not going to promise that it
will change in 9.1 --- we might wait longer --- but once => is official
standard syntax the pressure to do it will be high.
regards, tom lane