diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml index 558bea0c60..892c466565 100644 --- a/doc/src/sgml/ref/alter_collation.sgml +++ b/doc/src/sgml/ref/alter_collation.sgml @@ -104,9 +104,9 @@ ALTER COLLATION name SET SCHEMA new_sche Notes - When using collations provided by the ICU library, the ICU-specific version - of the collator is recorded in the system catalog when the collation object - is created. When the collation is used, the current version is + When a collation object is created, the provider-specific version of the + collation is recorded in the system catalog. When the collation is used, + the current version is checked against the recorded version, and a warning is issued when there is a mismatch, for example: @@ -117,21 +117,24 @@ HINT: Rebuild all objects affected by this collation and run ALTER COLLATION pg A change in collation definitions can lead to corrupt indexes and other problems because the database system relies on stored objects having a certain sort order. Generally, this should be avoided, but it can happen - in legitimate circumstances, such as when + in legitimate circumstances, such as when upgrading the operating system + to a new major version or when using pg_upgrade to upgrade to server binaries linked with a newer version of ICU. When this happens, all objects depending on the collation should be rebuilt, for example, using REINDEX. When that is done, the collation version can be refreshed using the command ALTER COLLATION ... REFRESH VERSION. This will update the system catalog to record the - current collator version and will make the warning go away. Note that this + current collation version and will make the warning go away. Note that this does not actually check whether all affected objects have been rebuilt correctly. When using collations provided by libc, version information is recorded on systems using the GNU C library (most Linux - systems), FreeBSD and Windows. + systems), FreeBSD and Windows. When using collations provided by ICU, the + version information is provided by the ICU library and is available on all + platforms.