Allow ALTER TYPE to change some properties of a base type.

Specifically, this patch allows ALTER TYPE to:
* Change the default TOAST strategy for a toastable base type;
* Promote a non-toastable type to toastable;
* Add/remove binary I/O functions for a type;
* Add/remove typmod I/O functions for a type;
* Add/remove a custom ANALYZE statistics functions for a type.

The first of these can be done by the type's owner; all the others
require superuser privilege since misuse could cause problems.

The main motivation for this patch is to allow extensions to
upgrade the feature sets of their data types, so the set of
alterable properties is biased towards that use-case.  However
it's also true that changing some other properties would be
a lot harder, as they get baked into physical storage and/or
stored expressions that depend on the type.

Along the way, refactor GenerateTypeDependencies() to make it easier
to call, refactor DefineType's volatility checks so they can be shared
by AlterType, and teach typcache.c that it might have to reload data
from the type's pg_type row, a scenario it never handled before.
Also rearrange alter_type.sgml a bit for clarity (put the
composite-type operations together).

Tomas Vondra and Tom Lane

Discussion: https://postgr.es/m/20200228004440.b23ein4qvmxnlpht@development

2 files changed, 152 insertions, 31 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 34bc0d05266..c6f95fa6881 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -7828,28 +7828,38 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        types (those with <structfield>typlen</structfield> = -1) if
        the type is prepared for toasting and what the default strategy
        for attributes of this type should be.
-       Possible values are
+       Possible values are:
        <itemizedlist>
         <listitem>
-         <para><literal>p</literal>: Value must always be stored plain.</para>
+         <para>
+          <literal>p</literal> (plain): Values must always be stored plain
+          (non-varlena types always use this value).
+         </para>
         </listitem>
         <listitem>
          <para>
-          <literal>e</literal>: Value can be stored in a <quote>secondary</quote>
-          relation (if relation has one, see
+          <literal>e</literal> (external): Values can be stored in a
+          secondary <quote>TOAST</quote> relation (if relation has one, see
           <literal>pg_class.reltoastrelid</literal>).
          </para>
         </listitem>
         <listitem>
-         <para><literal>m</literal>: Value can be stored compressed inline.</para>
+         <para>
+          <literal>m</literal> (main): Values can be compressed and stored
+          inline.
+         </para>
         </listitem>
         <listitem>
-         <para><literal>x</literal>: Value can be stored compressed inline or stored in <quote>secondary</quote> storage.</para>
+         <para>
+          <literal>x</literal> (extended): Values can be compressed and/or
+          moved to a secondary relation.
+         </para>
         </listitem>
        </itemizedlist>
-       Note that <literal>m</literal> columns can also be moved out to secondary
-       storage, but only as a last resort (<literal>e</literal> and <literal>x</literal> columns are
-       moved first).
+       <literal>x</literal> is the usual choice for toast-able types.
+       Note that <literal>m</literal> values can also be moved out to
+       secondary storage, but only as a last resort (<literal>e</literal>
+       and <literal>x</literal> values are moved first).
       </para></entry>
      </row>
 
diff --git a/doc/src/sgml/ref/alter_type.sgml b/doc/src/sgml/ref/alter_type.sgml
index 67be1dd5683..e0afaf8d0b0 100644
--- a/doc/src/sgml/ref/alter_type.sgml
+++ b/doc/src/sgml/ref/alter_type.sgml
@@ -23,13 +23,14 @@ 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> | CURRENT_USER | SESSION_USER }
-ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME ATTRIBUTE <replaceable class="parameter">attribute_name</replaceable> TO <replaceable class="parameter">new_attribute_name</replaceable> [ CASCADE | RESTRICT ]
 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> RENAME ATTRIBUTE <replaceable class="parameter">attribute_name</replaceable> TO <replaceable class="parameter">new_attribute_name</replaceable> [ CASCADE | RESTRICT ]
+ALTER TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">action</replaceable> [, ... ]
 ALTER TYPE <replaceable class="parameter">name</replaceable> ADD VALUE [ IF NOT EXISTS ] <replaceable class="parameter">new_enum_value</replaceable> [ { BEFORE | AFTER } <replaceable class="parameter">neighbor_enum_value</replaceable> ]
 ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <replaceable class="parameter">existing_enum_value</replaceable> TO <replaceable class="parameter">new_enum_value</replaceable>
+ALTER TYPE <replaceable class="parameter">name</replaceable> SET ( <replaceable class="parameter">property</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )
 
 <phrase>where <replaceable class="parameter">action</replaceable> is one of:</phrase>
 
@@ -48,60 +49,69 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla
 
   <variablelist>
    <varlistentry>
-    <term><literal>ADD ATTRIBUTE</literal></term>
+    <term><literal>OWNER</literal></term>
     <listitem>
      <para>
-      This form adds a new attribute to a composite type, using the same syntax as
-      <xref linkend="sql-createtype"/>.
+      This form changes the owner of the type.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>DROP ATTRIBUTE [ IF EXISTS ]</literal></term>
+    <term><literal>RENAME</literal></term>
     <listitem>
      <para>
-      This form drops an attribute from a composite type.
-      If <literal>IF EXISTS</literal> is specified and the attribute
-      does not exist, no error is thrown. In this case a notice
-      is issued instead.
+      This form changes the name of the type.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>SET DATA TYPE</literal></term>
+    <term><literal>SET SCHEMA</literal></term>
     <listitem>
      <para>
-      This form changes the type of an attribute of a composite type.
+      This form moves the type into another schema.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>OWNER</literal></term>
+    <term><literal>RENAME ATTRIBUTE</literal></term>
     <listitem>
      <para>
