DDL support for collations

- collowner field
- CREATE COLLATION
- ALTER COLLATION
- DROP COLLATION
- COMMENT ON COLLATION
- integration with extensions
- pg_dump support for the above
- dependency management
- psql tab completion
- psql \dO command

doc/src/sgml/catalogs.sgml

@@ -2114,11 +2114,30 @@
       </entry>
      </row>
 
+     <row>
+      <entry><structfield>collowner</structfield></entry>
+      <entry><type>oid</type></entry>
+      <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry>
+      <entry>Owner of the collation</entry>
+     </row>
+
      <row>
       <entry><structfield>collencoding</structfield></entry>
       <entry><type>int4</type></entry>
       <entry></entry>
-      <entry>Encoding to which the collation is applicable</entry>
+      <entry>
+       Encoding to which the collation is applicable.  SQL-level
+       commands such as <command>ALTER COLLATION</command> only
+       operate on the collation belonging to the current database
+       encoding.  But this field is necessary because when this
+       catalog is initialized, the encoding of future databases is not
+       yet known.  For practical purposes, collations that do not
+       match the current database encoding should be considered
+       invalid or invisible.  It could be useful, however, to create
+       collations whose encoding does not match the database encoding
+       in template databases.  This would currently have to be done
+       manually.
+      </entry>
      </row>
 
      <row>

doc/src/sgml/charset.sgml

@@ -459,11 +459,12 @@ SELECT a || ('foo' COLLATE "y") FROM test1;
 
    <para>
     In case a collation is needed that has different values for
-    <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol>, or a
-    different name is needed for a collation (for example, for
-    compatibility with existing applications), a new collation may be
-    created.  But there is currently no SQL-level support for creating
-    or changing collations.
+    <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol>, a new
+    collation may be created using
+    the <xref linkend="sql-createcollation"> command.  That command
+    can also be used to create a new collation from an existing
+    collation, which can be useful to be able to use operating-system
+    independent collation names in applications.
    </para>
   </sect2>
  </sect1>

doc/src/sgml/ref/allfiles.sgml

@@ -7,6 +7,7 @@ Complete list of usable sgml source files in this directory.
 <!-- SQL commands -->
 <!entity abort              system "abort.sgml">
 <!entity alterAggregate     system "alter_aggregate.sgml">
+<!entity alterCollation     system "alter_collation.sgml">
 <!entity alterConversion    system "alter_conversion.sgml">
 <!entity alterDatabase      system "alter_database.sgml">
 <!entity alterDefaultPrivileges system "alter_default_privileges.sgml">
@@ -48,6 +49,7 @@ Complete list of usable sgml source files in this directory.
 <!entity copyTable          system "copy.sgml">
 <!entity createAggregate    system "create_aggregate.sgml">
 <!entity createCast         system "create_cast.sgml">
+<!entity createCollation    system "create_collation.sgml">
 <!entity createConversion   system "create_conversion.sgml">
 <!entity createDatabase     system "create_database.sgml">
 <!entity createDomain       system "create_domain.sgml">
@@ -85,6 +87,7 @@ Complete list of usable sgml source files in this directory.
 <!entity do                 system "do.sgml">
 <!entity dropAggregate      system "drop_aggregate.sgml">
 <!entity dropCast           system "drop_cast.sgml">
+<!entity dropCollation      system "drop_collation.sgml">
 <!entity dropConversion     system "drop_conversion.sgml">
 <!entity dropDatabase       system "drop_database.sgml">
 <!entity dropDomain         system "drop_domain.sgml">

doc/src/sgml/ref/alter_collation.sgml

@@ -0,0 +1,128 @@
+<!--
+doc/src/sgml/ref/alter_collation.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="SQL-ALTERCOLLATION">
+ <refmeta>
+  <refentrytitle>ALTER COLLATION</refentrytitle>
+  <manvolnum>7</manvolnum>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>ALTER COLLATION</refname>
+  <refpurpose>change the definition of a collation</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-altercollation">
+  <primary>ALTER COLLATION</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+ALTER COLLATION <replaceable>name</replaceable> RENAME TO <replaceable>new_name</replaceable>
+ALTER COLLATION <replaceable>name</replaceable> OWNER TO <replaceable>new_owner</replaceable>
+ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_schema</replaceable>
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <command>ALTER COLLATION</command> changes the definition of a
+   collation.
+  </para>
+
+  <para>
+   You must own the collation to use <command>ALTER COLLATION</>.
+   To alter the owner, you must also be a direct or indirect member of the new
+   owning role, and that role must have <literal>CREATE</literal> privilege on
+   the collation's schema.  (These restrictions enforce that altering the
+   owner doesn't do anything you couldn't do by dropping and recreating the
+   collation. However, a superuser can alter ownership of any collation
+   anyway.)
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><replaceable class="parameter">name</replaceable></term>
+    <listitem>
+     <para>
+      The name (optionally schema-qualified) of an existing collation.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">new_name</replaceable></term>
+    <listitem>
+     <para>
+      The new name of the collation.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">new_owner</replaceable></term>
+    <listitem>
+     <para>
+      The new owner of the collation.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">new_schema</replaceable></term>
+    <listitem>
+     <para>
+      The new schema for the collation.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+  <para>
+   To rename the collation <literal>de_DE</literal> to
+   <literal>german</literal>:
+<programlisting>
+ALTER COLLATION "de_DE" RENAME TO german;
+</programlisting>
+  </para>
+
+  <para>
+   To change the owner of the collation <literal>en_US</literal> to
+   <literal>joe</literal>:
+<programlisting>
+ALTER COLLATION "en_US" OWNER TO joe;
+</programlisting>
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
+
+  <para>
+   There is no <command>ALTER COLLATION</command> statement in the SQL
+   standard.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-createcollation"></member>
+   <member><xref linkend="sql-dropcollation"></member>
+  </simplelist>
+ </refsect1>
+</refentry>

doc/src/sgml/ref/alter_extension.sgml

@@ -32,6 +32,7 @@ ALTER EXTENSION <replaceable class="PARAMETER">extension_name</replaceable> DROP
 
   AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable> [, ...] ) |
   CAST (<replaceable>source_type</replaceable> AS <replaceable>target_type</replaceable>) |
+  COLLATION <replaceable class="PARAMETER">object_name</replaceable> |
   CONVERSION <replaceable class="PARAMETER">object_name</replaceable> |
   DOMAIN <replaceable class="PARAMETER">object_name</replaceable> |
   FOREIGN DATA WRAPPER <replaceable class="PARAMETER">object_name</replaceable> |

doc/src/sgml/ref/comment.sgml

@@ -27,6 +27,7 @@ COMMENT ON
   COLUMN <replaceable class="PARAMETER">table_name</replaceable>.<replaceable class="PARAMETER">column_name</replaceable> |
   AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable> [, ...] ) |
   CAST (<replaceable>source_type</replaceable> AS <replaceable>target_type</replaceable>) |
+  COLLATION <replaceable class="PARAMETER">object_name</replaceable> |
   CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
   CONVERSION <replaceable class="PARAMETER">object_name</replaceable> |
   DATABASE <replaceable class="PARAMETER">object_name</replaceable> |
@@ -245,6 +246,7 @@ COMMENT ON TABLE mytable IS NULL;
 <programlisting>
 COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
 COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
+COMMENT ON COLLATION "fr_CA" IS 'Canadian French';
 COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
 COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
 COMMENT ON DATABASE my_database IS 'Development Database';

doc/src/sgml/ref/create_collation.sgml

