From 5e45211a64149b3c659b90ff2de6fa982a5a93ed Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 4 May 2024 14:17:33 +0200 Subject: Adding upstream version 15.5. Signed-off-by: Daniel Baumann --- doc/src/sgml/ref/create_collation.sgml | 263 +++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 doc/src/sgml/ref/create_collation.sgml (limited to 'doc/src/sgml/ref/create_collation.sgml') diff --git a/doc/src/sgml/ref/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml new file mode 100644 index 0000000..58f5f0c --- /dev/null +++ b/doc/src/sgml/ref/create_collation.sgml @@ -0,0 +1,263 @@ + + + + + CREATE COLLATION + + + + CREATE COLLATION + 7 + SQL - Language Statements + + + + CREATE COLLATION + define a new collation + + + + +CREATE COLLATION [ IF NOT EXISTS ] name ( + [ LOCALE = locale, ] + [ LC_COLLATE = lc_collate, ] + [ LC_CTYPE = lc_ctype, ] + [ PROVIDER = provider, ] + [ DETERMINISTIC = boolean, ] + [ VERSION = version ] +) +CREATE COLLATION [ IF NOT EXISTS ] name FROM existing_collation + + + + + Description + + + CREATE COLLATION defines a new collation using + the specified operating system locale settings, + or by copying an existing collation. + + + + To be able to create a collation, you must + have CREATE privilege on the destination schema. + + + + + + Parameters + + + + IF NOT EXISTS + + + Do not throw an error if a collation with the same name already exists. + A notice is issued in this case. Note that there is no guarantee that + the existing collation is anything like the one that would have been created. + + + + + + name + + + + 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 that + schema. (The system catalogs can contain collations with the + same name for other encodings, but these are ignored if the + database encoding does not match.) + + + + + + locale + + + + This is a shortcut for setting LC_COLLATE + and LC_CTYPE at once. If you specify this, + you cannot specify either of those parameters. + + + + + + lc_collate + + + + Use the specified operating system locale for + the LC_COLLATE locale category. + + + + + + lc_ctype + + + + Use the specified operating system locale for + the LC_CTYPE locale category. + + + + + + provider + + + + Specifies the provider to use for locale services associated with this + collation. Possible values + are: icu,ICU + libc. + libc is the default. + The available choices depend on the operating system and build options. + + + + + + DETERMINISTIC + + + + Specifies whether the collation should use deterministic comparisons. + The default is true. A deterministic comparison considers strings that + are not byte-wise equal to be unequal even if they are considered + logically equal by the comparison. PostgreSQL breaks ties using a + byte-wise comparison. Comparison that is not deterministic can make the + collation be, say, case- or accent-insensitive. For that, you need to + choose an appropriate LC_COLLATE setting + and set the collation to not deterministic here. + + + + Nondeterministic collations are only supported with the ICU provider. + + + + + + version + + + + Specifies the version string to store with the collation. Normally, + this should be omitted, which will cause the version to be computed + from the actual version of the collation as provided by the operating + system. This option is intended to be used + by pg_upgrade for copying the version from an + existing installation. + + + + See also for how to handle + collation version mismatches. + + + + + + existing_collation + + + + The name of an existing collation to copy. The new collation + will have the same properties as the existing one, but it + will be an independent object. + + + + + + + + + Notes + + + CREATE COLLATION takes a SHARE ROW + EXCLUSIVE lock, which is self-conflicting, on the + pg_collation system catalog, so only one + CREATE COLLATION command can run at a time. + + + + Use DROP COLLATION to remove user-defined collations. + + + + See for more information on how to create collations. + + + + When using the libc collation provider, the locale must + be applicable to the current database encoding. + See for the precise rules. + + + + + Examples + + + To create a collation from the operating system locale + fr_FR.utf8 + (assuming the current database encoding is UTF8): + +CREATE COLLATION french (locale = 'fr_FR.utf8'); + + + + + To create a collation using the ICU provider using German phone book sort order: + +CREATE COLLATION german_phonebook (provider = icu, locale = 'de-u-co-phonebk'); + + + + + To create a collation from an existing collation: + +CREATE COLLATION german FROM "de_DE"; + + This can be convenient to be able to use operating-system-independent + collation names in applications. + + + + + + Compatibility + + + There is a CREATE COLLATION statement in the SQL + standard, but it is limited to copying an existing collation. The + syntax to create a new collation is + a PostgreSQL extension. + + + + + + See Also + + + + + + + + -- cgit v1.2.3