aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/catalogs.sgml21
-rw-r--r--doc/src/sgml/charset.sgml11
-rw-r--r--doc/src/sgml/ref/allfiles.sgml3
-rw-r--r--doc/src/sgml/ref/alter_collation.sgml128
-rw-r--r--doc/src/sgml/ref/alter_extension.sgml1
-rw-r--r--doc/src/sgml/ref/comment.sgml2
-rw-r--r--doc/src/sgml/ref/create_collation.sgml175
-rw-r--r--doc/src/sgml/ref/drop_collation.sgml110
-rw-r--r--doc/src/sgml/ref/psql-ref.sgml19
-rw-r--r--doc/src/sgml/reference.sgml3
10 files changed, 467 insertions, 6 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index a373829d39d..e93347992f2 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -2115,10 +2115,29 @@
</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>
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 49e1bd25b43..046c3d14168 100644
--- a/doc/src/sgml/charset.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index ba85cae0837..ac6ac5b3d2a 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/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">
diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml
new file mode 100644
index 00000000000..3aef656a0e9
--- /dev/null
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_extension.sgml b/doc/src/sgml/ref/alter_extension.sgml
index a6c0062fe24..d12aee251b5 100644
--- a/doc/src/sgml/ref/alter_extension.sgml
+++ b/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> |
diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index e1fe0c16f9a..2610fd5b8d5 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/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';
diff --git a/doc/src/sgml/ref/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml
new file mode 100644
index 00000000000..9d03ca5a4eb
--- /dev/null
+++ b/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>
diff --git a/doc/src/sgml/ref/drop_collation.sgml b/doc/src/sgml/ref/drop_collation.sgml
new file mode 100644
index 00000000000..7be9317932c
--- /dev/null
+++ b/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>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index cdf1abfa956..ff60a72059e 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1265,6 +1265,7 @@ testdb=&gt;
</listitem>
</varlistentry>
+
<varlistentry>
<term><literal>\dn[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
@@ -1298,6 +1299,24 @@ testdb=&gt;
<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>
<para>
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index 47cd01f58e2..9ae80005cdf 100644
--- a/doc/src/sgml/reference.sgml
+++ b/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;
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-07 12:41:14 +0000