@@ -0,0 +1,175 @@
+<!-- doc/src/sgml/ref/create_collation.sgml -->
+
+<refentry id="SQL-CREATECOLLATION">
+ <refmeta>
+  <refentrytitle>CREATE COLLATION</refentrytitle>
+  <manvolnum>7</manvolnum>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>CREATE COLLATION</refname>
+  <refpurpose>define a new collation</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-createcollation">
+  <primary>CREATE COLLATION</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+CREATE COLLATION <replaceable>name</replaceable> (
+    [ LOCALE = <replaceable>locale</replaceable>, ]
+    [ LC_COLLATE = <replaceable>lc_collate</replaceable>, ]
+    [ LC_CTYPE = <replaceable>lc_ctype</replaceable>, ]
+)
+CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_collation</replaceable>
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="sql-createcollation-description">
+  <title>Description</title>
+
+  <para>
+   <command>CREATE COLLATION</command> defines a new collation using
+   the specified operating system locales or from an existing collation.
+ </para>
+
+  <para>
+   To be able to create a collation, you must
+   have <literal>CREATE</literal> privilege on the destination schema.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Parameters</title>
+
+   <variablelist>
+    <varlistentry>
+     <term><replaceable>name</replaceable></term>
+
+     <listitem>
+      <para>
+       The name of the collation. The collation name can be
+       schema-qualified. If it is not, the collation is defined in the
+       current schema. The collation name must be unique within a
+       schema.  (The system catalogs can contain collations with the
+       same name for other encodings, but these are not usable if the
+       database encoding does not match.)
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>existing_collation</replaceable></term>
+
+     <listitem>
+      <para>
+       The name of an existing collation to copy.  The new collation
+       will have the same properties as the existing one, but they
+       will become independent objects.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>locale</replaceable></term>
+
+     <listitem>
+      <para>
+       This is a shortcut for setting <symbol>LC_COLLATE</symbol>
+       and <symbol>LC_CTYPE</symbol> at once.  If you specify this,
+       you cannot specify either of the other parameters.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>lc_collate</replaceable></term>
+
+     <listitem>
+      <para>
+       Use the specified operating system locale for
+       the <symbol>LC_COLLATE</symbol> locale category.  The locale
+       must be applicable to the current database encoding.
+       (See <xref linkend="sql-createdatabase"> for the precise
+       rules.)
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>lc_ctype</replaceable></term>
+
+     <listitem>
+      <para>
+       Use the specified operating system locale for
+       the <symbol>LC_CTYPE</symbol> locale category.  The locale
+       must be applicable to the current database encoding.
+       (See <xref linkend="sql-createdatabase"> for the precise
+       rules.)
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+ </refsect1>
+
+
+ <refsect1 id="sql-createcollation-notes">
+  <title>Notes</title>
+
+  <para>
+   Use <command>DROP COLLATION</command> to remove user-defined collations.
+  </para>
+
+  <para>
+   See <xref linkend="collation"> for more information about collation
+   support in PostgreSQL.
+  </para>
+ </refsect1>
+
+ <refsect1 id="sql-createcollation-examples">
+  <title>Examples</title>
+
+  <para>
+   To create a collation from the locale <literal>fr_FR.utf8</literal>
+   (assuming the current database encoding is <literal>UTF8</literal>):
+<programlisting>
+CREATE COLLATION french (LOCALE = 'fr_FR.utf8');
+</programlisting>
+  </para>
+
+  <para>
+   To create a collation from an existing collation:
+<programlisting>
+CREATE COLLATION german FROM "de_DE";
+</programlisting>
+   This can be convenient to be able to use operating-system
+   independent collation names in applications.
+  </para>
+ </refsect1>
+
+
+ <refsect1 id="sql-createcollation-compat">
+  <title>Compatibility</title>
+
+  <para>
+   There is a <command>CREATE COLLATION</command> statement in the SQL
+   standard, but it is limited to copying an existing collation.  The
+   syntax to create a new collation is
+   a <productname>PostgreSQL</productname> extension.
+  </para>
+ </refsect1>
+
+
+ <refsect1 id="sql-createcollation-seealso">
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-altercollation"></member>
+   <member><xref linkend="sql-dropcollation"></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>

