public inbox for [email protected]help / color / mirror / Atom feed
[PATCH v24 3/5] Track collation versions for indexes. 4+ messages / 3 participants [nested] [flat]
* [PATCH v24 3/5] Track collation versions for indexes. @ 2019-05-28 18:16 Thomas Munro <[email protected]> 0 siblings, 0 replies; 4+ messages in thread From: Thomas Munro @ 2019-05-28 18:16 UTC (permalink / raw) Record the current version of dependent collations in pg_depend when creating or rebuilding an index. The version is checked against the current version whenever we call get_relation_info for an index or open the parent table during non-full VACUUM or ANALYZE. Warn that the index may be corrupted if the versions don't match. A new flag is added in RelationData to specify that the check has already been done to avoid repetition. Thanks to Doug Doole, Peter Eisentraut, Christoph Berg, Laurenz Albe, Michael Paquier, Robert Haas, Tom Lane and others for design discussion. Author: Thomas Munro and Julien Rouhaud Reviewed-by: Peter Eisentraut, Laurenz Albe Discussion: https://postgr.es/m/CAEepm%3D0uEQCpfq_%2BLYFBdArCe4Ot98t1aR4eYiYTe%3DyavQygiQ%40mail.gmail.com --- doc/src/sgml/func.sgml | 3 +- doc/src/sgml/ref/pgupgrade.sgml | 18 ++ doc/src/sgml/ref/reindex.sgml | 6 + src/backend/catalog/dependency.c | 188 +++++++++++-- src/backend/catalog/heap.c | 7 +- src/backend/catalog/index.c | 265 ++++++++++++++++-- src/backend/catalog/pg_constraint.c | 2 +- src/backend/catalog/pg_depend.c | 256 ++++++++++++++++- src/backend/catalog/pg_type.c | 69 +++++ src/backend/commands/collationcmds.c | 22 +- src/backend/commands/vacuum.c | 32 +++ src/backend/optimizer/util/plancat.c | 9 + src/backend/utils/adt/pg_locale.c | 52 +++- src/backend/utils/adt/pg_upgrade_support.c | 25 ++ src/backend/utils/cache/relcache.c | 2 + src/bin/pg_dump/Makefile | 2 + src/bin/pg_dump/pg_backup.h | 1 + src/bin/pg_dump/pg_dump.c | 186 +++++++++++- src/bin/pg_dump/pg_dump.h | 3 + src/bin/pg_dump/t/002_pg_dump.pl | 248 ++++++++++++---- src/bin/pg_upgrade/dump.c | 4 +- src/bin/pg_upgrade/option.c | 7 + src/bin/pg_upgrade/pg_upgrade.h | 2 + src/include/catalog/dependency.h | 32 ++- src/include/catalog/index.h | 7 + src/include/catalog/pg_proc.dat | 4 + src/include/catalog/pg_type.h | 2 + src/include/utils/pg_locale.h | 2 +- src/include/utils/rel.h | 1 + src/test/Makefile | 5 +- src/test/locale/.gitignore | 1 + src/test/locale/Makefile | 7 + src/test/locale/t/001_index.pl | 76 +++++ src/test/perl/PostgresNode.pm | 6 +- .../regress/expected/collate.icu.utf8.out | 157 +++++++++++ src/test/regress/expected/create_index.out | 8 +- src/test/regress/sql/collate.icu.utf8.sql | 106 +++++++ 37 files changed, 1666 insertions(+), 157 deletions(-) create mode 100644 src/test/locale/t/001_index.pl diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 69fe242761..0bb1d6c15f 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -25419,7 +25419,8 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); </para> <para> Returns the actual version of the collation object as it is currently - installed in the operating system. + installed in the operating system. An empty string is returned if the + version is unknown. </para></entry> </row> diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 6779a5bddc..9be2547d16 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -215,6 +215,24 @@ PostgreSQL documentation </listitem> </varlistentry> + <varlistentry> + <term><option>--collation-binary-compatible</option></term> + <listitem> + <para> + After upgrading from a release of <productname>PostgreSQL</productname> + older than 13, warnings may be reported when collation-dependent + indexes are first accessed. This is because + <application>pg_upgrade</application> records the collation versions + as unknown, so <productname>PostgreSQL</productname> considers the + indexes to be potentially corrupted. If you're certain that the + collation definitions used by your operating system or ICU haven't + changed since all indexes were created, you can use this flag + to mark all indexes as using the currently installed version. + Otherwise, see <xref linkend="sql-reindex"/>. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><option>-?</option></term> <term><option>--help</option></term> diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index aac5d5be23..48726d261d 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -39,6 +39,12 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { IN <itemizedlist> <listitem> + <para> + The index depends on the sort order of a collation, and the definition + of the collation has changed. This can cause an index to fail to + find a key that is present in the index. On some systems, collation + versions are tracked in order to generate warnings when this happens. + </para> <para> An index has become corrupted, and no longer contains valid data. Although in theory this should never happen, in diff --git a/src/backend/catalog/dependency.c b/src/backend/catalog/dependency.c index 070b27c692..19d6255ca7 100644 --- a/src/backend/catalog/dependency.c +++ b/src/backend/catalog/dependency.c @@ -76,6 +76,7 @@ #include "rewrite/rewriteRemove.h" #include "storage/lmgr.h" #include "utils/acl.h" +#include "utils/builtins.h" #include "utils/fmgroids.h" #include "utils/guc.h" #include "utils/lsyscache.h" @@ -136,6 +137,9 @@ typedef struct { ObjectAddresses *addrs; /* addresses being accumulated */ List *rtables; /* list of rangetables to resolve Vars */ + bool track_version; /* whether caller asked to track dependency + * versions */ + NodeTag type; /* nodetag of the current node */ } find_expr_references_context; /* @@ -434,6 +438,81 @@ performMultipleDeletions(const ObjectAddresses *objects, table_close(depRel, RowExclusiveLock); } +/* + * Call a function for all objects that depend on 'object'. If the function + * returns a non-NULL pointer to a new version string, update the version. + */ +void +visitDependentObjects(const ObjectAddress *object, + VisitDependentObjectsFun callback, + void *userdata) +{ + Relation depRel; + ScanKeyData key[3]; + SysScanDesc scan; + HeapTuple tup; + ObjectAddress otherObject; + + ScanKeyInit(&key[0], + Anum_pg_depend_classid, + BTEqualStrategyNumber, F_OIDEQ, + ObjectIdGetDatum(object->classId)); + ScanKeyInit(&key[1], + Anum_pg_depend_objid, + BTEqualStrategyNumber, F_OIDEQ, + ObjectIdGetDatum(object->objectId)); + ScanKeyInit(&key[2], + Anum_pg_depend_objsubid, + BTEqualStrategyNumber, F_INT4EQ, + Int32GetDatum(object->objectSubId)); + + depRel = table_open(DependRelationId, RowExclusiveLock); + scan = systable_beginscan(depRel, DependDependerIndexId, true, + NULL, 3, key); + + while (HeapTupleIsValid(tup = systable_getnext(scan))) + { + Form_pg_depend foundDep = (Form_pg_depend) GETSTRUCT(tup); + char *cur_version, + *new_version; + Datum depversion; + bool isnull; + + otherObject.classId = foundDep->refclassid; + otherObject.objectId = foundDep->refobjid; + otherObject.objectSubId = foundDep->refobjsubid; + + depversion = heap_getattr(tup, Anum_pg_depend_refobjversion, + RelationGetDescr(depRel), &isnull); + + cur_version = isnull ? NULL : TextDatumGetCString(depversion); + + new_version = callback(&otherObject, cur_version, userdata); + if (new_version) + { + Datum values[Natts_pg_depend]; + bool nulls[Natts_pg_depend]; + bool replaces[Natts_pg_depend]; + + memset(values, 0, sizeof(values)); + memset(nulls, false, sizeof(nulls)); + memset(replaces, false, sizeof(replaces)); + + values[Anum_pg_depend_refobjversion - 1] = + CStringGetTextDatum(new_version); + replaces[Anum_pg_depend_refobjversion - 1] = true; + + tup = heap_modify_tuple(tup, RelationGetDescr(depRel), values, + nulls, replaces); + CatalogTupleUpdate(depRel, &tup->t_self, tup); + + heap_freetuple(tup); + } + } + systable_endscan(scan); + table_close(depRel, RowExclusiveLock); +} + /* * findDependentObjects - find all objects that depend on 'object' * @@ -1586,6 +1665,10 @@ recordDependencyOnExpr(const ObjectAddress *depender, find_expr_references_context context; context.addrs = new_object_addresses(); + if (expr) + context.type = expr->type; + else + context.type = T_Invalid; /* Set up interpretation for Vars at varlevelsup = 0 */ context.rtables = list_make1(rtable); @@ -1600,8 +1683,8 @@ recordDependencyOnExpr(const ObjectAddress *depender, recordMultipleDependencies(depender, context.addrs->refs, context.addrs->numrefs, - NULL, - behavior); + behavior, + false); free_object_addresses(context.addrs); } @@ -1628,12 +1711,18 @@ recordDependencyOnSingleRelExpr(const ObjectAddress *depender, Node *expr, Oid relId, DependencyType behavior, DependencyType self_behavior, - bool reverse_self) + bool reverse_self, + bool track_version) { find_expr_references_context context; RangeTblEntry rte; context.addrs = new_object_addresses(); + context.track_version = track_version; + if (expr) + context.type = expr->type; + else + context.type = T_Invalid; /* We gin up a rather bogus rangetable list to handle Vars */ MemSet(&rte, 0, sizeof(rte)); @@ -1689,8 +1778,8 @@ recordDependencyOnSingleRelExpr(const ObjectAddress *depender, recordMultipleDependencies(depender, self_addrs->refs, self_addrs->numrefs, - NULL, - self_behavior); + self_behavior, + track_version); else { /* Can't use recordMultipleDependencies, so do it the hard way */ @@ -1711,8 +1800,8 @@ recordDependencyOnSingleRelExpr(const ObjectAddress *depender, recordMultipleDependencies(depender, context.addrs->refs, context.addrs->numrefs, - NULL, - behavior); + behavior, + track_version); free_object_addresses(context.addrs); } @@ -1734,8 +1823,13 @@ static bool find_expr_references_walker(Node *node, find_expr_references_context *context) { + NodeTag parent_type = context->type; + if (node == NULL) return false; + + context->type = node->type; + if (IsA(node, Var)) { Var *var = (Var *) node; @@ -1768,6 +1862,49 @@ find_expr_references_walker(Node *node, /* If it's a plain relation, reference this column */ add_object_address(OCLASS_CLASS, rte->relid, var->varattno, context->addrs); + + /* + * Record collations from the type itself, or underlying in case + * of complex type. Note that if the direct parent is a + * CollateExpr node, there's no need to record the type underlying + * collation if any. A dependency already exists for the owning + * relation, and a change in the collation sort order wouldn't + * cause any harm as the collation isn't used at all in such case. + */ + if (parent_type != T_CollateExpr) + { + /* type's collation if valid */ + if (OidIsValid(var->varcollid)) + { + add_object_address(OCLASS_COLLATION, var->varcollid, 0, + context->addrs); + } + + /* + * otherwise, it may be a composite type having underlying + * collations + */ + else if (var->vartype >= FirstNormalObjectId) + { + List *collations = NIL; + ListCell *lc; + + collations = GetTypeCollations(var->vartype, false); + + foreach(lc, collations) + { + Oid coll = lfirst_oid(lc); + + if (OidIsValid(coll) && + (coll != DEFAULT_COLLATION_OID || + context->track_version) + ) + add_object_address(OCLASS_COLLATION, + lfirst_oid(lc), 0, + context->addrs); + } + } + } } /* @@ -1793,10 +1930,12 @@ find_expr_references_walker(Node *node, * We must also depend on the constant's collation: it could be * different from the datatype's, if a CollateExpr was const-folded to * a simple constant. However we can save work in the most common - * case where the collation is "default", since we know that's pinned. + * case where the collation is "default", since we know that's pinned, + * if the caller didn't ask to track dependency versions. */ if (OidIsValid(con->constcollid) && - con->constcollid != DEFAULT_COLLATION_OID) + (con->constcollid != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, con->constcollid, 0, context->addrs); @@ -1886,7 +2025,8 @@ find_expr_references_walker(Node *node, context->addrs); /* and its collation, just as for Consts */ if (OidIsValid(param->paramcollid) && - param->paramcollid != DEFAULT_COLLATION_OID) + (param->paramcollid != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, param->paramcollid, 0, context->addrs); } @@ -1974,7 +2114,8 @@ find_expr_references_walker(Node *node, context->addrs); /* the collation might not be referenced anywhere else, either */ if (OidIsValid(fselect->resultcollid) && - fselect->resultcollid != DEFAULT_COLLATION_OID) + (fselect->resultcollid != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, fselect->resultcollid, 0, context->addrs); } @@ -2005,7 +2146,8 @@ find_expr_references_walker(Node *node, context->addrs); /* the collation might not be referenced anywhere else, either */ if (OidIsValid(relab->resultcollid) && - relab->resultcollid != DEFAULT_COLLATION_OID) + (relab->resultcollid != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, relab->resultcollid, 0, context->addrs); } @@ -2018,7 +2160,8 @@ find_expr_references_walker(Node *node, context->addrs); /* the collation might not be referenced anywhere else, either */ if (OidIsValid(iocoerce->resultcollid) && - iocoerce->resultcollid != DEFAULT_COLLATION_OID) + (iocoerce->resultcollid != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, iocoerce->resultcollid, 0, context->addrs); } @@ -2031,7 +2174,8 @@ find_expr_references_walker(Node *node, context->addrs); /* the collation might not be referenced anywhere else, either */ if (OidIsValid(acoerce->resultcollid) && - acoerce->resultcollid != DEFAULT_COLLATION_OID) + (acoerce->resultcollid != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, acoerce->resultcollid, 0, context->addrs); /* fall through to examine arguments */ @@ -2120,7 +2264,8 @@ find_expr_references_walker(Node *node, add_object_address(OCLASS_PROC, wc->endInRangeFunc, 0, context->addrs); if (OidIsValid(wc->inRangeColl) && - wc->inRangeColl != DEFAULT_COLLATION_OID) + (wc->inRangeColl != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, wc->inRangeColl, 0, context->addrs); /* fall through to examine substructure */ @@ -2265,7 +2410,9 @@ find_expr_references_walker(Node *node, { Oid collid = lfirst_oid(ct); - if (OidIsValid(collid) && collid != DEFAULT_COLLATION_OID) + if (OidIsValid(collid) && + (collid != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, collid, 0, context->addrs); } @@ -2287,7 +2434,9 @@ find_expr_references_walker(Node *node, { Oid collid = lfirst_oid(ct); - if (OidIsValid(collid) && collid != DEFAULT_COLLATION_OID) + if (OidIsValid(collid) && + (collid != DEFAULT_COLLATION_OID || + context->track_version)) add_object_address(OCLASS_COLLATION, collid, 0, context->addrs); } @@ -2683,8 +2832,9 @@ record_object_address_dependencies(const ObjectAddress *depender, { eliminate_duplicate_dependencies(referenced); recordMultipleDependencies(depender, - referenced->refs, referenced->numrefs, NULL, - behavior); + referenced->refs, referenced->numrefs, + behavior, + false); } /* diff --git a/src/backend/catalog/heap.c b/src/backend/catalog/heap.c index 3c83fe6bab..d28512a638 100644 --- a/src/backend/catalog/heap.c +++ b/src/backend/catalog/heap.c @@ -2301,7 +2301,7 @@ StoreAttrDefault(Relation rel, AttrNumber attnum, */ recordDependencyOnSingleRelExpr(&colobject, expr, RelationGetRelid(rel), DEPENDENCY_AUTO, - DEPENDENCY_AUTO, false); + DEPENDENCY_AUTO, false, false); } else { @@ -2311,7 +2311,7 @@ StoreAttrDefault(Relation rel, AttrNumber attnum, */ recordDependencyOnSingleRelExpr(&defobject, expr, RelationGetRelid(rel), DEPENDENCY_NORMAL, - DEPENDENCY_NORMAL, false); + DEPENDENCY_NORMAL, false, false); } /* @@ -3635,7 +3635,8 @@ StorePartitionKey(Relation rel, RelationGetRelid(rel), DEPENDENCY_NORMAL, DEPENDENCY_INTERNAL, - true /* reverse the self-deps */ ); + true /* reverse the self-deps */ , + false /* don't track versions */ ); /* * We must invalidate the relcache so that the next diff --git a/src/backend/catalog/index.c b/src/backend/catalog/index.c index cdc01c49c9..210b25d147 100644 --- a/src/backend/catalog/index.c +++ b/src/backend/catalog/index.c @@ -53,6 +53,7 @@ #include "catalog/pg_trigger.h" #include "catalog/pg_type.h" #include "catalog/storage.h" +#include "commands/defrem.h" #include "commands/event_trigger.h" #include "commands/progress.h" #include "commands/tablecmds.h" @@ -75,6 +76,7 @@ #include "utils/guc.h" #include "utils/inval.h" #include "utils/lsyscache.h" +#include "utils/pg_locale.h" #include "utils/memutils.h" #include "utils/pg_rusage.h" #include "utils/snapmgr.h" @@ -119,6 +121,7 @@ static void UpdateIndexRelation(Oid indexoid, Oid heapoid, bool immediate, bool isvalid, bool isready); +static bool index_depends_stable_coll_order(Oid amoid); static void index_update_stats(Relation rel, bool hasindex, double reltuples); @@ -1029,6 +1032,10 @@ index_create(Relation heapRelation, { ObjectAddress myself, referenced; + ListCell *lc; + List *colls = NIL, + *determ_colls = NIL, + *nondeterm_colls = NIL; myself.classId = RelationRelationId; myself.objectId = indexRelationId; @@ -1119,21 +1126,77 @@ index_create(Relation heapRelation, recordDependencyOn(&myself, &referenced, DEPENDENCY_PARTITION_SEC); } - /* Store dependency on collations */ - /* The default collation is pinned, so don't bother recording it */ + /* First, get all dependencies on collations for all index keys. */ for (i = 0; i < indexInfo->ii_NumIndexKeyAttrs; i++) { - if (OidIsValid(collationObjectId[i]) && - collationObjectId[i] != DEFAULT_COLLATION_OID) + Oid colloid = collationObjectId[i]; + + if (OidIsValid(colloid)) + colls = lappend_oid(colls, colloid); + else { - referenced.classId = CollationRelationId; - referenced.objectId = collationObjectId[i]; - referenced.objectSubId = 0; + Form_pg_attribute att = TupleDescAttr(indexTupDesc, i); - recordDependencyOn(&myself, &referenced, DEPENDENCY_NORMAL); + Assert(i < indexTupDesc->natts); + + colls = list_concat(colls, + GetTypeCollations(att->atttypid, false)); } } + /* + * Then split the dependencies on whether they're deterministic or + * not, removing any duplicates. + */ + foreach(lc, colls) + { + Oid c = lfirst_oid(lc); + + if (!OidIsValid(c)) + continue; + + if (get_collation_isdeterministic(c)) + determ_colls = list_append_unique_oid(determ_colls, c); + else + nondeterm_colls = list_append_unique_oid(nondeterm_colls, c); + } + + /* + * For deterministic transaction, only track the version if the AM + * relies on a stable ordering. + */ + if (determ_colls) + { + bool track_version; + + track_version = index_depends_stable_coll_order(indexInfo->ii_Am); + + recordDependencyOnCollations(&myself, determ_colls, track_version); + + /* + * Advance the command counter so that later calls to + * recordMultipleDependencies calls can see the newly-entered + * pg_depend catalog tuples for the index. + */ + CommandCounterIncrement(); + } + + /* + * We always record the version for dependency on non-deterministic + * collations. + */ + if (nondeterm_colls) + { + recordDependencyOnCollations(&myself, nondeterm_colls, true); + + /* + * Advance the command counter so that later calls to + * recordMultipleDependencies calls can see the newly-entered + * pg_depend catalog tuples for the index. + */ + CommandCounterIncrement(); + } + /* Store dependency on operator classes */ for (i = 0; i < indexInfo->ii_NumIndexKeyAttrs; i++) { @@ -1147,21 +1210,30 @@ index_create(Relation heapRelation, /* Store dependencies on anything mentioned in index expressions */ if (indexInfo->ii_Expressions) { + /* recordDependencyOnSingleRelExpr get rid of duplicated entries */ recordDependencyOnSingleRelExpr(&myself, (Node *) indexInfo->ii_Expressions, heapRelationId, DEPENDENCY_NORMAL, - DEPENDENCY_AUTO, false); + DEPENDENCY_AUTO, false, true); + + /* + * Advance the command counter so that later + * recordMultipleDependencies calls can see the newly-entered + * pg_depend catalog tuples for the index. + */ + CommandCounterIncrement(); } /* Store dependencies on anything mentioned in predicate */ if (indexInfo->ii_Predicate) { + /* recordDependencyOnSingleRelExpr get rid of duplicated entries */ recordDependencyOnSingleRelExpr(&myself, (Node *) indexInfo->ii_Predicate, heapRelationId, DEPENDENCY_NORMAL, - DEPENDENCY_AUTO, false); + DEPENDENCY_AUTO, false, true); } } else @@ -1240,6 +1312,94 @@ index_create(Relation heapRelation, return indexRelationId; } +static char * +index_check_collation_version(const ObjectAddress *otherObject, + const char *version, + void *userdata) +{ + Oid relid = *(Oid *) userdata; + char *current_version; + + /* We only care about dependencies on collations. */ + if (otherObject->classId != CollationRelationId) + return NULL; + + /* Compare with the current version. */ + current_version = get_collation_version_for_oid(otherObject->objectId); + + /* XXX should we warn about "disappearing" versions? */ + if (current_version) + { + /* + * We now support versioning for the underlying collation library on + * this system, or previous version is unknown. + */ + if (!version || (strcmp(version, "") == 0 && strcmp(current_version, + "") != 0)) + { + ereport(WARNING, + (errmsg("index \"%s\" depends on collation \"%s\" with an unknown version, and the current version is \"%s\"", + get_rel_name(relid), + get_collation_name(otherObject->objectId), + current_version), + errdetail("The index may be corrupted due to changes in sort order."), + errhint("REINDEX to avoid the risk of corruption."))); + } + else if (strcmp(current_version, version) != 0) + { + ereport(WARNING, + (errmsg("index \"%s\" depends on collation \"%s\" version \"%s\", but the current version is \"%s\"", + get_rel_name(relid), + get_collation_name(otherObject->objectId), + version, + current_version), + errdetail("The index may be corrupted due to changes in sort order."), + errhint("REINDEX to avoid the risk of corruption."))); + } + } + + return NULL; +} + +void +index_check_collation_versions(Oid relid) +{ + ObjectAddress object; + + object.classId = RelationRelationId; + object.objectId = relid; + object.objectSubId = 0; + visitDependentObjects(&object, &index_check_collation_version, &relid); +} + +static char * +index_update_collation_version(const ObjectAddress *otherObject, + const char *version, + void *userdata) +{ + char *current_version = (char *) userdata; + + /* We only care about dependencies on collations. */ + if (otherObject->classId != CollationRelationId) + return NULL; + + current_version = get_collation_version_for_oid(otherObject->objectId); + return current_version; +} + +void +index_update_collation_versions(Oid relid) +{ + ObjectAddress object; + NameData current_version; + + object.classId = RelationRelationId; + object.objectId = relid; + object.objectSubId = 0; + visitDependentObjects(&object, &index_update_collation_version, + ¤t_version); +} + /* * index_concurrently_create_copy * @@ -1691,14 +1851,9 @@ index_concurrently_swap(Oid newIndexId, Oid oldIndexId, const char *oldName) /* * Swap all dependencies of and on the old index to the new one, and - * vice-versa. Note that a call to CommandCounterIncrement() would cause - * duplicate entries in pg_depend, so this should not be done. + * vice-versa. */ - changeDependenciesOf(RelationRelationId, newIndexId, oldIndexId); - changeDependenciesOn(RelationRelationId, newIndexId, oldIndexId); - - changeDependenciesOf(RelationRelationId, oldIndexId, newIndexId); - changeDependenciesOn(RelationRelationId, oldIndexId, newIndexId); + swapDependencies(RelationRelationId, newIndexId, oldIndexId); /* * Copy over statistics from old to new index @@ -2652,6 +2807,17 @@ FormIndexDatum(IndexInfo *indexInfo, elog(ERROR, "wrong number of index expressions"); } +/* + * Returns whether the given index access method depend on a stable collation + * order. + */ +static bool +index_depends_stable_coll_order(Oid amoid) +{ + return (amoid != HASH_AM_OID && + strcmp(get_am_name(amoid), "bloom") != 0); +} + /* * index_update_stats --- update pg_class entry after CREATE INDEX or REINDEX @@ -3005,6 +3171,68 @@ index_build(Relation heapRelation, SetUserIdAndSecContext(save_userid, save_sec_context); } +static char * +index_force_collation_version(const ObjectAddress *otherObject, + const char *version, + void *userdata) +{ + NewCollationVersionDependency *forced_dependency; + + forced_dependency = (NewCollationVersionDependency *) userdata; + + /* We only care about dependencies on collations. */ + if (otherObject->classId != CollationRelationId) + return NULL; + + /* + * We only care about dependencies on a specific collation if a valid Oid + * was given. + */ + if (OidIsValid(forced_dependency->oid) && + otherObject->objectId != forced_dependency->oid) + return NULL; + + return forced_dependency->version; +} + +/* index_force_collation_versions + * + * Override collation version dependencies for the given index. If no + * collation identifier is specified, all dependent collation should be + * reset to an unknown version dependency, and no version should be provided + * either. + */ +void +index_force_collation_versions(Oid indexid, Oid coll, char *version) +{ + Relation index; + ObjectAddress object; + NewCollationVersionDependency forced_dependency; + + Assert(version); + + index = relation_open(indexid, AccessExclusiveLock); + + if (index->rd_rel->relkind != RELKIND_INDEX) + ereport(ERROR, + (errcode(ERRCODE_WRONG_OBJECT_TYPE), + (errmsg("\"%s\" is not an index", get_rel_name(indexid))))); + + forced_dependency.oid = InvalidOid; + forced_dependency.version = version; + + object.classId = RelationRelationId; + object.objectId = indexid; + object.objectSubId = 0; + visitDependentObjects(&object, &index_force_collation_version, + &forced_dependency); + + /* Invalidate the index relcache */ + CacheInvalidateRelcache(index); + + relation_close(index, NoLock); +} + /* * IndexCheckExclusion - verify that a new exclusion constraint is satisfied * @@ -3633,6 +3861,9 @@ reindex_index(Oid indexId, bool skip_constraint_checks, char persistence, /* Close rels, but keep locks */ index_close(iRel, NoLock); table_close(heapRelation, NoLock); + + /* Record the current versions of all depended-on collations. */ + index_update_collation_versions(indexId); } /* diff --git a/src/backend/catalog/pg_constraint.c b/src/backend/catalog/pg_constraint.c index 90932be831..3cc0f6651c 100644 --- a/src/backend/catalog/pg_constraint.c +++ b/src/backend/catalog/pg_constraint.c @@ -360,7 +360,7 @@ CreateConstraintEntry(const char *constraintName, */ recordDependencyOnSingleRelExpr(&conobject, conExpr, relId, DEPENDENCY_NORMAL, - DEPENDENCY_NORMAL, false); + DEPENDENCY_NORMAL, false, true); } /* Post creation hook for new constraint */ diff --git a/src/backend/catalog/pg_depend.c b/src/backend/catalog/pg_depend.c index 5d45e706cb..b10fc9a241 100644 --- a/src/backend/catalog/pg_depend.c +++ b/src/backend/catalog/pg_depend.c @@ -19,6 +19,7 @@ #include "access/table.h" #include "catalog/dependency.h" #include "catalog/indexing.h" +#include "catalog/pg_collation.h" #include "catalog/pg_constraint.h" #include "catalog/pg_depend.h" #include "catalog/pg_extension.h" @@ -27,9 +28,18 @@ #include "utils/builtins.h" #include "utils/fmgroids.h" #include "utils/lsyscache.h" +#include "utils/pg_locale.h" #include "utils/rel.h" +static long changeDependenciesOf(Oid classId, Oid oldObjectId, + Oid newObjectId, bool preserve_version); +static long changeDependenciesOn(Oid refClassId, Oid oldRefObjectId, + Oid newRefObjectId); +static bool dependencyExists(const ObjectAddress *depender, + const ObjectAddress *referenced); +static char *getDependencyVersion(const ObjectAddress *depender, + const ObjectAddress *referenced); static bool isObjectPinned(const ObjectAddress *object, Relation rel); @@ -45,19 +55,48 @@ recordDependencyOn(const ObjectAddress *depender, const ObjectAddress *referenced, DependencyType behavior) { - recordMultipleDependencies(depender, referenced, 1, NULL, behavior); + recordMultipleDependencies(depender, referenced, 1, behavior, false); +} + +/* + * Given a list of collations, record a dependency on its underlying collation + * version. + */ +void +recordDependencyOnCollations(ObjectAddress *myself, + List *collations, + bool record_version) +{ + ListCell *lc; + + foreach(lc, collations) + { + ObjectAddress referenced; + + referenced.classId = CollationRelationId; + referenced.objectId = lfirst_oid(lc); + referenced.objectSubId = 0; + + recordMultipleDependencies(myself, &referenced, 1, + DEPENDENCY_NORMAL, record_version); + } } /* * Record multiple dependencies (of the same kind) for a single dependent * object. This has a little less overhead than recording each separately. + * + * If track_version is true, then a record could be added even if the referenced + * dependency is pinned, and the dependency version will be retrieved according + * to the referenced object kind. + * For now, only collation version is supported. */ void recordMultipleDependencies(const ObjectAddress *depender, const ObjectAddress *referenced, int nreferenced, - const char *version, - DependencyType behavior) + DependencyType behavior, + bool track_version) { Relation dependDesc; CatalogIndexState indstate; @@ -65,6 +104,7 @@ recordMultipleDependencies(const ObjectAddress *depender, int i; bool nulls[Natts_pg_depend]; Datum values[Natts_pg_depend]; + char *version = NULL; if (nreferenced <= 0) return; /* nothing to do */ @@ -83,12 +123,49 @@ recordMultipleDependencies(const ObjectAddress *depender, for (i = 0; i < nreferenced; i++, referenced++) { + bool ignore_systempin = false; + + if (track_version) + { + /* Only dependency on a collation is supported. */ + if (referenced->classId == CollationRelationId) + { + /* C and POSIX collations don't require tracking the version */ + if (referenced->objectId == C_COLLATION_OID || + referenced->objectId == POSIX_COLLATION_OID) + continue; + + /* + * We don't want to record redundant depedencies that are used + * to track versions to avoid redundant warnings in case of + * non-matching versions when those are checked. Note that + * callers have to take care of removing duplicated entries + * and calling CommandCounterIncrement() if the dependencies + * are registered in multiple calls. + */ + if (dependencyExists(depender, referenced)) + continue; + + /* + * Default collation is pinned, so we need to force recording + * the dependency to store the version. + */ + if (referenced->objectId == DEFAULT_COLLATION_OID) + ignore_systempin = true; + version = get_collation_version_for_oid(referenced->objectId); + Assert(version); + } + } + else + Assert(!version); + /* * If the referenced object is pinned by the system, there's no real - * need to record dependencies on it. This saves lots of space in - * pg_depend, so it's worth the time taken to check. + * need to record dependencies on it, unless we need to record a + * version. This saves lots of space in pg_depend, so it's worth the + * time taken to check. */ - if (!isObjectPinned(referenced, dependDesc)) + if (ignore_systempin || !isObjectPinned(referenced, dependDesc)) { /* * Record the Dependency. Note we don't bother to check for @@ -451,16 +528,33 @@ changeDependencyFor(Oid classId, Oid objectId, } /* - * Adjust all dependency records to come from a different object of the same type + * Swap all dependencies of and on the old index to the new one, and + * vice-versa, while preserving any referenced version for the original owners. + * Note that a call to CommandCounterIncrement() would cause duplicate entries + * in pg_depend, so this should not be done. + */ +void +swapDependencies(Oid classId, Oid firstObjectId, Oid secondObjectId) +{ + changeDependenciesOf(classId, firstObjectId, secondObjectId, true); + changeDependenciesOn(classId, firstObjectId, secondObjectId); + + changeDependenciesOf(classId, secondObjectId, firstObjectId, true); + changeDependenciesOn(classId, secondObjectId, firstObjectId); +} + +/* + * Adjust all dependency records to come from a different object of the same + * type, optionally preserving the original referenced version. * * classId/oldObjectId specify the old referencing object. * newObjectId is the new referencing object (must be of class classId). * * Returns the number of records updated. */ -long +static long changeDependenciesOf(Oid classId, Oid oldObjectId, - Oid newObjectId) + Oid newObjectId, bool preserve_version) { long count = 0; Relation depRel; @@ -485,13 +579,49 @@ changeDependenciesOf(Oid classId, Oid oldObjectId, while (HeapTupleIsValid((tup = systable_getnext(scan)))) { Form_pg_depend depform = (Form_pg_depend) GETSTRUCT(tup); + Datum values[Natts_pg_depend]; + bool nulls[Natts_pg_depend]; + bool replaces[Natts_pg_depend]; + bool isnull = true; - /* make a modifiable copy */ - tup = heap_copytuple(tup); - depform = (Form_pg_depend) GETSTRUCT(tup); + memset(values, 0, sizeof(values)); + memset(nulls, 0, sizeof(nulls)); + memset(replaces, 0, sizeof(replaces)); - depform->objid = newObjectId; + values[Anum_pg_depend_objid - 1] = newObjectId; + replaces[Anum_pg_depend_objid - 1] = true; + /* + * We assume that a version would exist for both the old and new + * object or none. + */ + if (preserve_version) + { + heap_getattr(tup, Anum_pg_depend_refobjversion, + RelationGetDescr(depRel), &isnull); + } + + if (!isnull) + { + ObjectAddress depender, + referenced; + char *version; + + ObjectAddressSubSet(depender, depform->classid, + newObjectId, depform->objsubid); + ObjectAddressSubSet(referenced, depform->refclassid, + depform->refobjid, depform->refobjsubid); + + version = getDependencyVersion(&depender, &referenced); + if (version) + values[Anum_pg_depend_refobjversion - 1] = CStringGetTextDatum(version); + else + nulls[Anum_pg_depend_refobjversion - 1] = true; + replaces[Anum_pg_depend_refobjversion - 1] = true; + } + + tup = heap_modify_tuple(tup, RelationGetDescr(depRel), values, + nulls, replaces); CatalogTupleUpdate(depRel, &tup->t_self, tup); heap_freetuple(tup); @@ -514,7 +644,7 @@ changeDependenciesOf(Oid classId, Oid oldObjectId, * * Returns the number of records updated. */ -long +static long changeDependenciesOn(Oid refClassId, Oid oldRefObjectId, Oid newRefObjectId) { @@ -594,6 +724,104 @@ changeDependenciesOn(Oid refClassId, Oid oldRefObjectId, return count; } +/* dependencyExists() + * + * Test if a record exists for the given depender and referenced addresses. + */ +static bool +dependencyExists(const ObjectAddress *depender, + const ObjectAddress *referenced) +{ + Relation depRel; + ScanKeyData key[3]; + SysScanDesc scan; + HeapTuple tup; + bool ret = false; + + ScanKeyInit(&key[0], + Anum_pg_depend_classid, + BTEqualStrategyNumber, F_OIDEQ, + ObjectIdGetDatum(depender->classId)); + ScanKeyInit(&key[1], + Anum_pg_depend_objid, + BTEqualStrategyNumber, F_OIDEQ, + ObjectIdGetDatum(depender->objectId)); + ScanKeyInit(&key[2], + Anum_pg_depend_objsubid, + BTEqualStrategyNumber, F_INT4EQ, + Int32GetDatum(depender->objectSubId)); + + depRel = table_open(DependRelationId, RowExclusiveLock); + scan = systable_beginscan(depRel, DependDependerIndexId, true, + NULL, 3, key); + + while (HeapTupleIsValid(tup = systable_getnext(scan))) + { + Form_pg_depend foundDep = (Form_pg_depend) GETSTRUCT(tup); + + if (foundDep->refclassid == referenced->classId && + foundDep->refobjid == referenced->objectId && + foundDep->refobjsubid == referenced->objectSubId) + { + ret = true; + break; + } + } + systable_endscan(scan); + table_close(depRel, RowExclusiveLock); + + return ret; +} + +static char * +getDependencyVersion(const ObjectAddress *depender, + const ObjectAddress *referenced) +{ + Relation depRel; + ScanKeyData key[3]; + SysScanDesc scan; + HeapTuple tup; + Datum depversion; + char *version = NULL; + + ScanKeyInit(&key[0], + Anum_pg_depend_classid, + BTEqualStrategyNumber, F_OIDEQ, + ObjectIdGetDatum(depender->classId)); + ScanKeyInit(&key[1], + Anum_pg_depend_objid, + BTEqualStrategyNumber, F_OIDEQ, + ObjectIdGetDatum(depender->objectId)); + ScanKeyInit(&key[2], + Anum_pg_depend_objsubid, + BTEqualStrategyNumber, F_INT4EQ, + Int32GetDatum(depender->objectSubId)); + + depRel = table_open(DependRelationId, RowExclusiveLock); + scan = systable_beginscan(depRel, DependDependerIndexId, true, + NULL, 3, key); + + while (HeapTupleIsValid(tup = systable_getnext(scan))) + { + Form_pg_depend foundDep = (Form_pg_depend) GETSTRUCT(tup); + bool isnull; + + if (foundDep->refclassid == referenced->classId && + foundDep->refobjid == referenced->objectId && + foundDep->refobjsubid == referenced->objectSubId) + { + depversion = heap_getattr(tup, Anum_pg_depend_refobjversion, + RelationGetDescr(depRel), &isnull); + version = isnull ? NULL : TextDatumGetCString(depversion); + break; + } + } + systable_endscan(scan); + table_close(depRel, RowExclusiveLock); + + return version; +} + /* * isObjectPinned() * diff --git a/src/backend/catalog/pg_type.c b/src/backend/catalog/pg_type.c index 79ffe317dd..a3836d315a 100644 --- a/src/backend/catalog/pg_type.c +++ b/src/backend/catalog/pg_type.c @@ -15,6 +15,7 @@ #include "postgres.h" #include "access/htup_details.h" +#include "access/relation.h" #include "access/table.h" #include "access/xact.h" #include "catalog/binary_upgrade.h" @@ -512,6 +513,74 @@ TypeCreate(Oid newTypeOid, return address; } +/* Get a list of all distinct collations oid that the given type depends on. */ +List * +GetTypeCollations(Oid typeoid, bool non_deterministic_only) +{ + List *result = NIL; + HeapTuple tuple; + Form_pg_type typeTup; + + tuple = SearchSysCache1(TYPEOID, ObjectIdGetDatum(typeoid)); + if (!HeapTupleIsValid(tuple)) + elog(ERROR, "cache lookup failed for type %u", typeoid); + typeTup = (Form_pg_type) GETSTRUCT(tuple); + + if (OidIsValid(typeTup->typcollation)) + { + if (!non_deterministic_only || + !get_collation_isdeterministic(typeTup->typcollation)) + result = list_append_unique_oid(result, typeTup->typcollation); + } + else if (typeTup->typtype == TYPTYPE_COMPOSITE) + { + Relation rel = relation_open(typeTup->typrelid, AccessShareLock); + TupleDesc desc = RelationGetDescr(rel); + + for (int i = 0; i < RelationGetNumberOfAttributes(rel); i++) + { + Form_pg_attribute att = TupleDescAttr(desc, i); + + if (OidIsValid(att->attcollation)) + { + if (!non_deterministic_only || + !get_collation_isdeterministic(att->attcollation)) + result = list_append_unique_oid(result, att->attcollation); + } + else + result = list_concat_unique_oid(result, + GetTypeCollations(att->atttypid, + non_deterministic_only)); + } + + relation_close(rel, NoLock); + } + else if (typeTup->typtype == TYPTYPE_DOMAIN) + { + Assert(OidIsValid(typeTup->typbasetype)); + + result = list_concat_unique_oid(result, + GetTypeCollations(typeTup->typbasetype, + non_deterministic_only)); + } + else if (typeTup->typtype == TYPTYPE_RANGE) + { + Oid rangeid = get_range_subtype(typeTup->oid); + + Assert(OidIsValid(rangeid)); + + result = list_concat_unique_oid(result, + GetTypeCollations(rangeid, non_deterministic_only)); + } + else if (OidIsValid(typeTup->typelem)) + result = list_concat_unique_oid(result, + GetTypeCollations(typeTup->typelem, non_deterministic_only)); + + ReleaseSysCache(tuple); + + return result; +} + /* * GenerateTypeDependencies: build the dependencies needed for a type * diff --git a/src/backend/commands/collationcmds.c b/src/backend/commands/collationcmds.c index 78eceda848..d4eccf163f 100644 --- a/src/backend/commands/collationcmds.c +++ b/src/backend/commands/collationcmds.c @@ -273,28 +273,12 @@ Datum pg_collation_actual_version(PG_FUNCTION_ARGS) { Oid collid = PG_GETARG_OID(0); - HeapTuple tp; - char *collcollate; - char collprovider; char *version; - tp = SearchSysCache1(COLLOID, ObjectIdGetDatum(collid)); - if (!HeapTupleIsValid(tp)) - ereport(ERROR, - (errcode(ERRCODE_UNDEFINED_OBJECT), - errmsg("collation with OID %u does not exist", collid))); - - collcollate = pstrdup(NameStr(((Form_pg_collation) GETSTRUCT(tp))->collcollate)); - collprovider = ((Form_pg_collation) GETSTRUCT(tp))->collprovider; - - ReleaseSysCache(tp); - - version = get_collation_actual_version(collprovider, collcollate); + version = get_collation_version_for_oid(collid); + Assert(version); - if (version) - PG_RETURN_TEXT_P(cstring_to_text(version)); - else - PG_RETURN_NULL(); + PG_RETURN_TEXT_P(cstring_to_text(version)); } diff --git a/src/backend/commands/vacuum.c b/src/backend/commands/vacuum.c index d32de23e62..65e65abb9a 100644 --- a/src/backend/commands/vacuum.c +++ b/src/backend/commands/vacuum.c @@ -31,6 +31,8 @@ #include "access/tableam.h" #include "access/transam.h" #include "access/xact.h" +#include "catalog/catalog.h" +#include "catalog/index.h" #include "catalog/namespace.h" #include "catalog/pg_database.h" #include "catalog/pg_inherits.h" @@ -632,6 +634,36 @@ vacuum_open_relation(Oid relid, RangeVar *relation, int options, rel_lock = false; } + /* + * Perform version sanity checks on the relation underlying indexes if + * it's not a VACUUM FULL, as VACUUM FULL will recreate the index and + * update the recorded collation version. + */ + if (!(options & VACOPT_FULL) && onerel && !IsSystemRelation(onerel) && + onerel->rd_rel->relhasindex) + { + List *indexoidlist; + ListCell *l; + + indexoidlist = RelationGetIndexList(onerel); + foreach(l, indexoidlist) + { + Oid indexoid = lfirst_oid(l); + Relation indexRelation; + + indexRelation = index_open(indexoid, AccessShareLock); + + /* Warn if any dependent collations' versions have moved. */ + if (!indexRelation->rd_version_checked) + { + index_check_collation_versions(indexoid); + indexRelation->rd_version_checked = true; + } + + index_close(indexRelation, NoLock); + } + } + /* if relation is opened, leave */ if (onerel) return onerel; diff --git a/src/backend/optimizer/util/plancat.c b/src/backend/optimizer/util/plancat.c index 25545029d7..ad1383e7b3 100644 --- a/src/backend/optimizer/util/plancat.c +++ b/src/backend/optimizer/util/plancat.c @@ -28,6 +28,7 @@ #include "catalog/catalog.h" #include "catalog/dependency.h" #include "catalog/heap.h" +#include "catalog/index.h" #include "catalog/pg_am.h" #include "catalog/pg_proc.h" #include "catalog/pg_statistic_ext.h" @@ -198,6 +199,14 @@ get_relation_info(PlannerInfo *root, Oid relationObjectId, bool inhparent, indexRelation = index_open(indexoid, lmode); index = indexRelation->rd_index; + /* Warn if any dependent collations' versions have moved. */ + if (!IsSystemRelation(relation) && + !indexRelation->rd_version_checked) + { + index_check_collation_versions(indexoid); + indexRelation->rd_version_checked = true; + } + /* * Ignore invalid indexes, since they can't safely be used for * queries. Note that this is OK because the data structure we diff --git a/src/backend/utils/adt/pg_locale.c b/src/backend/utils/adt/pg_locale.c index 2c5f5bfa37..4e116485c6 100644 --- a/src/backend/utils/adt/pg_locale.c +++ b/src/backend/utils/adt/pg_locale.c @@ -57,7 +57,9 @@ #include "access/htup_details.h" #include "catalog/pg_collation.h" #include "catalog/pg_control.h" +#include "catalog/pg_database.h" #include "mb/pg_wchar.h" +#include "miscadmin.h" #include "utils/builtins.h" #include "utils/formatting.h" #include "utils/hsearch.h" @@ -148,6 +150,9 @@ static char *IsoLocaleName(const char *); /* MSVC specific */ static void icu_set_collation_attributes(UCollator *collator, const char *loc); #endif +static char *get_collation_actual_version(char collprovider, + const char *collcollate); + /* * pg_perm_setlocale * @@ -1639,7 +1644,7 @@ pg_newlocale_from_collation(Oid collid) * Get provider-specific collation version string for the given collation from * the operating system/library. */ -char * +static char * get_collation_actual_version(char collprovider, const char *collcollate) { char *collversion = NULL; @@ -1721,6 +1726,51 @@ get_collation_actual_version(char collprovider, const char *collcollate) return collversion; } +/* + * Get provider-specific collation version string given a collation OID. + * + * As this version is used in index dependency tracking, an empty string is + * returned when the version is unknown, to distinguish from dependencies where + * the version should not be tracked, represented by a NULL version. + */ +char * +get_collation_version_for_oid(Oid oid) +{ + HeapTuple tp; + char *version = NULL; + + Assert(oid != C_COLLATION_OID && oid != POSIX_COLLATION_OID); + + if (oid == DEFAULT_COLLATION_OID) + { + Form_pg_database dbform; + + tp = SearchSysCache1(DATABASEOID, ObjectIdGetDatum(MyDatabaseId)); + if (!HeapTupleIsValid(tp)) + elog(ERROR, "cache lookup failed for database %u", MyDatabaseId); + dbform = (Form_pg_database) GETSTRUCT(tp); + version = get_collation_actual_version(COLLPROVIDER_LIBC, + NameStr(dbform->datcollate)); + } + else + { + Form_pg_collation collform; + + tp = SearchSysCache1(COLLOID, ObjectIdGetDatum(oid)); + if (!HeapTupleIsValid(tp)) + elog(ERROR, "cache lookup failed for collation %u", oid); + collform = (Form_pg_collation) GETSTRUCT(tp); + version = get_collation_actual_version(collform->collprovider, + NameStr(collform->collcollate)); + } + + ReleaseSysCache(tp); + + if (!version) + return ""; + else + return version; +} #ifdef USE_ICU /* diff --git a/src/backend/utils/adt/pg_upgrade_support.c b/src/backend/utils/adt/pg_upgrade_support.c index 18f2ee8226..07ff39f5aa 100644 --- a/src/backend/utils/adt/pg_upgrade_support.c +++ b/src/backend/utils/adt/pg_upgrade_support.c @@ -13,6 +13,7 @@ #include "catalog/binary_upgrade.h" #include "catalog/heap.h" +#include "catalog/index.h" #include "catalog/namespace.h" #include "catalog/pg_type.h" #include "commands/extension.h" @@ -208,3 +209,27 @@ binary_upgrade_set_missing_value(PG_FUNCTION_ARGS) PG_RETURN_VOID(); } + +Datum +binary_upgrade_set_index_coll_version(PG_FUNCTION_ARGS) +{ + Oid relid; + Oid coll; + char *version; + + CHECK_IS_BINARY_UPGRADE; + + relid = PG_GETARG_OID(0); + + /* Detect if a collation is specified */ + if (PG_ARGISNULL(1)) + coll = InvalidOid; + else + coll = PG_GETARG_OID(1); + + version = TextDatumGetCString(PG_GETARG_TEXT_PP(2)); + + index_force_collation_versions(relid, coll, version); + + PG_RETURN_VOID(); +} diff --git a/src/backend/utils/cache/relcache.c b/src/backend/utils/cache/relcache.c index 0b9eb00d2d..62fefc4fcc 100644 --- a/src/backend/utils/cache/relcache.c +++ b/src/backend/utils/cache/relcache.c @@ -42,6 +42,7 @@ #include "access/xact.h" #include "access/xlog.h" #include "catalog/catalog.h" +#include "catalog/index.h" #include "catalog/indexing.h" #include "catalog/namespace.h" #include "catalog/partition.h" @@ -5926,6 +5927,7 @@ load_relcache_init_file(bool shared) rel->rd_idattr = NULL; rel->rd_pubactions = NULL; rel->rd_statvalid = false; + rel->rd_version_checked = false; rel->rd_statlist = NIL; rel->rd_fkeyvalid = false; rel->rd_fkeylist = NIL; diff --git a/src/bin/pg_dump/Makefile b/src/bin/pg_dump/Makefile index 2532d9183a..c58ebaa681 100644 --- a/src/bin/pg_dump/Makefile +++ b/src/bin/pg_dump/Makefile @@ -16,6 +16,8 @@ subdir = src/bin/pg_dump top_builddir = ../../.. include $(top_builddir)/src/Makefile.global +export with_icu + override CPPFLAGS := -I$(libpq_srcdir) $(CPPFLAGS) LDFLAGS_INTERNAL += -L$(top_builddir)/src/fe_utils -lpgfeutils $(libpq_pgport) diff --git a/src/bin/pg_dump/pg_backup.h b/src/bin/pg_dump/pg_backup.h index 8c0cedcd98..dc82b076ef 100644 --- a/src/bin/pg_dump/pg_backup.h +++ b/src/bin/pg_dump/pg_backup.h @@ -171,6 +171,7 @@ typedef struct _dumpOptions int sequence_data; /* dump sequence data even in schema-only mode */ int do_nothing; + int unknown_coll_compat; } DumpOptions; /* diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c index 2f6bfede8e..f41acebe38 100644 --- a/src/bin/pg_dump/pg_dump.c +++ b/src/bin/pg_dump/pg_dump.c @@ -46,6 +46,7 @@ #include "catalog/pg_attribute_d.h" #include "catalog/pg_cast_d.h" #include "catalog/pg_class_d.h" +#include "catalog/pg_collation_d.h" #include "catalog/pg_default_acl_d.h" #include "catalog/pg_largeobject_d.h" #include "catalog/pg_largeobject_metadata_d.h" @@ -285,6 +286,8 @@ static void binary_upgrade_extension_member(PQExpBuffer upgrade_buffer, static const char *getAttrName(int attrnum, TableInfo *tblInfo); static const char *fmtCopyColumnList(const TableInfo *ti, PQExpBuffer buffer); static bool nonemptyReloptions(const char *reloptions); +static void appendIndexCollationVersion(PQExpBuffer buffer, IndxInfo *indxinfo, + int enc, int unknown_coll_compat); static void appendReloptionsArrayAH(PQExpBuffer buffer, const char *reloptions, const char *prefix, Archive *fout); static char *get_synchronized_snapshot(Archive *fout); @@ -386,6 +389,7 @@ main(int argc, char **argv) {"on-conflict-do-nothing", no_argument, &dopt.do_nothing, 1}, {"rows-per-insert", required_argument, NULL, 10}, {"include-foreign-data", required_argument, NULL, 11}, + {"unknown-collations-binary-compatible", no_argument, &dopt.unknown_coll_compat, 1}, {NULL, 0, NULL, 0} }; @@ -713,6 +717,10 @@ main(int argc, char **argv) if (archiveFormat != archDirectory && numWorkers > 1) fatal("parallel backup only supported by the directory format"); + /* Unknown collation versions can only be ignored in binary upgrade mode */ + if (dopt.unknown_coll_compat && !dopt.binary_upgrade) + fatal("option --unknown-collations-binary-compatible only works in binary upgrade mode"); + /* Open the output file */ fout = CreateArchive(filename, archiveFormat, compressLevel, dosync, archiveMode, setupDumpWorker); @@ -7014,7 +7022,9 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) i_tablespace, i_indreloptions, i_indstatcols, - i_indstatvals; + i_indstatvals, + i_inddependoids, + i_inddependversions; int ntups; for (i = 0; i < numTables; i++) @@ -7050,7 +7060,62 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) * is not. */ resetPQExpBuffer(query); - if (fout->remoteVersion >= 110000) + if (fout->remoteVersion >= 130000) + { + appendPQExpBuffer(query, + "SELECT t.tableoid, t.oid, " + "t.relname AS indexname, " + "inh.inhparent AS parentidx, " + "pg_catalog.pg_get_indexdef(i.indexrelid) AS indexdef, " + "i.indnkeyatts AS indnkeyatts, " + "i.indnatts AS indnatts, " + "i.indkey, i.indisclustered, " + "i.indisreplident, " + "c.contype, c.conname, " + "c.condeferrable, c.condeferred, " + "c.tableoid AS contableoid, " + "c.oid AS conoid, " + "pg_catalog.pg_get_constraintdef(c.oid, false) AS condef, " + "(SELECT spcname FROM pg_catalog.pg_tablespace s WHERE s.oid = t.reltablespace) AS tablespace, " + "t.reloptions AS indreloptions, " + "(SELECT pg_catalog.array_agg(attnum ORDER BY attnum) " + " FROM pg_catalog.pg_attribute " + " WHERE attrelid = i.indexrelid AND " + " attstattarget >= 0) AS indstatcols," + "(SELECT pg_catalog.array_agg(attstattarget ORDER BY attnum) " + " FROM pg_catalog.pg_attribute " + " WHERE attrelid = i.indexrelid AND " + " attstattarget >= 0) AS indstatvals, " + "(SELECT pg_catalog.array_agg(refobjid ORDER BY refobjid) " + " FROM pg_catalog.pg_depend " + " WHERE classid = " CppAsString2(RelationRelationId) " AND " + " objid = i.indexrelid AND " + " objsubid = 0 AND " + " refclassid = " CppAsString2(CollationRelationId) " AND " + " refobjversion IS NOT NULL) AS inddependoids, " + "(SELECT pg_catalog.array_agg(quote_literal(refobjversion) ORDER BY refobjid) " + " FROM pg_catalog.pg_depend " + " WHERE classid = " CppAsString2(RelationRelationId) " AND " + " objid = i.indexrelid AND " + " objsubid = 0 AND " + " refclassid = " CppAsString2(CollationRelationId) " AND " + " refobjversion IS NOT NULL) AS inddependversions " + "FROM pg_catalog.pg_index i " + "JOIN pg_catalog.pg_class t ON (t.oid = i.indexrelid) " + "JOIN pg_catalog.pg_class t2 ON (t2.oid = i.indrelid) " + "LEFT JOIN pg_catalog.pg_constraint c " + "ON (i.indrelid = c.conrelid AND " + "i.indexrelid = c.conindid AND " + "c.contype IN ('p','u','x')) " + "LEFT JOIN pg_catalog.pg_inherits inh " + "ON (inh.inhrelid = indexrelid) " + "WHERE i.indrelid = '%u'::pg_catalog.oid " + "AND (i.indisvalid OR t2.relkind = 'p') " + "AND i.indisready " + "ORDER BY indexname", + tbinfo->dobj.catId.oid); + } + else if (fout->remoteVersion >= 110000) { appendPQExpBuffer(query, "SELECT t.tableoid, t.oid, " @@ -7075,7 +7140,9 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) "(SELECT pg_catalog.array_agg(attstattarget ORDER BY attnum) " " FROM pg_catalog.pg_attribute " " WHERE attrelid = i.indexrelid AND " - " attstattarget >= 0) AS indstatvals " + " attstattarget >= 0) AS indstatvals, " + "' ' AS inddependoids, " + "' ' AS inddependversions " "FROM pg_catalog.pg_index i " "JOIN pg_catalog.pg_class t ON (t.oid = i.indexrelid) " "JOIN pg_catalog.pg_class t2 ON (t2.oid = i.indrelid) " @@ -7114,7 +7181,9 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) "(SELECT spcname FROM pg_catalog.pg_tablespace s WHERE s.oid = t.reltablespace) AS tablespace, " "t.reloptions AS indreloptions, " "'' AS indstatcols, " - "'' AS indstatvals " + "'' AS indstatvals, " + "' ' AS inddependoids, " + "' ' AS inddependversions " "FROM pg_catalog.pg_index i " "JOIN pg_catalog.pg_class t ON (t.oid = i.indexrelid) " "LEFT JOIN pg_catalog.pg_constraint c " @@ -7149,7 +7218,9 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) "(SELECT spcname FROM pg_catalog.pg_tablespace s WHERE s.oid = t.reltablespace) AS tablespace, " "t.reloptions AS indreloptions, " "'' AS indstatcols, " - "'' AS indstatvals " + "'' AS indstatvals, " + "' ' AS inddependoids, " + "' ' AS inddependversions " "FROM pg_catalog.pg_index i " "JOIN pg_catalog.pg_class t ON (t.oid = i.indexrelid) " "LEFT JOIN pg_catalog.pg_constraint c " @@ -7180,7 +7251,9 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) "(SELECT spcname FROM pg_catalog.pg_tablespace s WHERE s.oid = t.reltablespace) AS tablespace, " "t.reloptions AS indreloptions, " "'' AS indstatcols, " - "'' AS indstatvals " + "'' AS indstatvals, " + "' ' AS inddependoids, " + "' ' AS inddependversions " "FROM pg_catalog.pg_index i " "JOIN pg_catalog.pg_class t ON (t.oid = i.indexrelid) " "LEFT JOIN pg_catalog.pg_depend d " @@ -7214,7 +7287,9 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) "(SELECT spcname FROM pg_catalog.pg_tablespace s WHERE s.oid = t.reltablespace) AS tablespace, " "null AS indreloptions, " "'' AS indstatcols, " - "'' AS indstatvals " + "'' AS indstatvals, " + "' ' AS inddependoids, " + "' ' AS inddependversions " "FROM pg_catalog.pg_index i " "JOIN pg_catalog.pg_class t ON (t.oid = i.indexrelid) " "LEFT JOIN pg_catalog.pg_depend d " @@ -7254,6 +7329,8 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) i_indreloptions = PQfnumber(res, "indreloptions"); i_indstatcols = PQfnumber(res, "indstatcols"); i_indstatvals = PQfnumber(res, "indstatvals"); + i_inddependoids = PQfnumber(res, "inddependoids"); + i_inddependversions = PQfnumber(res, "inddependversions"); tbinfo->indexes = indxinfo = (IndxInfo *) pg_malloc(ntups * sizeof(IndxInfo)); @@ -7279,6 +7356,8 @@ getIndexes(Archive *fout, TableInfo tblinfo[], int numTables) indxinfo[j].indreloptions = pg_strdup(PQgetvalue(res, j, i_indreloptions)); indxinfo[j].indstatcols = pg_strdup(PQgetvalue(res, j, i_indstatcols)); indxinfo[j].indstatvals = pg_strdup(PQgetvalue(res, j, i_indstatvals)); + indxinfo[j].inddependoids = pg_strdup(PQgetvalue(res, j, i_inddependoids)); + indxinfo[j].inddependversions = pg_strdup(PQgetvalue(res, j, i_inddependversions)); indxinfo[j].indkeys = (Oid *) pg_malloc(indxinfo[j].indnattrs * sizeof(Oid)); parseOidArray(PQgetvalue(res, j, i_indkey), indxinfo[j].indkeys, indxinfo[j].indnattrs); @@ -16536,7 +16615,8 @@ dumpIndex(Archive *fout, IndxInfo *indxinfo) /* * If there's an associated constraint, don't dump the index per se, but - * do dump any comment for it. (This is safe because dependency ordering + * do dump any comment, or in binary upgrade mode dependency on a + * collation version for it. (This is safe because dependency ordering * will have ensured the constraint is emitted first.) Note that the * emitted comment has to be shown as depending on the constraint, not the * index, in such cases. @@ -16603,6 +16683,10 @@ dumpIndex(Archive *fout, IndxInfo *indxinfo) "pg_catalog.pg_class", "INDEX", qqindxname); + if (dopt->binary_upgrade) + appendIndexCollationVersion(q, indxinfo, fout->encoding, + dopt->unknown_coll_compat); + /* If the index defines identity, we need to record that. */ if (indxinfo->indisreplident) { @@ -16631,6 +16715,21 @@ dumpIndex(Archive *fout, IndxInfo *indxinfo) if (indstatvalsarray) free(indstatvalsarray); } + else if (dopt->binary_upgrade) + { + appendIndexCollationVersion(q, indxinfo, fout->encoding, + dopt->unknown_coll_compat); + + if (indxinfo->dobj.dump & DUMP_COMPONENT_DEFINITION) + ArchiveEntry(fout, indxinfo->dobj.catId, indxinfo->dobj.dumpId, + ARCHIVE_OPTS(.tag = indxinfo->dobj.name, + .namespace = tbinfo->dobj.namespace->dobj.name, + .tablespace = indxinfo->tablespace, + .owner = tbinfo->rolname, + .description = "INDEX", + .section = SECTION_POST_DATA, + .createStmt = q->data)); + } /* Dump Index Comments */ if (indxinfo->dobj.dump & DUMP_COMPONENT_COMMENT) @@ -18612,6 +18711,77 @@ nonemptyReloptions(const char *reloptions) return (reloptions != NULL && strlen(reloptions) > 2); } +/* + * Format inddependoids and inddependversions arrays and append it to the given + * buffer in the form of binary_upgrade_set_index_coll_version() calls. + */ +static void +appendIndexCollationVersion(PQExpBuffer buffer, IndxInfo *indxinfo, int enc, + int unknown_coll_compat) +{ + char *inddependoids = indxinfo->inddependoids; + char *inddependversions = indxinfo->inddependversions; + char **inddependoidsarray = NULL; + char **inddependversionsarray = NULL; + int ninddependoids; + int ninddependversions; + int i; + + /* + * for older versions that don't record the collation depndency, issue a + * statement to mark the collation version as unknown + */ + if (strcmp(inddependoids, " ") == 0) + { + /* + * do not issue UNKNOWN VERSION if caller specified that those are + * compatible + */ + if (unknown_coll_compat) + return; + + Assert(strcmp(inddependversions, " ") == 0); + + appendPQExpBufferStr(buffer, "\n-- For binary upgrade, restore dependent collation version.\n"); + appendPQExpBuffer(buffer, "SELECT " + "pg_catalog.binary_upgrade_set_index_coll_version(%d, NULL, '');", + indxinfo->dobj.catId.oid); + return; + } + + parsePGArray(inddependoids, &inddependoidsarray, &ninddependoids); + parsePGArray(inddependversions, &inddependversionsarray, &ninddependversions); + + Assert(ninddependoids == ninddependversions); + + for (i = 0; i < ninddependoids; i++) + { + /* + * If there was an unknown version dependency recorded for this + * collation and the caller asked to mark those as depending ono + * current version, don't emit a binary_upgrade_set_index_coll_version + * function call. + */ + if ((strcmp(inddependversionsarray[i], "''")) == 0 + && unknown_coll_compat) + { + continue; + } + + appendPQExpBufferStr(buffer, "\n-- For binary upgrade, restore dependent collation version.\n"); + appendPQExpBuffer(buffer, "SELECT " + "pg_catalog.binary_upgrade_set_index_coll_version(%d, %s, %s);", + indxinfo->dobj.catId.oid, + inddependoidsarray[i], + inddependversionsarray[i]); + } + + if (inddependoidsarray) + free(inddependoidsarray); + if (inddependversionsarray) + free(inddependversionsarray); +} + /* * Format a reloptions array and append it to the given buffer. * diff --git a/src/bin/pg_dump/pg_dump.h b/src/bin/pg_dump/pg_dump.h index 0c2fcfb3a9..2faab3b659 100644 --- a/src/bin/pg_dump/pg_dump.h +++ b/src/bin/pg_dump/pg_dump.h @@ -366,6 +366,9 @@ typedef struct _indxInfo int indnattrs; /* total number of index attributes */ Oid *indkeys; /* In spite of the name 'indkeys' this field * contains both key and nonkey attributes */ + char *inddependoids; /* oids of collation this index depends on */ + char *inddependversions; /* version of collation this index depends + * on */ bool indisclustered; bool indisreplident; Oid parentidx; /* if partitioned, parent index OID */ diff --git a/src/bin/pg_dump/t/002_pg_dump.pl b/src/bin/pg_dump/t/002_pg_dump.pl index e116235769..886d123e25 100644 --- a/src/bin/pg_dump/t/002_pg_dump.pl +++ b/src/bin/pg_dump/t/002_pg_dump.pl @@ -53,6 +53,24 @@ my %pgdump_runs = ( "$tempdir/binary_upgrade.dump", ], }, + binary_coll_compatible => { + dump_cmd => [ + 'pg_dump', + '--no-sync', + '--format=custom', + "--file=$tempdir/binary_coll_compatible.dump", + '-w', + '--schema-only', + '--binary-upgrade', + '--unknown-collations-binary-compatible', + '-d', 'postgres', # alternative way to specify database + ], + restore_cmd => [ + 'pg_restore', '-Fc', '--verbose', + "--file=$tempdir/binary_coll_compatible.sql", + "$tempdir/binary_coll_compatible.dump", + ], + }, clean => { dump_cmd => [ 'pg_dump', @@ -387,6 +405,7 @@ my %dump_test_schema_runs = ( # are flags used to exclude specific items (ACLs, blobs, etc). my %full_runs = ( binary_upgrade => 1, + binary_coll_compatible => 1, clean => 1, clean_if_exists => 1, createdb => 1, @@ -916,9 +935,10 @@ my %tests = ( test_schema_plus_blobs => 1, }, unlike => { - binary_upgrade => 1, - no_blobs => 1, - schema_only => 1, + binary_upgrade => 1, + binary_coll_compatible => 1, + no_blobs => 1, + schema_only => 1, }, }, @@ -1180,6 +1200,7 @@ my %tests = ( }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, exclude_test_table => 1, exclude_test_table_data => 1, @@ -1205,6 +1226,7 @@ my %tests = ( }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, schema_only => 1, }, @@ -1240,6 +1262,7 @@ my %tests = ( }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, schema_only => 1, }, @@ -1262,6 +1285,7 @@ my %tests = ( }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, schema_only => 1, }, @@ -1283,6 +1307,7 @@ my %tests = ( }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, schema_only => 1, }, @@ -1304,6 +1329,7 @@ my %tests = ( }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, schema_only => 1, }, @@ -1670,6 +1696,7 @@ my %tests = ( { %full_runs, %dump_test_schema_runs, section_pre_data => 1, }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, }, }, @@ -1684,7 +1711,7 @@ my %tests = ( \n.*^ \QALTER TYPE dump_test.planets ADD VALUE 'mars';\E \n/xms, - like => { binary_upgrade => 1, }, + like => { binary_upgrade => 1, binary_coll_compatible => 1, }, }, 'CREATE TYPE dump_test.textrange AS RANGE' => { @@ -2352,6 +2379,7 @@ my %tests = ( { %full_runs, %dump_test_schema_runs, section_pre_data => 1, }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, }, }, @@ -2545,6 +2573,7 @@ my %tests = ( }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, }, }, @@ -2613,6 +2642,7 @@ my %tests = ( /xm, like => { binary_upgrade => 1, + binary_coll_compatible => 1, clean => 1, clean_if_exists => 1, createdb => 1, @@ -2684,6 +2714,7 @@ my %tests = ( /xm, like => { binary_upgrade => 1, + binary_coll_compatible => 1, clean => 1, clean_if_exists => 1, createdb => 1, @@ -3151,6 +3182,7 @@ my %tests = ( { %full_runs, %dump_test_schema_runs, section_post_data => 1, }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, schema_only => 1, }, @@ -3166,6 +3198,7 @@ my %tests = ( { %full_runs, %dump_test_schema_runs, section_post_data => 1, }, unlike => { binary_upgrade => 1, + binary_coll_compatible => 1, exclude_dump_test_schema => 1, schema_only => 1, }, @@ -3298,16 +3331,53 @@ my %tests = ( %full_runs, %dump_test_schema_runs, section_pre_data => 1, }, unlike => { exclude_dump_test_schema => 1 }, + }, + + "binary_upgrade_set_index_coll_version(oid, oid, 'not_a_version')" => { + create_order => 101, + create_sql => ' + CREATE TABLE dump_test.regress_table_coll(id integer, val text); + CREATE INDEX regress_coll_idx1 ON dump_test.regress_table_coll(val COLLATE "fr-x-icu"); + UPDATE pg_depend SET refobjversion = \'not_a_version\' WHERE refobjversion IS NOT NULL AND objid::regclass::text = \'dump_test.regress_coll_idx1\';', + regexp => qr/^ + \QCREATE INDEX regress_coll_idx1 ON dump_test.regress_table_coll USING btree (val COLLATE "fr-x-icu");\E\n + \n + \Q-- For binary upgrade, restore dependent collation version.\E\n + \QSELECT pg_catalog.binary_upgrade_set_index_coll_version\E \(\d+,\ \d+,\ 'not_a_version'\);/xm, + like => { binary_upgrade => 1, binary_coll_compatible => 1, }, + icu => 1, + }, + "binary_upgrade_set_index_coll_version(?, ?, '')" => { + create_order => 102, + create_sql => ' + CREATE TABLE dump_test.regress_table_coll_no_ver(id integer, val text); + CREATE INDEX regress_coll_no_ver_idx1 ON dump_test.regress_table_coll_no_ver(val COLLATE "fr-x-icu"); + UPDATE pg_depend SET refobjversion = \'\' WHERE refobjversion IS NOT NULL AND objid::regclass::text = \'dump_test.regress_coll_no_ver_idx1\';', + regexp => qr/SELECT pg_catalog.binary_upgrade_set_index_coll_version\(\d+, \d+, ''\)/, + like => { binary_upgrade => 1}, + # should not appear in binary_coll_compatible case! + unlike => { binary_coll_compatible => 1}, + icu => 1, }); ######################################### # Create a PG instance to test actually dumping from -my $node = get_new_node('main'); -$node->init; -$node->start; +my $main_node = get_new_node('main'); +$main_node->init; +$main_node->start; + +my $port = $main_node->port; + +# And another instance to validate the binary dump +my $bin_node = get_new_node('binary'); +$bin_node->init; +$bin_node->start; -my $port = $node->port; +my $bin_port = $bin_node->port; + +# and add a $node variable pointing to main_node for now +my $node = $main_node; # We need to see if this system supports CREATE COLLATION or not # If it doesn't then we will skip all the COLLATION-related tests. @@ -3331,6 +3401,10 @@ $node->psql('postgres', 'create database regress_pg_dump_test;'); # command_fails_like is actually 2 tests) my $num_tests = 12; +# 4 more tests for restoring globals and binary_upgrade dump, dumping it again +# and regenerating the sql file +$num_tests+= 4; + foreach my $run (sort keys %pgdump_runs) { my $test_key = $run; @@ -3381,16 +3455,29 @@ foreach my $run (sort keys %pgdump_runs) next; } + # Skip any icu-related commands if there is no icu support + if ($ENV{with_icu} ne 'yes' && defined($tests{$test}->{icu})) + { + next; + } + # If there is a like entry, but no unlike entry, then we will test the like case if ($tests{$test}->{like}->{$test_key} && !defined($tests{$test}->{unlike}->{$test_key})) { $num_tests++; + + # binary_upgrade tests are also run after being restored and + # re-dumped. + $num_tests++ if ($test_key eq 'binary_upgrade'); } else { # We will test everything that isn't a 'like' $num_tests++; + # binary_upgrade tests are also run after being restored and + # re-dumped. + $num_tests++ if ($test_key eq 'binary_upgrade'); } } } @@ -3438,6 +3525,12 @@ foreach my $test ( next; } + # Skip any icu-related commands if there is no icu support + if ($ENV{with_icu} ne 'yes' && defined($tests{$test}->{icu})) + { + next; + } + # Add terminating semicolon $create_sql{$test_db} .= $tests{$test}->{create_sql} . ";"; } @@ -3491,79 +3584,116 @@ command_fails_like( ######################################### # Run all runs -foreach my $run (sort keys %pgdump_runs) +foreach my $pass (1, 2) { - my $test_key = $run; - my $run_db = 'postgres'; - - $node->command_ok(\@{ $pgdump_runs{$run}->{dump_cmd} }, - "$run: pg_dump runs"); - - if ($pgdump_runs{$run}->{restore_cmd}) + foreach my $run (sort keys %pgdump_runs) { - $node->command_ok(\@{ $pgdump_runs{$run}->{restore_cmd} }, - "$run: pg_restore runs"); - } - - if ($pgdump_runs{$run}->{test_key}) - { - $test_key = $pgdump_runs{$run}->{test_key}; - } - - my $output_file = slurp_file("$tempdir/${run}.sql"); + my $test_key = $run; + my $run_db = 'postgres'; - ######################################### - # Run all tests where this run is included - # as either a 'like' or 'unlike' test. + # we only test binary upgrade on the 2nd pass + next if ($pass == 2 and $test_key ne 'binary_upgrade'); - foreach my $test (sort keys %tests) - { - my $test_db = 'postgres'; + $node->command_ok(\@{ $pgdump_runs{$run}->{dump_cmd} }, + "$run: pg_dump runs"); - if (defined($pgdump_runs{$run}->{database})) + if ($pgdump_runs{$run}->{restore_cmd}) { - $run_db = $pgdump_runs{$run}->{database}; + $node->command_ok(\@{ $pgdump_runs{$run}->{restore_cmd} }, + "$run: pg_restore runs"); } - if (defined($tests{$test}->{database})) + if ($pgdump_runs{$run}->{test_key}) { - $test_db = $tests{$test}->{database}; + $test_key = $pgdump_runs{$run}->{test_key}; } - # Skip any collation-related commands if there is no collation support - if (!$collation_support && defined($tests{$test}->{collation})) - { - next; - } + my $output_file = slurp_file("$tempdir/${run}.sql"); - if ($run_db ne $test_db) - { - next; - } + ######################################### + # Run all tests where this run is included + # as either a 'like' or 'unlike' test. - # Run the test listed as a like, unless it is specifically noted - # as an unlike (generally due to an explicit exclusion or similar). - if ($tests{$test}->{like}->{$test_key} - && !defined($tests{$test}->{unlike}->{$test_key})) + foreach my $test (sort keys %tests) { - if (!ok($output_file =~ $tests{$test}->{regexp}, - "$run: should dump $test")) + my $test_db = 'postgres'; + + if (defined($pgdump_runs{$run}->{database})) { - diag("Review $run results in $tempdir"); + $run_db = $pgdump_runs{$run}->{database}; } - } - else - { - if (!ok($output_file !~ $tests{$test}->{regexp}, - "$run: should not dump $test")) + + if (defined($tests{$test}->{database})) + { + $test_db = $tests{$test}->{database}; + } + + # Skip any collation-related commands if there is no collation support + if (!$collation_support && defined($tests{$test}->{collation})) + { + next; + } + + # Skip any icu-related commands if there is no icu support + if ($ENV{with_icu} ne 'yes' && defined($tests{$test}->{icu})) + { + next; + } + + if ($run_db ne $test_db) + { + next; + } + + # Run the test listed as a like, unless it is specifically noted + # as an unlike (generally due to an explicit exclusion or similar). + if ($tests{$test}->{like}->{$test_key} + && !defined($tests{$test}->{unlike}->{$test_key})) { - diag("Review $run results in $tempdir"); + if (!ok($output_file =~ $tests{$test}->{regexp}, + "$run: should dump $test")) + { + diag("Review $run results in $tempdir"); + } + } + else + { + if (!ok($output_file !~ $tests{$test}->{regexp}, + "$run: should not dump $test")) + { + diag("Review $run results in $tempdir"); + } } } } + + # After all dump have been generated, restore the binary_upgrade dump with + # the required global objects on a suitable node, and continue with the 2nd + # pass. + if ($pass == 1) + { + # Stop the original database instance as we don't need it anymore. + $node->stop('fast'); + + $bin_node->command_ok(\@{['psql', + "-d", "postgres", "-f", "$tempdir/pg_dumpall_globals.sql"]}, + "Restore globals"); + + $bin_node->stop('fast'); + $bin_node->start(binary_start => 1); + $bin_node->command_ok(\@{['pg_restore', '-p', $bin_port, + '-d', 'postgres', + "$tempdir/binary_upgrade.dump"]}, + "Restore the binary_upgrade dump"); + $bin_node->stop('fast'); + $bin_node->start; + + # And change $node to point to the freshly restored node. + $node = $bin_node; + } } ######################################### # Stop the database instance, which will be removed at the end of the tests. -$node->stop('fast'); +$bin_node->stop('fast'); diff --git a/src/bin/pg_upgrade/dump.c b/src/bin/pg_upgrade/dump.c index 4d730adfe2..672ecda169 100644 --- a/src/bin/pg_upgrade/dump.c +++ b/src/bin/pg_upgrade/dump.c @@ -52,9 +52,11 @@ generate_old_dump(void) parallel_exec_prog(log_file_name, NULL, "\"%s/pg_dump\" %s --schema-only --quote-all-identifiers " - "--binary-upgrade --format=custom %s --file=\"%s\" %s", + "--binary-upgrade --format=custom %s %s --file=\"%s\" %s", new_cluster.bindir, cluster_conn_opts(&old_cluster), log_opts.verbose ? "--verbose" : "", + user_opts.coll_compat ? + "--unknown-collations-binary-compatible" : "", sql_file_name, escaped_connstr.data); termPQExpBuffer(&escaped_connstr); diff --git a/src/bin/pg_upgrade/option.c b/src/bin/pg_upgrade/option.c index aca1ee8b48..c7e291f7e7 100644 --- a/src/bin/pg_upgrade/option.c +++ b/src/bin/pg_upgrade/option.c @@ -56,6 +56,7 @@ parseCommandLine(int argc, char *argv[]) {"socketdir", required_argument, NULL, 's'}, {"verbose", no_argument, NULL, 'v'}, {"clone", no_argument, NULL, 1}, + {"collation-binary-compatible", no_argument, NULL, 2}, {NULL, 0, NULL, 0} }; @@ -203,6 +204,10 @@ parseCommandLine(int argc, char *argv[]) user_opts.transfer_mode = TRANSFER_MODE_CLONE; break; + case 2: + user_opts.coll_compat = true; + break; + default: fprintf(stderr, _("Try \"%s --help\" for more information.\n"), os_info.progname); @@ -307,6 +312,8 @@ usage(void) printf(_(" -v, --verbose enable verbose internal logging\n")); printf(_(" -V, --version display version information, then exit\n")); printf(_(" --clone clone instead of copying files to new cluster\n")); + printf(_(" --collation-binary-compatible mark collations as depending on current collation\n" + " versions rather than unknown if they're unknown\n")); printf(_(" -?, --help show this help, then exit\n")); printf(_("\n" "Before running pg_upgrade you must:\n" diff --git a/src/bin/pg_upgrade/pg_upgrade.h b/src/bin/pg_upgrade/pg_upgrade.h index 8b90cefbe0..68e637ce8a 100644 --- a/src/bin/pg_upgrade/pg_upgrade.h +++ b/src/bin/pg_upgrade/pg_upgrade.h @@ -292,6 +292,8 @@ typedef struct transferMode transfer_mode; /* copy files or link them? */ int jobs; /* number of processes/threads to use */ char *socketdir; /* directory to use for Unix sockets */ + bool coll_compat; /* should we skip marking index collations as + * unknown version */ } UserOpts; typedef struct diff --git a/src/include/catalog/dependency.h b/src/include/catalog/dependency.h index 3baa5e498a..4949044041 100644 --- a/src/include/catalog/dependency.h +++ b/src/include/catalog/dependency.h @@ -130,6 +130,13 @@ typedef enum ObjectClass #define LAST_OCLASS OCLASS_TRANSFORM +/* Struct describing one forced collation version dependency */ +typedef struct NewCollationVersionDependency +{ + char *version; /* forced collation version */ + Oid oid; /* target collation oid */ +} NewCollationVersionDependency; + /* flag bits for performDeletion/performMultipleDeletions: */ #define PERFORM_DELETION_INTERNAL 0x0001 /* internal action */ #define PERFORM_DELETION_CONCURRENTLY 0x0002 /* concurrent drop */ @@ -160,7 +167,8 @@ extern void recordDependencyOnSingleRelExpr(const ObjectAddress *depender, Node *expr, Oid relId, DependencyType behavior, DependencyType self_behavior, - bool reverse_self); + bool reverse_self, + bool track_version); extern ObjectClass getObjectClass(const ObjectAddress *object); @@ -180,17 +188,29 @@ extern void sort_object_addresses(ObjectAddresses *addrs); extern void free_object_addresses(ObjectAddresses *addrs); +typedef char *(*VisitDependentObjectsFun) (const ObjectAddress *otherObject, + const char *version, + void *userdata); + +extern void visitDependentObjects(const ObjectAddress *object, + VisitDependentObjectsFun callback, + void *userdata); + /* in pg_depend.c */ extern void recordDependencyOn(const ObjectAddress *depender, const ObjectAddress *referenced, DependencyType behavior); +extern void recordDependencyOnCollations(ObjectAddress *myself, + List *collations, + bool record_version); + extern void recordMultipleDependencies(const ObjectAddress *depender, const ObjectAddress *referenced, int nreferenced, - const char *version, - DependencyType behavior); + DependencyType behavior, + bool track_version); extern void recordDependencyOnCurrentExtension(const ObjectAddress *object, bool isReplace); @@ -209,11 +229,7 @@ extern long changeDependencyFor(Oid classId, Oid objectId, Oid refClassId, Oid oldRefObjectId, Oid newRefObjectId); -extern long changeDependenciesOf(Oid classId, Oid oldObjectId, - Oid newObjectId); - -extern long changeDependenciesOn(Oid refClassId, Oid oldRefObjectId, - Oid newRefObjectId); +extern void swapDependencies(Oid classId, Oid firstObjectId, Oid secondObjectId); extern Oid getExtensionOfObject(Oid classId, Oid objectId); extern List *getAutoExtensionsOfObject(Oid classId, Oid objectId); diff --git a/src/include/catalog/index.h b/src/include/catalog/index.h index f58e8675f3..9b4de26514 100644 --- a/src/include/catalog/index.h +++ b/src/include/catalog/index.h @@ -121,6 +121,11 @@ extern void FormIndexDatum(IndexInfo *indexInfo, Datum *values, bool *isnull); +extern void index_check_collation_versions(Oid relid); + +extern void index_force_collation_versions(Oid indexid, Oid coll, + char *version); + extern void index_build(Relation heapRelation, Relation indexRelation, IndexInfo *indexInfo, @@ -131,6 +136,8 @@ extern void validate_index(Oid heapId, Oid indexId, Snapshot snapshot); extern void index_set_state_flags(Oid indexId, IndexStateFlagsAction action); +extern void index_update_collation_versions(Oid relid); + extern Oid IndexGetRelation(Oid indexId, bool missing_ok); extern void reindex_index(Oid indexId, bool skip_constraint_checks, diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat index 38295aca48..3a9bb0d783 100644 --- a/src/include/catalog/pg_proc.dat +++ b/src/include/catalog/pg_proc.dat @@ -10343,6 +10343,10 @@ proname => 'binary_upgrade_set_missing_value', provolatile => 'v', proparallel => 'u', prorettype => 'void', proargtypes => 'oid text text', prosrc => 'binary_upgrade_set_missing_value' }, +{ oid => '8178', descr => 'for use by pg_upgrade', + proname => 'binary_upgrade_set_index_coll_version', provolatile => 'v', + proparallel => 'u', prorettype => 'void', proargtypes => 'oid oid text', + prosrc => 'binary_upgrade_set_index_coll_version' }, # conversion functions { oid => '4302', diff --git a/src/include/catalog/pg_type.h b/src/include/catalog/pg_type.h index 7b37562648..2d511c5cba 100644 --- a/src/include/catalog/pg_type.h +++ b/src/include/catalog/pg_type.h @@ -361,6 +361,8 @@ extern void GenerateTypeDependencies(HeapTuple typeTuple, bool isDependentType, bool rebuild); +extern List *GetTypeCollations(Oid typeObjectid, bool non_deterministic_only); + extern void RenameTypeInternal(Oid typeOid, const char *newTypeName, Oid typeNamespace); diff --git a/src/include/utils/pg_locale.h b/src/include/utils/pg_locale.h index 9cb7d91ddf..96da132c03 100644 --- a/src/include/utils/pg_locale.h +++ b/src/include/utils/pg_locale.h @@ -103,7 +103,7 @@ typedef struct pg_locale_struct *pg_locale_t; extern pg_locale_t pg_newlocale_from_collation(Oid collid); -extern char *get_collation_actual_version(char collprovider, const char *collcollate); +extern char *get_collation_version_for_oid(Oid collid); #ifdef USE_ICU extern int32_t icu_to_uchar(UChar **buff_uchar, const char *buff, size_t nbytes); diff --git a/src/include/utils/rel.h b/src/include/utils/rel.h index 0b5957ba02..f79667d651 100644 --- a/src/include/utils/rel.h +++ b/src/include/utils/rel.h @@ -63,6 +63,7 @@ typedef struct RelationData bool rd_indexvalid; /* is rd_indexlist valid? (also rd_pkindex and * rd_replidindex) */ bool rd_statvalid; /* is rd_statlist valid? */ + bool rd_version_checked; /* has version check being done yet? */ /*---------- * rd_createSubid is the ID of the highest subtransaction the rel has diff --git a/src/test/Makefile b/src/test/Makefile index efb206aa75..4ef0d11702 100644 --- a/src/test/Makefile +++ b/src/test/Makefile @@ -12,7 +12,8 @@ subdir = src/test top_builddir = ../.. include $(top_builddir)/src/Makefile.global -SUBDIRS = perl regress isolation modules authentication recovery subscription +SUBDIRS = perl regress isolation modules authentication recovery subscription \ + locale # Test suites that are not safe by default but can be run if selected # by the user via the whitespace-separated list in variable @@ -37,7 +38,7 @@ endif # clean" etc to recurse into them. (We must filter out those that we # have conditionally included into SUBDIRS above, else there will be # make confusion.) -ALWAYS_SUBDIRS = $(filter-out $(SUBDIRS),examples kerberos ldap locale thread ssl) +ALWAYS_SUBDIRS = $(filter-out $(SUBDIRS),examples kerberos ldap thread ssl) # We want to recurse to all subdirs for all standard targets, except that # installcheck and install should not recurse into the subdirectory "modules". diff --git a/src/test/locale/.gitignore b/src/test/locale/.gitignore index 620d3df425..64e1bf2a80 100644 --- a/src/test/locale/.gitignore +++ b/src/test/locale/.gitignore @@ -1 +1,2 @@ /test-ctype +/tmp_check/ diff --git a/src/test/locale/Makefile b/src/test/locale/Makefile index 22a45b65f2..73495cf16b 100644 --- a/src/test/locale/Makefile +++ b/src/test/locale/Makefile @@ -4,6 +4,7 @@ subdir = src/test/locale top_builddir = ../../.. include $(top_builddir)/src/Makefile.global +export with_icu PROGS = test-ctype DIRS = de_DE.ISO8859-1 gr_GR.ISO8859-7 koi8-r koi8-to-win1251 @@ -19,3 +20,9 @@ clean distclean maintainer-clean: # These behave like installcheck targets. check-%: all @$(MAKE) -C `echo $@ | sed 's/^check-//'` test + +check: + $(prove_check) + +installcheck: + $(prove_installcheck) diff --git a/src/test/locale/t/001_index.pl b/src/test/locale/t/001_index.pl new file mode 100644 index 0000000000..468fbb63b6 --- /dev/null +++ b/src/test/locale/t/001_index.pl @@ -0,0 +1,76 @@ +use strict; +use warnings; + +use Config; +use PostgresNode; +use TestLib; +use Test::More; + +if ($ENV{with_icu} eq 'yes') +{ + plan tests => 12; +} +else +{ + plan skip_all => 'ICU not supported by this build'; +} + +#### Set up the server + +note "setting up data directory"; +my $node = get_new_node('main'); +$node->init; + +$ENV{PGHOST} = $node->host; +$ENV{PGPORT} = $node->port; +$node->start; + +sub test_index +{ + my ($err_like, $err_comm) = @_; + + my ($ret, $out, $err) = $node->psql('postgres', + 'SET enable_seqscan = 0;' + . "EXPLAIN SELECT val FROM icu1 WHERE val = '0'"); + + is($ret, 0, 'EXPLAIN should succeed.'); + like($out, qr/icu1_fr/, 'Index icu1_fr should be used.'); + like($err, $err_like, $err_comm); +} + +$node->safe_psql('postgres', + 'CREATE TABLE icu1(val text);' + . 'INSERT INTO icu1 SELECT i::text FROM generate_series(1, 10000) i;' + . 'CREATE INDEX icu1_fr ON icu1 (val COLLATE "fr-x-icu");'); +$node->safe_psql('postgres', 'VACUUM ANALYZE icu1;'); + +test_index(qr/^$/, 'No warning should be raised'); + +# Simulate different collation version +$node->safe_psql('postgres', + "UPDATE pg_depend SET refobjversion = 'not_a_version'" + . " WHERE refobjversion IS NOT NULL" + . " AND objid::regclass::text = 'icu1_fr';"); + +test_index(qr/index "icu1_fr" depends on collation "fr-x-icu" version "not_a_version", but the current version is/, + 'Different collation version warning should be raised.'); + +# Simulate unknown collation version +$node->safe_psql('postgres', + "UPDATE pg_depend SET refobjversion = ''" + . " WHERE refobjversion IS NOT NULL" + . " AND objid::regclass::text = 'icu1_fr';"); + +test_index(qr/index "icu1_fr" depends on collation "fr-x-icu" with an unknown version, and the current version is/, + 'Unknown collation version warning should be raised.'); + +# Simulate previously unhandled collation versioning +$node->safe_psql('postgres', + "UPDATE pg_depend SET refobjversion = NULL" + . " WHERE refobjversion IS NOT NULL" + . " AND objid::regclass::text = 'icu1_fr';"); + +test_index(qr/index "icu1_fr" depends on collation "fr-x-icu" with an unknown version, and the current version is/, + 'Unknown collation version warning should be raised.'); + +$node->stop; diff --git a/src/test/perl/PostgresNode.pm b/src/test/perl/PostgresNode.pm index 1407359aef..f39b9433a8 100644 --- a/src/test/perl/PostgresNode.pm +++ b/src/test/perl/PostgresNode.pm @@ -765,10 +765,14 @@ sub start local %ENV = %ENV; delete $ENV{PGAPPNAME}; + my $options = "--cluster-name=$name"; + + $options .= ' -b' if ($params{binary_start}); + # Note: We set the cluster_name here, not in postgresql.conf (in # sub init) so that it does not get copied to standbys. $ret = TestLib::system_log('pg_ctl', '-D', $self->data_dir, '-l', - $self->logfile, '-o', "--cluster-name=$name", 'start'); + $self->logfile, '-o', $options, 'start'); } if ($ret != 0) diff --git a/src/test/regress/expected/collate.icu.utf8.out b/src/test/regress/expected/collate.icu.utf8.out index 60d9263a2f..db386c1b09 100644 --- a/src/test/regress/expected/collate.icu.utf8.out +++ b/src/test/regress/expected/collate.icu.utf8.out @@ -1897,6 +1897,163 @@ SELECT (SELECT count(*) FROM test33_0) <> (SELECT count(*) FROM test33_1); t (1 row) +-- collation versioning support +CREATE TYPE t_en_fr AS (fr text COLLATE "fr-x-icu", en text COLLATE "en-x-icu"); +CREATE DOMAIN d_en_fr AS t_en_fr; +CREATE DOMAIN d_es AS text COLLATE "es-x-icu"; +CREATE TYPE t_en_fr_ga AS (en_fr t_en_fr, ga text COLLATE "ga-x-icu"); +CREATE DOMAIN d_en_fr_ga AS t_en_fr_ga; +CREATE TYPE t_custom AS (meh text, meh2 text); +CREATE DOMAIN d_custom AS t_custom; +CREATE COLLATION custom ( + LOCALE = 'fr-x-icu', PROVIDER = 'icu' +); +CREATE TYPE myrange AS range (subtype = text); +CREATE TYPE myrange_en_fr_ga AS range(subtype = t_en_fr_ga); +CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy'); +CREATE TABLE collate_test ( + id integer, + t_en_fr t_en_fr, + d_en_fr d_en_fr, + d_es d_es, + t_en_fr_ga t_en_fr_ga, + d_en_fr_ga d_en_fr_ga, + d_en_fr_ga_arr d_en_fr_ga[], + myrange myrange, + myrange_en_fr_ga myrange_en_fr_ga, + mood mood +); +CREATE INDEX icuidx01_t_en_fr__d_es ON collate_test (t_en_fr, d_es); +CREATE INDEX icuidx02_d_en_fr ON collate_test (d_en_fr); +CREATE INDEX icuidx03_t_en_fr_ga ON collate_test (t_en_fr_ga); +CREATE INDEX icuidx04_d_en_fr_ga ON collate_test (d_en_fr_ga); +CREATE INDEX icuidx05_d_en_fr_ga_arr ON collate_test (d_en_fr_ga_arr); +CREATE INDEX icuidx06_d_en_fr_ga ON collate_test(id) WHERE (d_en_fr_ga).en_fr.fr = 'foo'; +CREATE INDEX icuidx07_d_en_fr_ga ON collate_test(id) WHERE (d_en_fr_ga).ga = 'foo'; +CREATE INDEX icuidx08_d_en_fr_ga ON collate_test(id) WHERE (t_en_fr_ga) = ('foo', 'bar', 'baz'); +CREATE INDEX icuidx09_d_en_fr_ga ON collate_test(id) WHERE (d_en_fr_ga) = ('foo', 'bar', 'baz'); +CREATE INDEX icuidx10_d_en_fr_ga_es ON collate_test(id) WHERE (d_en_fr_ga) = ('foo', 'bar', 'baz' COLLATE "es-x-icu"); +CREATE INDEX icuidx11_d_es ON collate_test(id) WHERE (d_es) = ('foo'); +CREATE INDEX icuidx12_custom ON collate_test(id) WHERE ('foo', 'bar')::d_custom = ('foo', 'bar' collate custom)::d_custom; +CREATE INDEX icuidx13_custom ON collate_test(id) WHERE ('foo' collate custom, 'bar')::d_custom = ('foo', 'bar')::d_custom; +CREATE INDEX icuidx14_myrange ON collate_test(myrange); +CREATE INDEX icuidx15_myrange_en_fr_ga ON collate_test USING gist (myrange_en_fr_ga); +CREATE INDEX icuidx16_mood ON collate_test(id) WHERE mood > 'ok' collate "fr-x-icu"; +CREATE TABLE collate_part(id integer, val text COLLATE "en-x-icu") PARTITION BY range(id); +CREATE TABLE collate_part_0 PARTITION OF collate_part FOR VALUES FROM (0) TO (1); +CREATE TABLE collate_part_1 PARTITION OF collate_part FOR VALUES FROM (1) TO (1000000); +CREATE INDEX icuidx17_part ON collate_part_1 (val); +-- for key columns, hash indexes should record dependency on the collation but +-- not the version +CREATE INDEX icuidx18_hash_d_es ON collate_test USING hash (d_es); +CREATE INDEX icuidx19_hash_id_d_es_eq ON collate_test USING hash (id) WHERE (d_es) = 'foo'; +CREATE INDEX icuidx20_hash_id_d_es_lt ON collate_test USING hash (id) WHERE (d_es) < 'foo'; +SELECT objid::regclass, refobjid::regcollation, +CASE +WHEN refobjversion IS NULL THEN 'version not tracked' +ELSE CASE + WHEN refobjversion = pg_collation_actual_version(refobjid) THEN 'up to date' + ELSE 'out of date' + END +END AS version +FROM pg_depend d +LEFT JOIN pg_class c ON c.oid = d.objid +WHERE refclassid = 'pg_collation'::regclass +AND coalesce(relkind, 'i') = 'i' +AND relname LIKE 'icuidx%' +ORDER BY 1, 2; + objid | refobjid | version +---------------------------+------------+--------------------- + icuidx01_t_en_fr__d_es | "en-x-icu" | up to date + icuidx01_t_en_fr__d_es | "es-x-icu" | up to date + icuidx01_t_en_fr__d_es | "fr-x-icu" | up to date + icuidx02_d_en_fr | "en-x-icu" | up to date + icuidx02_d_en_fr | "fr-x-icu" | up to date + icuidx03_t_en_fr_ga | "en-x-icu" | up to date + icuidx03_t_en_fr_ga | "fr-x-icu" | up to date + icuidx03_t_en_fr_ga | "ga-x-icu" | up to date + icuidx04_d_en_fr_ga | "en-x-icu" | up to date + icuidx04_d_en_fr_ga | "fr-x-icu" | up to date + icuidx04_d_en_fr_ga | "ga-x-icu" | up to date + icuidx05_d_en_fr_ga_arr | "en-x-icu" | up to date + icuidx05_d_en_fr_ga_arr | "fr-x-icu" | up to date + icuidx05_d_en_fr_ga_arr | "ga-x-icu" | up to date + icuidx06_d_en_fr_ga | "default" | up to date + icuidx06_d_en_fr_ga | "en-x-icu" | up to date + icuidx06_d_en_fr_ga | "fr-x-icu" | up to date + icuidx06_d_en_fr_ga | "ga-x-icu" | up to date + icuidx07_d_en_fr_ga | "default" | up to date + icuidx07_d_en_fr_ga | "en-x-icu" | up to date + icuidx07_d_en_fr_ga | "fr-x-icu" | up to date + icuidx07_d_en_fr_ga | "ga-x-icu" | up to date + icuidx08_d_en_fr_ga | "en-x-icu" | up to date + icuidx08_d_en_fr_ga | "fr-x-icu" | up to date + icuidx08_d_en_fr_ga | "ga-x-icu" | up to date + icuidx09_d_en_fr_ga | "en-x-icu" | up to date + icuidx09_d_en_fr_ga | "fr-x-icu" | up to date + icuidx09_d_en_fr_ga | "ga-x-icu" | up to date + icuidx10_d_en_fr_ga_es | "en-x-icu" | up to date + icuidx10_d_en_fr_ga_es | "es-x-icu" | up to date + icuidx10_d_en_fr_ga_es | "fr-x-icu" | up to date + icuidx10_d_en_fr_ga_es | "ga-x-icu" | up to date + icuidx11_d_es | "default" | up to date + icuidx11_d_es | "es-x-icu" | up to date + icuidx12_custom | "default" | up to date + icuidx12_custom | custom | up to date + icuidx13_custom | "default" | up to date + icuidx13_custom | custom | up to date + icuidx14_myrange | "default" | up to date + icuidx15_myrange_en_fr_ga | "en-x-icu" | up to date + icuidx15_myrange_en_fr_ga | "fr-x-icu" | up to date + icuidx15_myrange_en_fr_ga | "ga-x-icu" | up to date + icuidx16_mood | "fr-x-icu" | up to date + icuidx17_part | "en-x-icu" | up to date + icuidx18_hash_d_es | "es-x-icu" | version not tracked + icuidx19_hash_id_d_es_eq | "default" | up to date + icuidx19_hash_id_d_es_eq | "es-x-icu" | up to date + icuidx20_hash_id_d_es_lt | "default" | up to date + icuidx20_hash_id_d_es_lt | "es-x-icu" | up to date +(49 rows) + +-- Validate that REINDEX will update the stored version. +UPDATE pg_depend SET refobjversion = 'not a version' +WHERE refclassid = 'pg_collation'::regclass +AND objid::regclass::text LIKE 'icuidx%' +AND refobjversion IS NOT NULL; +REINDEX TABLE collate_test; +REINDEX TABLE collate_part_0; +REINDEX TABLE collate_part_1; +SELECT objid::regclass FROM pg_depend WHERE refobjversion = 'not a version'; + objid +------- +(0 rows) + +-- Validate that REINDEX CONCURRENTLY will update the stored version. +UPDATE pg_depend SET refobjversion = 'not a version' +WHERE refclassid = 'pg_collation'::regclass +AND objid::regclass::text LIKE 'icuidx%' +AND refobjversion IS NOT NULL; +REINDEX TABLE CONCURRENTLY collate_test; +REINDEX TABLE CONCURRENTLY collate_part_0; +REINDEX INDEX CONCURRENTLY icuidx17_part; +SELECT objid::regclass FROM pg_depend WHERE refobjversion = 'not a version'; + objid +------- +(0 rows) + +-- Validate that VACUUM FULL will update the stored version. +UPDATE pg_depend SET refobjversion = 'not a version' +WHERE refclassid = 'pg_collation'::regclass +AND objid::regclass::text LIKE 'icuidx%' +AND refobjversion IS NOT NULL; +VACUUM FULL collate_test; +VACUUM FULL collate_part_0; +VACUUM FULL collate_part_1; +SELECT objid::regclass FROM pg_depend WHERE refobjversion = 'not a version'; + objid +------- +(0 rows) + -- cleanup RESET search_path; SET client_min_messages TO warning; diff --git a/src/test/regress/expected/create_index.out b/src/test/regress/expected/create_index.out index e3e6634d7e..ce3d45cf2c 100644 --- a/src/test/regress/expected/create_index.out +++ b/src/test/regress/expected/create_index.out @@ -2065,15 +2065,17 @@ WHERE classid = 'pg_class'::regclass AND obj | objref | deptype ------------------------------------------+------------------------------------------------------------+--------- index concur_reindex_ind1 | constraint concur_reindex_ind1 on table concur_reindex_tab | i + index concur_reindex_ind2 | collation "default" | n index concur_reindex_ind2 | column c2 of table concur_reindex_tab | a index concur_reindex_ind3 | column c1 of table concur_reindex_tab | a index concur_reindex_ind3 | table concur_reindex_tab | a + index concur_reindex_ind4 | collation "default" | n index concur_reindex_ind4 | column c1 of table concur_reindex_tab | a index concur_reindex_ind4 | column c1 of table concur_reindex_tab | a index concur_reindex_ind4 | column c2 of table concur_reindex_tab | a materialized view concur_reindex_matview | schema public | n table concur_reindex_tab | schema public | n -(9 rows) +(11 rows) REINDEX INDEX CONCURRENTLY concur_reindex_ind1; REINDEX TABLE CONCURRENTLY concur_reindex_tab; @@ -2093,15 +2095,17 @@ WHERE classid = 'pg_class'::regclass AND obj | objref | deptype ------------------------------------------+------------------------------------------------------------+--------- index concur_reindex_ind1 | constraint concur_reindex_ind1 on table concur_reindex_tab | i + index concur_reindex_ind2 | collation "default" | n index concur_reindex_ind2 | column c2 of table concur_reindex_tab | a index concur_reindex_ind3 | column c1 of table concur_reindex_tab | a index concur_reindex_ind3 | table concur_reindex_tab | a + index concur_reindex_ind4 | collation "default" | n index concur_reindex_ind4 | column c1 of table concur_reindex_tab | a index concur_reindex_ind4 | column c1 of table concur_reindex_tab | a index concur_reindex_ind4 | column c2 of table concur_reindex_tab | a materialized view concur_reindex_matview | schema public | n table concur_reindex_tab | schema public | n -(9 rows) +(11 rows) -- Check that comments are preserved CREATE TABLE testcomment (i int); diff --git a/src/test/regress/sql/collate.icu.utf8.sql b/src/test/regress/sql/collate.icu.utf8.sql index 35acf91fbf..e93530af55 100644 --- a/src/test/regress/sql/collate.icu.utf8.sql +++ b/src/test/regress/sql/collate.icu.utf8.sql @@ -716,6 +716,112 @@ INSERT INTO test33 VALUES (2, 'DEF'); -- they end up in the same partition (but it's platform-dependent which one) SELECT (SELECT count(*) FROM test33_0) <> (SELECT count(*) FROM test33_1); +-- collation versioning support +CREATE TYPE t_en_fr AS (fr text COLLATE "fr-x-icu", en text COLLATE "en-x-icu"); +CREATE DOMAIN d_en_fr AS t_en_fr; +CREATE DOMAIN d_es AS text COLLATE "es-x-icu"; +CREATE TYPE t_en_fr_ga AS (en_fr t_en_fr, ga text COLLATE "ga-x-icu"); +CREATE DOMAIN d_en_fr_ga AS t_en_fr_ga; +CREATE TYPE t_custom AS (meh text, meh2 text); +CREATE DOMAIN d_custom AS t_custom; + +CREATE COLLATION custom ( + LOCALE = 'fr-x-icu', PROVIDER = 'icu' +); + +CREATE TYPE myrange AS range (subtype = text); +CREATE TYPE myrange_en_fr_ga AS range(subtype = t_en_fr_ga); + +CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy'); + +CREATE TABLE collate_test ( + id integer, + t_en_fr t_en_fr, + d_en_fr d_en_fr, + d_es d_es, + t_en_fr_ga t_en_fr_ga, + d_en_fr_ga d_en_fr_ga, + d_en_fr_ga_arr d_en_fr_ga[], + myrange myrange, + myrange_en_fr_ga myrange_en_fr_ga, + mood mood +); + +CREATE INDEX icuidx01_t_en_fr__d_es ON collate_test (t_en_fr, d_es); +CREATE INDEX icuidx02_d_en_fr ON collate_test (d_en_fr); +CREATE INDEX icuidx03_t_en_fr_ga ON collate_test (t_en_fr_ga); +CREATE INDEX icuidx04_d_en_fr_ga ON collate_test (d_en_fr_ga); +CREATE INDEX icuidx05_d_en_fr_ga_arr ON collate_test (d_en_fr_ga_arr); +CREATE INDEX icuidx06_d_en_fr_ga ON collate_test(id) WHERE (d_en_fr_ga).en_fr.fr = 'foo'; +CREATE INDEX icuidx07_d_en_fr_ga ON collate_test(id) WHERE (d_en_fr_ga).ga = 'foo'; +CREATE INDEX icuidx08_d_en_fr_ga ON collate_test(id) WHERE (t_en_fr_ga) = ('foo', 'bar', 'baz'); +CREATE INDEX icuidx09_d_en_fr_ga ON collate_test(id) WHERE (d_en_fr_ga) = ('foo', 'bar', 'baz'); +CREATE INDEX icuidx10_d_en_fr_ga_es ON collate_test(id) WHERE (d_en_fr_ga) = ('foo', 'bar', 'baz' COLLATE "es-x-icu"); +CREATE INDEX icuidx11_d_es ON collate_test(id) WHERE (d_es) = ('foo'); +CREATE INDEX icuidx12_custom ON collate_test(id) WHERE ('foo', 'bar')::d_custom = ('foo', 'bar' collate custom)::d_custom; +CREATE INDEX icuidx13_custom ON collate_test(id) WHERE ('foo' collate custom, 'bar')::d_custom = ('foo', 'bar')::d_custom; +CREATE INDEX icuidx14_myrange ON collate_test(myrange); +CREATE INDEX icuidx15_myrange_en_fr_ga ON collate_test USING gist (myrange_en_fr_ga); +CREATE INDEX icuidx16_mood ON collate_test(id) WHERE mood > 'ok' collate "fr-x-icu"; + +CREATE TABLE collate_part(id integer, val text COLLATE "en-x-icu") PARTITION BY range(id); +CREATE TABLE collate_part_0 PARTITION OF collate_part FOR VALUES FROM (0) TO (1); +CREATE TABLE collate_part_1 PARTITION OF collate_part FOR VALUES FROM (1) TO (1000000); +CREATE INDEX icuidx17_part ON collate_part_1 (val); +-- for key columns, hash indexes should record dependency on the collation but +-- not the version +CREATE INDEX icuidx18_hash_d_es ON collate_test USING hash (d_es); +CREATE INDEX icuidx19_hash_id_d_es_eq ON collate_test USING hash (id) WHERE (d_es) = 'foo'; +CREATE INDEX icuidx20_hash_id_d_es_lt ON collate_test USING hash (id) WHERE (d_es) < 'foo'; + +SELECT objid::regclass, refobjid::regcollation, +CASE +WHEN refobjversion IS NULL THEN 'version not tracked' +ELSE CASE + WHEN refobjversion = pg_collation_actual_version(refobjid) THEN 'up to date' + ELSE 'out of date' + END +END AS version +FROM pg_depend d +LEFT JOIN pg_class c ON c.oid = d.objid +WHERE refclassid = 'pg_collation'::regclass +AND coalesce(relkind, 'i') = 'i' +AND relname LIKE 'icuidx%' +ORDER BY 1, 2; + +-- Validate that REINDEX will update the stored version. +UPDATE pg_depend SET refobjversion = 'not a version' +WHERE refclassid = 'pg_collation'::regclass +AND objid::regclass::text LIKE 'icuidx%' +AND refobjversion IS NOT NULL; + +REINDEX TABLE collate_test; +REINDEX TABLE collate_part_0; +REINDEX TABLE collate_part_1; + +SELECT objid::regclass FROM pg_depend WHERE refobjversion = 'not a version'; + +-- Validate that REINDEX CONCURRENTLY will update the stored version. +UPDATE pg_depend SET refobjversion = 'not a version' +WHERE refclassid = 'pg_collation'::regclass +AND objid::regclass::text LIKE 'icuidx%' +AND refobjversion IS NOT NULL; +REINDEX TABLE CONCURRENTLY collate_test; +REINDEX TABLE CONCURRENTLY collate_part_0; +REINDEX INDEX CONCURRENTLY icuidx17_part; + +SELECT objid::regclass FROM pg_depend WHERE refobjversion = 'not a version'; + +-- Validate that VACUUM FULL will update the stored version. +UPDATE pg_depend SET refobjversion = 'not a version' +WHERE refclassid = 'pg_collation'::regclass +AND objid::regclass::text LIKE 'icuidx%' +AND refobjversion IS NOT NULL; +VACUUM FULL collate_test; +VACUUM FULL collate_part_0; +VACUUM FULL collate_part_1; + +SELECT objid::regclass FROM pg_depend WHERE refobjversion = 'not a version'; -- cleanup RESET search_path; -- 2.20.1 --wac7ysb48OaltWcw Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="v24-0004-Add-ALTER-INDEX-.-ALTER-COLLATION-.-REFRESH-VERS.patch" ^ permalink raw reply [nested|flat] 4+ messages in thread
* Doc: Rework contrib appendix -- informative titles, tweaked sentences @ 2023-01-03 00:00 Karl O. Pinc <[email protected]> 0 siblings, 1 reply; 4+ messages in thread From: Karl O. Pinc @ 2023-01-03 00:00 UTC (permalink / raw) To: PostgreSQL Hackers <[email protected]> Hi, Attached is a patch: contrib_v1.patch It modifies Appendix F, the contrib directory. It adds brief text into the titles shown in the table of contents so it's easier to tell what each module does. It also suffixes [trusted] or [obsolete] on the relevant titles. I added the word "extension" into the appendix title because I always have problems scanning through the appendix and finding the one to do with extensions. The sentences describing what the modules are and how to build them have been reworked. Some split in 2, some words removed or replaced, etc. I introduced the word "component" because the appendix has build instructions for command line programs as well as extensions and libraries loaded with shared_preload_libraries(). This involved removing most occurrences of the word "module", although it is left in the section title. Regards, Karl <[email protected]> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein Attachments: [text/x-patch] contrib_v1.patch (27.0K, ../../[email protected]/2-contrib_v1.patch) download | inline diff: diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 184e96d7a0..04f3b52379 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/adminpack.sgml --> <sect1 id="adminpack" xreflabel="adminpack"> - <title>adminpack</title> + <title>adminpack — pgAdmin support toolpack</title> <indexterm zone="adminpack"> <primary>adminpack</primary> diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml index 5d61a33936..48d72a24a3 100644 --- a/doc/src/sgml/amcheck.sgml +++ b/doc/src/sgml/amcheck.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/amcheck.sgml --> <sect1 id="amcheck" xreflabel="amcheck"> - <title>amcheck</title> + <title>amcheck — tools to verify index consistency</title> <indexterm zone="amcheck"> <primary>amcheck</primary> diff --git a/doc/src/sgml/auth-delay.sgml b/doc/src/sgml/auth-delay.sgml index 3bc9cfb207..690774f86f 100644 --- a/doc/src/sgml/auth-delay.sgml +++ b/doc/src/sgml/auth-delay.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/auth-delay.sgml --> <sect1 id="auth-delay" xreflabel="auth_delay"> - <title>auth_delay</title> + <title>auth_delay — pause on authentication failure</title> <indexterm zone="auth-delay"> <primary>auth_delay</primary> diff --git a/doc/src/sgml/auto-explain.sgml b/doc/src/sgml/auto-explain.sgml index 394fec94e8..a80910dab5 100644 --- a/doc/src/sgml/auto-explain.sgml +++ b/doc/src/sgml/auto-explain.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/auto-explain.sgml --> <sect1 id="auto-explain" xreflabel="auto_explain"> - <title>auto_explain</title> + <title>auto_explain — log execution plans of slow queries</title> <indexterm zone="auto-explain"> <primary>auto_explain</primary> diff --git a/doc/src/sgml/basebackup-to-shell.sgml b/doc/src/sgml/basebackup-to-shell.sgml index b2ecc373eb..fd082ceb0b 100644 --- a/doc/src/sgml/basebackup-to-shell.sgml +++ b/doc/src/sgml/basebackup-to-shell.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/basebackup-to-shell.sgml --> <sect1 id="basebackup-to-shell" xreflabel="basebackup_to_shell"> - <title>basebackup_to_shell</title> + <title>basebackup_to_shell — example "shell" pg_basebackup module</title> <indexterm zone="basebackup-to-shell"> <primary>basebackup_to_shell</primary> diff --git a/doc/src/sgml/basic-archive.sgml b/doc/src/sgml/basic-archive.sgml index 0b650f17a8..c412590dd6 100644 --- a/doc/src/sgml/basic-archive.sgml +++ b/doc/src/sgml/basic-archive.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/basic-archive.sgml --> <sect1 id="basic-archive" xreflabel="basic_archive"> - <title>basic_archive</title> + <title>basic_archive — an example WAL archive module</title> <indexterm zone="basic-archive"> <primary>basic_archive</primary> diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml index a3f51cfdc4..4a188ad5f1 100644 --- a/doc/src/sgml/bloom.sgml +++ b/doc/src/sgml/bloom.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/bloom.sgml --> <sect1 id="bloom" xreflabel="bloom"> - <title>bloom</title> + <title>bloom — bloom filter index access</title> <indexterm zone="bloom"> <primary>bloom</primary> diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml index 5bc5a054e8..5aafe856b5 100644 --- a/doc/src/sgml/btree-gin.sgml +++ b/doc/src/sgml/btree-gin.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/btree-gin.sgml --> <sect1 id="btree-gin" xreflabel="btree_gin"> - <title>btree_gin</title> + <title>btree_gin — + sample GIN B-tree equalivent operator classes [trusted]</title> <indexterm zone="btree-gin"> <primary>btree_gin</primary> diff --git a/doc/src/sgml/btree-gist.sgml b/doc/src/sgml/btree-gist.sgml index b67f20a00f..67ff13c77f 100644 --- a/doc/src/sgml/btree-gist.sgml +++ b/doc/src/sgml/btree-gist.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/btree-gist.sgml --> <sect1 id="btree-gist" xreflabel="btree_gist"> - <title>btree_gist</title> + <title>btree_gist — + B-tree equalivent GiST index operators [trusted]</title> <indexterm zone="btree-gist"> <primary>btree_gist</primary> diff --git a/doc/src/sgml/citext.sgml b/doc/src/sgml/citext.sgml index 5986601327..bf08e9e6a2 100644 --- a/doc/src/sgml/citext.sgml +++ b/doc/src/sgml/citext.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/citext.sgml --> <sect1 id="citext" xreflabel="citext"> - <title>citext</title> + <title>citext — + a case-insensitive character string type [trusted]</title> <indexterm zone="citext"> <primary>citext</primary> diff --git a/doc/src/sgml/contrib-spi.sgml b/doc/src/sgml/contrib-spi.sgml index fed6f24932..edeb5b6346 100644 --- a/doc/src/sgml/contrib-spi.sgml +++ b/doc/src/sgml/contrib-spi.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/contrib-spi.sgml --> <sect1 id="contrib-spi" xreflabel="spi"> - <title>spi</title> + <title>spi — Server Programming Interface features/examples</title> <indexterm zone="contrib-spi"> <primary>SPI</primary> diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 4e7b87a42f..fd2e40980d 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -1,27 +1,31 @@ <!-- doc/src/sgml/contrib.sgml --> <appendix id="contrib"> - <title>Additional Supplied Modules</title> + <title>Additional Supplied Modules and Extensions</title> <para> - This appendix and the next one contain information regarding the modules that - can be found in the <literal>contrib</literal> directory of the + This appendix and the next one contain information on the + optional components + found in the <literal>contrib</literal> directory of the <productname>PostgreSQL</productname> distribution. These include porting tools, analysis utilities, - and plug-in features that are not part of the core PostgreSQL system, - mainly because they address a limited audience or are too experimental + and plug-in features that are not part of the core PostgreSQL system. + They are separate mainly + because they address a limited audience or are too experimental to be part of the main source tree. This does not preclude their usefulness. </para> <para> - This appendix covers extensions and other server plug-in modules found in + This appendix covers extensions and other server plug-in module + libraries found in <literal>contrib</literal>. <xref linkend="contrib-prog"/> covers utility programs. </para> <para> - When building from the source distribution, these components are not built + When building from the source distribution, these optional + components are not built automatically, unless you build the "world" target (see <xref linkend="build"/>). You can build and install all of them by running: @@ -31,8 +35,8 @@ </screen> in the <literal>contrib</literal> directory of a configured source tree; or to build and install - just one selected module, do the same in that module's subdirectory. - Many of the modules have regression tests, which can be executed by + just one selection, do the same in that selection's subdirectory. + Many have regression tests, which can be executed by running: <screen> <userinput>make check</userinput> @@ -46,41 +50,41 @@ <para> If you are using a pre-packaged version of <productname>PostgreSQL</productname>, - these modules are typically made available as a separate subpackage, + these components are typically made available as a separate subpackage, such as <literal>postgresql-contrib</literal>. </para> <para> - Many modules supply new user-defined functions, operators, or types. - To make use of one of these modules, after you have installed the code + Many components supply new user-defined functions, operators, or types. + To make use of one of these extensions, after you have installed the code you need to register the new SQL objects in the database system. This is done by executing a <xref linkend="sql-createextension"/> command. In a fresh database, you can simply do <programlisting> -CREATE EXTENSION <replaceable>module_name</replaceable>; +CREATE EXTENSION <replaceable>extension_name</replaceable>; </programlisting> - This command registers the new SQL objects in the current database only, - so you need to run it in each database that you want - the module's facilities to be available in. Alternatively, run it in + This command only registers the new SQL objects in the current database, + so you need to run it in every database in which you want + the extension's facilities to be available. Alternatively, run it in database <literal>template1</literal> so that the extension will be copied into subsequently-created databases by default. </para> <para> - For all these modules, <command>CREATE EXTENSION</command> must be run - by a database superuser, unless the module is - considered <quote>trusted</quote>, in which case it can be run by any + For all extensions the <command>CREATE EXTENSION</command> must be run + by a database superuser, unless the extension is + considered <quote>trusted</quote>. Trusted extensions can be run by any user who has <literal>CREATE</literal> privilege on the current - database. Modules that are trusted are identified as such in the - sections that follow. Generally, trusted modules are ones that cannot + database. Extensions that are trusted are identified as such in the + sections that follow. Generally, trusted extensions are ones that cannot provide access to outside-the-database functionality. </para> <para> - Many modules allow you to install their objects in a schema of your + Many extensions allow you to install their objects in a schema of your choice. To do that, add <literal>SCHEMA <replaceable>schema_name</replaceable></literal> to the <command>CREATE EXTENSION</command> command. By default, the objects will be placed in your current creation @@ -88,11 +92,11 @@ CREATE EXTENSION <replaceable>module_name</replaceable>; </para> <para> - Note, however, that some of these modules are not <quote>extensions</quote> + Note, however, that some of these components are not <quote>extensions</quote> in this sense, but are loaded into the server in some other way, for instance by way of <xref linkend="guc-shared-preload-libraries"/>. See the documentation of each - module for details. + component for details. </para> &adminpack; diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml index 52506fc822..fc8d7988c3 100644 --- a/doc/src/sgml/cube.sgml +++ b/doc/src/sgml/cube.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/cube.sgml --> <sect1 id="cube" xreflabel="cube"> - <title>cube</title> + <title>cube — a multi-dimensional cube data type [trusted]</title> <indexterm zone="cube"> <primary>cube (extension)</primary> diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml index 50c49f533b..17f9d99b1c 100644 --- a/doc/src/sgml/dblink.sgml +++ b/doc/src/sgml/dblink.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/dblink.sgml --> <sect1 id="dblink" xreflabel="dblink"> - <title>dblink</title> + <title>dblink — connect to other PostgreSQL databases</title> <indexterm zone="dblink"> <primary>dblink</primary> diff --git a/doc/src/sgml/dict-int.sgml b/doc/src/sgml/dict-int.sgml index 8babfdd5c2..3e53a468e1 100644 --- a/doc/src/sgml/dict-int.sgml +++ b/doc/src/sgml/dict-int.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/dict-int.sgml --> <sect1 id="dict-int" xreflabel="dict_int"> - <title>dict_int</title> + <title>dict_int — + example full-text search dictionary for integers [trusted]</title> <indexterm zone="dict-int"> <primary>dict_int</primary> diff --git a/doc/src/sgml/dict-xsyn.sgml b/doc/src/sgml/dict-xsyn.sgml index 256aff7c58..fc1ab863d6 100644 --- a/doc/src/sgml/dict-xsyn.sgml +++ b/doc/src/sgml/dict-xsyn.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/dict-xsyn.sgml --> <sect1 id="dict-xsyn" xreflabel="dict_xsyn"> - <title>dict_xsyn</title> + <title>dict_xsyn — example synonym full-text search dictionary</title> <indexterm zone="dict-xsyn"> <primary>dict_xsyn</primary> diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml index 4377249c36..cc29b83164 100644 --- a/doc/src/sgml/earthdistance.sgml +++ b/doc/src/sgml/earthdistance.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/earthdistance.sgml --> <sect1 id="earthdistance" xreflabel="earthdistance"> - <title>earthdistance</title> + <title>earthdistance — calculate great-circle distances</title> <indexterm zone="earthdistance"> <primary>earthdistance</primary> diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml index 5b98782064..56d696c323 100644 --- a/doc/src/sgml/file-fdw.sgml +++ b/doc/src/sgml/file-fdw.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/file-fdw.sgml --> <sect1 id="file-fdw" xreflabel="file_fdw"> - <title>file_fdw</title> + <title>file_fdw — access data files in the server's file system</title> <indexterm zone="file-fdw"> <primary>file_fdw</primary> diff --git a/doc/src/sgml/fuzzystrmatch.sgml b/doc/src/sgml/fuzzystrmatch.sgml index 382e54be91..6087aeca4f 100644 --- a/doc/src/sgml/fuzzystrmatch.sgml +++ b/doc/src/sgml/fuzzystrmatch.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/fuzzystrmatch.sgml --> <sect1 id="fuzzystrmatch" xreflabel="fuzzystrmatch"> - <title>fuzzystrmatch</title> + <title>fuzzystrmatch — + determine string similarities and distance [trusted]</title> <indexterm zone="fuzzystrmatch"> <primary>fuzzystrmatch</primary> diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml index 335d64641b..a491a13f4d 100644 --- a/doc/src/sgml/hstore.sgml +++ b/doc/src/sgml/hstore.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/hstore.sgml --> <sect1 id="hstore" xreflabel="hstore"> - <title>hstore</title> + <title>hstore — hstore key/value datatype [trusted]</title> <indexterm zone="hstore"> <primary>hstore</primary> diff --git a/doc/src/sgml/intagg.sgml b/doc/src/sgml/intagg.sgml index c410f64f3e..67e6de6c3b 100644 --- a/doc/src/sgml/intagg.sgml +++ b/doc/src/sgml/intagg.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/intagg.sgml --> <sect1 id="intagg" xreflabel="intagg"> - <title>intagg</title> + <title>intagg — integer aggregator and enumerator [obsolete]</title> <indexterm zone="intagg"> <primary>intagg</primary> diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml index 18c6f8c3ba..9563950397 100644 --- a/doc/src/sgml/intarray.sgml +++ b/doc/src/sgml/intarray.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/intarray.sgml --> <sect1 id="intarray" xreflabel="intarray"> - <title>intarray</title> + <title>intarray — manipulate arrays of integers [trusted]</title> <indexterm zone="intarray"> <primary>intarray</primary> diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml index 709bc8345c..bde88e6ee9 100644 --- a/doc/src/sgml/isn.sgml +++ b/doc/src/sgml/isn.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/isn.sgml --> <sect1 id="isn" xreflabel="isn"> - <title>isn</title> + <title>isn — + data types for various ISN standards (UPC, books, etc.) [trusted]</title> <indexterm zone="isn"> <primary>isn</primary> diff --git a/doc/src/sgml/lo.sgml b/doc/src/sgml/lo.sgml index f46cd392df..a3fb7aed40 100644 --- a/doc/src/sgml/lo.sgml +++ b/doc/src/sgml/lo.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/lo.sgml --> <sect1 id="lo" xreflabel="lo"> - <title>lo</title> + <title>lo — manage large objects (BLOBs) [trusted]</title> <indexterm zone="lo"> <primary>lo</primary> diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml index 508f404ae8..597e359fcf 100644 --- a/doc/src/sgml/ltree.sgml +++ b/doc/src/sgml/ltree.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/ltree.sgml --> <sect1 id="ltree" xreflabel="ltree"> - <title>ltree</title> + <title>ltree — label tree (ltree) data type [trusted]</title> <indexterm zone="ltree"> <primary>ltree</primary> diff --git a/doc/src/sgml/oldsnapshot.sgml b/doc/src/sgml/oldsnapshot.sgml index a665ae72e7..0be8b858ac 100644 --- a/doc/src/sgml/oldsnapshot.sgml +++ b/doc/src/sgml/oldsnapshot.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/oldsnapshot.sgml --> <sect1 id="oldsnapshot" xreflabel="old_snapshot"> - <title>old_snapshot</title> + <title>old_snapshot — inspect guc-old-snapshot-threshold state</title> <indexterm zone="oldsnapshot"> <primary>old_snapshot</primary> diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml index 04aca998e7..60a18664c4 100644 --- a/doc/src/sgml/pageinspect.sgml +++ b/doc/src/sgml/pageinspect.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pageinspect.sgml --> <sect1 id="pageinspect" xreflabel="pageinspect"> - <title>pageinspect</title> + <title>pageinspect — low-level inspection of database pages</title> <indexterm zone="pageinspect"> <primary>pageinspect</primary> diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml index 0d89bb95b9..6cd4f6af0e 100644 --- a/doc/src/sgml/passwordcheck.sgml +++ b/doc/src/sgml/passwordcheck.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/passwordcheck.sgml --> <sect1 id="passwordcheck" xreflabel="passwordcheck"> - <title>passwordcheck</title> + <title>passwordcheck — check for weak password when (re)set</title> <indexterm zone="passwordcheck"> <primary>passwordcheck</primary> diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml index 5316472b96..453ffcac0e 100644 --- a/doc/src/sgml/pgcrypto.sgml +++ b/doc/src/sgml/pgcrypto.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgcrypto.sgml --> <sect1 id="pgcrypto" xreflabel="pgcrypto"> - <title>pgcrypto</title> + <title>pgcrypto — cryptographic functions [trusted]</title> <indexterm zone="pgcrypto"> <primary>pgcrypto</primary> diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml index 4dd7a084b9..e79de8f859 100644 --- a/doc/src/sgml/pgfreespacemap.sgml +++ b/doc/src/sgml/pgfreespacemap.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgfreespacemap.sgml --> <sect1 id="pgfreespacemap" xreflabel="pg_freespacemap"> - <title>pg_freespacemap</title> + <title>pg_freespacemap — examine the free space map</title> <indexterm zone="pgfreespacemap"> <primary>pg_freespacemap</primary> diff --git a/doc/src/sgml/pgprewarm.sgml b/doc/src/sgml/pgprewarm.sgml index 754a21a076..abf788830b 100644 --- a/doc/src/sgml/pgprewarm.sgml +++ b/doc/src/sgml/pgprewarm.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/pgprewarm.sgml --> <sect1 id="pgprewarm" xreflabel="pg_prewarm"> - <title>pg_prewarm</title> + <title>pg_prewarm — + preload relation data into O/S or PG buffer caches</title> <indexterm zone="pgprewarm"> <primary>pg_prewarm</primary> diff --git a/doc/src/sgml/pgrowlocks.sgml b/doc/src/sgml/pgrowlocks.sgml index ad15cda668..8eb60bf288 100644 --- a/doc/src/sgml/pgrowlocks.sgml +++ b/doc/src/sgml/pgrowlocks.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgrowlocks.sgml --> <sect1 id="pgrowlocks" xreflabel="pgrowlocks"> - <title>pgrowlocks</title> + <title>pgrowlocks — show a table's row locking information</title> <indexterm zone="pgrowlocks"> <primary>pgrowlocks</primary> diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml index ea90365c7f..063b06ede4 100644 --- a/doc/src/sgml/pgstatstatements.sgml +++ b/doc/src/sgml/pgstatstatements.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/pgstatstatements.sgml --> <sect1 id="pgstatstatements" xreflabel="pg_stat_statements"> - <title>pg_stat_statements</title> + <title>pg_stat_statements — + track SQL planning and execution statistics</title> <indexterm zone="pgstatstatements"> <primary>pg_stat_statements</primary> diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml index b17b3c59e0..aa7eeecf4a 100644 --- a/doc/src/sgml/pgstattuple.sgml +++ b/doc/src/sgml/pgstattuple.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgstattuple.sgml --> <sect1 id="pgstattuple" xreflabel="pgstattuple"> - <title>pgstattuple</title> + <title>pgstattuple — obtain tuple-level statistics</title> <indexterm zone="pgstattuple"> <primary>pgstattuple</primary> diff --git a/doc/src/sgml/pgsurgery.sgml b/doc/src/sgml/pgsurgery.sgml index 4bba14f217..611a173feb 100644 --- a/doc/src/sgml/pgsurgery.sgml +++ b/doc/src/sgml/pgsurgery.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgsurgery.sgml --> <sect1 id="pgsurgery" xreflabel="pg_surgery"> - <title>pg_surgery</title> + <title>pg_surgery — perform surgery on damaged relations</title> <indexterm zone="pgsurgery"> <primary>pg_surgery</primary> diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml index fefe30afb7..7f295d0a6f 100644 --- a/doc/src/sgml/pgtrgm.sgml +++ b/doc/src/sgml/pgtrgm.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/pgtrgm.sgml --> <sect1 id="pgtrgm" xreflabel="pg_trgm"> - <title>pg_trgm</title> + <title>pg_trgm — + support for similarity of text using trigram matching [trusted]</title> <indexterm zone="pgtrgm"> <primary>pg_trgm</primary> diff --git a/doc/src/sgml/pgvisibility.sgml b/doc/src/sgml/pgvisibility.sgml index 8090aa5207..b2ae8c1372 100644 --- a/doc/src/sgml/pgvisibility.sgml +++ b/doc/src/sgml/pgvisibility.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgvisibility.sgml --> <sect1 id="pgvisibility" xreflabel="pg_visibility"> - <title>pg_visibility</title> + <title>pg_visibility — visibility map information and utilities</title> <indexterm zone="pgvisibility"> <primary>pg_visibility</primary> diff --git a/doc/src/sgml/pgwalinspect.sgml b/doc/src/sgml/pgwalinspect.sgml index 1a1bee7d6a..413121a9ba 100644 --- a/doc/src/sgml/pgwalinspect.sgml +++ b/doc/src/sgml/pgwalinspect.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgwalinspect.sgml --> <sect1 id="pgwalinspect" xreflabel="pg_walinspect"> - <title>pg_walinspect</title> + <title>pg_walinspect — low-level WAL inspection</title> <indexterm zone="pgwalinspect"> <primary>pg_walinspect</primary> diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml index 6c94318485..f4d6fe9f94 100644 --- a/doc/src/sgml/postgres-fdw.sgml +++ b/doc/src/sgml/postgres-fdw.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/postgres-fdw.sgml --> <sect1 id="postgres-fdw" xreflabel="postgres_fdw"> - <title>postgres_fdw</title> + <title>postgres_fdw — + access data stored in external Postgres servers</title> <indexterm zone="postgres-fdw"> <primary>postgres_fdw</primary> diff --git a/doc/src/sgml/seg.sgml b/doc/src/sgml/seg.sgml index 9be69e3609..9280adaaac 100644 --- a/doc/src/sgml/seg.sgml +++ b/doc/src/sgml/seg.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/seg.sgml --> <sect1 id="seg" xreflabel="seg"> - <title>seg</title> + <title>seg — + line segment/floating point interval data type [trusted]</title> <indexterm zone="seg"> <primary>seg</primary> diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml index 620d0636e8..13f89c85b0 100644 --- a/doc/src/sgml/sepgsql.sgml +++ b/doc/src/sgml/sepgsql.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/sepgsql.sgml --> <sect1 id="sepgsql" xreflabel="sepgsql"> - <title>sepgsql</title> + <title>sepgsql — + label-based, SELinux-like, mandatory access control</title> <indexterm zone="sepgsql"> <primary>sepgsql</primary> diff --git a/doc/src/sgml/sslinfo.sgml b/doc/src/sgml/sslinfo.sgml index 2a9c45a111..8cd1006fe0 100644 --- a/doc/src/sgml/sslinfo.sgml +++ b/doc/src/sgml/sslinfo.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/sslinfo.sgml --> <sect1 id="sslinfo" xreflabel="sslinfo"> - <title>sslinfo</title> + <title>sslinfo — obtain client SSL information</title> <indexterm zone="sslinfo"> <primary>sslinfo</primary> diff --git a/doc/src/sgml/tablefunc.sgml b/doc/src/sgml/tablefunc.sgml index 808162b89b..25280b598d 100644 --- a/doc/src/sgml/tablefunc.sgml +++ b/doc/src/sgml/tablefunc.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/tablefunc.sgml --> <sect1 id="tablefunc" xreflabel="tablefunc"> - <title>tablefunc</title> + <title>tablefunc — + useful/example functions which return tables [trusted]</title> <indexterm zone="tablefunc"> <primary>tablefunc</primary> diff --git a/doc/src/sgml/tcn.sgml b/doc/src/sgml/tcn.sgml index 82afe9ada4..60f8ebb80f 100644 --- a/doc/src/sgml/tcn.sgml +++ b/doc/src/sgml/tcn.sgml @@ -1,7 +1,9 @@ <!-- doc/src/sgml/tcn.sgml --> <sect1 id="tcn" xreflabel="tcn"> - <title>tcn</title> + <title>tcn — + a trigger function to notify listeners of changes to table content + [trusted]</title> <indexterm zone="tcn"> <primary>tcn</primary> diff --git a/doc/src/sgml/test-decoding.sgml b/doc/src/sgml/test-decoding.sgml index 9b07195427..88f72c204e 100644 --- a/doc/src/sgml/test-decoding.sgml +++ b/doc/src/sgml/test-decoding.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/test-decoding.sgml --> <sect1 id="test-decoding" xreflabel="test_decoding"> - <title>test_decoding</title> + <title>test_decoding — example of WAL logical decoding in SQL</title> <indexterm zone="test-decoding"> <primary>test_decoding</primary> diff --git a/doc/src/sgml/tsm-system-rows.sgml b/doc/src/sgml/tsm-system-rows.sgml index d960aa3e0f..7e53a716cb 100644 --- a/doc/src/sgml/tsm-system-rows.sgml +++ b/doc/src/sgml/tsm-system-rows.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/tsm-system-rows.sgml --> <sect1 id="tsm-system-rows" xreflabel="tsm_system_rows"> - <title>tsm_system_rows</title> + <title>tsm_system_rows — + a table row sampling method for TABLESAMPLE clauses [trusted]</title> <indexterm zone="tsm-system-rows"> <primary>tsm_system_rows</primary> diff --git a/doc/src/sgml/tsm-system-time.sgml b/doc/src/sgml/tsm-system-time.sgml index df6e83a923..fd709ce012 100644 --- a/doc/src/sgml/tsm-system-time.sgml +++ b/doc/src/sgml/tsm-system-time.sgml @@ -1,7 +1,9 @@ <!-- doc/src/sgml/tsm-system-time.sgml --> <sect1 id="tsm-system-time" xreflabel="tsm_system_time"> - <title>tsm_system_time</title> + <title>tsm_system_time — + a SYSTEM_TIME table sampling method for the TABLESAMPLE clauses + [trusted]</title> <indexterm zone="tsm-system-time"> <primary>tsm_system_time</primary> diff --git a/doc/src/sgml/unaccent.sgml b/doc/src/sgml/unaccent.sgml index 5cd716a2aa..a34de537e5 100644 --- a/doc/src/sgml/unaccent.sgml +++ b/doc/src/sgml/unaccent.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/unaccent.sgml --> <sect1 id="unaccent" xreflabel="unaccent"> - <title>unaccent</title> + <title>unaccent — + a full-text search dictionary which removes diacritics [trusted]</title> <indexterm zone="unaccent"> <primary>unaccent</primary> diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml index 26bfb908da..e037cbf2a1 100644 --- a/doc/src/sgml/uuid-ossp.sgml +++ b/doc/src/sgml/uuid-ossp.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/uuid-ossp.sgml --> <sect1 id="uuid-ossp" xreflabel="uuid-ossp"> - <title>uuid-ossp</title> + <title>uuid-ossp — + generate UUIDs when there are special requirements [trusted]</title> <indexterm zone="uuid-ossp"> <primary>uuid-ossp</primary> diff --git a/doc/src/sgml/xml2.sgml b/doc/src/sgml/xml2.sgml index 47650d9dfd..ebe3246405 100644 --- a/doc/src/sgml/xml2.sgml +++ b/doc/src/sgml/xml2.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/xml2.sgml --> <sect1 id="xml2" xreflabel="xml2"> - <title>xml2</title> + <title>xml2 — XPath qeurying and XSLT functionality [obsolete]</title> <indexterm zone="xml2"> <primary>xml2</primary> ^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences @ 2023-01-18 12:25 Alvaro Herrera <[email protected]> parent: Karl O. Pinc <[email protected]> 0 siblings, 1 reply; 4+ messages in thread From: Alvaro Herrera @ 2023-01-18 12:25 UTC (permalink / raw) To: Karl O. Pinc <[email protected]>; +Cc: PostgreSQL Hackers <[email protected]> On 2023-Jan-02, Karl O. Pinc wrote: > Hi, > > Attached is a patch: contrib_v1.patch > > It modifies Appendix F, the contrib directory. > > It adds brief text into the titles shown in the > table of contents so it's easier to tell what > each module does. It also suffixes [trusted] or [obsolete] > on the relevant titles. This looks a good idea to me. I'm not 100% sold on having the "trusted" or "obsolete" marker on the titles themselves, though. Not sure what alternative do we have, though, other than leave them out completely. There's a typo "equalivent" in two places. In passwordcheck, I would say just "check for weak passwords" or maybe "verify password strength". pg_buffercache is missing. Maybe "-- inspect state of the Postgres buffer cache". For pg_stat_statements I suggest "track statistics of planning and execution of SQL queries" For sepgsql, as I understand it is strictly SELinux based, not just "-like". So this needs rewording: "label-based, SELinux-like, mandatory access control". Maybe "SELinux-based implementation of mandatory access control for row-level security". xml -- typo "qeurying" > The sentences describing what the modules are and how > to build them have been reworked. Some split in 2, > some words removed or replaced, etc. > > I introduced the word "component" because the appendix > has build instructions for command line programs as well > as extensions and libraries loaded with shared_preload_libraries(). > This involved removing most occurrences of the word > "module", although it is left in the section title. I haven't read this part yet. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "But static content is just dynamic content that isn't moving!" http://smylers.hates-software.com/2007/08/15/fe244d0c.html ^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences @ 2023-01-18 19:01 Karl O. Pinc <[email protected]> parent: Alvaro Herrera <[email protected]> 0 siblings, 0 replies; 4+ messages in thread From: Karl O. Pinc @ 2023-01-18 19:01 UTC (permalink / raw) To: Alvaro Herrera <[email protected]>; +Cc: PostgreSQL Hackers <[email protected]> On Wed, 18 Jan 2023 13:25:57 +0100 Alvaro Herrera <[email protected]> wrote: > On 2023-Jan-02, Karl O. Pinc wrote: > > Attached is a patch: contrib_v1.patch > > > > It modifies Appendix F, the contrib directory. > > > > It adds brief text into the titles shown in the > > table of contents so it's easier to tell what > > each module does. It also suffixes [trusted] or [obsolete] > > on the relevant titles. > <snip> > I'm not 100% sold on having the > "trusted" or "obsolete" marker on the titles themselves, though. Not > sure what alternative do we have, though, other than leave them out > completely. The alternative would be to have a separate table with modules for rows and "trusted" and "obsolete" columns. It seems like more of a maintenance hassle than having the markers in the titles. Let me know if you want a table. I do like having a place to look to over all the modules to see what is "trusted" or "obsolete". I suppose there could just be a table, with module names, descriptions, and trusted and obsolete flags. Instead of a table of contents for the modules the module names in the table could be links. But that'd involve suppressing the table of contents showing all the module names. And has the problem of possible mis-match between the modules listed in the table and the modules that exist. > There's a typo "equalivent" in two places. Fixed. > In passwordcheck, I would say just "check for weak passwords" or maybe > "verify password strength". I used "verify password strength". > > pg_buffercache is missing. Maybe "-- inspect state of the Postgres > buffer cache". I used "inspect Postgres buffer cache state" > For pg_stat_statements I suggest "track statistics of planning and > execution of SQL queries" I had written "track SQL query planning and execution statistics". Changed to: "track statistics of SQL planning and execution" I don't really care. If you want your version I'll submit another patch. > For sepgsql, as I understand it is strictly SELinux based, not just > "-like". So this needs rewording: "label-based, SELinux-like, > mandatory access control". Maybe "SELinux-based implementation of > mandatory access control for row-level security". Changed to: "SELinux-based row-level security mandatory access control" > xml -- typo "qeurying" Fixed. I have also made the patch put each module on a separate page when producing PDF documents. This did produce one warning, which seems unrelated to me. The pdf seems right. I also tried just "make", to be sure I didn't break anything unrelated. Seemed to work. So..., works for me. New patch attached: contrib_v2.patch Regards, Karl <[email protected]> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein Attachments: [text/x-patch] contrib_v2.patch (29.7K, ../../[email protected]/2-contrib_v2.patch) download | inline diff: diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 184e96d7a0..04f3b52379 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/adminpack.sgml --> <sect1 id="adminpack" xreflabel="adminpack"> - <title>adminpack</title> + <title>adminpack — pgAdmin support toolpack</title> <indexterm zone="adminpack"> <primary>adminpack</primary> diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml index 923cbde9dd..4006c75cdf 100644 --- a/doc/src/sgml/amcheck.sgml +++ b/doc/src/sgml/amcheck.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/amcheck.sgml --> <sect1 id="amcheck" xreflabel="amcheck"> - <title>amcheck</title> + <title>amcheck — tools to verify index consistency</title> <indexterm zone="amcheck"> <primary>amcheck</primary> diff --git a/doc/src/sgml/auth-delay.sgml b/doc/src/sgml/auth-delay.sgml index 40629311b1..0571f2a99d 100644 --- a/doc/src/sgml/auth-delay.sgml +++ b/doc/src/sgml/auth-delay.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/auth-delay.sgml --> <sect1 id="auth-delay" xreflabel="auth_delay"> - <title>auth_delay</title> + <title>auth_delay — pause on authentication failure</title> <indexterm zone="auth-delay"> <primary>auth_delay</primary> diff --git a/doc/src/sgml/auto-explain.sgml b/doc/src/sgml/auto-explain.sgml index bb7342b120..0c4656ee30 100644 --- a/doc/src/sgml/auto-explain.sgml +++ b/doc/src/sgml/auto-explain.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/auto-explain.sgml --> <sect1 id="auto-explain" xreflabel="auto_explain"> - <title>auto_explain</title> + <title>auto_explain — log execution plans of slow queries</title> <indexterm zone="auto-explain"> <primary>auto_explain</primary> diff --git a/doc/src/sgml/basebackup-to-shell.sgml b/doc/src/sgml/basebackup-to-shell.sgml index 491368eb8f..b6a3b39541 100644 --- a/doc/src/sgml/basebackup-to-shell.sgml +++ b/doc/src/sgml/basebackup-to-shell.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/basebackup-to-shell.sgml --> <sect1 id="basebackup-to-shell" xreflabel="basebackup_to_shell"> - <title>basebackup_to_shell</title> + <title>basebackup_to_shell — example "shell" pg_basebackup module</title> <indexterm zone="basebackup-to-shell"> <primary>basebackup_to_shell</primary> diff --git a/doc/src/sgml/basic-archive.sgml b/doc/src/sgml/basic-archive.sgml index 60f23d2855..b4d43ced20 100644 --- a/doc/src/sgml/basic-archive.sgml +++ b/doc/src/sgml/basic-archive.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/basic-archive.sgml --> <sect1 id="basic-archive" xreflabel="basic_archive"> - <title>basic_archive</title> + <title>basic_archive — an example WAL archive module</title> <indexterm zone="basic-archive"> <primary>basic_archive</primary> diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml index 98d0316175..672ac2ed19 100644 --- a/doc/src/sgml/bloom.sgml +++ b/doc/src/sgml/bloom.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/bloom.sgml --> <sect1 id="bloom" xreflabel="bloom"> - <title>bloom</title> + <title>bloom — bloom filter index access</title> <indexterm zone="bloom"> <primary>bloom</primary> diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml index 870c25559e..0eaea0dbcd 100644 --- a/doc/src/sgml/btree-gin.sgml +++ b/doc/src/sgml/btree-gin.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/btree-gin.sgml --> <sect1 id="btree-gin" xreflabel="btree_gin"> - <title>btree_gin</title> + <title>btree_gin — + sample GIN B-tree equivalent operator classes [trusted]</title> <indexterm zone="btree-gin"> <primary>btree_gin</primary> diff --git a/doc/src/sgml/btree-gist.sgml b/doc/src/sgml/btree-gist.sgml index 92aa8e277e..c08d1fdfc3 100644 --- a/doc/src/sgml/btree-gist.sgml +++ b/doc/src/sgml/btree-gist.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/btree-gist.sgml --> <sect1 id="btree-gist" xreflabel="btree_gist"> - <title>btree_gist</title> + <title>btree_gist — + B-tree equivalent GiST index operators [trusted]</title> <indexterm zone="btree-gist"> <primary>btree_gist</primary> diff --git a/doc/src/sgml/citext.sgml b/doc/src/sgml/citext.sgml index 3df2825592..710fbdddf2 100644 --- a/doc/src/sgml/citext.sgml +++ b/doc/src/sgml/citext.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/citext.sgml --> <sect1 id="citext" xreflabel="citext"> - <title>citext</title> + <title>citext — + a case-insensitive character string type [trusted]</title> <indexterm zone="citext"> <primary>citext</primary> diff --git a/doc/src/sgml/contrib-spi.sgml b/doc/src/sgml/contrib-spi.sgml index 77328ae6e8..e7cae4e38d 100644 --- a/doc/src/sgml/contrib-spi.sgml +++ b/doc/src/sgml/contrib-spi.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/contrib-spi.sgml --> <sect1 id="contrib-spi" xreflabel="spi"> - <title>spi</title> + <title>spi — Server Programming Interface features/examples</title> <indexterm zone="contrib-spi"> <primary>SPI</primary> diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 4e7b87a42f..c3897d03f9 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -1,27 +1,31 @@ <!-- doc/src/sgml/contrib.sgml --> <appendix id="contrib"> - <title>Additional Supplied Modules</title> + <title>Additional Supplied Modules and Extensions</title> <para> - This appendix and the next one contain information regarding the modules that - can be found in the <literal>contrib</literal> directory of the + This appendix and the next one contain information on the + optional components + found in the <literal>contrib</literal> directory of the <productname>PostgreSQL</productname> distribution. These include porting tools, analysis utilities, - and plug-in features that are not part of the core PostgreSQL system, - mainly because they address a limited audience or are too experimental + and plug-in features that are not part of the core PostgreSQL system. + They are separate mainly + because they address a limited audience or are too experimental to be part of the main source tree. This does not preclude their usefulness. </para> <para> - This appendix covers extensions and other server plug-in modules found in + This appendix covers extensions and other server plug-in module + libraries found in <literal>contrib</literal>. <xref linkend="contrib-prog"/> covers utility programs. </para> <para> - When building from the source distribution, these components are not built + When building from the source distribution, these optional + components are not built automatically, unless you build the "world" target (see <xref linkend="build"/>). You can build and install all of them by running: @@ -31,8 +35,8 @@ </screen> in the <literal>contrib</literal> directory of a configured source tree; or to build and install - just one selected module, do the same in that module's subdirectory. - Many of the modules have regression tests, which can be executed by + just one selection, do the same in that selection's subdirectory. + Many have regression tests, which can be executed by running: <screen> <userinput>make check</userinput> @@ -46,41 +50,41 @@ <para> If you are using a pre-packaged version of <productname>PostgreSQL</productname>, - these modules are typically made available as a separate subpackage, + these components are typically made available as a separate subpackage, such as <literal>postgresql-contrib</literal>. </para> <para> - Many modules supply new user-defined functions, operators, or types. - To make use of one of these modules, after you have installed the code + Many components supply new user-defined functions, operators, or types. + To make use of one of these extensions, after you have installed the code you need to register the new SQL objects in the database system. This is done by executing a <xref linkend="sql-createextension"/> command. In a fresh database, you can simply do <programlisting> -CREATE EXTENSION <replaceable>module_name</replaceable>; +CREATE EXTENSION <replaceable>extension_name</replaceable>; </programlisting> - This command registers the new SQL objects in the current database only, - so you need to run it in each database that you want - the module's facilities to be available in. Alternatively, run it in + This command only registers the new SQL objects in the current database, + so you need to run it in every database in which you want + the extension's facilities to be available. Alternatively, run it in database <literal>template1</literal> so that the extension will be copied into subsequently-created databases by default. </para> <para> - For all these modules, <command>CREATE EXTENSION</command> must be run - by a database superuser, unless the module is - considered <quote>trusted</quote>, in which case it can be run by any + For all extensions the <command>CREATE EXTENSION</command> must be run + by a database superuser, unless the extension is + considered <quote>trusted</quote>. Trusted extensions can be run by any user who has <literal>CREATE</literal> privilege on the current - database. Modules that are trusted are identified as such in the - sections that follow. Generally, trusted modules are ones that cannot + database. Extensions that are trusted are identified as such in the + sections that follow. Generally, trusted extensions are ones that cannot provide access to outside-the-database functionality. </para> <para> - Many modules allow you to install their objects in a schema of your + Many extensions allow you to install their objects in a schema of your choice. To do that, add <literal>SCHEMA <replaceable>schema_name</replaceable></literal> to the <command>CREATE EXTENSION</command> command. By default, the objects will be placed in your current creation @@ -88,62 +92,112 @@ CREATE EXTENSION <replaceable>module_name</replaceable>; </para> <para> - Note, however, that some of these modules are not <quote>extensions</quote> + Note, however, that some of these components are not <quote>extensions</quote> in this sense, but are loaded into the server in some other way, for instance by way of <xref linkend="guc-shared-preload-libraries"/>. See the documentation of each - module for details. + component for details. </para> + <?hard-pagebreak?> &adminpack; + <?hard-pagebreak?> &amcheck; + <?hard-pagebreak?> &auth-delay; + <?hard-pagebreak?> &auto-explain; + <?hard-pagebreak?> &basebackup-to-shell; + <?hard-pagebreak?> &basic-archive; + <?hard-pagebreak?> &bloom; + <?hard-pagebreak?> &btree-gin; + <?hard-pagebreak?> &btree-gist; + <?hard-pagebreak?> &citext; + <?hard-pagebreak?> &cube; + <?hard-pagebreak?> &dblink; + <?hard-pagebreak?> &dict-int; + <?hard-pagebreak?> &dict-xsyn; + <?hard-pagebreak?> &earthdistance; + <?hard-pagebreak?> &file-fdw; + <?hard-pagebreak?> &fuzzystrmatch; + <?hard-pagebreak?> &hstore; + <?hard-pagebreak?> &intagg; + <?hard-pagebreak?> &intarray; + <?hard-pagebreak?> &isn; + <?hard-pagebreak?> &lo; + <?hard-pagebreak?> <ree; + <?hard-pagebreak?> &oldsnapshot; + <?hard-pagebreak?> &pageinspect; + <?hard-pagebreak?> &passwordcheck; + <?hard-pagebreak?> &pgbuffercache; + <?hard-pagebreak?> &pgcrypto; + <?hard-pagebreak?> &pgfreespacemap; + <?hard-pagebreak?> &pgprewarm; + <?hard-pagebreak?> &pgrowlocks; + <?hard-pagebreak?> &pgstatstatements; + <?hard-pagebreak?> &pgstattuple; + <?hard-pagebreak?> &pgsurgery; + <?hard-pagebreak?> &pgtrgm; + <?hard-pagebreak?> &pgvisibility; + <?hard-pagebreak?> &pgwalinspect; + <?hard-pagebreak?> &postgres-fdw; + <?hard-pagebreak?> &seg; + <?hard-pagebreak?> &sepgsql; + <?hard-pagebreak?> &contrib-spi; + <?hard-pagebreak?> &sslinfo; + <?hard-pagebreak?> &tablefunc; + <?hard-pagebreak?> &tcn; + <?hard-pagebreak?> &test-decoding; + <?hard-pagebreak?> &tsm-system-rows; + <?hard-pagebreak?> &tsm-system-time; + <?hard-pagebreak?> &unaccent; + <?hard-pagebreak?> &uuid-ossp; + <?hard-pagebreak?> &xml2; </appendix> diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml index 0744816e7c..1998e6d81a 100644 --- a/doc/src/sgml/cube.sgml +++ b/doc/src/sgml/cube.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/cube.sgml --> <sect1 id="cube" xreflabel="cube"> - <title>cube</title> + <title>cube — a multi-dimensional cube data type [trusted]</title> <indexterm zone="cube"> <primary>cube (extension)</primary> diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml index 50c49f533b..17f9d99b1c 100644 --- a/doc/src/sgml/dblink.sgml +++ b/doc/src/sgml/dblink.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/dblink.sgml --> <sect1 id="dblink" xreflabel="dblink"> - <title>dblink</title> + <title>dblink — connect to other PostgreSQL databases</title> <indexterm zone="dblink"> <primary>dblink</primary> diff --git a/doc/src/sgml/dict-int.sgml b/doc/src/sgml/dict-int.sgml index 53ae8b6637..293ba83ce6 100644 --- a/doc/src/sgml/dict-int.sgml +++ b/doc/src/sgml/dict-int.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/dict-int.sgml --> <sect1 id="dict-int" xreflabel="dict_int"> - <title>dict_int</title> + <title>dict_int — + example full-text search dictionary for integers [trusted]</title> <indexterm zone="dict-int"> <primary>dict_int</primary> diff --git a/doc/src/sgml/dict-xsyn.sgml b/doc/src/sgml/dict-xsyn.sgml index 27b24628d4..a94c6430ed 100644 --- a/doc/src/sgml/dict-xsyn.sgml +++ b/doc/src/sgml/dict-xsyn.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/dict-xsyn.sgml --> <sect1 id="dict-xsyn" xreflabel="dict_xsyn"> - <title>dict_xsyn</title> + <title>dict_xsyn — example synonym full-text search dictionary</title> <indexterm zone="dict-xsyn"> <primary>dict_xsyn</primary> diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml index f15dde3a66..5a709e3d47 100644 --- a/doc/src/sgml/earthdistance.sgml +++ b/doc/src/sgml/earthdistance.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/earthdistance.sgml --> <sect1 id="earthdistance" xreflabel="earthdistance"> - <title>earthdistance</title> + <title>earthdistance — calculate great-circle distances</title> <indexterm zone="earthdistance"> <primary>earthdistance</primary> diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml index 5b98782064..56d696c323 100644 --- a/doc/src/sgml/file-fdw.sgml +++ b/doc/src/sgml/file-fdw.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/file-fdw.sgml --> <sect1 id="file-fdw" xreflabel="file_fdw"> - <title>file_fdw</title> + <title>file_fdw — access data files in the server's file system</title> <indexterm zone="file-fdw"> <primary>file_fdw</primary> diff --git a/doc/src/sgml/fuzzystrmatch.sgml b/doc/src/sgml/fuzzystrmatch.sgml index 5dedbd8f7a..2c6a666da8 100644 --- a/doc/src/sgml/fuzzystrmatch.sgml +++ b/doc/src/sgml/fuzzystrmatch.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/fuzzystrmatch.sgml --> <sect1 id="fuzzystrmatch" xreflabel="fuzzystrmatch"> - <title>fuzzystrmatch</title> + <title>fuzzystrmatch — + determine string similarities and distance [trusted]</title> <indexterm zone="fuzzystrmatch"> <primary>fuzzystrmatch</primary> diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml index 815ef641a0..b75c63f348 100644 --- a/doc/src/sgml/hstore.sgml +++ b/doc/src/sgml/hstore.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/hstore.sgml --> <sect1 id="hstore" xreflabel="hstore"> - <title>hstore</title> + <title>hstore — hstore key/value datatype [trusted]</title> <indexterm zone="hstore"> <primary>hstore</primary> diff --git a/doc/src/sgml/intagg.sgml b/doc/src/sgml/intagg.sgml index 34562a66c8..ce7b929a34 100644 --- a/doc/src/sgml/intagg.sgml +++ b/doc/src/sgml/intagg.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/intagg.sgml --> <sect1 id="intagg" xreflabel="intagg"> - <title>intagg</title> + <title>intagg — integer aggregator and enumerator [obsolete]</title> <indexterm zone="intagg"> <primary>intagg</primary> diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml index c861f50497..9194e94c28 100644 --- a/doc/src/sgml/intarray.sgml +++ b/doc/src/sgml/intarray.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/intarray.sgml --> <sect1 id="intarray" xreflabel="intarray"> - <title>intarray</title> + <title>intarray — manipulate arrays of integers [trusted]</title> <indexterm zone="intarray"> <primary>intarray</primary> diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml index 14bf2d14aa..0568436a26 100644 --- a/doc/src/sgml/isn.sgml +++ b/doc/src/sgml/isn.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/isn.sgml --> <sect1 id="isn" xreflabel="isn"> - <title>isn</title> + <title>isn — + data types for various ISN standards (UPC, books, etc.) [trusted]</title> <indexterm zone="isn"> <primary>isn</primary> diff --git a/doc/src/sgml/lo.sgml b/doc/src/sgml/lo.sgml index d6076aeb7f..c51781b0bb 100644 --- a/doc/src/sgml/lo.sgml +++ b/doc/src/sgml/lo.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/lo.sgml --> <sect1 id="lo" xreflabel="lo"> - <title>lo</title> + <title>lo — manage large objects (BLOBs) [trusted]</title> <indexterm zone="lo"> <primary>lo</primary> diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml index 45a86188cb..92264251cd 100644 --- a/doc/src/sgml/ltree.sgml +++ b/doc/src/sgml/ltree.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/ltree.sgml --> <sect1 id="ltree" xreflabel="ltree"> - <title>ltree</title> + <title>ltree — label tree (ltree) data type [trusted]</title> <indexterm zone="ltree"> <primary>ltree</primary> diff --git a/doc/src/sgml/oldsnapshot.sgml b/doc/src/sgml/oldsnapshot.sgml index 0e03084562..a6e40043d1 100644 --- a/doc/src/sgml/oldsnapshot.sgml +++ b/doc/src/sgml/oldsnapshot.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/oldsnapshot.sgml --> <sect1 id="oldsnapshot" xreflabel="old_snapshot"> - <title>old_snapshot</title> + <title>old_snapshot — inspect guc-old-snapshot-threshold state</title> <indexterm zone="oldsnapshot"> <primary>old_snapshot</primary> diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml index 8674872e8b..01f1e96204 100644 --- a/doc/src/sgml/pageinspect.sgml +++ b/doc/src/sgml/pageinspect.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pageinspect.sgml --> <sect1 id="pageinspect" xreflabel="pageinspect"> - <title>pageinspect</title> + <title>pageinspect — low-level inspection of database pages</title> <indexterm zone="pageinspect"> <primary>pageinspect</primary> diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml index 0d89bb95b9..601f489227 100644 --- a/doc/src/sgml/passwordcheck.sgml +++ b/doc/src/sgml/passwordcheck.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/passwordcheck.sgml --> <sect1 id="passwordcheck" xreflabel="passwordcheck"> - <title>passwordcheck</title> + <title>passwordcheck — verify password strength</title> <indexterm zone="passwordcheck"> <primary>passwordcheck</primary> diff --git a/doc/src/sgml/pgbuffercache.sgml b/doc/src/sgml/pgbuffercache.sgml index 7b118f2030..f5d1901af2 100644 --- a/doc/src/sgml/pgbuffercache.sgml +++ b/doc/src/sgml/pgbuffercache.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgbuffercache.sgml --> <sect1 id="pgbuffercache" xreflabel="pg_buffercache"> - <title>pg_buffercache</title> + <title>pg_buffercache — inspect Postgres buffer cache state</title> <indexterm zone="pgbuffercache"> <primary>pg_buffercache</primary> diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml index bde3071923..2231a65dde 100644 --- a/doc/src/sgml/pgcrypto.sgml +++ b/doc/src/sgml/pgcrypto.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgcrypto.sgml --> <sect1 id="pgcrypto" xreflabel="pgcrypto"> - <title>pgcrypto</title> + <title>pgcrypto — cryptographic functions [trusted]</title> <indexterm zone="pgcrypto"> <primary>pgcrypto</primary> diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml index 9d93fb5a72..829ad60f32 100644 --- a/doc/src/sgml/pgfreespacemap.sgml +++ b/doc/src/sgml/pgfreespacemap.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgfreespacemap.sgml --> <sect1 id="pgfreespacemap" xreflabel="pg_freespacemap"> - <title>pg_freespacemap</title> + <title>pg_freespacemap — examine the free space map</title> <indexterm zone="pgfreespacemap"> <primary>pg_freespacemap</primary> diff --git a/doc/src/sgml/pgprewarm.sgml b/doc/src/sgml/pgprewarm.sgml index e103a2746d..6e1de21303 100644 --- a/doc/src/sgml/pgprewarm.sgml +++ b/doc/src/sgml/pgprewarm.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/pgprewarm.sgml --> <sect1 id="pgprewarm" xreflabel="pg_prewarm"> - <title>pg_prewarm</title> + <title>pg_prewarm — + preload relation data into O/S or PG buffer caches</title> <indexterm zone="pgprewarm"> <primary>pg_prewarm</primary> diff --git a/doc/src/sgml/pgrowlocks.sgml b/doc/src/sgml/pgrowlocks.sgml index 91dfd452ee..b5e655735a 100644 --- a/doc/src/sgml/pgrowlocks.sgml +++ b/doc/src/sgml/pgrowlocks.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgrowlocks.sgml --> <sect1 id="pgrowlocks" xreflabel="pgrowlocks"> - <title>pgrowlocks</title> + <title>pgrowlocks — show a table's row locking information</title> <indexterm zone="pgrowlocks"> <primary>pgrowlocks</primary> diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml index ded33acd18..abdee744ac 100644 --- a/doc/src/sgml/pgstatstatements.sgml +++ b/doc/src/sgml/pgstatstatements.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/pgstatstatements.sgml --> <sect1 id="pgstatstatements" xreflabel="pg_stat_statements"> - <title>pg_stat_statements</title> + <title>pg_stat_statements — + track statistics of SQL planning and execution</title> <indexterm zone="pgstatstatements"> <primary>pg_stat_statements</primary> diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml index 581bea2788..4071da4ed9 100644 --- a/doc/src/sgml/pgstattuple.sgml +++ b/doc/src/sgml/pgstattuple.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgstattuple.sgml --> <sect1 id="pgstattuple" xreflabel="pgstattuple"> - <title>pgstattuple</title> + <title>pgstattuple — obtain tuple-level statistics</title> <indexterm zone="pgstattuple"> <primary>pgstattuple</primary> diff --git a/doc/src/sgml/pgsurgery.sgml b/doc/src/sgml/pgsurgery.sgml index 6c6be70c24..caadc10309 100644 --- a/doc/src/sgml/pgsurgery.sgml +++ b/doc/src/sgml/pgsurgery.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgsurgery.sgml --> <sect1 id="pgsurgery" xreflabel="pg_surgery"> - <title>pg_surgery</title> + <title>pg_surgery — perform surgery on damaged relations</title> <indexterm zone="pgsurgery"> <primary>pg_surgery</primary> diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml index f0344590dd..1497172762 100644 --- a/doc/src/sgml/pgtrgm.sgml +++ b/doc/src/sgml/pgtrgm.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/pgtrgm.sgml --> <sect1 id="pgtrgm" xreflabel="pg_trgm"> - <title>pg_trgm</title> + <title>pg_trgm — + support for similarity of text using trigram matching [trusted]</title> <indexterm zone="pgtrgm"> <primary>pg_trgm</primary> diff --git a/doc/src/sgml/pgvisibility.sgml b/doc/src/sgml/pgvisibility.sgml index 68c43b7f39..097f7e0566 100644 --- a/doc/src/sgml/pgvisibility.sgml +++ b/doc/src/sgml/pgvisibility.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgvisibility.sgml --> <sect1 id="pgvisibility" xreflabel="pg_visibility"> - <title>pg_visibility</title> + <title>pg_visibility — visibility map information and utilities</title> <indexterm zone="pgvisibility"> <primary>pg_visibility</primary> diff --git a/doc/src/sgml/pgwalinspect.sgml b/doc/src/sgml/pgwalinspect.sgml index 08eedab071..119e162e60 100644 --- a/doc/src/sgml/pgwalinspect.sgml +++ b/doc/src/sgml/pgwalinspect.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/pgwalinspect.sgml --> <sect1 id="pgwalinspect" xreflabel="pg_walinspect"> - <title>pg_walinspect</title> + <title>pg_walinspect — low-level WAL inspection</title> <indexterm zone="pgwalinspect"> <primary>pg_walinspect</primary> diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml index 78f2d7d8d5..644f51835b 100644 --- a/doc/src/sgml/postgres-fdw.sgml +++ b/doc/src/sgml/postgres-fdw.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/postgres-fdw.sgml --> <sect1 id="postgres-fdw" xreflabel="postgres_fdw"> - <title>postgres_fdw</title> + <title>postgres_fdw — + access data stored in external Postgres servers</title> <indexterm zone="postgres-fdw"> <primary>postgres_fdw</primary> diff --git a/doc/src/sgml/seg.sgml b/doc/src/sgml/seg.sgml index 72387c7d45..e1d20b4a0e 100644 --- a/doc/src/sgml/seg.sgml +++ b/doc/src/sgml/seg.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/seg.sgml --> <sect1 id="seg" xreflabel="seg"> - <title>seg</title> + <title>seg — + line segment/floating point interval data type [trusted]</title> <indexterm zone="seg"> <primary>seg</primary> diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml index fd4bb83cbf..786fdbbc26 100644 --- a/doc/src/sgml/sepgsql.sgml +++ b/doc/src/sgml/sepgsql.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/sepgsql.sgml --> <sect1 id="sepgsql" xreflabel="sepgsql"> - <title>sepgsql</title> + <title>sepgsql — + SELinux-based row-level security mandatory access control</title> <indexterm zone="sepgsql"> <primary>sepgsql</primary> diff --git a/doc/src/sgml/sslinfo.sgml b/doc/src/sgml/sslinfo.sgml index 786f113072..85d49f6653 100644 --- a/doc/src/sgml/sslinfo.sgml +++ b/doc/src/sgml/sslinfo.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/sslinfo.sgml --> <sect1 id="sslinfo" xreflabel="sslinfo"> - <title>sslinfo</title> + <title>sslinfo — obtain client SSL information</title> <indexterm zone="sslinfo"> <primary>sslinfo</primary> diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl index 0c4dff92c4..9dde0a89dd 100644 --- a/doc/src/sgml/stylesheet-fo.xsl +++ b/doc/src/sgml/stylesheet-fo.xsl @@ -132,4 +132,10 @@ </fo:bookmark> </xsl:template> +<!-- Provide a hard page break processing instruction + http://www.sagehill.net/docbookxsl/PageBreaking.html#HardPageBreaks --> +<xsl:template match="processing-instruction('hard-pagebreak')"> + <fo:block break-after='page'/> +</xsl:template> + </xsl:stylesheet> diff --git a/doc/src/sgml/tablefunc.sgml b/doc/src/sgml/tablefunc.sgml index c1b70953f0..77e0178902 100644 --- a/doc/src/sgml/tablefunc.sgml +++ b/doc/src/sgml/tablefunc.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/tablefunc.sgml --> <sect1 id="tablefunc" xreflabel="tablefunc"> - <title>tablefunc</title> + <title>tablefunc — + useful/example functions which return tables [trusted]</title> <indexterm zone="tablefunc"> <primary>tablefunc</primary> diff --git a/doc/src/sgml/tcn.sgml b/doc/src/sgml/tcn.sgml index 82afe9ada4..60f8ebb80f 100644 --- a/doc/src/sgml/tcn.sgml +++ b/doc/src/sgml/tcn.sgml @@ -1,7 +1,9 @@ <!-- doc/src/sgml/tcn.sgml --> <sect1 id="tcn" xreflabel="tcn"> - <title>tcn</title> + <title>tcn — + a trigger function to notify listeners of changes to table content + [trusted]</title> <indexterm zone="tcn"> <primary>tcn</primary> diff --git a/doc/src/sgml/test-decoding.sgml b/doc/src/sgml/test-decoding.sgml index 9b07195427..88f72c204e 100644 --- a/doc/src/sgml/test-decoding.sgml +++ b/doc/src/sgml/test-decoding.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/test-decoding.sgml --> <sect1 id="test-decoding" xreflabel="test_decoding"> - <title>test_decoding</title> + <title>test_decoding — example of WAL logical decoding in SQL</title> <indexterm zone="test-decoding"> <primary>test_decoding</primary> diff --git a/doc/src/sgml/tsm-system-rows.sgml b/doc/src/sgml/tsm-system-rows.sgml index f5357791c0..2c8ef6a7d4 100644 --- a/doc/src/sgml/tsm-system-rows.sgml +++ b/doc/src/sgml/tsm-system-rows.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/tsm-system-rows.sgml --> <sect1 id="tsm-system-rows" xreflabel="tsm_system_rows"> - <title>tsm_system_rows</title> + <title>tsm_system_rows — + a table row sampling method for TABLESAMPLE clauses [trusted]</title> <indexterm zone="tsm-system-rows"> <primary>tsm_system_rows</primary> diff --git a/doc/src/sgml/tsm-system-time.sgml b/doc/src/sgml/tsm-system-time.sgml index 0de15ae7e8..e532174eab 100644 --- a/doc/src/sgml/tsm-system-time.sgml +++ b/doc/src/sgml/tsm-system-time.sgml @@ -1,7 +1,9 @@ <!-- doc/src/sgml/tsm-system-time.sgml --> <sect1 id="tsm-system-time" xreflabel="tsm_system_time"> - <title>tsm_system_time</title> + <title>tsm_system_time — + a SYSTEM_TIME table sampling method for the TABLESAMPLE clauses + [trusted]</title> <indexterm zone="tsm-system-time"> <primary>tsm_system_time</primary> diff --git a/doc/src/sgml/unaccent.sgml b/doc/src/sgml/unaccent.sgml index 139a87d4ff..38df3be27d 100644 --- a/doc/src/sgml/unaccent.sgml +++ b/doc/src/sgml/unaccent.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/unaccent.sgml --> <sect1 id="unaccent" xreflabel="unaccent"> - <title>unaccent</title> + <title>unaccent — + a full-text search dictionary which removes diacritics [trusted]</title> <indexterm zone="unaccent"> <primary>unaccent</primary> diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml index 0a42d516e8..7cc68cdd92 100644 --- a/doc/src/sgml/uuid-ossp.sgml +++ b/doc/src/sgml/uuid-ossp.sgml @@ -1,7 +1,8 @@ <!-- doc/src/sgml/uuid-ossp.sgml --> <sect1 id="uuid-ossp" xreflabel="uuid-ossp"> - <title>uuid-ossp</title> + <title>uuid-ossp — + generate UUIDs when there are special requirements [trusted]</title> <indexterm zone="uuid-ossp"> <primary>uuid-ossp</primary> diff --git a/doc/src/sgml/xml2.sgml b/doc/src/sgml/xml2.sgml index e9a223ca5b..2bd4a3fd3a 100644 --- a/doc/src/sgml/xml2.sgml +++ b/doc/src/sgml/xml2.sgml @@ -1,7 +1,7 @@ <!-- doc/src/sgml/xml2.sgml --> <sect1 id="xml2" xreflabel="xml2"> - <title>xml2</title> + <title>xml2 — XPath querying and XSLT functionality [obsolete]</title> <indexterm zone="xml2"> <primary>xml2</primary> ^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2023-01-18 19:01 UTC | newest] Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2019-05-28 18:16 [PATCH v24 3/5] Track collation versions for indexes. Thomas Munro <[email protected]> 2023-01-03 00:00 Doc: Rework contrib appendix -- informative titles, tweaked sentences Karl O. Pinc <[email protected]> 2023-01-18 12:25 ` Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences Alvaro Herrera <[email protected]> 2023-01-18 19:01 ` Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences Karl O. Pinc <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox