diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 34 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_type.sgml | 67 |
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> |