-      This form changes the owner of the type.
+      This form is only usable with composite types.
+      It changes the name of an individual attribute of the type.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>RENAME</literal></term>
+    <term><literal>ADD ATTRIBUTE</literal></term>
     <listitem>
      <para>
-      This form changes the name of the type or the name of an
-      individual attribute of a composite type.
+      This form adds a new attribute to a composite type, using the same syntax as
+      <xref linkend="sql-createtype"/>.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>SET SCHEMA</literal></term>
+    <term><literal>DROP ATTRIBUTE [ IF EXISTS ]</literal></term>
     <listitem>
      <para>
-      This form moves the type into another schema.
+      This form drops an attribute from a composite type.
+      If <literal>IF EXISTS</literal> is specified and the attribute
+      does not exist, no error is thrown. In this case a notice
+      is issued instead.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><literal>ALTER ATTRIBUTE ... SET DATA TYPE</literal></term>
+    <listitem>
+     <para>
+      This form changes the type of an attribute of a composite type.
      </para>
     </listitem>
    </varlistentry>
@@ -135,6 +145,84 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla
      </para>
     </listitem>
    </varlistentry>
+
+   <varlistentry>
+    <term>
+     <literal>SET ( <replaceable class="parameter">property</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )</literal>
+    </term>
+    <listitem>
+     <para>
+      This form is only applicable to base types.  It allows adjustment of a
+      subset of the base-type properties that can be set in <command>CREATE
+      TYPE</command>.  Specifically, these properties can be changed:
+      <itemizedlist>
+       <listitem>
+        <para>
+         <literal>RECEIVE</literal> can be set to the name of a binary input
+         function, or <literal>NONE</literal> to remove the type's binary
+         input function.  Using this option requires superuser privilege.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         <literal>SEND</literal> can be set to the name of a binary output
+         function, or <literal>NONE</literal> to remove the type's binary
+         output function.  Using this option requires superuser privilege.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         <literal>TYPMOD_IN</literal> can be set to the name of a type
+         modifier input function, or <literal>NONE</literal> to remove the
+         type's type modifier input function.  Using this option requires
+         superuser privilege.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         <literal>TYPMOD_OUT</literal> can be set to the name of a type
+         modifier output function, or <literal>NONE</literal> to remove the
+         type's type modifier output function.  Using this option requires
+         superuser privilege.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         <literal>ANALYZE</literal> can be set to the name of a type-specific
+         statistics collection function, or <literal>NONE</literal> to remove
+         the type's statistics collection function.  Using this option
+         requires superuser privilege.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         <literal>STORAGE</literal><indexterm>
+          <primary>TOAST</primary>
+          <secondary>per-type storage settings</secondary>
+         </indexterm>
+         can be set to <literal>plain</literal>,
+         <literal>extended</literal>, <literal>external</literal>,
+         or <literal>main</literal> (see <xref linkend="storage-toast"/> for
+         more information about what these mean).  However, changing
+         from <literal>plain</literal> to another setting requires superuser
+         privilege (because it requires that the type's C functions all be
+         TOAST-ready), and changing to <literal>plain</literal> from another
+         setting is not allowed at all (since the type may already have
+         TOASTed values present in the database).  Note that changing this
+         option doesn't by itself change any stored data, it just sets the
+         default TOAST strategy to be used for table columns created in the
+         future.  See <xref linkend="sql-altertable"/> to change the TOAST
+         strategy for existing table columns.
+        </para>
+       </listitem>
+      </itemizedlist>
+      See <xref linkend="sql-createtype"/> for more details about these
+      type properties.  Note that where appropriate, a change in these
+      properties for a base type will be propagated automatically to domains
+      based on that type.
+     </para>
+    </listitem>
+   </varlistentry>
   </variablelist>
   </para>
 
@@ -156,7 +244,7 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla
    doesn't do anything you couldn't do by dropping and recreating the type.
    However, a superuser can alter ownership of any type anyway.)
    To add an attribute or alter an attribute type, you must also
-   have <literal>USAGE</literal> privilege on the data type.
+   have <literal>USAGE</literal> privilege on the attribute's data type.
   </para>
  </refsect1>
 
@@ -263,6 +351,16 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla
      </varlistentry>
 
      <varlistentry>
+      <term><replaceable class="parameter">property</replaceable></term>
+      <listitem>
+       <para>
+        The name of a base-type property to be modified; see above for
+        possible values.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><literal>CASCADE</literal></term>
       <listitem>
        <para>
@@ -336,7 +434,7 @@ ALTER TYPE email SET SCHEMA customers;
   </para>
 
   <para>
-   To add a new attribute to a type:
+   To add a new attribute to a composite type:
 <programlisting>
 ALTER TYPE compfoo ADD ATTRIBUTE f3 int;
 </programlisting>
@@ -353,7 +451,20 @@ ALTER TYPE colors ADD VALUE 'orange' AFTER 'red';
    To rename an enum value:
 <programlisting>
 ALTER TYPE colors RENAME VALUE 'purple' TO 'mauve';
-</programlisting></para>
+</programlisting>
+  </para>
+
+  <para>
+   To create binary I/O functions for an existing base type:
+<programlisting>
+CREATE FUNCTION mytypesend(mytype) RETURNS bytea ...;
+CREATE FUNCTION mytyperecv(internal, oid, integer) RETURNS mytype ...;
+ALTER TYPE mytype SET (
+    SEND = mytypesend,
+    RECEIVE = mytyperecv
+);
+</programlisting>
+  </para>
  </refsect1>
 
  <refsect1>