From 257836a75585934cc05ed7a80bccf8190d41e056 Mon Sep 17 00:00:00 2001 From: Thomas Munro Date: Mon, 2 Nov 2020 19:50:45 +1300 Subject: Track collation versions for indexes. Record the current version of dependent collations in pg_depend when creating or rebuilding an index. When accessing the index later, warn that the index may be corrupted if the current version doesn't match. Thanks to Douglas Doole, Peter Eisentraut, Christoph Berg, Laurenz Albe, Michael Paquier, Robert Haas, Tom Lane and others for very helpful discussion. Author: Thomas Munro Author: Julien Rouhaud Reviewed-by: Peter Eisentraut (earlier versions) Discussion: https://postgr.es/m/CAEepm%3D0uEQCpfq_%2BLYFBdArCe4Ot98t1aR4eYiYTe%3DyavQygiQ%40mail.gmail.com --- doc/src/sgml/catalogs.sgml | 3 ++- doc/src/sgml/charset.sgml | 38 ++++++++++++++++++++++++++++++++++++++ doc/src/sgml/func.sgml | 4 +++- doc/src/sgml/ref/alter_index.sgml | 15 +++++++++++++++ doc/src/sgml/ref/pgupgrade.sgml | 15 +++++++++++++++ doc/src/sgml/ref/reindex.sgml | 9 +++++++++ 6 files changed, 82 insertions(+), 2 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index c3f324f05eb..5fb9dca4258 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -3308,7 +3308,8 @@ SCRAM-SHA-256$<iteration count>:&l refobjversion text - An optional version for the referenced object. + An optional version for the referenced object. Currently used for + indexes' collations (see ). diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml index 2745b444176..832a701523d 100644 --- a/doc/src/sgml/charset.sgml +++ b/doc/src/sgml/charset.sgml @@ -948,6 +948,44 @@ CREATE COLLATION ignore_accents (provider = icu, locale = 'und-u-ks-level1-kc-tr + + + Collation Versions + + + The sort order defined by a collation is not necessarily fixed over time. + PostgreSQL relies on external libraries that + are subject to operating system upgrades, and can also differ between + servers involved in binary replication and file-system-level migration. + Persistent data structures such as B-trees that depend on sort order might + be corrupted by any resulting change. + PostgreSQL defends against this by recording the + current version of each referenced collation for any index that depends on + it in the + pg_depend + catalog, if the collation provider makes that information available. If the + provider later begins to report a different version, a warning will be + issued when the index is accessed, until either the + command or the + command is used to update the version. + + + Version information is available from the + icu provider on all operating systems. For the + libc provider, versions are currently only available + on systems using the GNU C library (most Linux systems) and Windows. + + + + + When using the GNU C library for collations, the C library's version + is used as a proxy for the collation version. Many Linux distributions + change collation definitions only when upgrading the C library, but this + approach is imperfect as maintainers are free to back-port newer + collation definitions to older C library releases. + + + diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0398b4909bf..bf6004f321f 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -25444,7 +25444,9 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Returns the actual version of the collation object as it is currently - installed in the operating system. + installed in the operating system. null is returned + on operating systems where PostgreSQL + doesn't have support for versions. diff --git a/doc/src/sgml/ref/alter_index.sgml b/doc/src/sgml/ref/alter_index.sgml index 793119d2fc1..214005a86c5 100644 --- a/doc/src/sgml/ref/alter_index.sgml +++ b/doc/src/sgml/ref/alter_index.sgml @@ -25,6 +25,7 @@ ALTER INDEX [ IF EXISTS ] name RENA ALTER INDEX [ IF EXISTS ] name SET TABLESPACE tablespace_name ALTER INDEX name ATTACH PARTITION index_name ALTER INDEX name DEPENDS ON EXTENSION extension_name +ALTER INDEX name ALTER COLLATION collation_name REFRESH VERSION ALTER INDEX [ IF EXISTS ] name SET ( storage_parameter [= value] [, ... ] ) ALTER INDEX [ IF EXISTS ] name RESET ( storage_parameter [, ... ] ) ALTER INDEX [ IF EXISTS ] name ALTER [ COLUMN ] column_number @@ -112,6 +113,20 @@ ALTER INDEX ALL IN TABLESPACE name + + ALTER COLLATION collation_name REFRESH VERSION + + + Silences warnings about mismatched collation versions, by declaring + that the index is compatible with the current collation definition. + Be aware that incorrect use of this command can hide index corruption. + If you don't know whether a collation's definition has changed + incompatibly, is a safe alternative. + See for more information. + + + + SET ( storage_parameter [= value] [, ... ] ) diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index b59c5697a36..92e1d09a55c 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -215,6 +215,21 @@ PostgreSQL documentation + + + + + When upgrading indexes from releases before 14 that didn't track + collation versions, pg_upgrade + assumes by default that the upgraded indexes are compatible with the + currently installed versions of relevant collations (see + ). Specify + to mark + them as needing to be rebuilt instead. + + + + diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index fa43e3a9720..f6d425a6910 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -38,6 +38,15 @@ REINDEX [ ( option [, ...] ) ] { IN several scenarios in which to use REINDEX: + + + The index depends on the sort order of a collation, and the definition + of the collation has changed. This can cause index scans to fail to + find keys that are present. See for + more information. + + + An index has become corrupted, and no longer contains valid -- cgit v1.2.3