| blob | d312eaef165aaaf08b9ba1cc680676f5d4d0e41b |
1 /*-------------------------------------------------------------------------
2 *
3 * index.c
4 * code to create and destroy POSTGRES index relations
5 *
6 * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
7 * Portions Copyright (c) 1994, Regents of the University of California
8 *
9 *
10 * IDENTIFICATION
11 * $PostgreSQL$
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>
66 /* state info for validate_index bulkdelete callback */
68 {
70 /* statistics (for debug purposes only): */
72 itups,
73 tups_inserted;
76 /* non-export function prototypes */
79 Oid accessMethodObjectId,
94 Relation indexRelation,
96 Snapshot snapshot,
101 /*
102 * ConstructTupleDescriptor
103 *
104 * Build an index tuple descriptor for a new index
105 */
106 static TupleDesc
109 Oid accessMethodObjectId,
111 {
114 HeapTuple amtuple;
115 Form_pg_am amform;
116 TupleDesc heapTupDesc;
117 TupleDesc indexTupDesc;
121 /* We need access to the index AM's pg_am tuple */
127 accessMethodObjectId);
130 /* ... and to the table's tuple descriptor */
134 /*
135 * allocate the new tuple descriptor
136 */
139 /*
140 * For simple index columns, we copy the pg_attribute row from the parent
141 * relation and modify it as necessary. For expressions we have to cons
142 * up a pg_attribute row the hard way.
143 */
145 {
148 HeapTuple tuple;
149 Form_pg_type typeTup;
150 Form_pg_opclass opclassTup;
151 Oid keyType;
154 {
155 /* Simple index column */
156 Form_pg_attribute from;
159 {
160 /*
161 * here we are indexing on a system attribute (-1...-n)
162 */
165 }
166 else
167 {
168 /*
169 * here we are indexing on a normal attribute (1...n)
170 */
174 }
176 /*
177 * now that we've determined the "from", let's copy the tuple desc
178 * data...
179 */
182 /*
183 * Fix the stuff that should not be the same as the underlying
184 * attr
185 */
194 }
195 else
196 {
197 /* Expressional index */
207 /*
208 * Make the attribute's name "pg_expresssion_nnn" (maybe think of
209 * something better later)
210 */
213 /*
214 * Lookup the expression type in pg_type for the type length etc.
215 */
224 /*
225 * Assign some of the attributes values. Leave the rest as 0.
226 */
239 }
241 /*
242 * We do not yet have the correct relation OID for the index, so just
243 * set it invalid for now. InitializeAttributeOids() will fix it
244 * later.
245 */
248 /*
249 * Check the opclass and index AM to see if either provides a keytype
250 * (overriding the attribute type). Opclass takes precedence.
251 */
261 else
266 {
267 /* index value and heap value have different types */
283 }
284 }
289 }
291 /* ----------------------------------------------------------------
292 * InitializeAttributeOids
293 * ----------------------------------------------------------------
294 */
295 static void
298 Oid indexoid)
299 {
300 TupleDesc tupleDescriptor;
307 }
309 /* ----------------------------------------------------------------
310 * AppendAttributeTuples
311 * ----------------------------------------------------------------
312 */
313 static void
315 {
316 Relation pg_attribute;
317 CatalogIndexState indstate;
318 TupleDesc indexTupDesc;
319 HeapTuple new_tuple;
322 /*
323 * open the attribute relation and its indexes
324 */
329 /*
330 * insert data from new index's tupdesc into pg_attribute
331 */
335 {
336 /*
337 * There used to be very grotty code here to set these fields, but I
338 * think it's unnecessary. They should be set already.
339 */
345 ATTRIBUTE_TUPLE_SIZE,
353 }
358 }
360 /* ----------------------------------------------------------------
361 * UpdateIndexRelation
362 *
363 * Construct and insert a new entry in the pg_index catalog
364 * ----------------------------------------------------------------
365 */
366 static void
368 Oid heapoid,
374 {
378 Datum exprsDatum;
379 Datum predDatum;
382 Relation pg_index;
383 HeapTuple tuple;
386 /*
387 * Copy the index key, opclass, and indoption info into arrays (should we
388 * make the caller pass them like this to start with?)
389 */
396 /*
397 * Convert the index expressions (if any) to a text datum
398 */
400 {
406 }
407 else
410 /*
411 * Convert the index predicate (if any) to a text datum. Note we convert
412 * implicit-AND format to normal explicit-AND for storage.
413 */
415 {
421 }
422 else
425 /*
426 * open the system catalog index relation
427 */
430 /*
431 * Build a pg_index tuple
432 */
443 /* we set isvalid and isready the same way */
457 /*
458 * insert the tuple into the pg_index catalog
459 */
462 /* update the indexes on pg_index */
465 /*
466 * close the relation and free the tuple
467 */
470 }
473 /*
474 * index_create
475 *
476 * heapRelationId: OID of table to build index on
477 * indexRelationName: what it say
478 * indexRelationId: normally, pass InvalidOid to let this routine
479 * generate an OID for the index. During bootstrap this may be
480 * nonzero to specify a preselected OID.
481 * indexInfo: same info executor uses to insert into the index
482 * accessMethodObjectId: OID of index AM to use
483 * tableSpaceId: OID of tablespace to use
484 * classObjectId: array of index opclass OIDs, one per index column
485 * coloptions: array of per-index-column indoption settings
486 * reloptions: AM-specific options
487 * isprimary: index is a PRIMARY KEY
488 * isconstraint: index is owned by a PRIMARY KEY or UNIQUE constraint
489 * allow_system_table_mods: allow table to be a system catalog
490 * skip_build: true to skip the index_build() step for the moment; caller
491 * must do it later (typically via reindex_index())
492 * concurrent: if true, do not lock the table against writers. The index
493 * will be marked "invalid" and the caller must take additional steps
494 * to fix it up.
495 *
496 * Returns OID of the created index.
497 */
498 Oid
501 Oid indexRelationId,
503 Oid accessMethodObjectId,
504 Oid tableSpaceId,
507 Datum reloptions,
513 {
514 Relation pg_class;
515 Relation heapRelation;
516 Relation indexRelation;
517 TupleDesc indexTupDesc;
519 Oid namespaceId;
524 /*
525 * Only SELECT ... FOR UPDATE/SHARE are allowed while doing a standard
526 * index build; but for concurrent builds we allow INSERT/UPDATE/DELETE
527 * (but not VACUUM).
528 */
532 /*
533 * The index will be in the same namespace as its parent table, and is
534 * shared across databases if and only if the parent is.
535 */
539 /*
540 * check parameters
541 */
552 /*
553 * concurrent index build on a system catalog is unsafe because we tend to
554 * release locks before committing in catalogs
555 */
562 /*
563 * We cannot allow indexing a shared relation after initdb (because
564 * there's no way to make the entry in other databases' pg_class).
565 */
571 /*
572 * Validate shared/non-shared tablespace (must check this before doing
573 * GetNewRelFileNode, to prevent Assert therein)
574 */
576 {
578 /* elog since this is not a user-facing error */
581 }
582 else
583 {
588 }
594 indexRelationName)));
596 /*
597 * construct tuple descriptor for index tuples
598 */
600 indexInfo,
601 accessMethodObjectId,
602 classObjectId);
604 /*
605 * Allocate an OID for the index, unless we were told what to use.
606 *
607 * The OID will be the relfilenode as well, so make sure it doesn't
608 * collide with either pg_class OIDs or existing physical files.
609 */
612 pg_class);
614 /*
615 * create the index relation's relcache entry and physical disk file. (If
616 * we fail further down, it's the smgr's responsibility to remove the disk
617 * file again.)
618 */
620 namespaceId,
621 tableSpaceId,
622 indexRelationId,
623 indexTupDesc,
624 RELKIND_INDEX,
625 shared_relation,
626 allow_system_table_mods);
630 /*
631 * Obtain exclusive lock on it. Although no other backends can see it
632 * until we commit, this prevents deadlock-risk complaints from lock
633 * manager in cases such as CLUSTER.
634 */
637 /*
638 * Fill in fields of the index's pg_class entry that are not set correctly
639 * by heap_create.
640 *
641 * XXX should have a cleaner way to create cataloged indexes
642 */
648 /*
649 * store index's pg_class entry
650 */
653 reloptions);
655 /* done with pg_class */
658 /*
659 * now update the object id's of all the attribute tuple forms in the
660 * index relation's tuple descriptor
661 */
664 indexRelationId);
666 /*
667 * append ATTRIBUTE tuples for the index
668 */
671 /* ----------------
672 * update pg_index
673 * (append INDEX tuple)
674 *
675 * Note that this stows away a representation of "predicate".
676 * (Or, could define a rule to maintain the predicate) --Nels, Feb '92
677 * ----------------
678 */
682 /*
683 * Register constraint and dependencies for the index.
684 *
685 * If the index is from a CONSTRAINT clause, construct a pg_constraint
686 * entry. The index is then linked to the constraint, which in turn is
687 * linked to the table. If it's not a CONSTRAINT, make the dependency
688 * directly on the table.
689 *
690 * We don't need a dependency on the namespace, because there'll be an
691 * indirect dependency via our parent table.
692 *
693 * During bootstrap we can't register any dependencies, and we don't try
694 * to make a constraint either.
695 */
697 {
698 ObjectAddress myself,
699 referenced;
706 {
708 Oid conOid;
714 else
715 {
718 }
720 /* Shouldn't have any expressions */
725 namespaceId,
726 constraintType,
729 heapRelationId,
734 NULL,
735 NULL,
736 NULL,
737 NULL,
744 NULL,
745 NULL,
754 }
755 else
756 {
759 /* Create auto dependencies on simply-referenced columns */
761 {
763 {
771 }
772 }
774 /*
775 * It's possible for an index to not depend on any columns of the
776 * table at all, in which case we need to give it a dependency on
777 * the table as a whole; else it won't get dropped when the table
778 * is dropped. This edge case is not totally useless; for
779 * example, a unique index on a constant expression can serve to
780 * prevent a table from containing more than one row.
781 */
785 {
791 }
792 }
794 /* Store dependency on operator classes */
796 {
802 }
804 /* Store dependencies on anything mentioned in index expressions */
806 {
809 heapRelationId,
810 DEPENDENCY_NORMAL,
811 DEPENDENCY_AUTO);
812 }
814 /* Store dependencies on anything mentioned in predicate */
816 {
819 heapRelationId,
820 DEPENDENCY_NORMAL,
821 DEPENDENCY_AUTO);
822 }
823 }
825 /*
826 * Advance the command counter so that we can see the newly-entered
827 * catalog tuples for the index.
828 */
831 /*
832 * In bootstrap mode, we have to fill in the index strategy structure with
833 * information from the catalogs. If we aren't bootstrapping, then the
834 * relcache entry has already been rebuilt thanks to sinval update during
835 * CommandCounterIncrement.
836 */
839 else
842 /*
843 * If this is bootstrap (initdb) time, then we don't actually fill in the
844 * index yet. We'll be creating more indexes and classes later, so we
845 * delay filling them in until just before we're done with bootstrapping.
846 * Similarly, if the caller specified skip_build then filling the index is
847 * delayed till later (ALTER TABLE can save work in some cases with this).
848 * Otherwise, we call the AM routine that constructs the index.
849 */
851 {
853 }
855 {
856 /*
857 * Caller is responsible for filling the index later on. However,
858 * we'd better make sure that the heap relation is correctly marked as
859 * having an index.
860 */
863 isprimary,
864 InvalidOid,
866 /* Make the above update visible */
868 }
869 else
870 {
872 }
874 /*
875 * Close the heap and index; but we keep the locks that we acquired above
876 * until end of transaction.
877 */
882 }
884 /*
885 * index_drop
886 *
887 * NOTE: this routine should now only be called through performDeletion(),
888 * else associated dependencies won't be cleaned up.
889 */
890 void
892 {
893 Oid heapId;
894 Relation userHeapRelation;
895 Relation userIndexRelation;
896 Relation indexRelation;
897 HeapTuple tuple;
899 ForkNumber forknum;
901 /*
902 * To drop an index safely, we must grab exclusive lock on its parent
903 * table; otherwise there could be other backends using the index!
904 * Exclusive lock on the index alone is insufficient because another
905 * backend might be in the midst of devising a query plan that will use
906 * the index. The parser and planner take care to hold an appropriate
907 * lock on the parent table while working, but having them hold locks on
908 * all the indexes too seems overly expensive. We do grab exclusive lock
909 * on the index too, just to be safe. Both locks must be held till end of
910 * transaction, else other backends will still see this index in pg_index.
911 */
917 /*
918 * Schedule physical removal of the files
919 */
927 /*
928 * Close and flush the index's relcache entry, to ensure relcache doesn't
929 * try to rebuild it while we're deleting catalog entries. We keep the
930 * lock though.
931 */
936 /*
937 * fix INDEX relation, and check for expressional index
938 */
954 /*
955 * if it has any expression columns, we might have stored statistics about
956 * them.
957 */
961 /*
962 * fix ATTRIBUTE relation
963 */
966 /*
967 * fix RELATION relation
968 */
971 /*
972 * We are presently too lazy to attempt to compute the new correct value
973 * of relhasindex (the next VACUUM will fix it if necessary). So there is
974 * no need to update the pg_class tuple for the owning relation. But we
975 * must send out a shared-cache-inval notice on the owning relation to
976 * ensure other backends update their relcache lists of indexes.
977 */
980 /*
981 * Close owning rel, but keep lock
982 */
984 }
986 /* ----------------------------------------------------------------
987 * index_build support
988 * ----------------------------------------------------------------
989 */
991 /* ----------------
992 * BuildIndexInfo
993 * Construct an IndexInfo record for an open index
994 *
995 * IndexInfo stores the information about the index that's needed by
996 * FormIndexDatum, which is used for both index_build() and later insertion
997 * of individual index tuples. Normally we build an IndexInfo for an index
998 * just once per command, and then use it for (potentially) many tuples.
999 * ----------------
1000 */
1001 IndexInfo *
1003 {
1009 /* check the number of keys, and copy attr numbers into the IndexInfo */
1018 /* fetch any expressions needed for expressional indexes */
1022 /* fetch index predicate if any */
1026 /* other info */
1030 /* initialize index-build state to default */
1035 }
1037 /* ----------------
1038 * FormIndexDatum
1039 * Construct values[] and isnull[] arrays for a new index tuple.
1040 *
1041 * indexInfo Info about the index
1042 * slot Heap tuple for which we must prepare an index entry
1043 * estate executor state for evaluating any index expressions
1044 * values Array of index Datums (output area)
1045 * isnull Array of is-null indicators (output area)
1046 *
1047 * When there are no index expressions, estate may be NULL. Otherwise it
1048 * must be supplied, *and* the ecxt_scantuple slot of its per-tuple expr
1049 * context must point to the heap tuple passed in.
1050 *
1051 * Notice we don't actually call index_form_tuple() here; we just prepare
1052 * its input arrays values[] and isnull[]. This is because the index AM
1053 * may wish to alter the data before storage.
1054 * ----------------
1055 */
1056 void
1062 {
1068 {
1069 /* First time through, set up expression evaluation state */
1072 estate);
1073 /* Check caller has set up context correctly */
1075 }
1079 {
1081 Datum iDatum;
1085 {
1086 /*
1087 * Plain index column; get the value we need directly from the
1088 * heap tuple.
1089 */
1091 }
1092 else
1093 {
1094 /*
1095 * Index expression --- need to evaluate it.
1096 */
1102 NULL);
1104 }
1107 }
1111 }
1114 /*
1115 * index_update_stats --- update pg_class entry after CREATE INDEX or REINDEX
1116 *
1117 * This routine updates the pg_class row of either an index or its parent
1118 * relation after CREATE INDEX or REINDEX. Its rather bizarre API is designed
1119 * to ensure we can do all the necessary work in just one update.
1120 *
1121 * hasindex: set relhasindex to this value
1122 * isprimary: if true, set relhaspkey true; else no change
1123 * reltoastidxid: if not InvalidOid, set reltoastidxid to this value;
1124 * else no change
1125 * reltuples: set reltuples to this value
1126 *
1127 * relpages is also updated (using RelationGetNumberOfBlocks()).
1128 *
1129 * NOTE: an important side-effect of this operation is that an SI invalidation
1130 * message is sent out to all backends --- including me --- causing relcache
1131 * entries to be flushed or updated with the new data. This must happen even
1132 * if we find that no change is needed in the pg_class row. When updating
1133 * a heap entry, this ensures that other backends find out about the new
1134 * index. When updating an index, it's important because some index AMs
1135 * expect a relcache flush to occur after REINDEX.
1136 */
1137 static void
1140 {
1143 Relation pg_class;
1144 HeapTuple tuple;
1145 Form_pg_class rd_rel;
1148 /*
1149 * We always update the pg_class row using a non-transactional,
1150 * overwrite-in-place update. There are several reasons for this:
1151 *
1152 * 1. In bootstrap mode, we have no choice --- UPDATE wouldn't work.
1153 *
1154 * 2. We could be reindexing pg_class itself, in which case we can't move
1155 * its pg_class row because CatalogUpdateIndexes might not know about all
1156 * the indexes yet (see reindex_relation).
1157 *
1158 * 3. Because we execute CREATE INDEX with just share lock on the parent
1159 * rel (to allow concurrent index creations), an ordinary update could
1160 * suffer a tuple-concurrently-updated failure against another CREATE
1161 * INDEX committing at about the same time. We can avoid that by having
1162 * them both do nontransactional updates (we assume they will both be
1163 * trying to change the pg_class row to the same thing, so it doesn't
1164 * matter which goes first).
1165 *
1166 * 4. Even with just a single CREATE INDEX, there's a risk factor because
1167 * someone else might be trying to open the rel while we commit, and this
1168 * creates a race condition as to whether he will see both or neither of
1169 * the pg_class row versions as valid. Again, a non-transactional update
1170 * avoids the risk. It is indeterminate which state of the row the other
1171 * process will see, but it doesn't matter (if he's only taking
1172 * AccessShareLock, then it's not critical that he see relhasindex true).
1173 *
1174 * It is safe to use a non-transactional update even though our
1175 * transaction could still fail before committing. Setting relhasindex
1176 * true is safe even if there are no indexes (VACUUM will eventually fix
1177 * it), and of course the relpages and reltuples counts are correct (or at
1178 * least more so than the old values) regardless.
1179 */
1183 /*
1184 * Make a copy of the tuple to update. Normally we use the syscache, but
1185 * we can't rely on that during bootstrap or while reindexing pg_class
1186 * itself.
1187 */
1190 {
1191 /* don't assume syscache will work */
1192 HeapScanDesc pg_class_scan;
1196 ObjectIdAttributeNumber,
1204 }
1205 else
1206 {
1207 /* normal case, use syscache */
1211 }
1217 /* Apply required updates, if any, to copied tuple */
1221 {
1224 }
1226 {
1228 {
1231 }
1232 }
1234 {
1237 {
1240 }
1241 }
1243 {
1246 }
1248 {
1251 }
1253 /*
1254 * If anything changed, write out the tuple
1255 */
1257 {
1259 /* the above sends a cache inval message */
1260 }
1261 else
1262 {
1263 /* no need to change tuple, but force relcache inval anyway */
1265 }
1270 }
1272 /*
1273 * setNewRelfilenode - assign a new relfilenode value to the relation
1274 *
1275 * Caller must already hold exclusive lock on the relation.
1276 *
1277 * The relation is marked with relfrozenxid=freezeXid (InvalidTransactionId
1278 * must be passed for indexes)
1279 */
1280 void
1282 {
1283 Oid newrelfilenode;
1284 RelFileNode newrnode;
1285 SMgrRelation srel;
1286 Relation pg_class;
1287 HeapTuple tuple;
1288 Form_pg_class rd_rel;
1289 ForkNumber i;
1291 /* Can't change relfilenode for nailed tables (indexes ok though) */
1294 /* Can't change for shared tables or indexes */
1296 /* Indexes must have Invalid frozenxid; other relations must not */
1301 /* Allocate a new relfilenode */
1304 NULL);
1306 /*
1307 * Find the pg_class tuple for the given relation. This is not used
1308 * during bootstrap, so okay to use heap_update always.
1309 */
1322 /*
1323 * ... and create storage for corresponding forks in the new relfilenode.
1324 *
1325 * NOTE: any conflict in relfilenode value will be caught here
1326 */
1331 /* Create the main fork, like heap_create() does */
1334 /*
1335 * For a heap, create FSM fork as well. Indexams are responsible for
1336 * creating any extra forks themselves.
1337 */
1342 /* schedule unlinking old files */
1344 {
1347 }
1352 /* update the pg_class row */
1364 /* Make sure the relfilenode change is visible */
1367 /* Mark the rel as having a new relfilenode in current transaction */
1369 }
1372 /*
1373 * index_build - invoke access-method-specific index build procedure
1374 *
1375 * On entry, the index's catalog entries are valid, and its physical disk
1376 * file has been created but is empty. We call the AM-specific build
1377 * procedure to fill in the index contents. We then update the pg_class
1378 * entries of the index and heap relation as needed, using statistics
1379 * returned by ambuild as well as data passed by the caller.
1380 *
1381 * Note: when reindexing an existing index, isprimary can be false;
1382 * the index is already properly marked and need not be re-marked.
1383 *
1384 * Note: before Postgres 8.2, the passed-in heap and index Relations
1385 * were automatically closed by this routine. This is no longer the case.
1386 * The caller opened 'em, and the caller should close 'em.
1387 */
1388 void
1390 Relation indexRelation,
1393 {
1394 RegProcedure procedure;
1396 Oid save_userid;
1399 /*
1400 * sanity checks
1401 */
1408 /*
1409 * Switch to the table owner's userid, so that any index functions are
1410 * run as that user.
1411 */
1415 /*
1416 * Call the access method's build procedure
1417 */
1425 /* Restore userid */
1428 /*
1429 * If we found any potentially broken HOT chains, mark the index as not
1430 * being usable until the current transaction is below the event horizon.
1431 * See src/backend/access/heap/README.HOT for discussion.
1432 */
1434 {
1436 Relation pg_index;
1437 HeapTuple indexTuple;
1438 Form_pg_index indexForm;
1455 }
1457 /*
1458 * Update heap and index pg_class rows
1459 */
1462 isprimary,
1470 InvalidOid,
1473 /* Make the updated versions visible */
1475 }
1478 /*
1479 * IndexBuildHeapScan - scan the heap relation to find tuples to be indexed
1480 *
1481 * This is called back from an access-method-specific index build procedure
1482 * after the AM has done whatever setup it needs. The parent heap relation
1483 * is scanned to find tuples that should be entered into the index. Each
1484 * such tuple is passed to the AM's callback routine, which does the right
1485 * things to add it to the new index. After we return, the AM's index
1486 * build procedure does whatever cleanup is needed; in particular, it should
1487 * close the heap and index relations.
1488 *
1489 * The total count of heap tuples is returned. This is for updating pg_class
1490 * statistics. (It's annoying not to be able to do that here, but we can't
1491 * do it until after the relation is closed.) Note that the index AM itself
1492 * must keep track of the number of index tuples; we don't do so here because
1493 * the AM might reject some of the tuples for its own reasons, such as being
1494 * unable to store NULLs.
1495 *
1496 * A side effect is to set indexInfo->ii_BrokenHotChain to true if we detect
1497 * any potentially broken HOT chains. Currently, we set this if there are
1498 * any RECENTLY_DEAD entries in a HOT chain, without trying very hard to
1499 * detect whether they're really incompatible with the chain tip.
1500 */
1501 double
1503 Relation indexRelation,
1505 IndexBuildCallback callback,
1507 {
1508 HeapScanDesc scan;
1509 HeapTuple heapTuple;
1517 Snapshot snapshot;
1518 TransactionId OldestXmin;
1522 /*
1523 * sanity checks
1524 */
1527 /*
1528 * Need an EState for evaluation of index expressions and partial-index
1529 * predicates. Also a slot to hold the current tuple.
1530 */
1535 /* Arrange for econtext's scan tuple to be the tuple under test */
1538 /* Set up execution state for predicate, if any. */
1541 estate);
1543 /*
1544 * Prepare for scan of the base relation. In a normal index build, we use
1545 * SnapshotAny because we must retrieve all tuples and do our own time
1546 * qual checks (because we have to index RECENTLY_DEAD tuples). In a
1547 * concurrent build, we take a regular MVCC snapshot and index whatever's
1548 * live according to that. During bootstrap we just use SnapshotNow.
1549 */
1551 {
1554 }
1556 {
1559 }
1560 else
1561 {
1563 /* okay to ignore lazy VACUUMs here */
1565 }
1571 /*
1572 * Scan all tuples in the base relation.
1573 */
1575 {
1580 /*
1581 * When dealing with a HOT-chain of updated tuples, we want to index
1582 * the values of the live tuple (if any), but index it under the TID
1583 * of the chain's root tuple. This approach is necessary to preserve
1584 * the HOT-chain structure in the heap. So we need to be able to find
1585 * the root item offset for every tuple that's in a HOT-chain. When
1586 * first reaching a new page of the relation, call
1587 * heap_get_root_tuples() to build a map of root item offsets on the
1588 * page.
1589 *
1590 * It might look unsafe to use this information across buffer
1591 * lock/unlock. However, we hold ShareLock on the table so no
1592 * ordinary insert/update/delete should occur; and we hold pin on the
1593 * buffer continuously while visiting the page, so no pruning
1594 * operation can occur either.
1595 *
1596 * Note the implied assumption that there is no more than one live
1597 * tuple per HOT-chain ...
1598 */
1600 {
1608 }
1611 {
1612 /* do our own time qual check */
1615 recheck:
1617 /*
1618 * We could possibly get away with not locking the buffer here,
1619 * since caller should hold ShareLock on the relation, but let's
1620 * be conservative about it. (This remark is still correct even
1621 * with HOT-pruning: our pin on the buffer prevents pruning.)
1622 */
1627 {
1629 /* Definitely dead, we can ignore it */
1634 /* Normal case, index and unique-check it */
1640 /*
1641 * If tuple is recently deleted then we must index it
1642 * anyway to preserve MVCC semantics. (Pre-existing
1643 * transactions could try to use the index after we finish
1644 * building it, and may need to see such tuples.)
1645 *
1646 * However, if it was HOT-updated then we must only index
1647 * the live tuple at the end of the HOT-chain. Since this
1648 * breaks semantics for pre-existing snapshots, mark the
1649 * index as unusable for them.
1650 *
1651 * If we've already decided that the index will be unsafe
1652 * for old snapshots, we may as well stop indexing
1653 * recently-dead tuples, since there's no longer any
1654 * point.
1655 */
1657 {
1659 /* mark the index as unsafe for old snapshots */
1661 }
1664 else
1666 /* In any case, exclude the tuple from unique-checking */
1671 /*
1672 * Since caller should hold ShareLock or better, we should
1673 * not see any tuples inserted by open transactions ---
1674 * unless it's our own transaction. (Consider INSERT
1675 * followed by CREATE INDEX within a transaction.) An
1676 * exception occurs when reindexing a system catalog,
1677 * because we often release lock on system catalogs before
1678 * committing. In that case we wait for the inserting
1679 * transaction to finish and check again. (We could do
1680 * that on user tables too, but since the case is not
1681 * expected it seems better to throw an error.)
1682 */
1685 {
1688 else
1689 {
1690 /*
1691 * Must drop the lock on the buffer before we wait
1692 */
1698 }
1699 }
1701 /*
1702 * We must index such tuples, since if the index build
1703 * commits then they're good.
1704 */
1710 /*
1711 * Since caller should hold ShareLock or better, we should
1712 * not see any tuples deleted by open transactions ---
1713 * unless it's our own transaction. (Consider DELETE
1714 * followed by CREATE INDEX within a transaction.) An
1715 * exception occurs when reindexing a system catalog,
1716 * because we often release lock on system catalogs before
1717 * committing. In that case we wait for the deleting
1718 * transaction to finish and check again. (We could do
1719 * that on user tables too, but since the case is not
1720 * expected it seems better to throw an error.)
1721 */
1725 {
1728 else
1729 {
1730 /*
1731 * Must drop the lock on the buffer before we wait
1732 */
1738 }
1739 }
1741 /*
1742 * Otherwise, we have to treat these tuples just like
1743 * RECENTLY_DELETED ones.
1744 */
1746 {
1748 /* mark the index as unsafe for old snapshots */
1750 }
1753 else
1755 /* In any case, exclude the tuple from unique-checking */
1762 }
1768 }
1769 else
1770 {
1771 /* heap_getnext did the time qual check */
1773 }
1779 /* Set up for predicate or expression evaluation */
1782 /*
1783 * In a partial index, discard tuples that don't satisfy the
1784 * predicate.
1785 */
1787 {
1790 }
1792 /*
1793 * For the current heap tuple, extract all the attributes we use in
1794 * this index, and note which are null. This also performs evaluation
1795 * of any expressions needed.
1796 */
1798 slot,
1799 estate,
1800 values,
1801 isnull);
1803 /*
1804 * You'd think we should go ahead and build the index tuple here, but
1805 * some index AMs want to do further processing on the data first. So
1806 * pass the values[] and isnull[] arrays, instead.
1807 */
1810 {
1811 /*
1812 * For a heap-only tuple, pretend its TID is that of the root. See
1813 * src/backend/access/heap/README.HOT for discussion.
1814 */
1815 HeapTupleData rootTuple;
1816 OffsetNumber offnum;
1826 /* Call the AM's callback routine to process the tuple */
1828 callback_state);
1829 }
1830 else
1831 {
1832 /* Call the AM's callback routine to process the tuple */
1834 callback_state);
1835 }
1836 }
1840 /* we can now forget our snapshot, if set */
1848 /* These may have been pointing to the now-gone estate */
1853 }
1856 /*
1857 * validate_index - support code for concurrent index builds
1858 *
1859 * We do a concurrent index build by first inserting the catalog entry for the
1860 * index via index_create(), marking it not indisready and not indisvalid.
1861 * Then we commit our transaction and start a new one, then we wait for all
1862 * transactions that could have been modifying the table to terminate. Now
1863 * we know that any subsequently-started transactions will see the index and
1864 * honor its constraints on HOT updates; so while existing HOT-chains might
1865 * be broken with respect to the index, no currently live tuple will have an
1866 * incompatible HOT update done to it. We now build the index normally via
1867 * index_build(), while holding a weak lock that allows concurrent
1868 * insert/update/delete. Also, we index only tuples that are valid
1869 * as of the start of the scan (see IndexBuildHeapScan), whereas a normal
1870 * build takes care to include recently-dead tuples. This is OK because
1871 * we won't mark the index valid until all transactions that might be able
1872 * to see those tuples are gone. The reason for doing that is to avoid
1873 * bogus unique-index failures due to concurrent UPDATEs (we might see
1874 * different versions of the same row as being valid when we pass over them,
1875 * if we used HeapTupleSatisfiesVacuum). This leaves us with an index that
1876 * does not contain any tuples added to the table while we built the index.
1877 *
1878 * Next, we mark the index "indisready" (but still not "indisvalid") and
1879 * commit the second transaction and start a third. Again we wait for all
1880 * transactions that could have been modifying the table to terminate. Now
1881 * we know that any subsequently-started transactions will see the index and
1882 * insert their new tuples into it. We then take a new reference snapshot
1883 * which is passed to validate_index(). Any tuples that are valid according
1884 * to this snap, but are not in the index, must be added to the index.
1885 * (Any tuples committed live after the snap will be inserted into the
1886 * index by their originating transaction. Any tuples committed dead before
1887 * the snap need not be indexed, because we will wait out all transactions
1888 * that might care about them before we mark the index valid.)
1889 *
1890 * validate_index() works by first gathering all the TIDs currently in the
1891 * index, using a bulkdelete callback that just stores the TIDs and doesn't
1892 * ever say "delete it". (This should be faster than a plain indexscan;
1893 * also, not all index AMs support full-index indexscan.) Then we sort the
1894 * TIDs, and finally scan the table doing a "merge join" against the TID list
1895 * to see which tuples are missing from the index. Thus we will ensure that
1896 * all tuples valid according to the reference snapshot are in the index.
1897 *
1898 * Building a unique index this way is tricky: we might try to insert a
1899 * tuple that is already dead or is in process of being deleted, and we
1900 * mustn't have a uniqueness failure against an updated version of the same
1901 * row. We could try to check the tuple to see if it's already dead and tell
1902 * index_insert() not to do the uniqueness check, but that still leaves us
1903 * with a race condition against an in-progress update. To handle that,
1904 * we expect the index AM to recheck liveness of the to-be-inserted tuple
1905 * before it declares a uniqueness error.
1906 *
1907 * After completing validate_index(), we wait until all transactions that
1908 * were alive at the time of the reference snapshot are gone; this is
1909 * necessary to be sure there are none left with a serializable snapshot
1910 * older than the reference (and hence possibly able to see tuples we did
1911 * not index). Then we mark the index "indisvalid" and commit. Subsequent
1912 * transactions will be able to use it for queries.
1913 *
1914 * Doing two full table scans is a brute-force strategy. We could try to be
1915 * cleverer, eg storing new tuples in a special area of the table (perhaps
1916 * making the table append-only by setting use_fsm). However that would
1917 * add yet more locking issues.
1918 */
1919 void
1921 {
1922 Relation heapRelation,
1923 indexRelation;
1925 IndexVacuumInfo ivinfo;
1926 v_i_state state;
1927 Oid save_userid;
1930 /* Open and lock the parent heap relation */
1932 /* And the target index relation */
1935 /*
1936 * Fetch info needed for index_insert. (You might think this should be
1937 * passed in from DefineIndex, but its copy is long gone due to having
1938 * been built in a previous transaction.)
1939 */
1942 /* mark build is concurrent just for consistency */
1945 /*
1946 * Switch to the table owner's userid, so that any index functions are
1947 * run as that user.
1948 */
1952 /*
1953 * Scan the index and gather up all the TIDs into a tuplesort object.
1954 */
1963 maintenance_work_mem,
1970 /* Execute the sort */
1973 /*
1974 * Now scan the heap and "merge" it with the index
1975 */
1977 indexRelation,
1978 indexInfo,
1979 snapshot,
1982 /* Done with tuplesort object */
1989 /* Restore userid */
1992 /* Close rels, but keep locks */
1995 }
1997 /*
1998 * validate_index_callback - bulkdelete callback to collect the index TIDs
1999 */
2000 static bool
2002 {
2008 }
2010 /*
2011 * validate_index_heapscan - second table scan for concurrent index build
2012 *
2013 * This has much code in common with IndexBuildHeapScan, but it's enough
2014 * different that it seems cleaner to have two routines not one.
2015 */
2016 static void
2018 Relation indexRelation,
2020 Snapshot snapshot,
2022 {
2023 HeapScanDesc scan;
2024 HeapTuple heapTuple;
2035 /* state variables for the merge */
2039 /*
2040 * sanity checks
2041 */
2044 /*
2045 * Need an EState for evaluation of index expressions and partial-index
2046 * predicates. Also a slot to hold the current tuple.
2047 */
2052 /* Arrange for econtext's scan tuple to be the tuple under test */
2055 /* Set up execution state for predicate, if any. */
2058 estate);
2060 /*
2061 * Prepare for scan of the base relation. We need just those tuples
2062 * satisfying the passed-in reference snapshot. We must disable syncscan
2063 * here, because it's critical that we read from block zero forward to
2064 * match the sorted TIDs.
2065 */
2073 /*
2074 * Scan all tuples matching the snapshot.
2075 */
2077 {
2079 ItemPointerData rootTuple;
2080 OffsetNumber root_offnum;
2086 /*
2087 * As commented in IndexBuildHeapScan, we should index heap-only
2088 * tuples under the TIDs of their root tuples; so when we advance onto
2089 * a new heap page, build a map of root item offsets on the page.
2090 *
2091 * This complicates merging against the tuplesort output: we will
2092 * visit the live tuples in order by their offsets, but the root
2093 * offsets that we need to compare against the index contents might be
2094 * ordered differently. So we might have to "look back" within the
2095 * tuplesort output, but only within the current page. We handle that
2096 * by keeping a bool array in_index[] showing all the
2097 * already-passed-over tuplesort output TIDs of the current page. We
2098 * clear that array here, when advancing onto a new heap page.
2099 */
2101 {
2111 }
2113 /* Convert actual tuple TID to root TID */
2118 {
2122 }
2124 /*
2125 * "merge" by skipping through the index tuples until we find or pass
2126 * the current root tuple.
2127 */
2131 {
2132 Datum ts_val;
2136 {
2137 /*
2138 * Remember index items seen earlier on the current heap page
2139 */
2143 }
2149 }
2151 /*
2152 * If the tuplesort has overshot *and* we didn't see a match earlier,
2153 * then this tuple is missing from the index, so insert it.
2154 */
2158 {
2161 /* Set up for predicate or expression evaluation */
2164 /*
2165 * In a partial index, discard tuples that don't satisfy the
2166 * predicate.
2167 */
2169 {
2172 }
2174 /*
2175 * For the current heap tuple, extract all the attributes we use
2176 * in this index, and note which are null. This also performs
2177 * evaluation of any expressions needed.
2178 */
2180 slot,
2181 estate,
2182 values,
2183 isnull);
2185 /*
2186 * You'd think we should go ahead and build the index tuple here,
2187 * but some index AMs want to do further processing on the data
2188 * first. So pass the values[] and isnull[] arrays, instead.
2189 */
2191 /*
2192 * If the tuple is already committed dead, you might think we
2193 * could suppress uniqueness checking, but this is no longer true
2194 * in the presence of HOT, because the insert is actually a proxy
2195 * for a uniqueness check on the whole HOT-chain. That is, the
2196 * tuple we have here could be dead because it was already
2197 * HOT-updated, and if so the updating transaction will not have
2198 * thought it should insert index entries. The index AM will
2199 * check the whole HOT-chain and correctly detect a conflict if
2200 * there is one.
2201 */
2204 values,
2205 isnull,
2207 heapRelation,
2211 }
2212 }
2220 /* These may have been pointing to the now-gone estate */
2223 }
2226 /*
2227 * IndexGetRelation: given an index's relation OID, get the OID of the
2228 * relation it is an index on. Uses the system cache.
2229 */
2230 static Oid
2232 {
2233 HeapTuple tuple;
2234 Form_pg_index index;
2235 Oid result;
2248 }
2250 /*
2251 * reindex_index - This routine is used to recreate a single index
2252 */
2253 void
2255 {
2256 Relation iRel,
2257 heapRelation,
2258 pg_index;
2259 Oid heapId;
2261 HeapTuple indexTuple;
2262 Form_pg_index indexForm;
2264 /*
2265 * Open and lock the parent heap relation. ShareLock is sufficient since
2266 * we only need to be sure no schema or data changes are going on.
2267 */
2271 /*
2272 * Open the target index relation and get an exclusive lock on it, to
2273 * ensure that no one else is touching this particular index.
2274 */
2277 /*
2278 * Don't allow reindex on temp tables of other backends ... their local
2279 * buffer manager is not going to cope.
2280 */
2286 /*
2287 * Also check for active uses of the index in the current transaction;
2288 * we don't want to reindex underneath an open indexscan.
2289 */
2292 /*
2293 * If it's a shared index, we must do inplace processing (because we have
2294 * no way to update relfilenode in other databases). Otherwise we can do
2295 * it the normal transaction-safe way.
2296 *
2297 * Since inplace processing isn't crash-safe, we only allow it in a
2298 * standalone backend. (In the REINDEX TABLE and REINDEX DATABASE cases,
2299 * the caller should have detected this.)
2300 */
2310 {
2313 /* Suppress use of the target index while rebuilding it */
2316 /* Fetch info needed for index_build */
2320 {
2321 /*
2322 * Truncate the actual file (and discard buffers). The indexam
2323 * is responsible for truncating the FSM, if applicable
2324 */
2326 }
2327 else
2328 {
2329 /*
2330 * We'll build a new physical relation for the index.
2331 */
2333 }
2335 /* Initialize the index and rebuild */
2336 /* Note: we do not need to re-establish pkey setting */
2338 }
2340 {
2341 /* Make sure flag gets cleared on error exit */
2344 }
2348 /*
2349 * If the index is marked invalid or not ready (ie, it's from a failed
2350 * CREATE INDEX CONCURRENTLY), we can now mark it valid. This allows
2351 * REINDEX to be used to clean up in such cases.
2352 */
2363 {
2368 }
2371 /* Close rels, but keep locks */
2374 }
2376 /*
2377 * reindex_relation - This routine is used to recreate all indexes
2378 * of a relation (and optionally its toast relation too, if any).
2379 *
2380 * Returns true if any indexes were rebuilt. Note that a
2381 * CommandCounterIncrement will occur after each index rebuild.
2382 */
2383 bool
2385 {
2386 Relation rel;
2387 Oid toast_relid;
2394 /*
2395 * Open and lock the relation. ShareLock is sufficient since we only need
2396 * to prevent schema and data changes in it.
2397 */
2402 /*
2403 * Get the list of index OIDs for this relation. (We trust to the
2404 * relcache to get this with a sequential scan if ignoring system
2405 * indexes.)
2406 */
2409 /*
2410 * reindex_index will attempt to update the pg_class rows for the relation
2411 * and index. If we are processing pg_class itself, we want to make sure
2412 * that the updates do not try to insert index entries into indexes we
2413 * have not processed yet. (When we are trying to recover from corrupted
2414 * indexes, that could easily cause a crash.) We can accomplish this
2415 * because CatalogUpdateIndexes will use the relcache's index list to know
2416 * which indexes to update. We just force the index list to be only the
2417 * stuff we've processed.
2418 *
2419 * It is okay to not insert entries into the indexes we have not processed
2420 * yet because all of this is transaction-safe. If we fail partway
2421 * through, the updated rows are dead and it doesn't matter whether they
2422 * have index entries. Also, a new pg_class index will be created with an
2423 * entry for its own pg_class row because we do setNewRelfilenode() before
2424 * we do index_build().
2425 *
2426 * Note that we also clear pg_class's rd_oidindex until the loop is done,
2427 * so that that index can't be accessed either. This means we cannot
2428 * safely generate new relation OIDs while in the loop; shouldn't be a
2429 * problem.
2430 */
2433 /* Ensure rd_indexattr is valid; see comments for RelationSetIndexList */
2437 /* Reindex all the indexes. */
2440 {
2452 }
2457 /*
2458 * Close rel, but continue to hold the lock.
2459 */
2464 /*
2465 * If the relation has a secondary toast rel, reindex that too while we
2466 * still hold the lock on the master table.
2467 */
2472 }