| blob | 1be27eec52e6e1150f8d29d01d0941f416dd7516 |
1 /*-------------------------------------------------------------------------
2 *
3 * index.c
4 * code to create and destroy POSTGRES index relations
5 *
6 * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
7 * Portions Copyright (c) 1994, Regents of the University of California
8 *
9 *
10 * IDENTIFICATION
11 * src/backend/catalog/index.c
12 *
13 *
14 * INTERFACE ROUTINES
15 * index_create() - Create a cataloged index relation
16 * index_drop() - Removes index relation from catalogs
17 * BuildIndexInfo() - Prepare to insert index tuples
18 * FormIndexDatum() - Construct datum vector for one index tuple
19 *
20 *-------------------------------------------------------------------------
21 */
24 #include <unistd.h>
84 /* Potentially set by pg_upgrade_support functions */
87 /*
88 * Pointer-free representation of variables used when reindexing system
89 * catalogs; we use this to propagate those values to parallel workers.
90 */
92 {
93 Oid currentlyReindexedHeap;
94 Oid currentlyReindexedIndex;
99 /* non-export function prototypes */
104 Oid accessMethodObjectId,
111 Oid parentIndexId,
125 Relation indexRelation,
135 /*
136 * relationHasPrimaryKey
137 * See whether an existing relation has a primary key.
138 *
139 * Caller must have suitable lock on the relation.
140 *
141 * Note: we intentionally do not check indisvalid here; that's because this
142 * is used to enforce the rule that there can be only one indisprimary index,
143 * and we want that to be true even if said index is invalid.
144 */
145 static bool
147 {
152 /*
153 * Get the list of index OIDs for the table from the relcache, and look up
154 * each one in the pg_index syscache until we find one marked primary key
155 * (hopefully there isn't more than one such).
156 */
160 {
162 HeapTuple indexTuple;
171 }
176 }
178 /*
179 * index_check_primary_key
180 * Apply special checks needed before creating a PRIMARY KEY index
181 *
182 * This processing used to be in DefineIndex(), but has been split out
183 * so that it can be applied during ALTER TABLE ADD PRIMARY KEY USING INDEX.
184 *
185 * We check for a pre-existing primary key, and that all columns of the index
186 * are simple column references (not expressions), and that all those
187 * columns are marked NOT NULL. If not, fail.
188 *
189 * We used to automatically change unmarked columns to NOT NULL here by doing
190 * our own local ALTER TABLE command. But that doesn't work well if we're
191 * executing one subcommand of an ALTER TABLE: the operations may not get
192 * performed in the right order overall. Now we expect that the parser
193 * inserted any required ALTER TABLE SET NOT NULL operations before trying
194 * to create a primary-key index.
195 *
196 * Caller had better have at least ShareLock on the table, else the not-null
197 * checking isn't trustworthy.
198 */
199 void
204 {
207 /*
208 * If ALTER TABLE or CREATE TABLE .. PARTITION OF, check that there isn't
209 * already a PRIMARY KEY. In CREATE TABLE for an ordinary relation, we
210 * have faith that the parser rejected multiple pkey clauses; and CREATE
211 * INDEX doesn't have a way to say PRIMARY KEY, so it's no problem either.
212 */
215 {
220 }
222 /*
223 * Check that all of the attributes in a primary key are marked as not
224 * null. (We don't really expect to see that; it'd mean the parser messed
225 * up. But it seems wise to check anyway.)
226 */
228 {
230 HeapTuple atttuple;
231 Form_pg_attribute attform;
238 /* System attributes are never null, so no need to check */
257 }
258 }
260 /*
261 * ConstructTupleDescriptor
262 *
263 * Build an index tuple descriptor for a new index
264 */
265 static TupleDesc
269 Oid accessMethodObjectId,
272 {
278 TupleDesc heapTupDesc;
279 TupleDesc indexTupDesc;
283 /* We need access to the index AM's API struct */
286 /* ... and to the table's tuple descriptor */
290 /*
291 * allocate the new tuple descriptor
292 */
295 /*
296 * Fill in the pg_attribute row.
297 */
299 {
302 HeapTuple tuple;
303 Form_pg_type typeTup;
304 Form_pg_opclass opclassTup;
305 Oid keyType;
315 /*
316 * Set the attribute name as specified by caller.
317 */
323 /*
324 * For simple index columns, we copy some pg_attribute fields from the
325 * parent relation. For expressions we have to look at the expression
326 * result.
327 */
329 {
330 /* Simple index column */
347 }
348 else
349 {
350 /* Expressional index */
358 /*
359 * Lookup the expression type in pg_type for the type length etc.
360 */
367 /*
368 * Assign some of the attributes values. Leave the rest.
369 */
379 /*
380 * Make sure the expression yields a type that's safe to store in
381 * an index. We need this defense because we have index opclasses
382 * for pseudo-types such as "record", and the actually stored type
383 * had better be safe; eg, a named composite type is okay, an
384 * anonymous record type is not. The test is the same as for
385 * whether a table column is of a safe type (which is why we
386 * needn't check for the non-expression case).
387 */
391 }
393 /*
394 * We do not yet have the correct relation OID for the index, so just
395 * set it invalid for now. InitializeAttributeOids() will fix it
396 * later.
397 */
400 /*
401 * Check the opclass and index AM to see if either provides a keytype
402 * (overriding the attribute type). Opclass (if exists) takes
403 * precedence.
404 */
408 {
417 /*
418 * If keytype is specified as ANYELEMENT, and opcintype is
419 * ANYARRAY, then the attribute type must be an array (else it'd
420 * not have matched this opclass); use its element type.
421 *
422 * We could also allow ANYCOMPATIBLE/ANYCOMPATIBLEARRAY here, but
423 * there seems no need to do so; there's no reason to declare an
424 * opclass as taking ANYCOMPATIBLEARRAY rather than ANYARRAY.
425 */
427 {
432 }
435 }
437 /*
438 * If a key type different from the heap value is specified, update
439 * the type-related fields in the index tupdesc.
440 */
442 {
456 }
457 }
462 }
464 /* ----------------------------------------------------------------
465 * InitializeAttributeOids
466 * ----------------------------------------------------------------
467 */
468 static void
471 Oid indexoid)
472 {
473 TupleDesc tupleDescriptor;
480 }
482 /* ----------------------------------------------------------------
483 * AppendAttributeTuples
484 * ----------------------------------------------------------------
485 */
486 static void
488 {
489 Relation pg_attribute;
490 CatalogIndexState indstate;
491 TupleDesc indexTupDesc;
493 /*
494 * open the attribute relation and its indexes
495 */
500 /*
501 * insert data from new index's tupdesc into pg_attribute
502 */
510 }
512 /* ----------------------------------------------------------------
513 * UpdateIndexRelation
514 *
515 * Construct and insert a new entry in the pg_index catalog
516 * ----------------------------------------------------------------
517 */
518 static void
520 Oid heapoid,
521 Oid parentIndexId,
531 {
536 Datum exprsDatum;
537 Datum predDatum;
540 Relation pg_index;
541 HeapTuple tuple;
544 /*
545 * Copy the index key, opclass, and indoption info into arrays (should we
546 * make the caller pass them like this to start with?)
547 */
555 /*
556 * Convert the index expressions (if any) to a text datum
557 */
559 {
565 }
566 else
569 /*
570 * Convert the index predicate (if any) to a text datum. Note we convert
571 * implicit-AND format to normal explicit-AND for storage.
572 */
574 {
580 }
581 else
585 /*
586 * open the system catalog index relation
587 */
590 /*
591 * Build a pg_index tuple
592 */
622 /*
623 * insert the tuple into the pg_index catalog
624 */
627 /*
628 * close the relation and free the tuple
629 */
632 }
635 /*
636 * index_create
637 *
638 * heapRelation: table to build index on (suitably locked by caller)
639 * indexRelationName: what it say
640 * indexRelationId: normally, pass InvalidOid to let this routine
641 * generate an OID for the index. During bootstrap this may be
642 * nonzero to specify a preselected OID.
643 * parentIndexRelid: if creating an index partition, the OID of the
644 * parent index; otherwise InvalidOid.
645 * parentConstraintId: if creating a constraint on a partition, the OID
646 * of the constraint in the parent; otherwise InvalidOid.
647 * relFileNode: normally, pass InvalidOid to get new storage. May be
648 * nonzero to attach an existing valid build.
649 * indexInfo: same info executor uses to insert into the index
650 * indexColNames: column names to use for index (List of char *)
651 * accessMethodObjectId: OID of index AM to use
652 * tableSpaceId: OID of tablespace to use
653 * collationObjectId: array of collation OIDs, one per index column
654 * classObjectId: array of index opclass OIDs, one per index column
655 * coloptions: array of per-index-column indoption settings
656 * reloptions: AM-specific options
657 * flags: bitmask that can include any combination of these bits:
658 * INDEX_CREATE_IS_PRIMARY
659 * the index is a primary key
660 * INDEX_CREATE_ADD_CONSTRAINT:
661 * invoke index_constraint_create also
662 * INDEX_CREATE_SKIP_BUILD:
663 * skip the index_build() step for the moment; caller must do it
664 * later (typically via reindex_index())
665 * INDEX_CREATE_CONCURRENT:
666 * do not lock the table against writers. The index will be
667 * marked "invalid" and the caller must take additional steps
668 * to fix it up.
669 * INDEX_CREATE_IF_NOT_EXISTS:
670 * do not throw an error if a relation with the same name
671 * already exists.
672 * INDEX_CREATE_PARTITIONED:
673 * create a partitioned index (table must be partitioned)
674 * constr_flags: flags passed to index_constraint_create
675 * (only if INDEX_CREATE_ADD_CONSTRAINT is set)
676 * allow_system_table_mods: allow table to be a system catalog
677 * is_internal: if true, post creation hook for new index
678 * constraintId: if not NULL, receives OID of created constraint
679 *
680 * Returns the OID of the created index.
681 */
682 Oid
685 Oid indexRelationId,
686 Oid parentIndexRelid,
687 Oid parentConstraintId,
688 Oid relFileNode,
691 Oid accessMethodObjectId,
692 Oid tableSpaceId,
696 Datum reloptions,
697 bits16 flags,
698 bits16 constr_flags,
702 {
704 Relation pg_class;
705 Relation indexRelation;
706 TupleDesc indexTupDesc;
710 Oid namespaceId;
718 TransactionId relfrozenxid;
719 MultiXactId relminmxid;
721 /* constraint flags can only be set when a constraint is requested */
724 /* partitioned indexes must never be "built" by themselves */
732 /*
733 * The index will be in the same namespace as its parent table, and is
734 * shared across databases if and only if the parent is. Likewise, it
735 * will use the relfilenode map if and only if the parent does; and it
736 * inherits the parent's relpersistence.
737 */
743 /*
744 * check parameters
745 */
756 /*
757 * Btree text_pattern_ops uses text_eq as the equality operator, which is
758 * fine as long as the collation is deterministic; text_eq then reduces to
759 * bitwise equality and so it is semantically compatible with the other
760 * operators and functions in that opclass. But with a nondeterministic
761 * collation, text_eq could yield results that are incompatible with the
762 * actual behavior of the index (which is determined by the opclass's
763 * comparison function). We prevent such problems by refusing creation of
764 * an index with that opclass and a nondeterministic collation.
765 *
766 * The same applies to varchar_pattern_ops and bpchar_pattern_ops. If we
767 * find more cases, we might decide to create a real mechanism for marking
768 * opclasses as incompatible with nondeterminism; but for now, this small
769 * hack suffices.
770 *
771 * Another solution is to use a special operator, not text_eq, as the
772 * equality opclass member; but that is undesirable because it would
773 * prevent index usage in many queries that work fine today.
774 */
776 {
781 {
786 {
787 HeapTuple classtup;
797 }
798 }
799 }
801 /*
802 * Concurrent index build on a system catalog is unsafe because we tend to
803 * release locks before committing in catalogs.
804 */
811 /*
812 * This case is currently not supported. There's no way to ask for it in
813 * the grammar with CREATE INDEX, but it can happen with REINDEX.
814 */
820 /*
821 * We cannot allow indexing a shared relation after initdb (because
822 * there's no way to make the entry in other databases' pg_class).
823 */
829 /*
830 * Shared relations must be in pg_global, too (last-ditch check)
831 */
835 /*
836 * Check for duplicate name (both as to the index, and as to the
837 * associated constraint if any). Such cases would fail on the relevant
838 * catalogs' unique indexes anyway, but we prefer to give a friendlier
839 * error message.
840 */
842 {
844 {
848 indexRelationName)));
851 }
856 indexRelationName)));
857 }
861 indexRelationName))
862 {
863 /*
864 * INDEX_CREATE_IF_NOT_EXISTS does not apply here, since the
865 * conflicting constraint is not an index.
866 */
871 }
873 /*
874 * construct tuple descriptor for index tuples
875 */
877 indexInfo,
878 indexColNames,
879 accessMethodObjectId,
880 collationObjectId,
881 classObjectId);
883 /*
884 * Allocate an OID for the index, unless we were told what to use.
885 *
886 * The OID will be the relfilenode as well, so make sure it doesn't
887 * collide with either pg_class OIDs or existing physical files.
888 */
890 {
891 /* Use binary-upgrade override for pg_class.oid/relfilenode? */
893 {
901 }
902 else
903 {
904 indexRelationId =
906 }
907 }
909 /*
910 * create the index relation's relcache entry and, if necessary, the
911 * physical disk file. (If we fail further down, it's the smgr's
912 * responsibility to remove the disk file again, if any.)
913 */
915 namespaceId,
916 tableSpaceId,
917 indexRelationId,
918 relFileNode,
919 accessMethodObjectId,
920 indexTupDesc,
921 relkind,
922 relpersistence,
923 shared_relation,
924 mapped_relation,
925 allow_system_table_mods,
933 /*
934 * Obtain exclusive lock on it. Although no other transactions can see it
935 * until we commit, this prevents deadlock-risk complaints from lock
936 * manager in cases such as CLUSTER.
937 */
940 /*
941 * Fill in fields of the index's pg_class entry that are not set correctly
942 * by heap_create.
943 *
944 * XXX should have a cleaner way to create cataloged indexes
945 */
950 /*
951 * store index's pg_class entry
952 */
956 reloptions);
958 /* done with pg_class */
961 /*
962 * now update the object id's of all the attribute tuple forms in the
963 * index relation's tuple descriptor
964 */
967 indexRelationId);
969 /*
970 * append ATTRIBUTE tuples for the index
971 */
974 /* ----------------
975 * update pg_index
976 * (append INDEX tuple)
977 *
978 * Note that this stows away a representation of "predicate".
979 * (Or, could define a rule to maintain the predicate) --Nels, Feb '92
980 * ----------------
981 */
983 indexInfo,
990 /*
991 * Register relcache invalidation on the indexes' heap relation, to
992 * maintain consistency of its index list
993 */
996 /* update pg_inherits and the parent's relhassubclass, if needed */
998 {
1001 }
1003 /*
1004 * Register constraint and dependencies for the index.
1005 *
1006 * If the index is from a CONSTRAINT clause, construct a pg_constraint
1007 * entry. The index will be linked to the constraint, which in turn is
1008 * linked to the table. If it's not a CONSTRAINT, we need to make a
1009 * dependency directly on the table.
1010 *
1011 * We don't need a dependency on the namespace, because there'll be an
1012 * indirect dependency via our parent table.
1013 *
1014 * During bootstrap we can't register any dependencies, and we don't try
1015 * to make a constraint either.
1016 */
1018 {
1019 ObjectAddress myself,
1020 referenced;
1025 {
1027 ObjectAddress localaddr;
1035 else
1036 {
1039 }
1042 indexRelationId,
1043 parentConstraintId,
1044 indexInfo,
1045 indexRelationName,
1046 constraintType,
1047 constr_flags,
1048 allow_system_table_mods,
1049 is_internal);
1052 }
1053 else
1054 {
1057 /* Create auto dependencies on simply-referenced columns */
1059 {
1061 {
1063 heapRelationId,
1067 }
1068 }
1070 /*
1071 * If there are no simply-referenced columns, give the index an
1072 * auto dependency on the whole table. In most cases, this will
1073 * be redundant, but it might not be if the index expressions and
1074 * predicate contain no Vars or only whole-row Vars.
1075 */
1077 {
1079 heapRelationId);
1081 }
1082 }
1084 /*
1085 * If this is an index partition, create partition dependencies on
1086 * both the parent index and the table. (Note: these must be *in
1087 * addition to*, not instead of, all other dependencies. Otherwise
1088 * we'll be short some dependencies after DETACH PARTITION.)
1089 */
1091 {
1097 }
1099 /* Store dependency on collations */
1100 /* The default collation is pinned, so don't bother recording it */
1102 {
1105 {
1109 }
1110 }
1112 /* Store dependency on operator classes */
1114 {
1117 }
1119 /* Store dependencies on anything mentioned in index expressions */
1121 {
1124 heapRelationId,
1125 DEPENDENCY_NORMAL,
1127 }
1129 /* Store dependencies on anything mentioned in predicate */
1131 {
1134 heapRelationId,
1135 DEPENDENCY_NORMAL,
1137 }
1138 }
1139 else
1140 {
1141 /* Bootstrap mode - assert we weren't asked for constraint support */
1143 }
1145 /* Post creation hook for new index */
1149 /*
1150 * Advance the command counter so that we can see the newly-entered
1151 * catalog tuples for the index.
1152 */
1155 /*
1156 * In bootstrap mode, we have to fill in the index strategy structure with
1157 * information from the catalogs. If we aren't bootstrapping, then the
1158 * relcache entry has already been rebuilt thanks to sinval update during
1159 * CommandCounterIncrement.
1160 */
1163 else
1168 /* Validate opclass-specific options */
1175 /*
1176 * If this is bootstrap (initdb) time, then we don't actually fill in the
1177 * index yet. We'll be creating more indexes and classes later, so we
1178 * delay filling them in until just before we're done with bootstrapping.
1179 * Similarly, if the caller specified to skip the build then filling the
1180 * index is delayed till later (ALTER TABLE can save work in some cases
1181 * with this). Otherwise, we call the AM routine that constructs the
1182 * index.
1183 */
1185 {
1187 }
1189 {
1190 /*
1191 * Caller is responsible for filling the index later on. However,
1192 * we'd better make sure that the heap relation is correctly marked as
1193 * having an index.
1194 */
1198 /* Make the above update visible */
1200 }
1201 else
1202 {
1204 }
1206 /*
1207 * Close the index; but we keep the lock that we acquired above until end
1208 * of transaction. Closing the heap is caller's responsibility.
1209 */
1213 }
1215 /*
1216 * index_concurrently_create_copy
1217 *
1218 * Create concurrently an index based on the definition of the one provided by
1219 * caller. The index is inserted into catalogs and needs to be built later
1220 * on. This is called during concurrent reindex processing.
1221 */
1222 Oid
1224 {
1225 Relation indexRelation;
1229 HeapTuple indexTuple,
1230 classTuple;
1231 Datum indclassDatum,
1232 colOptionDatum,
1233 optionDatum;
1243 /* The new index needs some information from the old index */
1246 /*
1247 * Concurrent build of an index with exclusion constraints is not
1248 * supported.
1249 */
1255 /* Get the array of class and column options IDs from index info */
1269 /* Fetch options of index if any */
1276 /*
1277 * Fetch the list of expressions and predicates directly from the
1278 * catalogs. This cannot rely on the information from IndexInfo of the
1279 * old index as these have been flattened for the planner.
1280 */
1282 {
1283 Datum exprDatum;
1292 }
1294 {
1295 Datum predDatum;
1304 /* Also convert to implicit-AND format */
1307 }
1309 /*
1310 * Build the index information for the new index. Note that rebuild of
1311 * indexes with exclusion constraints is not supported, hence there is no
1312 * need to fill all the ii_Exclusion* fields.
1313 */
1317 indexExprs,
1318 indexPreds,
1323 /*
1324 * Extract the list of column names and the column numbers for the new
1325 * index information. All this information will be used for the index
1326 * creation.
1327 */
1329 {
1335 }
1337 /*
1338 * Now create the new index.
1339 *
1340 * For a partition index, we adjust the partition dependency later, to
1341 * ensure a consistent state at all times. That is why parentIndexRelid
1342 * is not set here.
1343 */
1345 newName,
1350 newInfo,
1351 indexColNames,
1357 optionDatum,
1362 NULL);
1364 /* Close the relations used and clean up */
1370 }
1372 /*
1373 * index_concurrently_build
1374 *
1375 * Build index for a concurrent operation. Low-level locks are taken when
1376 * this operation is performed to prevent only schema changes, but they need
1377 * to be kept until the end of the transaction performing this operation.
1378 * 'indexOid' refers to an index relation OID already created as part of
1379 * previous processing, and 'heapOid' refers to its parent heap relation.
1380 */
1381 void
1383 Oid indexRelationId)
1384 {
1385 Relation heapRel;
1386 Relation indexRelation;
1389 /* This had better make sure that a snapshot is active */
1392 /* Open and lock the parent heap relation */
1395 /* And the target index relation */
1398 /*
1399 * We have to re-build the IndexInfo struct, since it was lost in the
1400 * commit of the transaction where this concurrent index was created at
1401 * the catalog level.
1402 */
1408 /* Now build the index */
1411 /* Close both the relations, but keep the locks */
1415 /*
1416 * Update the pg_index row to mark the index as ready for inserts. Once we
1417 * commit this transaction, any new transactions that open the table must
1418 * insert new entries into the index for insertions and non-HOT updates.
1419 */
1421 }
1423 /*
1424 * index_concurrently_swap
1425 *
1426 * Swap name, dependencies, and constraints of the old index over to the new
1427 * index, while marking the old index as invalid and the new as valid.
1428 */
1429 void
1431 {
1432 Relation pg_class,
1433 pg_index,
1434 pg_constraint,
1435 pg_trigger;
1436 Relation oldClassRel,
1437 newClassRel;
1438 HeapTuple oldClassTuple,
1439 newClassTuple;
1440 Form_pg_class oldClassForm,
1441 newClassForm;
1442 HeapTuple oldIndexTuple,
1443 newIndexTuple;
1444 Form_pg_index oldIndexForm,
1445 newIndexForm;
1447 Oid indexConstraintOid;
1451 /*
1452 * Take a necessary lock on the old and new index before swapping them.
1453 */
1457 /* Now swap names and dependencies of those indexes */
1472 /* Swap the names */
1476 /* Swap the partition flags to track inheritance properly */
1487 /* Now swap index info */
1502 /*
1503 * Copy constraint flags from the old index. This is safe because the old
1504 * index guaranteed uniqueness.
1505 */
1513 /* Preserve indisreplident in the new index */
1517 /* Preserve indisclustered in the new index */
1520 /*
1521 * Mark the new index as valid, and the old index as invalid similarly to
1522 * what index_set_state_flags() does.
1523 */
1534 /*
1535 * Move constraints and triggers over to the new index
1536 */
1549 {
1550 HeapTuple constraintTuple,
1551 triggerTuple;
1552 Form_pg_constraint conForm;
1554 SysScanDesc scan;
1557 /* Move the constraint from the old to the new index */
1566 {
1570 }
1574 /* Search for trigger records */
1576 Anum_pg_trigger_tgconstraint,
1584 {
1590 /* Make a modifiable copy */
1599 }
1602 }
1604 /*
1605 * Move comment if any
1606 */
1607 {
1608 Relation description;
1610 SysScanDesc sd;
1611 HeapTuple tuple;
1620 Anum_pg_description_objoid,
1624 Anum_pg_description_classoid,
1628 Anum_pg_description_objsubid,
1638 {
1644 }
1648 }
1650 /*
1651 * Swap inheritance relationship with parent index
1652 */
1654 {
1662 }
1664 /*
1665 * Swap all dependencies of and on the old index to the new one, and
1666 * vice-versa. Note that a call to CommandCounterIncrement() would cause
1667 * duplicate entries in pg_depend, so this should not be done.
1668 */
1675 /*
1676 * Copy over statistics from old to new index
1677 */
1678 {
1683 {
1685 {
1692 /*
1693 * The data will be sent by the next pgstat_report_stat()
1694 * call.
1695 */
1696 }
1697 }
1698 }
1700 /* Close relations */
1706 /* The lock taken previously is not released until the end of transaction */
1709 }
1711 /*
1712 * index_concurrently_set_dead
1713 *
1714 * Perform the last invalidation stage of DROP INDEX CONCURRENTLY or REINDEX
1715 * CONCURRENTLY before actually dropping the index. After calling this
1716 * function, the index is seen by all the backends as dead. Low-level locks
1717 * taken here are kept until the end of the transaction calling this function.
1718 */
1719 void
1721 {
1722 Relation userHeapRelation;
1723 Relation userIndexRelation;
1725 /*
1726 * No more predicate locks will be acquired on this index, and we're about
1727 * to stop doing inserts into the index which could show conflicts with
1728 * existing predicate locks, so now is the time to move them to the heap
1729 * relation.
1730 */
1735 /*
1736 * Now we are sure that nobody uses the index for queries; they just might
1737 * have it open for updating it. So now we can unset indisready and
1738 * indislive, then wait till nobody could be using it at all anymore.
1739 */
1742 /*
1743 * Invalidate the relcache for the table, so that after this commit all
1744 * sessions will refresh the table's index list. Forgetting just the
1745 * index's relcache entry is not enough.
1746 */
1749 /*
1750 * Close the relations again, though still holding session lock.
1751 */
1754 }
1756 /*
1757 * index_constraint_create
1758 *
1759 * Set up a constraint associated with an index. Return the new constraint's
1760 * address.
1761 *
1762 * heapRelation: table owning the index (must be suitably locked by caller)
1763 * indexRelationId: OID of the index
1764 * parentConstraintId: if constraint is on a partition, the OID of the
1765 * constraint in the parent.
1766 * indexInfo: same info executor uses to insert into the index
1767 * constraintName: what it say (generally, should match name of index)
1768 * constraintType: one of CONSTRAINT_PRIMARY, CONSTRAINT_UNIQUE, or
1769 * CONSTRAINT_EXCLUSION
1770 * flags: bitmask that can include any combination of these bits:
1771 * INDEX_CONSTR_CREATE_MARK_AS_PRIMARY: index is a PRIMARY KEY
1772 * INDEX_CONSTR_CREATE_DEFERRABLE: constraint is DEFERRABLE
1773 * INDEX_CONSTR_CREATE_INIT_DEFERRED: constraint is INITIALLY DEFERRED
1774 * INDEX_CONSTR_CREATE_UPDATE_INDEX: update the pg_index row
1775 * INDEX_CONSTR_CREATE_REMOVE_OLD_DEPS: remove existing dependencies
1776 * of index on table's columns
1777 * allow_system_table_mods: allow table to be a system catalog
1778 * is_internal: index is constructed due to internal process
1779 */
1780 ObjectAddress
1782 Oid indexRelationId,
1783 Oid parentConstraintId,
1787 bits16 constr_flags,
1790 {
1792 ObjectAddress myself,
1793 idxaddr;
1794 Oid conOid;
1806 /* constraint creation support doesn't work while bootstrapping */
1809 /* enforce system-table restriction */
1817 /* primary/unique constraints shouldn't have any expressions */
1822 /*
1823 * If we're manufacturing a constraint for a pre-existing index, we need
1824 * to get rid of the existing auto dependencies for the index (the ones
1825 * that index_create() would have made instead of calling this function).
1826 *
1827 * Note: this code would not necessarily do the right thing if the index
1828 * has any expressions or predicate, but we'd never be turning such an
1829 * index into a UNIQUE or PRIMARY KEY constraint.
1830 */
1836 {
1840 }
1841 else
1842 {
1846 }
1848 /*
1849 * Construct a pg_constraint entry.
1850 */
1852 namespaceId,
1853 constraintType,
1854 deferrable,
1855 initdeferred,
1857 parentConstraintId,
1865 NULL,
1866 NULL,
1867 NULL,
1868 NULL,
1875 NULL,
1876 islocal,
1877 inhcount,
1878 noinherit,
1879 is_internal);
1881 /*
1882 * Register the index as internally dependent on the constraint.
1883 *
1884 * Note that the constraint has a dependency on the table, so we don't
1885 * need (or want) any direct dependency from the index to the table.
1886 */
1891 /*
1892 * Also, if this is a constraint on a partition, give it partition-type
1893 * dependencies on the parent constraint as well as the table.
1894 */
1896 {
1897 ObjectAddress referenced;
1904 }
1906 /*
1907 * If the constraint is deferrable, create the deferred uniqueness
1908 * checking trigger. (The trigger will be given an internal dependency on
1909 * the constraint by CreateTrigger.)
1910 */
1912 {
1935 }
1937 /*
1938 * If needed, mark the index as primary and/or deferred in pg_index.
1939 *
1940 * Note: When making an existing index into a constraint, caller must have
1941 * a table lock that prevents concurrent table updates; otherwise, there
1942 * is a risk that concurrent readers of the table will miss seeing this
1943 * index at all.
1944 */
1947 {
1948 Relation pg_index;
1949 HeapTuple indexTuple;
1950 Form_pg_index indexForm;
1962 {
1965 }
1968 {
1971 }
1974 {
1979 }
1983 }
1986 }
1988 /*
1989 * index_drop
1990 *
1991 * NOTE: this routine should now only be called through performDeletion(),
1992 * else associated dependencies won't be cleaned up.
1993 *
1994 * If concurrent is true, do a DROP INDEX CONCURRENTLY. If concurrent is
1995 * false but concurrent_lock_mode is true, then do a normal DROP INDEX but
1996 * take a lock for CONCURRENTLY processing. That is used as part of REINDEX
1997 * CONCURRENTLY.
1998 */
1999 void
2001 {
2002 Oid heapId;
2003 Relation userHeapRelation;
2004 Relation userIndexRelation;
2005 Relation indexRelation;
2006 HeapTuple tuple;
2008 LockRelId heaprelid,
2009 indexrelid;
2010 LOCKTAG heaplocktag;
2011 LOCKMODE lockmode;
2013 /*
2014 * A temporary relation uses a non-concurrent DROP. Other backends can't
2015 * access a temporary relation, so there's no harm in grabbing a stronger
2016 * lock (see comments in RemoveRelations), and a non-concurrent DROP is
2017 * more efficient.
2018 */
2022 /*
2023 * To drop an index safely, we must grab exclusive lock on its parent
2024 * table. Exclusive lock on the index alone is insufficient because
2025 * another backend might be about to execute a query on the parent table.
2026 * If it relies on a previously cached list of index OIDs, then it could
2027 * attempt to access the just-dropped index. We must therefore take a
2028 * table lock strong enough to prevent all queries on the table from
2029 * proceeding until we commit and send out a shared-cache-inval notice
2030 * that will make them update their index lists.
2031 *
2032 * In the concurrent case we avoid this requirement by disabling index use
2033 * in multiple steps and waiting out any transactions that might be using
2034 * the index, so we don't need exclusive lock on the parent table. Instead
2035 * we take ShareUpdateExclusiveLock, to ensure that two sessions aren't
2036 * doing CREATE/DROP INDEX CONCURRENTLY on the same index. (We will get
2037 * AccessExclusiveLock on the index below, once we're sure nobody else is
2038 * using it.)
2039 */
2041 lockmode = (concurrent || concurrent_lock_mode) ? ShareUpdateExclusiveLock : AccessExclusiveLock;
2045 /*
2046 * We might still have open queries using it in our own session, which the
2047 * above locking won't prevent, so test explicitly.
2048 */
2051 /*
2052 * Drop Index Concurrently is more or less the reverse process of Create
2053 * Index Concurrently.
2054 *
2055 * First we unset indisvalid so queries starting afterwards don't use the
2056 * index to answer queries anymore. We have to keep indisready = true so
2057 * transactions that are still scanning the index can continue to see
2058 * valid index contents. For instance, if they are using READ COMMITTED
2059 * mode, and another transaction makes changes and commits, they need to
2060 * see those new tuples in the index.
2061 *
2062 * After all transactions that could possibly have used the index for
2063 * queries end, we can unset indisready and indislive, then wait till
2064 * nobody could be touching it anymore. (Note: we need indislive because
2065 * this state must be distinct from the initial state during CREATE INDEX
2066 * CONCURRENTLY, which has indislive true while indisready and indisvalid
2067 * are false. That's because in that state, transactions must examine the
2068 * index for HOT-safety decisions, while in this state we don't want them
2069 * to open it at all.)
2070 *
2071 * Since all predicate locks on the index are about to be made invalid, we
2072 * must promote them to predicate locks on the heap. In the
2073 * non-concurrent case we can just do that now. In the concurrent case
2074 * it's a bit trickier. The predicate locks must be moved when there are
2075 * no index scans in progress on the index and no more can subsequently
2076 * start, so that no new predicate locks can be made on the index. Also,
2077 * they must be moved before heap inserts stop maintaining the index, else
2078 * the conflict with the predicate lock on the index gap could be missed
2079 * before the lock on the heap relation is in place to detect a conflict
2080 * based on the heap tuple insert.
2081 */
2083 {
2084 /*
2085 * We must commit our transaction in order to make the first pg_index
2086 * state update visible to other sessions. If the DROP machinery has
2087 * already performed any other actions (removal of other objects,
2088 * pg_depend entries, etc), the commit would make those actions
2089 * permanent, which would leave us with inconsistent catalog state if
2090 * we fail partway through the following sequence. Since DROP INDEX
2091 * CONCURRENTLY is restricted to dropping just one index that has no
2092 * dependencies, we should get here before anything's been done ---
2093 * but let's check that to be sure. We can verify that the current
2094 * transaction has not executed any transactional updates by checking
2095 * that no XID has been assigned.
2096 */
2102 /*
2103 * Mark index invalid by updating its pg_index entry
2104 */
2107 /*
2108 * Invalidate the relcache for the table, so that after this commit
2109 * all sessions will refresh any cached plans that might reference the
2110 * index.
2111 */
2114 /* save lockrelid and locktag for below, then close but keep locks */
2122 /*
2123 * We must commit our current transaction so that the indisvalid
2124 * update becomes visible to other transactions; then start another.
2125 * Note that any previously-built data structures are lost in the
2126 * commit. The only data we keep past here are the relation IDs.
2127 *
2128 * Before committing, get a session-level lock on the table, to ensure
2129 * that neither it nor the index can be dropped before we finish. This
2130 * cannot block, even if someone else is waiting for access, because
2131 * we already have the same lock within our transaction.
2132 */
2140 /*
2141 * Now we must wait until no running transaction could be using the
2142 * index for a query. Use AccessExclusiveLock here to check for
2143 * running transactions that hold locks of any kind on the table. Note
2144 * we do not need to worry about xacts that open the table for reading
2145 * after this point; they will see the index as invalid when they open
2146 * the relation.
2147 *
2148 * Note: the reason we use actual lock acquisition here, rather than
2149 * just checking the ProcArray and sleeping, is that deadlock is
2150 * possible if one of the transactions in question is blocked trying
2151 * to acquire an exclusive lock on our table. The lock code will
2152 * detect deadlock and error out properly.
2153 *
2154 * Note: we report progress through WaitForLockers() unconditionally
2155 * here, even though it will only be used when we're called by REINDEX
2156 * CONCURRENTLY and not when called by DROP INDEX CONCURRENTLY.
2157 */
2160 /* Finish invalidation of index and mark it as dead */
2163 /*
2164 * Again, commit the transaction to make the pg_index update visible
2165 * to other sessions.
2166 */
2170 /*
2171 * Wait till every transaction that saw the old index state has
2172 * finished. See above about progress reporting.
2173 */
2176 /*
2177 * Re-open relations to allow us to complete our actions.
2178 *
2179 * At this point, nothing should be accessing the index, but lets
2180 * leave nothing to chance and grab AccessExclusiveLock on the index
2181 * before the physical deletion.
2182 */
2185 }
2186 else
2187 {
2188 /* Not concurrent, so just transfer predicate locks and we're good */
2190 }
2192 /*
2193 * Schedule physical removal of the files (if any)
2194 */
2198 /*
2199 * Close and flush the index's relcache entry, to ensure relcache doesn't
2200 * try to rebuild it while we're deleting catalog entries. We keep the
2201 * lock though.
2202 */
2207 /*
2208 * fix INDEX relation, and check for expressional index
2209 */
2224 /*
2225 * if it has any expression columns, we might have stored statistics about
2226 * them.
2227 */
2231 /*
2232 * fix ATTRIBUTE relation
2233 */
2236 /*
2237 * fix RELATION relation
2238 */
2241 /*
2242 * fix INHERITS relation
2243 */
2246 /*
2247 * We are presently too lazy to attempt to compute the new correct value
2248 * of relhasindex (the next VACUUM will fix it if necessary). So there is
2249 * no need to update the pg_class tuple for the owning relation. But we
2250 * must send out a shared-cache-inval notice on the owning relation to
2251 * ensure other backends update their relcache lists of indexes. (In the
2252 * concurrent case, this is redundant but harmless.)
2253 */
2256 /*
2257 * Close owning rel, but keep lock
2258 */
2261 /*
2262 * Release the session locks before we go.
2263 */
2265 {
2268 }
2269 }
2271 /* ----------------------------------------------------------------
2272 * index_build support
2273 * ----------------------------------------------------------------
2274 */
2276 /* ----------------
2277 * BuildIndexInfo
2278 * Construct an IndexInfo record for an open index
2279 *
2280 * IndexInfo stores the information about the index that's needed by
2281 * FormIndexDatum, which is used for both index_build() and later insertion
2282 * of individual index tuples. Normally we build an IndexInfo for an index
2283 * just once per command, and then use it for (potentially) many tuples.
2284 * ----------------
2285 */
2286 IndexInfo *
2288 {
2294 /* check the number of keys, and copy attr numbers into the IndexInfo */
2300 /*
2301 * Create the node, fetching any expressions needed for expressional
2302 * indexes and index predicate if any.
2303 */
2313 /* fill in attribute numbers */
2317 /* fetch exclusion constraint info if any */
2319 {
2324 }
2329 }
2331 /* ----------------
2332 * BuildDummyIndexInfo
2333 * Construct a dummy IndexInfo record for an open index
2334 *
2335 * This differs from the real BuildIndexInfo in that it will never run any
2336 * user-defined code that might exist in index expressions or predicates.
2337 * Instead of the real index expressions, we return null constants that have
2338 * the right types/typmods/collations. Predicates and exclusion clauses are
2339 * just ignored. This is sufficient for the purpose of truncating an index,
2340 * since we will not need to actually evaluate the expressions or predicates;
2341 * the only thing that's likely to be done with the data is construction of
2342 * a tupdesc describing the index's rowtype.
2343 * ----------------
2344 */
2345 IndexInfo *
2347 {
2353 /* check the number of keys, and copy attr numbers into the IndexInfo */
2359 /*
2360 * Create the node, using dummy index expressions, and pretending there is
2361 * no predicate.
2362 */
2367 NIL,
2372 /* fill in attribute numbers */
2376 /* We ignore the exclusion constraint if any */
2379 }
2381 /*
2382 * CompareIndexInfo
2383 * Return whether the properties of two indexes (in different tables)
2384 * indicate that they have the "same" definitions.
2385 *
2386 * Note: passing collations and opfamilies separately is a kludge. Adding
2387 * them to IndexInfo may result in better coding here and elsewhere.
2388 *
2389 * Use build_attrmap_by_name(index2, index1) to build the attmap.
2390 */
2391 bool
2396 {
2402 /* indexes are only equivalent if they have the same access method */
2406 /* and same number of attributes */
2410 /* and same number of key attributes */
2414 /*
2415 * and columns match through the attribute map (actual attribute numbers
2416 * might differ!) Note that this implies that index columns that are
2417 * expressions appear in the same positions. We will next compare the
2418 * expressions themselves.
2419 */
2421 {
2425 /* ignore expressions at this stage */
2431 /* collation and opfamily is not valid for including columns */
2439 }
2441 /*
2442 * For expression indexes: either both are expression indexes, or neither
2443 * is; if they are, make sure the expressions match.
2444 */
2448 {
2456 {
2457 /*
2458 * we could throw an error here, but seems out of scope for this
2459 * routine.
2460 */
2462 }
2466 }
2468 /* Partial index predicates must be identical, if they exist */
2472 {
2480 {
2481 /*
2482 * we could throw an error here, but seems out of scope for this
2483 * routine.
2484 */
2486 }
2489 }
2491 /* No support currently for comparing exclusion indexes. */
2496 }
2498 /* ----------------
2499 * BuildSpeculativeIndexInfo
2500 * Add extra state to IndexInfo record
2501 *
2502 * For unique indexes, we usually don't want to add info to the IndexInfo for
2503 * checking uniqueness, since the B-Tree AM handles that directly. However,
2504 * in the case of speculative insertion, additional support is required.
2505 *
2506 * Do this processing here rather than in BuildIndexInfo() to not incur the
2507 * overhead in the common non-speculative cases.
2508 * ----------------
2509 */
2510 void
2512 {
2518 /*
2519 * fetch info for checking unique indexes
2520 */
2530 /*
2531 * We have to look up the operator's strategy number. This provides a
2532 * cross-check that the operator does match the index.
2533 */
2534 /* We need the func OIDs and strategy numbers too */
2536 {
2548 }
2549 }
2551 /* ----------------
2552 * FormIndexDatum
2553 * Construct values[] and isnull[] arrays for a new index tuple.
2554 *
2555 * indexInfo Info about the index
2556 * slot Heap tuple for which we must prepare an index entry
2557 * estate executor state for evaluating any index expressions
2558 * values Array of index Datums (output area)
2559 * isnull Array of is-null indicators (output area)
2560 *
2561 * When there are no index expressions, estate may be NULL. Otherwise it
2562 * must be supplied, *and* the ecxt_scantuple slot of its per-tuple expr
2563 * context must point to the heap tuple passed in.
2564 *
2565 * Notice we don't actually call index_form_tuple() here; we just prepare
2566 * its input arrays values[] and isnull[]. This is because the index AM
2567 * may wish to alter the data before storage.
2568 * ----------------
2569 */
2570 void
2576 {
2582 {
2583 /* First time through, set up expression evaluation state */
2586 /* Check caller has set up context correctly */
2588 }
2592 {
2594 Datum iDatum;
2600 {
2601 /*
2602 * Plain index column; get the value we need directly from the
2603 * heap tuple.
2604 */
2606 }
2607 else
2608 {
2609 /*
2610 * Index expression --- need to evaluate it.
2611 */
2618 }
2621 }
2625 }
2628 /*
2629 * index_update_stats --- update pg_class entry after CREATE INDEX or REINDEX
2630 *
2631 * This routine updates the pg_class row of either an index or its parent
2632 * relation after CREATE INDEX or REINDEX. Its rather bizarre API is designed
2633 * to ensure we can do all the necessary work in just one update.
2634 *
2635 * hasindex: set relhasindex to this value
2636 * reltuples: if >= 0, set reltuples to this value; else no change
2637 *
2638 * If reltuples >= 0, relpages and relallvisible are also updated (using
2639 * RelationGetNumberOfBlocks() and visibilitymap_count()).
2640 *
2641 * NOTE: an important side-effect of this operation is that an SI invalidation
2642 * message is sent out to all backends --- including me --- causing relcache
2643 * entries to be flushed or updated with the new data. This must happen even
2644 * if we find that no change is needed in the pg_class row. When updating
2645 * a heap entry, this ensures that other backends find out about the new
2646 * index. When updating an index, it's important because some index AMs
2647 * expect a relcache flush to occur after REINDEX.
2648 */
2649 static void
2653 {
2655 Relation pg_class;
2656 HeapTuple tuple;
2657 Form_pg_class rd_rel;
2660 /*
2661 * We always update the pg_class row using a non-transactional,
2662 * overwrite-in-place update. There are several reasons for this:
2663 *
2664 * 1. In bootstrap mode, we have no choice --- UPDATE wouldn't work.
2665 *
2666 * 2. We could be reindexing pg_class itself, in which case we can't move
2667 * its pg_class row because CatalogTupleInsert/CatalogTupleUpdate might
2668 * not know about all the indexes yet (see reindex_relation).
2669 *
2670 * 3. Because we execute CREATE INDEX with just share lock on the parent
2671 * rel (to allow concurrent index creations), an ordinary update could
2672 * suffer a tuple-concurrently-updated failure against another CREATE
2673 * INDEX committing at about the same time. We can avoid that by having
2674 * them both do nontransactional updates (we assume they will both be
2675 * trying to change the pg_class row to the same thing, so it doesn't
2676 * matter which goes first).
2677 *
2678 * It is safe to use a non-transactional update even though our
2679 * transaction could still fail before committing. Setting relhasindex
2680 * true is safe even if there are no indexes (VACUUM will eventually fix
2681 * it). And of course the new relpages and reltuples counts are correct
2682 * regardless. However, we don't want to change relpages (or
2683 * relallvisible) if the caller isn't providing an updated reltuples
2684 * count, because that would bollix the reltuples/relpages ratio which is
2685 * what's really important.
2686 */
2690 /*
2691 * Make a copy of the tuple to update. Normally we use the syscache, but
2692 * we can't rely on that during bootstrap or while reindexing pg_class
2693 * itself.
2694 */
2697 {
2698 /* don't assume syscache will work */
2699 TableScanDesc pg_class_scan;
2703 Anum_pg_class_oid,
2711 }
2712 else
2713 {
2714 /* normal case, use syscache */
2716 }
2722 /* Should this be a more comprehensive test? */
2725 /* Apply required updates, if any, to copied tuple */
2729 {
2732 }
2735 {
2737 BlockNumber relallvisible;
2745 {
2748 }
2750 {
2753 }
2755 {
2758 }
2759 }
2761 /*
2762 * If anything changed, write out the tuple
2763 */
2765 {
2767 /* the above sends a cache inval message */
2768 }
2769 else
2770 {
2771 /* no need to change tuple, but force relcache inval anyway */
2773 }
2778 }
2781 /*
2782 * index_build - invoke access-method-specific index build procedure
2783 *
2784 * On entry, the index's catalog entries are valid, and its physical disk
2785 * file has been created but is empty. We call the AM-specific build
2786 * procedure to fill in the index contents. We then update the pg_class
2787 * entries of the index and heap relation as needed, using statistics
2788 * returned by ambuild as well as data passed by the caller.
2789 *
2790 * isreindex indicates we are recreating a previously-existing index.
2791 * parallel indicates if parallelism may be useful.
2792 *
2793 * Note: before Postgres 8.2, the passed-in heap and index Relations
2794 * were automatically closed by this routine. This is no longer the case.
2795 * The caller opened 'em, and the caller should close 'em.
2796 */
2797 void
2799 Relation indexRelation,
2803 {
2805 Oid save_userid;
2809 /*
2810 * sanity checks
2811 */
2817 /*
2818 * Determine worker process details for parallel CREATE INDEX. Currently,
2819 * only btree has support for parallel builds.
2820 *
2821 * Note that planner considers parallel safety for us.
2822 */
2834 else
2843 /*
2844 * Switch to the table owner's userid, so that any index functions are run
2845 * as that user. Also lock down security-restricted operations and
2846 * arrange to make GUC variable changes local to this command.
2847 */
2853 /* Set up initial progress report status */
2854 {
2856 PROGRESS_CREATEIDX_PHASE,
2857 PROGRESS_CREATEIDX_SUBPHASE,
2858 PROGRESS_CREATEIDX_TUPLES_DONE,
2859 PROGRESS_CREATEIDX_TUPLES_TOTAL,
2860 PROGRESS_SCAN_BLOCKS_DONE,
2861 PROGRESS_SCAN_BLOCKS_TOTAL
2862 };
2864 PROGRESS_CREATEIDX_PHASE_BUILD,
2865 PROGRESS_CREATEIDX_SUBPHASE_INITIALIZE,
2867 };
2870 }
2872 /*
2873 * Call the access method's build procedure
2874 */
2876 indexInfo);
2879 /*
2880 * If this is an unlogged index, we may need to write out an init fork for
2881 * it -- but we must first check whether one already exists. If, for
2882 * example, an unlogged relation is truncated in the transaction that
2883 * created it, or truncated twice in a subsequent transaction, the
2884 * relfilenode won't change, and nothing needs to be done here.
2885 */
2888 {
2892 }
2894 /*
2895 * If we found any potentially broken HOT chains, mark the index as not
2896 * being usable until the current transaction is below the event horizon.
2897 * See src/backend/access/heap/README.HOT for discussion. Also set this
2898 * if early pruning/vacuuming is enabled for the heap relation. While it
2899 * might become safe to use the index earlier based on actual cleanup
2900 * activity and other active transactions, the test for that would be much
2901 * more complex and would require some form of blocking, so keep it simple
2902 * and fast by just using the current transaction.
2903 *
2904 * However, when reindexing an existing index, we should do nothing here.
2905 * Any HOT chains that are broken with respect to the index must predate
2906 * the index's original creation, so there is no need to change the
2907 * index's usability horizon. Moreover, we *must not* try to change the
2908 * index's pg_index entry while reindexing pg_index itself, and this
2909 * optimization nicely prevents that. The more complex rules needed for a
2910 * reindex are handled separately after this function returns.
2911 *
2912 * We also need not set indcheckxmin during a concurrent index build,
2913 * because we won't set indisvalid true until all transactions that care
2914 * about the broken HOT chains or early pruning/vacuuming are gone.
2915 *
2916 * Therefore, this code path can only be taken during non-concurrent
2917 * CREATE INDEX. Thus the fact that heap_update will set the pg_index
2918 * tuple's xmin doesn't matter, because that tuple was created in the
2919 * current transaction anyway. That also means we don't need to worry
2920 * about any concurrent readers of the tuple; no other transaction can see
2921 * it yet.
2922 */
2926 {
2928 Relation pg_index;
2929 HeapTuple indexTuple;
2930 Form_pg_index indexForm;
2940 /* If it's a new index, indcheckxmin shouldn't be set ... */
2948 }
2950 /*
2951 * Update heap and index pg_class rows
2952 */
2961 /* Make the updated catalog row versions visible */
2964 /*
2965 * If it's for an exclusion constraint, make a second pass over the heap
2966 * to verify that the constraint is satisfied. We must not do this until
2967 * the index is fully valid. (Broken HOT chains shouldn't matter, though;
2968 * see comments for IndexCheckExclusion.)
2969 */
2973 /* Roll back any GUC changes executed by index functions */
2976 /* Restore userid and security context */
2978 }
2980 /*
2981 * IndexCheckExclusion - verify that a new exclusion constraint is satisfied
2982 *
2983 * When creating an exclusion constraint, we first build the index normally
2984 * and then rescan the heap to check for conflicts. We assume that we only
2985 * need to validate tuples that are live according to an up-to-date snapshot,
2986 * and that these were correctly indexed even in the presence of broken HOT
2987 * chains. This should be OK since we are holding at least ShareLock on the
2988 * table, meaning there can be no uncommitted updates from other transactions.
2989 * (Note: that wouldn't necessarily work for system catalogs, since many
2990 * operations release write lock early on the system catalogs.)
2991 */
2992 static void
2994 Relation indexRelation,
2996 {
2997 TableScanDesc scan;
3004 Snapshot snapshot;
3006 /*
3007 * If we are reindexing the target index, mark it as no longer being
3008 * reindexed, to forestall an Assert in index_beginscan when we try to use
3009 * the index for probes. This is OK because the index is now fully valid.
3010 */
3014 /*
3015 * Need an EState for evaluation of index expressions and partial-index
3016 * predicates. Also a slot to hold the current tuple.
3017 */
3022 /* Arrange for econtext's scan tuple to be the tuple under test */
3025 /* Set up execution state for predicate, if any. */
3028 /*
3029 * Scan all live tuples in the base relation.
3030 */
3040 {
3043 /*
3044 * In a partial index, ignore tuples that don't satisfy the predicate.
3045 */
3047 {
3050 }
3052 /*
3053 * Extract index column values, including computing expressions.
3054 */
3056 slot,
3057 estate,
3058 values,
3059 isnull);
3061 /*
3062 * Check that this tuple has no conflicts.
3063 */
3070 }
3079 /* These may have been pointing to the now-gone estate */
3082 }
3085 /*
3086 * validate_index - support code for concurrent index builds
3087 *
3088 * We do a concurrent index build by first inserting the catalog entry for the
3089 * index via index_create(), marking it not indisready and not indisvalid.
3090 * Then we commit our transaction and start a new one, then we wait for all
3091 * transactions that could have been modifying the table to terminate. Now
3092 * we know that any subsequently-started transactions will see the index and
3093 * honor its constraints on HOT updates; so while existing HOT-chains might
3094 * be broken with respect to the index, no currently live tuple will have an
3095 * incompatible HOT update done to it. We now build the index normally via
3096 * index_build(), while holding a weak lock that allows concurrent
3097 * insert/update/delete. Also, we index only tuples that are valid
3098 * as of the start of the scan (see table_index_build_scan), whereas a normal
3099 * build takes care to include recently-dead tuples. This is OK because
3100 * we won't mark the index valid until all transactions that might be able
3101 * to see those tuples are gone. The reason for doing that is to avoid
3102 * bogus unique-index failures due to concurrent UPDATEs (we might see
3103 * different versions of the same row as being valid when we pass over them,
3104 * if we used HeapTupleSatisfiesVacuum). This leaves us with an index that
3105 * does not contain any tuples added to the table while we built the index.
3106 *
3107 * Next, we mark the index "indisready" (but still not "indisvalid") and
3108 * commit the second transaction and start a third. Again we wait for all
3109 * transactions that could have been modifying the table to terminate. Now
3110 * we know that any subsequently-started transactions will see the index and
3111 * insert their new tuples into it. We then take a new reference snapshot
3112 * which is passed to validate_index(). Any tuples that are valid according
3113 * to this snap, but are not in the index, must be added to the index.
3114 * (Any tuples committed live after the snap will be inserted into the
3115 * index by their originating transaction. Any tuples committed dead before
3116 * the snap need not be indexed, because we will wait out all transactions
3117 * that might care about them before we mark the index valid.)
3118 *
3119 * validate_index() works by first gathering all the TIDs currently in the
3120 * index, using a bulkdelete callback that just stores the TIDs and doesn't
3121 * ever say "delete it". (This should be faster than a plain indexscan;
3122 * also, not all index AMs support full-index indexscan.) Then we sort the
3123 * TIDs, and finally scan the table doing a "merge join" against the TID list
3124 * to see which tuples are missing from the index. Thus we will ensure that
3125 * all tuples valid according to the reference snapshot are in the index.
3126 *
3127 * Building a unique index this way is tricky: we might try to insert a
3128 * tuple that is already dead or is in process of being deleted, and we
3129 * mustn't have a uniqueness failure against an updated version of the same
3130 * row. We could try to check the tuple to see if it's already dead and tell
3131 * index_insert() not to do the uniqueness check, but that still leaves us
3132 * with a race condition against an in-progress update. To handle that,
3133 * we expect the index AM to recheck liveness of the to-be-inserted tuple
3134 * before it declares a uniqueness error.
3135 *
3136 * After completing validate_index(), we wait until all transactions that
3137 * were alive at the time of the reference snapshot are gone; this is
3138 * necessary to be sure there are none left with a transaction snapshot
3139 * older than the reference (and hence possibly able to see tuples we did
3140 * not index). Then we mark the index "indisvalid" and commit. Subsequent
3141 * transactions will be able to use it for queries.
3142 *
3143 * Doing two full table scans is a brute-force strategy. We could try to be
3144 * cleverer, eg storing new tuples in a special area of the table (perhaps
3145 * making the table append-only by setting use_fsm). However that would
3146 * add yet more locking issues.
3147 */
3148 void
3150 {
3151 Relation heapRelation,
3152 indexRelation;
3154 IndexVacuumInfo ivinfo;
3155 ValidateIndexState state;
3156 Oid save_userid;
3160 {
3162 PROGRESS_CREATEIDX_PHASE,
3163 PROGRESS_CREATEIDX_TUPLES_DONE,
3164 PROGRESS_CREATEIDX_TUPLES_TOTAL,
3165 PROGRESS_SCAN_BLOCKS_DONE,
3166 PROGRESS_SCAN_BLOCKS_TOTAL
3167 };
3169 PROGRESS_CREATEIDX_PHASE_VALIDATE_IDXSCAN,
3171 };
3174 }
3176 /* Open and lock the parent heap relation */
3178 /* And the target index relation */
3181 /*
3182 * Fetch info needed for index_insert. (You might think this should be
3183 * passed in from DefineIndex, but its copy is long gone due to having
3184 * been built in a previous transaction.)
3185 */
3188 /* mark build is concurrent just for consistency */
3191 /*
3192 * Switch to the table owner's userid, so that any index functions are run
3193 * as that user. Also lock down security-restricted operations and
3194 * arrange to make GUC variable changes local to this command.
3195 */
3201 /*
3202 * Scan the index and gather up all the TIDs into a tuplesort object.
3203 */
3212 /*
3213 * Encode TIDs as int8 values for the sort, rather than directly sorting
3214 * item pointers. This can be significantly faster, primarily because TID
3215 * is a pass-by-reference type on all platforms, whereas int8 is
3216 * pass-by-value on most platforms.
3217 */
3220 maintenance_work_mem,
3224 /* ambulkdelete updates progress metrics */
3228 /* Execute the sort */
3229 {
3231 PROGRESS_CREATEIDX_PHASE,
3232 PROGRESS_SCAN_BLOCKS_DONE,
3233 PROGRESS_SCAN_BLOCKS_TOTAL
3234 };
3236 PROGRESS_CREATEIDX_PHASE_VALIDATE_SORT,
3238 };
3241 }
3244 /*
3245 * Now scan the heap and "merge" it with the index
3246 */
3248 PROGRESS_CREATEIDX_PHASE_VALIDATE_TABLESCAN);
3250 indexRelation,
3251 indexInfo,
3252 snapshot,
3255 /* Done with tuplesort object */
3262 /* Roll back any GUC changes executed by index functions */
3265 /* Restore userid and security context */
3268 /* Close rels, but keep locks */
3271 }
3273 /*
3274 * validate_index_callback - bulkdelete callback to collect the index TIDs
3275 */
3276 static bool
3278 {
3285 }
3287 /*
3288 * index_set_state_flags - adjust pg_index state flags
3289 *
3290 * This is used during CREATE/DROP INDEX CONCURRENTLY to adjust the pg_index
3291 * flags that denote the index's state. Because the update is not
3292 * transactional and will not roll back on error, this must only be used as
3293 * the last step in a transaction that has not made any transactional catalog
3294 * updates!
3295 *
3296 * Note that heap_inplace_update does send a cache inval message for the
3297 * tuple, so other sessions will hear about the update as soon as we commit.
3298 *
3299 * NB: In releases prior to PostgreSQL 9.4, the use of a non-transactional
3300 * update here would have been unsafe; now that MVCC rules apply even for
3301 * system catalog scans, we could potentially use a transactional update here
3302 * instead.
3303 */
3304 void
3306 {
3307 Relation pg_index;
3308 HeapTuple indexTuple;
3309 Form_pg_index indexForm;
3311 /* Assert that current xact hasn't done any transactional updates */
3314 /* Open pg_index and fetch a writable copy of the index's tuple */
3323 /* Perform the requested state change on the copy */
3325 {
3327 /* Set indisready during a CREATE INDEX CONCURRENTLY sequence */
3334 /* Set indisvalid during a CREATE INDEX CONCURRENTLY sequence */
3342 /*
3343 * Clear indisvalid during a DROP INDEX CONCURRENTLY sequence
3344 *
3345 * If indisready == true we leave it set so the index still gets
3346 * maintained by active transactions. We only need to ensure that
3347 * indisvalid is false. (We don't assert that either is initially
3348 * true, though, since we want to be able to retry a DROP INDEX
3349 * CONCURRENTLY that failed partway through.)
3350 *
3351 * Note: the CLUSTER logic assumes that indisclustered cannot be
3352 * set on any invalid index, so clear that flag too.
3353 */
3359 /*
3360 * Clear indisready/indislive during DROP INDEX CONCURRENTLY
3361 *
3362 * We clear both indisready and indislive, because we not only
3363 * want to stop updates, we want to prevent sessions from touching
3364 * the index at all.
3365 */
3370 }
3372 /* ... and write it back in-place */
3376 }
3379 /*
3380 * IndexGetRelation: given an index's relation OID, get the OID of the
3381 * relation it is an index on. Uses the system cache.
3382 */
3383 Oid
3385 {
3386 HeapTuple tuple;
3387 Form_pg_index index;
3388 Oid result;
3392 {
3396 }
3403 }
3405 /*
3406 * reindex_index - This routine is used to recreate a single index
3407 */
3408 void
3411 {
3412 Relation iRel,
3413 heapRelation;
3414 Oid heapId;
3417 PGRUsage ru0;
3422 /*
3423 * Open and lock the parent heap relation. ShareLock is sufficient since
3424 * we only need to be sure no schema or data changes are going on.
3425 */
3430 {
3432 heapId);
3434 PROGRESS_CREATEIDX_COMMAND_REINDEX);
3436 indexId);
3437 }
3439 /*
3440 * Open the target index relation and get an exclusive lock on it, to
3441 * ensure that no one else is touching this particular index.
3442 */
3449 /*
3450 * The case of reindexing partitioned tables and indexes is handled
3451 * differently by upper layers, so this case shouldn't arise.
3452 */
3457 /*
3458 * Don't allow reindex on temp tables of other backends ... their local
3459 * buffer manager is not going to cope.
3460 */
3466 /*
3467 * Don't allow reindex of an invalid index on TOAST table. This is a
3468 * leftover from a failed REINDEX CONCURRENTLY, and if rebuilt it would
3469 * not be possible to drop it anymore.
3470 */
3477 /*
3478 * Also check for active uses of the index in the current transaction; we
3479 * don't want to reindex underneath an open indexscan.
3480 */
3483 /*
3484 * All predicate locks on the index are about to be made invalid. Promote
3485 * them to relation locks on the heap.
3486 */
3489 /* Fetch info needed for index_build */
3492 /* If requested, skip checking uniqueness/exclusion constraints */
3494 {
3501 }
3503 /* Suppress use of the target index while rebuilding it */
3506 /* Create a new physical relation for the index */
3509 /* Initialize the index and rebuild */
3510 /* Note: we do not need to re-establish pkey setting */
3513 /* Re-allow use of target index */
3516 /*
3517 * If the index is marked invalid/not-ready/dead (ie, it's from a failed
3518 * CREATE INDEX CONCURRENTLY, or a DROP INDEX CONCURRENTLY failed midway),
3519 * and we didn't skip a uniqueness check, we can now mark it valid. This
3520 * allows REINDEX to be used to clean up in such cases.
3521 *
3522 * We can also reset indcheckxmin, because we have now done a
3523 * non-concurrent index build, *except* in the case where index_build
3524 * found some still-broken HOT chains. If it did, and we don't have to
3525 * change any of the other flags, we just leave indcheckxmin alone (note
3526 * that index_build won't have changed it, because this is a reindex).
3527 * This is okay and desirable because not updating the tuple leaves the
3528 * index's usability horizon (recorded as the tuple's xmin value) the same
3529 * as it was.
3530 *
3531 * But, if the index was invalid/not-ready/dead and there were broken HOT
3532 * chains, we had better force indcheckxmin true, because the normal
3533 * argument that the HOT chains couldn't conflict with the index is
3534 * suspect for an invalid index. (A conflict is definitely possible if
3535 * the index was dead. It probably shouldn't happen otherwise, but let's
3536 * be conservative.) In this case advancing the usability horizon is
3537 * appropriate.
3538 *
3539 * Another reason for avoiding unnecessary updates here is that while
3540 * reindexing pg_index itself, we must not try to update tuples in it.
3541 * pg_index's indexes should always have these flags in their clean state,
3542 * so that won't happen.
3543 *
3544 * If early pruning/vacuuming is enabled for the heap relation, the
3545 * usability horizon must be advanced to the current transaction on every
3546 * build or rebuild. pg_index is OK in this regard because catalog tables
3547 * are not subject to early cleanup.
3548 */
3550 {
3551 Relation pg_index;
3552 HeapTuple indexTuple;
3553 Form_pg_index indexForm;
3570 early_pruning_enabled)
3571 {
3581 /*
3582 * Invalidate the relcache for the table, so that after we commit
3583 * all sessions will refresh the table's index list. This ensures
3584 * that if anyone misses seeing the pg_index row during this
3585 * update, they'll refresh their list before attempting any update
3586 * on the table.
3587 */
3589 }
3592 }
3594 /* Log what we did */
3605 /* Close rels, but keep locks */
3608 }
3610 /*
3611 * reindex_relation - This routine is used to recreate all indexes
3612 * of a relation (and optionally its toast relation too, if any).
3613 *
3614 * "flags" is a bitmask that can include any combination of these bits:
3615 *
3616 * REINDEX_REL_PROCESS_TOAST: if true, process the toast table too (if any).
3617 *
3618 * REINDEX_REL_SUPPRESS_INDEX_USE: if true, the relation was just completely
3619 * rebuilt by an operation such as VACUUM FULL or CLUSTER, and therefore its
3620 * indexes are inconsistent with it. This makes things tricky if the relation
3621 * is a system catalog that we might consult during the reindexing. To deal
3622 * with that case, we mark all of the indexes as pending rebuild so that they
3623 * won't be trusted until rebuilt. The caller is required to call us *without*
3624 * having made the rebuilt table visible by doing CommandCounterIncrement;
3625 * we'll do CCI after having collected the index list. (This way we can still
3626 * use catalog indexes while collecting the list.)
3627 *
3628 * REINDEX_REL_CHECK_CONSTRAINTS: if true, recheck unique and exclusion
3629 * constraint conditions, else don't. To avoid deadlocks, VACUUM FULL or
3630 * CLUSTER on a system catalog must omit this flag. REINDEX should be used to
3631 * rebuild an index if constraint inconsistency is suspected. For optimal
3632 * performance, other callers should include the flag only after transforming
3633 * the data in a manner that risks a change in constraint validity.
3634 *
3635 * REINDEX_REL_FORCE_INDEXES_UNLOGGED: if true, set the persistence of the
3636 * rebuilt indexes to unlogged.
3637 *
3638 * REINDEX_REL_FORCE_INDEXES_PERMANENT: if true, set the persistence of the
3639 * rebuilt indexes to permanent.
3640 *
3641 * Returns true if any indexes were rebuilt (including toast table's index
3642 * when relevant). Note that a CommandCounterIncrement will occur after each
3643 * index rebuild.
3644 */
3645 bool
3647 {
3648 Relation rel;
3649 Oid toast_relid;
3656 /*
3657 * Open and lock the relation. ShareLock is sufficient since we only need
3658 * to prevent schema and data changes in it. The lock level used here
3659 * should match ReindexTable().
3660 */
3663 /*
3664 * This may be useful when implemented someday; but that day is not today.
3665 * For now, avoid erroring out when called in a multi-table context
3666 * (REINDEX SCHEMA) and happen to come across a partitioned table. The
3667 * partitions may be reindexed on their own anyway.
3668 */
3670 {
3677 }
3681 /*
3682 * Get the list of index OIDs for this relation. (We trust to the
3683 * relcache to get this with a sequential scan if ignoring system
3684 * indexes.)
3685 */
3689 {
3690 /* Suppress use of all the indexes until they are rebuilt */
3693 /*
3694 * Make the new heap contents visible --- now things might be
3695 * inconsistent!
3696 */
3698 }
3700 /*
3701 * Compute persistence of indexes: same as that of owning rel, unless
3702 * caller specified otherwise.
3703 */
3708 else
3711 /* Reindex all the indexes. */
3714 {
3718 /*
3719 * Skip any invalid indexes on a TOAST table. These can only be
3720 * duplicate leftovers from a failed REINDEX CONCURRENTLY, and if
3721 * rebuilt it would not be possible to drop them anymore.
3722 */
3725 {
3732 }
3739 /* Index should no longer be in the pending list */
3742 /* Set index rebuild count */
3744 i);
3745 i++;
3746 }
3748 /*
3749 * Close rel, but continue to hold the lock.
3750 */
3755 /*
3756 * If the relation has a secondary toast rel, reindex that too while we
3757 * still hold the lock on the main table.
3758 */
3763 }
3766 /* ----------------------------------------------------------------
3767 * System index reindexing support
3768 *
3769 * When we are busy reindexing a system index, this code provides support
3770 * for preventing catalog lookups from using that index. We also make use
3771 * of this to catch attempted uses of user indexes during reindexing of
3772 * those indexes. This information is propagated to parallel workers;
3773 * attempting to change it during a parallel operation is not permitted.
3774 * ----------------------------------------------------------------
3775 */
3782 /*
3783 * ReindexIsProcessingHeap
3784 * True if heap specified by OID is currently being reindexed.
3785 */
3786 bool
3788 {
3790 }
3792 /*
3793 * ReindexIsCurrentlyProcessingIndex
3794 * True if index specified by OID is currently being reindexed.
3795 */
3796 static bool
3798 {
3800 }
3802 /*
3803 * ReindexIsProcessingIndex
3804 * True if index specified by OID is currently being reindexed,
3805 * or should be treated as invalid because it is awaiting reindex.
3806 */
3807 bool
3809 {
3812 }
3814 /*
3815 * SetReindexProcessing
3816 * Set flag that specified heap/index are being reindexed.
3817 */
3818 static void
3820 {
3822 /* Reindexing is not re-entrant. */
3827 /* Index is no longer "pending" reindex. */
3829 /* This may have been set already, but in case it isn't, do so now. */
3831 }
3833 /*
3834 * ResetReindexProcessing
3835 * Unset reindexing status.
3836 */
3837 static void
3839 {
3842 /* reindexingNestLevel remains set till end of (sub)transaction */
3843 }
3845 /*
3846 * SetReindexPending
3847 * Mark the given indexes as pending reindex.
3848 *
3849 * NB: we assume that the current memory context stays valid throughout.
3850 */
3851 static void
3853 {
3854 /* Reindexing is not re-entrant. */
3861 }
3863 /*
3864 * RemoveReindexPending
3865 * Remove the given index from the pending list.
3866 */
3867 static void
3869 {
3873 indexOid);
3874 }
3876 /*
3877 * ResetReindexState
3878 * Clear all reindexing state during (sub)transaction abort.
3879 */
3880 void
3882 {
3883 /*
3884 * Because reindexing is not re-entrant, we don't need to cope with nested
3885 * reindexing states. We just need to avoid messing up the outer-level
3886 * state in case a subtransaction fails within a REINDEX. So checking the
3887 * current nest level against that of the reindex operation is sufficient.
3888 */
3890 {
3894 /*
3895 * We needn't try to release the contents of pendingReindexedIndexes;
3896 * that list should be in a transaction-lifespan context, so it will
3897 * go away automatically.
3898 */
3902 }
3903 }
3905 /*
3906 * EstimateReindexStateSpace
3907 * Estimate space needed to pass reindex state to parallel workers.
3908 */
3909 Size
3911 {
3914 }
3916 /*
3917 * SerializeReindexState
3918 * Serialize reindex state for parallel workers.
3919 */
3920 void
3922 {
3932 }
3934 /*
3935 * RestoreReindexState
3936 * Restore reindex state in a parallel worker.
3937 */
3938 void
3940 {
3943 MemoryContext oldcontext;
3951 pendingReindexedIndexes =
3956 /* Note the worker has its own transaction nesting level */
3958 }