aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/catalogs.sgml28
-rw-r--r--doc/src/sgml/ref/alter_type.sgml155
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>