Allow new values to be added to an existing enum type.

After much expenditure of effort, we've got this to the point where the
performance penalty is pretty minimal in typical cases.

Andrew Dunstan, reviewed by Brendan Jurd, Dean Rasheed, and Tom Lane

2 files changed, 94 insertions, 7 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index b7b48e4fb93..9a8729b8b31 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -2623,12 +2623,9 @@
 
   <para>
    The <structname>pg_enum</structname> catalog contains entries
-   matching enum types to their associated values and labels. The
+   showing the values and labels for each enum type. The
    internal representation of a given enum value is actually the OID
-   of its associated row in <structname>pg_enum</structname>.  The
-   OIDs for a particular enum type are guaranteed to be ordered in
-   the way the type should sort, but there is no guarantee about the
-   ordering of OIDs of unrelated enum types.
+   of its associated row in <structname>pg_enum</structname>.
   </para>
 
   <table>
@@ -2653,6 +2650,13 @@
      </row>
 
      <row>
+      <entry><structfield>enumsortorder</structfield></entry>
+      <entry><type>float4</type></entry>
+      <entry></entry>
+      <entry>The sort position of this enum value within its enum type</entry>
+     </row>
+
+     <row>
       <entry><structfield>enumlabel</structfield></entry>
       <entry><type>name</type></entry>
       <entry></entry>
@@ -2661,6 +2665,26 @@
     </tbody>
    </tgroup>
   </table>
+
+  <para>
+   The OIDs for <structname>pg_enum</structname> rows follow a special
+   rule: even-numbered OIDs are guaranteed to be ordered in the same way
+   as the sort ordering of their enum type.  That is, if two even OIDs
+   belong to the same enum type, the smaller OID must have the smaller
+   <structfield>enumsortorder</structfield> value.  Odd-numbered OID values
+   need bear no relationship to the sort order.  This rule allows the
+   enum comparison routines to avoid catalog lookups in many common cases.
+   The routines that create and alter enum types attempt to assign even
+   OIDs to enum values whenever possible.
+  </para>
+
+  <para>
+   When an enum type is created, its members are assigned sort-order
+   positions 1..<replaceable>n</>.  But members added later might be given
+   negative or fractional values of <structfield>enumsortorder</structfield>.
+   The only requirement on these values is that they be correctly
+   ordered and unique within each enum type.
+  </para>
  </sect1>
 
 
diff --git a/doc/src/sgml/ref/alter_type.sgml b/doc/src/sgml/ref/alter_type.sgml
index 315922ea836..90de2e81ef8 100644
--- a/doc/src/sgml/ref/alter_type.sgml
+++ b/doc/src/sgml/ref/alter_type.sgml
@@ -24,10 +24,11 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> <replaceable class="PARAMETER">action</replaceable> [, ... ]
-ALTER TYPE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable class="PARAMETER">new_owner</replaceable> 
+ALTER TYPE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> RENAME ATTRIBUTE <replaceable class="PARAMETER">attribute_name</replaceable> TO <replaceable class="PARAMETER">new_attribute_name</replaceable>
 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable class="PARAMETER">new_name</replaceable>
 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable>
+ALTER TYPE <replaceable class="PARAMETER">name</replaceable> ADD <replaceable class="PARAMETER">new_enum_value</replaceable> [ { BEFORE | AFTER } <replaceable class="PARAMETER">existing_enum_value</replaceable> ]
 
 <phrase>where <replaceable class="PARAMETER">action</replaceable> is one of:</phrase>
 
@@ -103,6 +104,18 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> SET SCHEMA <replace
      </para>
     </listitem>
    </varlistentry>
+
+   <varlistentry>
+    <term><literal>ADD [ BEFORE | AFTER ]</literal></term>
+    <listitem>
+     <para>
+      This form adds a new value to an enum type. If the new value's place in
+      the enum's ordering is not specified using <literal>BEFORE</literal> or
+      <literal>AFTER</literal>, then the new item is placed at the end of the
+      list of values.
+     </para>
+    </listitem>
+   </varlistentry>
   </variablelist>
   </para>
 
@@ -181,7 +194,7 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> SET SCHEMA <replace
       <term><replaceable class="PARAMETER">new_attribute_name</replaceable></term>
       <listitem>
        <para>
-        The new name of the attribute begin renamed.
+        The new name of the attribute to be renamed.
        </para>
       </listitem>
      </varlistentry>
@@ -196,11 +209,54 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> SET SCHEMA <replace
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><replaceable class="PARAMETER">new_enum_value</replaceable></term>
+      <listitem>
+       <para>
+        The new value to be added to an enum type's list of values.
+        Like all enum literals, it needs to be quoted.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="PARAMETER">existing_enum_value</replaceable></term>
+      <listitem>
+       <para>
+        The existing enum value that the new value should be added immediately
+        before or after in the enum type's sort ordering.
+        Like all enum literals, it needs to be quoted.
+       </para>
+      </listitem>
+     </varlistentry>
+
     </variablelist>
    </para>
   </refsect1>
 
  <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <command>ALTER TYPE ... ADD</> (the form that adds a new value to an
+   enum type) cannot be executed inside a transaction block.
+  </para>
+
+  <para>
+   Comparisons involving an added enum value will sometimes be slower than
+   comparisons involving only original members of the enum type.  This will
+   usually only occur if <literal>BEFORE</literal> or <literal>AFTER</literal>
+   is used to set the new value's sort position somewhere other than at the
+   end of the list.  However, sometimes it will happen even though the new
+   value is added at the end (this occurs if the OID counter <quote>wrapped
+   around</> since the original creation of the enum type).  The slowdown is
+   usually insignificant; but if it matters, optimal performance can be
+   regained by dropping and recreating the enum type, or by dumping and
+   reloading the database.
+  </para>
+ </refsect1>
+
+ <refsect1>
   <title>Examples</title>
 
   <para>
@@ -232,6 +288,13 @@ ALTER TYPE email SET SCHEMA customers;
 ALTER TYPE compfoo ADD ATTRIBUTE f3 int;
 </programlisting>
   </para>
+
+  <para>
+   To add a new value to an enum type in a particular sort position:
+<programlisting>
+ALTER TYPE colors ADD 'orange' AFTER 'red';
+</programlisting>
+  </para>
  </refsect1>
 
  <refsect1>