doc/src/sgml/ref/drop_collation.sgml

@@ -0,0 +1,110 @@
+<!-- doc/src/sgml/ref/drop_collation.sgml -->
+
+<refentry id="SQL-DROPCOLLATION">
+ <refmeta>
+  <refentrytitle>DROP COLLATION</refentrytitle>
+  <manvolnum>7</manvolnum>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>DROP COLLATION</refname>
+  <refpurpose>remove a collation</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-dropcollation">
+  <primary>DROP COLLATION</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+DROP COLLATION [ IF EXISTS ] <replaceable>name</replaceable> [ CASCADE | RESTRICT ]
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="sql-dropcollation-description">
+  <title>Description</title>
+
+  <para>
+   <command>DROP COLLATION</command> removes a previously defined collation.
+   To be able to drop a collation, you must own the collation.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Parameters</title>
+
+   <variablelist>
+    <varlistentry>
+     <term><literal>IF EXISTS</literal></term>
+     <listitem>
+      <para>
+       Do not throw an error if the collation does not exist.
+       A notice is issued in this case.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>name</replaceable></term>
+
+     <listitem>
+      <para>
+       The name of the collation. The collation name can be
+       schema-qualified.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><literal>CASCADE</literal></term>
+     <listitem>
+      <para>
+       Automatically drop objects that depend on the collation.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><literal>RESTRICT</literal></term>
+     <listitem>
+      <para>
+       Refuse to drop the collation if any objects depend on it.  This
+       is the default.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+ </refsect1>
+
+ <refsect1 id="sql-dropcollation-examples">
+  <title>Examples</title>
+
+  <para>
+   To drop the collation named <literal>german</>:
+<programlisting>
+DROP COLLATION german;
+</programlisting>
+  </para>
+ </refsect1>
+
+ <refsect1 id="sql-dropcollation-compat">
+  <title>Compatibility</title>
+
+  <para>
+   The <command>DROP COLLATION</command> command conforms to the
+   <acronym>SQL</acronym> standard, apart from the <literal>IF
+   EXISTS</> option, which is a <productname>PostgreSQL</> extension..
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-altercollation"></member>
+   <member><xref linkend="sql-createcollation"></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>

doc/src/sgml/ref/psql-ref.sgml

@@ -1265,6 +1265,7 @@ testdb=>
         </listitem>
       </varlistentry>
 
+
       <varlistentry>
         <term><literal>\dn[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
 
@@ -1297,6 +1298,24 @@ testdb=&gt;
       </varlistentry>
 
 
+      <varlistentry>
+        <term><literal>\dO[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
+
+        <listitem>
+        <para>
+        Lists collations.
+        If <replaceable class="parameter">pattern</replaceable> is
+        specified, only collations whose names match the pattern are
+        listed.  By default, only user-created objects are shown;
+        supply a pattern or the <literal>S</literal> modifier to
+        include system objects.  If <literal>+</literal> is appended
+        to the command name, each object is listed with its associated
+        description, if any.
+        </para>
+        </listitem>
+      </varlistentry>
+
+
       <varlistentry>
         <term><literal>\dp [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>

doc/src/sgml/reference.sgml

@@ -35,6 +35,7 @@
 
    &abort;
    &alterAggregate;
+   &alterCollation;
    &alterConversion;
    &alterDatabase;
    &alterDefaultPrivileges;
@@ -76,6 +77,7 @@
    &copyTable;
    &createAggregate;
    &createCast;
+   &createCollation;
    &createConversion;
    &createDatabase;
    &createDomain;
@@ -113,6 +115,7 @@
    &do;
    &dropAggregate;
    &dropCast;
+   &dropCollation;
    &dropConversion;
    &dropDatabase;
    &dropDomain;