| blob | e244f92f0b1a0ef64db1510920b4c31e71081d0f |
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 */
240 /*
241 * Make sure the expression yields a type that's safe to store in
242 * an index. We need this defense because we have index opclasses
243 * for pseudo-types such as "record", and the actually stored type
244 * had better be safe; eg, a named composite type is okay, an
245 * anonymous record type is not. The test is the same as for
246 * whether a table column is of a safe type (which is why we
247 * needn't check for the non-expression case).
248 */
250 }
252 /*
253 * We do not yet have the correct relation OID for the index, so just
254 * set it invalid for now. InitializeAttributeOids() will fix it
255 * later.
256 */
259 /*
260 * Check the opclass and index AM to see if either provides a keytype
261 * (overriding the attribute type). Opclass takes precedence.
262 */
272 else
277 {
278 /* index value and heap value have different types */
294 }
295 }
300 }
302 /* ----------------------------------------------------------------
303 * InitializeAttributeOids
304 * ----------------------------------------------------------------
305 */
306 static void
309 Oid indexoid)
310 {
311 TupleDesc tupleDescriptor;
318 }
320 /* ----------------------------------------------------------------
321 * AppendAttributeTuples
322 * ----------------------------------------------------------------
323 */
324 static void
326 {
327 Relation pg_attribute;
328 CatalogIndexState indstate;
329 TupleDesc indexTupDesc;
332 /*
333 * open the attribute relation and its indexes
334 */
339 /*
340 * insert data from new index's tupdesc into pg_attribute
341 */
345 {
346 /*
347 * There used to be very grotty code here to set these fields, but I
348 * think it's unnecessary. They should be set already.
349 */
354 }
359 }
361 /* ----------------------------------------------------------------
362 * UpdateIndexRelation
363 *
364 * Construct and insert a new entry in the pg_index catalog
365 * ----------------------------------------------------------------
366 */
367 static void
369 Oid heapoid,
375 {
379 Datum exprsDatum;
380 Datum predDatum;
383 Relation pg_index;
384 HeapTuple tuple;
387 /*
388 * Copy the index key, opclass, and indoption info into arrays (should we
389 * make the caller pass them like this to start with?)
390 */
397 /*
398 * Convert the index expressions (if any) to a text datum
399 */
401 {
407 }
408 else
411 /*
412 * Convert the index predicate (if any) to a text datum. Note we convert
413 * implicit-AND format to normal explicit-AND for storage.
414 */
416 {
422 }
423 else
426 /*
427 * open the system catalog index relation
428 */
431 /*
432 * Build a pg_index tuple
433 */
444 /* we set isvalid and isready the same way */
458 /*
459 * insert the tuple into the pg_index catalog
460 */
463 /* update the indexes on pg_index */
466 /*
467 * close the relation and free the tuple
468 */
471 }
474 /*
475 * index_create
476 *
477 * heapRelationId: OID of table to build index on
478 * indexRelationName: what it say
479 * indexRelationId: normally, pass InvalidOid to let this routine
480 * generate an OID for the index. During bootstrap this may be
481 * nonzero to specify a preselected OID.
482 * indexInfo: same info executor uses to insert into the index
483 * accessMethodObjectId: OID of index AM to use
484 * tableSpaceId: OID of tablespace to use
485 * classObjectId: array of index opclass OIDs, one per index column
486 * coloptions: array of per-index-column indoption settings
487 * reloptions: AM-specific options
488 * isprimary: index is a PRIMARY KEY
489 * isconstraint: index is owned by a PRIMARY KEY or UNIQUE constraint
490 * allow_system_table_mods: allow table to be a system catalog
491 * skip_build: true to skip the index_build() step for the moment; caller
492 * must do it later (typically via reindex_index())
493 * concurrent: if true, do not lock the table against writers. The index
494 * will be marked "invalid" and the caller must take additional steps
495 * to fix it up.
496 *
497 * Returns OID of the created index.
498 */
499 Oid
502 Oid indexRelationId,
504 Oid accessMethodObjectId,
505 Oid tableSpaceId,
508 Datum reloptions,
514 {
515 Relation pg_class;
516 Relation heapRelation;
517 Relation indexRelation;
518 TupleDesc indexTupDesc;
520 Oid namespaceId;
525 /*
526 * Only SELECT ... FOR UPDATE/SHARE are allowed while doing a standard
527 * index build; but for concurrent builds we allow INSERT/UPDATE/DELETE
528 * (but not VACUUM).
529 */
533 /*
534 * The index will be in the same namespace as its parent table, and is
535 * shared across databases if and only if the parent is.
536 */
540 /*
541 * check parameters
542 */
553 /*
554 * concurrent index build on a system catalog is unsafe because we tend to
555 * release locks before committing in catalogs
556 */
563 /*
564 * We cannot allow indexing a shared relation after initdb (because
565 * there's no way to make the entry in other databases' pg_class).
566 */
572 /*
573 * Validate shared/non-shared tablespace (must check this before doing
574 * GetNewRelFileNode, to prevent Assert therein)
575 */
577 {
579 /* elog since this is not a user-facing error */
582 }
583 else
584 {
589 }
595 indexRelationName)));
597 /*
598 * construct tuple descriptor for index tuples
599 */
601 indexInfo,
602 accessMethodObjectId,
603 classObjectId);
605 /*
606 * Allocate an OID for the index, unless we were told what to use.
607 *
608 * The OID will be the relfilenode as well, so make sure it doesn't
609 * collide with either pg_class OIDs or existing physical files.
610 */
613 pg_class);
615 /*
616 * create the index relation's relcache entry and physical disk file. (If
617 * we fail further down, it's the smgr's responsibility to remove the disk
618 * file again.)
619 */
621 namespaceId,
622 tableSpaceId,
623 indexRelationId,
624 indexTupDesc,
625 RELKIND_INDEX,
626 shared_relation,
627 allow_system_table_mods);
631 /*
632 * Obtain exclusive lock on it. Although no other backends can see it
633 * until we commit, this prevents deadlock-risk complaints from lock
634 * manager in cases such as CLUSTER.
635 */
638 /*
639 * Fill in fields of the index's pg_class entry that are not set correctly
640 * by heap_create.
641 *
642 * XXX should have a cleaner way to create cataloged indexes
643 */
649 /*
650 * store index's pg_class entry
651 */
654 reloptions);
656 /* done with pg_class */
659 /*
660 * now update the object id's of all the attribute tuple forms in the
661 * index relation's tuple descriptor
662 */
665 indexRelationId);
667 /*
668 * append ATTRIBUTE tuples for the index
669 */
672 /* ----------------
673 * update pg_index
674 * (append INDEX tuple)
675 *
676 * Note that this stows away a representation of "predicate".
677 * (Or, could define a rule to maintain the predicate) --Nels, Feb '92
678 * ----------------
679 */
683 /*
684 * Register constraint and dependencies for the index.
685 *
686 * If the index is from a CONSTRAINT clause, construct a pg_constraint
687 * entry. The index is then linked to the constraint, which in turn is
688 * linked to the table. If it's not a CONSTRAINT, make the dependency
689 * directly on the table.
690 *
691 * We don't need a dependency on the namespace, because there'll be an
692 * indirect dependency via our parent table.
693 *
694 * During bootstrap we can't register any dependencies, and we don't try
695 * to make a constraint either.
696 */
698 {
699 ObjectAddress myself,
700 referenced;
707 {
709 Oid conOid;
715 else
716 {
719 }
721 /* Shouldn't have any expressions */
726 namespaceId,
727 constraintType,
730 heapRelationId,
735 NULL,
736 NULL,
737 NULL,
738 NULL,
745 NULL,
746 NULL,
755 }
756 else
757 {
760 /* Create auto dependencies on simply-referenced columns */
762 {
764 {
772 }
773 }
775 /*
776 * It's possible for an index to not depend on any columns of the
777 * table at all, in which case we need to give it a dependency on
778 * the table as a whole; else it won't get dropped when the table
779 * is dropped. This edge case is not totally useless; for
780 * example, a unique index on a constant expression can serve to
781 * prevent a table from containing more than one row.
782 */
786 {
792 }
793 }
795 /* Store dependency on operator classes */
797 {
803 }
805 /* Store dependencies on anything mentioned in index expressions */
807 {
810 heapRelationId,
811 DEPENDENCY_NORMAL,
812 DEPENDENCY_AUTO);
813 }
815 /* Store dependencies on anything mentioned in predicate */
817 {
820 heapRelationId,
821 DEPENDENCY_NORMAL,
822 DEPENDENCY_AUTO);
823 }
824 }
826 /*
827 * Advance the command counter so that we can see the newly-entered
828 * catalog tuples for the index.
829 */
832 /*
833 * In bootstrap mode, we have to fill in the index strategy structure with
834 * information from the catalogs. If we aren't bootstrapping, then the
835 * relcache entry has already been rebuilt thanks to sinval update during
836 * CommandCounterIncrement.
837 */
840 else
843 /*
844 * If this is bootstrap (initdb) time, then we don't actually fill in the
845 * index yet. We'll be creating more indexes and classes later, so we
846 * delay filling them in until just before we're done with bootstrapping.
847 * Similarly, if the caller specified skip_build then filling the index is
848 * delayed till later (ALTER TABLE can save work in some cases with this).
849 * Otherwise, we call the AM routine that constructs the index.
850 */
852 {
854 }
856 {
857 /*
858 * Caller is responsible for filling the index later on. However,
859 * we'd better make sure that the heap relation is correctly marked as
860 * having an index.
861 */
864 isprimary,
865 InvalidOid,
867 /* Make the above update visible */
869 }
870 else
871 {
873 }
875 /*
876 * Close the heap and index; but we keep the locks that we acquired above
877 * until end of transaction.
878 */
883 }
885 /*
886 * index_drop
887 *
888 * NOTE: this routine should now only be called through performDeletion(),
889 * else associated dependencies won't be cleaned up.
890 */
891 void
893 {
894 Oid heapId;
895 Relation userHeapRelation;
896 Relation userIndexRelation;
897 Relation indexRelation;
898 HeapTuple tuple;
900 ForkNumber forknum;
902 /*
903 * To drop an index safely, we must grab exclusive lock on its parent
904 * table; otherwise there could be other backends using the index!
905 * Exclusive lock on the index alone is insufficient because another
906 * backend might be in the midst of devising a query plan that will use
907 * the index. The parser and planner take care to hold an appropriate
908 * lock on the parent table while working, but having them hold locks on
909 * all the indexes too seems overly expensive. We do grab exclusive lock
910 * on the index too, just to be safe. Both locks must be held till end of
911 * transaction, else other backends will still see this index in pg_index.
912 */
918 /*
919 * Schedule physical removal of the files
920 */
928 /*
929 * Close and flush the index's relcache entry, to ensure relcache doesn't
930 * try to rebuild it while we're deleting catalog entries. We keep the
931 * lock though.
932 */
937 /*
938 * fix INDEX relation, and check for expressional index
939 */
955 /*
956 * if it has any expression columns, we might have stored statistics about
957 * them.
958 */
962 /*
963 * fix ATTRIBUTE relation
964 */
967 /*
968 * fix RELATION relation
969 */
972 /*
973 * We are presently too lazy to attempt to compute the new correct value
974 * of relhasindex (the next VACUUM will fix it if necessary). So there is
975 * no need to update the pg_class tuple for the owning relation. But we
976 * must send out a shared-cache-inval notice on the owning relation to
977 * ensure other backends update their relcache lists of indexes.
978 */
981 /*
982 * Close owning rel, but keep lock
983 */
985 }
987 /* ----------------------------------------------------------------
988 * index_build support
989 * ----------------------------------------------------------------
990 */
992 /* ----------------
993 * BuildIndexInfo
994 * Construct an IndexInfo record for an open index
995 *
996 * IndexInfo stores the information about the index that's needed by
997 * FormIndexDatum, which is used for both index_build() and later insertion
998 * of individual index tuples. Normally we build an IndexInfo for an index
999 * just once per command, and then use it for (potentially) many tuples.
1000 * ----------------
1001 */
1002 IndexInfo *
1004 {
1010 /* check the number of keys, and copy attr numbers into the IndexInfo */
1019 /* fetch any expressions needed for expressional indexes */
1023 /* fetch index predicate if any */
1027 /* other info */
1031 /* initialize index-build state to default */
1036 }
1038 /* ----------------
1039 * FormIndexDatum
1040 * Construct values[] and isnull[] arrays for a new index tuple.
1041 *
1042 * indexInfo Info about the index
1043 * slot Heap tuple for which we must prepare an index entry
1044 * estate executor state for evaluating any index expressions
1045 * values Array of index Datums (output area)
1046 * isnull Array of is-null indicators (output area)
1047 *
1048 * When there are no index expressions, estate may be NULL. Otherwise it
1049 * must be supplied, *and* the ecxt_scantuple slot of its per-tuple expr
1050 * context must point to the heap tuple passed in.
1051 *
1052 * Notice we don't actually call index_form_tuple() here; we just prepare
1053 * its input arrays values[] and isnull[]. This is because the index AM
1054 * may wish to alter the data before storage.
1055 * ----------------
1056 */
1057 void
1063 {
1069 {
1070 /* First time through, set up expression evaluation state */
1073 estate);
1074 /* Check caller has set up context correctly */
1076 }
1080 {
1082 Datum iDatum;
1086 {
1087 /*
1088 * Plain index column; get the value we need directly from the
1089 * heap tuple.
1090 */
1092 }
1093 else
1094 {
1095 /*
1096 * Index expression --- need to evaluate it.
1097 */
1103 NULL);
1105 }
1108 }
1112 }
1115 /*
1116 * index_update_stats --- update pg_class entry after CREATE INDEX or REINDEX
1117 *
1118 * This routine updates the pg_class row of either an index or its parent
1119 * relation after CREATE INDEX or REINDEX. Its rather bizarre API is designed
1120 * to ensure we can do all the necessary work in just one update.
1121 *
1122 * hasindex: set relhasindex to this value
1123 * isprimary: if true, set relhaspkey true; else no change
1124 * reltoastidxid: if not InvalidOid, set reltoastidxid to this value;
1125 * else no change
1126 * reltuples: set reltuples to this value
1127 *
1128 * relpages is also updated (using RelationGetNumberOfBlocks()).
1129 *
1130 * NOTE: an important side-effect of this operation is that an SI invalidation
1131 * message is sent out to all backends --- including me --- causing relcache
1132 * entries to be flushed or updated with the new data. This must happen even
1133 * if we find that no change is needed in the pg_class row. When updating
1134 * a heap entry, this ensures that other backends find out about the new
1135 * index. When updating an index, it's important because some index AMs
1136 * expect a relcache flush to occur after REINDEX.
1137 */
1138 static void
1141 {
1144 Relation pg_class;
1145 HeapTuple tuple;
1146 Form_pg_class rd_rel;
1149 /*
1150 * We always update the pg_class row using a non-transactional,
1151 * overwrite-in-place update. There are several reasons for this:
1152 *
1153 * 1. In bootstrap mode, we have no choice --- UPDATE wouldn't work.
1154 *
1155 * 2. We could be reindexing pg_class itself, in which case we can't move
1156 * its pg_class row because CatalogUpdateIndexes might not know about all
1157 * the indexes yet (see reindex_relation).
1158 *
1159 * 3. Because we execute CREATE INDEX with just share lock on the parent
1160 * rel (to allow concurrent index creations), an ordinary update could
1161 * suffer a tuple-concurrently-updated failure against another CREATE
1162 * INDEX committing at about the same time. We can avoid that by having
1163 * them both do nontransactional updates (we assume they will both be
1164 * trying to change the pg_class row to the same thing, so it doesn't
1165 * matter which goes first).
1166 *
1167 * 4. Even with just a single CREATE INDEX, there's a risk factor because
1168 * someone else might be trying to open the rel while we commit, and this
1169 * creates a race condition as to whether he will see both or neither of
1170 * the pg_class row versions as valid. Again, a non-transactional update
1171 * avoids the risk. It is indeterminate which state of the row the other
1172 * process will see, but it doesn't matter (if he's only taking
1173 * AccessShareLock, then it's not critical that he see relhasindex true).
1174 *
1175 * It is safe to use a non-transactional update even though our
1176 * transaction could still fail before committing. Setting relhasindex
1177 * true is safe even if there are no indexes (VACUUM will eventually fix
1178 * it), and of course the relpages and reltuples counts are correct (or at
1179 * least more so than the old values) regardless.
1180 */
1184 /*
1185 * Make a copy of the tuple to update. Normally we use the syscache, but
1186 * we can't rely on that during bootstrap or while reindexing pg_class
1187 * itself.
1188 */
1191 {
1192 /* don't assume syscache will work */
1193 HeapScanDesc pg_class_scan;
1197 ObjectIdAttributeNumber,
1205 }
1206 else
1207 {
1208 /* normal case, use syscache */
1212 }
1218 /* Apply required updates, if any, to copied tuple */
1222 {
1225 }
1227 {
1229 {
1232 }
1233 }
1235 {
1238 {
1241 }
1242 }
1244 {
1247 }
1249 {
1252 }
1254 /*
1255 * If anything changed, write out the tuple
1256 */
1258 {
1260 /* the above sends a cache inval message */
1261 }
1262 else
1263 {
1264 /* no need to change tuple, but force relcache inval anyway */
1266 }
1271 }
1273 /*
1274 * setNewRelfilenode - assign a new relfilenode value to the relation
1275 *
1276 * Caller must already hold exclusive lock on the relation.
1277 *
1278 * The relation is marked with relfrozenxid=freezeXid (InvalidTransactionId
1279 * must be passed for indexes)
1280 */
1281 void
1283 {
1284 Oid newrelfilenode;
1285 RelFileNode newrnode;
1286 SMgrRelation srel;
1287 Relation pg_class;
1288 HeapTuple tuple;
1289 Form_pg_class rd_rel;
1290 ForkNumber i;
1292 /* Can't change relfilenode for nailed tables (indexes ok though) */
1295 /* Can't change for shared tables or indexes */
1297 /* Indexes must have Invalid frozenxid; other relations must not */
1302 /* Allocate a new relfilenode */
1305 NULL);
1307 /*
1308 * Find the pg_class tuple for the given relation. This is not used
1309 * during bootstrap, so okay to use heap_update always.
1310 */
1323 /*
1324 * ... and create storage for corresponding forks in the new relfilenode.
1325 *
1326 * NOTE: any conflict in relfilenode value will be caught here
1327 */
1332 /* Create the main fork, like heap_create() does */
1335 /*
1336 * For a heap, create FSM fork as well. Indexams are responsible for
1337 * creating any extra forks themselves.
1338 */
1343 /* schedule unlinking old files */
1345 {
1348 }
1353 /* update the pg_class row */
1365 /* Make sure the relfilenode change is visible */
1368 /* Mark the rel as having a new relfilenode in current transaction */
1370 }
1373 /*
1374 * index_build - invoke access-method-specific index build procedure
1375 *
1376 * On entry, the index's catalog entries are valid, and its physical disk
1377 * file has been created but is empty. We call the AM-specific build
1378 * procedure to fill in the index contents. We then update the pg_class
1379 * entries of the index and heap relation as needed, using statistics
1380 * returned by ambuild as well as data passed by the caller.
1381 *
1382 * Note: when reindexing an existing index, isprimary can be false;
1383 * the index is already properly marked and need not be re-marked.
1384 *
1385 * Note: before Postgres 8.2, the passed-in heap and index Relations
1386 * were automatically closed by this routine. This is no longer the case.
1387 * The caller opened 'em, and the caller should close 'em.
1388 */
1389 void
1391 Relation indexRelation,
1394 {
1395 RegProcedure procedure;
1397 Oid save_userid;
1400 /*
1401 * sanity checks
1402 */
1409 /*
1410 * Switch to the table owner's userid, so that any index functions are
1411 * run as that user.
1412 */
1416 /*
1417 * Call the access method's build procedure
1418 */
1426 /* Restore userid */
1429 /*
1430 * If we found any potentially broken HOT chains, mark the index as not
1431 * being usable until the current transaction is below the event horizon.
1432 * See src/backend/access/heap/README.HOT for discussion.
1433 */
1435 {
1437 Relation pg_index;
1438 HeapTuple indexTuple;
1439 Form_pg_index indexForm;
1456 }
1458 /*
1459 * Update heap and index pg_class rows
1460 */
1463 isprimary,
1471 InvalidOid,
1474 /* Make the updated versions visible */
1476 }
1479 /*
1480 * IndexBuildHeapScan - scan the heap relation to find tuples to be indexed
1481 *
1482 * This is called back from an access-method-specific index build procedure
1483 * after the AM has done whatever setup it needs. The parent heap relation
1484 * is scanned to find tuples that should be entered into the index. Each
1485 * such tuple is passed to the AM's callback routine, which does the right
1486 * things to add it to the new index. After we return, the AM's index
1487 * build procedure does whatever cleanup is needed; in particular, it should
1488 * close the heap and index relations.
1489 *
1490 * The total count of heap tuples is returned. This is for updating pg_class
1491 * statistics. (It's annoying not to be able to do that here, but we can't
1492 * do it until after the relation is closed.) Note that the index AM itself
1493 * must keep track of the number of index tuples; we don't do so here because
1494 * the AM might reject some of the tuples for its own reasons, such as being
1495 * unable to store NULLs.
1496 *
1497 * A side effect is to set indexInfo->ii_BrokenHotChain to true if we detect
1498 * any potentially broken HOT chains. Currently, we set this if there are
1499 * any RECENTLY_DEAD entries in a HOT chain, without trying very hard to
1500 * detect whether they're really incompatible with the chain tip.
1501 */
1502 double
1504 Relation indexRelation,
1507 IndexBuildCallback callback,
1509 {
1510 HeapScanDesc scan;
1511 HeapTuple heapTuple;
1519 Snapshot snapshot;
1520 TransactionId OldestXmin;
1524 /*
1525 * sanity checks
1526 */
1529 /*
1530 * Need an EState for evaluation of index expressions and partial-index
1531 * predicates. Also a slot to hold the current tuple.
1532 */
1537 /* Arrange for econtext's scan tuple to be the tuple under test */
1540 /* Set up execution state for predicate, if any. */
1543 estate);
1545 /*
1546 * Prepare for scan of the base relation. In a normal index build, we use
1547 * SnapshotAny because we must retrieve all tuples and do our own time
1548 * qual checks (because we have to index RECENTLY_DEAD tuples). In a
1549 * concurrent build, we take a regular MVCC snapshot and index whatever's
1550 * live according to that. During bootstrap we just use SnapshotNow.
1551 */
1553 {
1556 }
1558 {
1561 }
1562 else
1563 {
1565 /* okay to ignore lazy VACUUMs here */
1567 }
1578 /*
1579 * Scan all tuples in the base relation.
1580 */
1582 {
1587 /*
1588 * When dealing with a HOT-chain of updated tuples, we want to index
1589 * the values of the live tuple (if any), but index it under the TID
1590 * of the chain's root tuple. This approach is necessary to preserve
1591 * the HOT-chain structure in the heap. So we need to be able to find
1592 * the root item offset for every tuple that's in a HOT-chain. When
1593 * first reaching a new page of the relation, call
1594 * heap_get_root_tuples() to build a map of root item offsets on the
1595 * page.
1596 *
1597 * It might look unsafe to use this information across buffer
1598 * lock/unlock. However, we hold ShareLock on the table so no
1599 * ordinary insert/update/delete should occur; and we hold pin on the
1600 * buffer continuously while visiting the page, so no pruning
1601 * operation can occur either.
1602 *
1603 * Note the implied assumption that there is no more than one live
1604 * tuple per HOT-chain ...
1605 */
1607 {
1615 }
1618 {
1619 /* do our own time qual check */
1622 recheck:
1624 /*
1625 * We could possibly get away with not locking the buffer here,
1626 * since caller should hold ShareLock on the relation, but let's
1627 * be conservative about it. (This remark is still correct even
1628 * with HOT-pruning: our pin on the buffer prevents pruning.)
1629 */
1634 {
1636 /* Definitely dead, we can ignore it */
1641 /* Normal case, index and unique-check it */
1647 /*
1648 * If tuple is recently deleted then we must index it
1649 * anyway to preserve MVCC semantics. (Pre-existing
1650 * transactions could try to use the index after we finish
1651 * building it, and may need to see such tuples.)
1652 *
1653 * However, if it was HOT-updated then we must only index
1654 * the live tuple at the end of the HOT-chain. Since this
1655 * breaks semantics for pre-existing snapshots, mark the
1656 * index as unusable for them.
1657 *
1658 * If we've already decided that the index will be unsafe
1659 * for old snapshots, we may as well stop indexing
1660 * recently-dead tuples, since there's no longer any
1661 * point.
1662 */
1664 {
1666 /* mark the index as unsafe for old snapshots */
1668 }
1671 else
1673 /* In any case, exclude the tuple from unique-checking */
1678 /*
1679 * Since caller should hold ShareLock or better, we should
1680 * not see any tuples inserted by open transactions ---
1681 * unless it's our own transaction. (Consider INSERT
1682 * followed by CREATE INDEX within a transaction.) An
1683 * exception occurs when reindexing a system catalog,
1684 * because we often release lock on system catalogs before
1685 * committing. In that case we wait for the inserting
1686 * transaction to finish and check again. (We could do
1687 * that on user tables too, but since the case is not
1688 * expected it seems better to throw an error.)
1689 */
1692 {
1695 else
1696 {
1697 /*
1698 * Must drop the lock on the buffer before we wait
1699 */
1705 }
1706 }
1708 /*
1709 * We must index such tuples, since if the index build
1710 * commits then they're good.
1711 */
1717 /*
1718 * Since caller should hold ShareLock or better, we should
1719 * not see any tuples deleted by open transactions ---
1720 * unless it's our own transaction. (Consider DELETE
1721 * followed by CREATE INDEX within a transaction.) An
1722 * exception occurs when reindexing a system catalog,
1723 * because we often release lock on system catalogs before
1724 * committing. In that case we wait for the deleting
1725 * transaction to finish and check again. (We could do
1726 * that on user tables too, but since the case is not
1727 * expected it seems better to throw an error.)
1728 */
1732 {
1735 else
1736 {
1737 /*
1738 * Must drop the lock on the buffer before we wait
1739 */
1745 }
1746 }
1748 /*
1749 * Otherwise, we have to treat these tuples just like
1750 * RECENTLY_DELETED ones.
1751 */
1753 {
1755 /* mark the index as unsafe for old snapshots */
1757 }
1760 else
1762 /* In any case, exclude the tuple from unique-checking */
1769 }
1775 }
1776 else
1777 {
1778 /* heap_getnext did the time qual check */
1780 }
1786 /* Set up for predicate or expression evaluation */
1789 /*
1790 * In a partial index, discard tuples that don't satisfy the
1791 * predicate.
1792 */
1794 {
1797 }
1799 /*
1800 * For the current heap tuple, extract all the attributes we use in
1801 * this index, and note which are null. This also performs evaluation
1802 * of any expressions needed.
1803 */
1805 slot,
1806 estate,
1807 values,
1808 isnull);
1810 /*
1811 * You'd think we should go ahead and build the index tuple here, but
1812 * some index AMs want to do further processing on the data first. So
1813 * pass the values[] and isnull[] arrays, instead.
1814 */
1817 {
1818 /*
1819 * For a heap-only tuple, pretend its TID is that of the root. See
1820 * src/backend/access/heap/README.HOT for discussion.
1821 */
1822 HeapTupleData rootTuple;
1823 OffsetNumber offnum;
1833 /* Call the AM's callback routine to process the tuple */
1835 callback_state);
1836 }
1837 else
1838 {
1839 /* Call the AM's callback routine to process the tuple */
1841 callback_state);
1842 }
1843 }
1847 /* we can now forget our snapshot, if set */
1855 /* These may have been pointing to the now-gone estate */
1860 }
1863 /*
1864 * validate_index - support code for concurrent index builds
1865 *
1866 * We do a concurrent index build by first inserting the catalog entry for the
1867 * index via index_create(), marking it not indisready and not indisvalid.
1868 * Then we commit our transaction and start a new one, then we wait for all
1869 * transactions that could have been modifying the table to terminate. Now
1870 * we know that any subsequently-started transactions will see the index and
1871 * honor its constraints on HOT updates; so while existing HOT-chains might
1872 * be broken with respect to the index, no currently live tuple will have an
1873 * incompatible HOT update done to it. We now build the index normally via
1874 * index_build(), while holding a weak lock that allows concurrent
1875 * insert/update/delete. Also, we index only tuples that are valid
1876 * as of the start of the scan (see IndexBuildHeapScan), whereas a normal
1877 * build takes care to include recently-dead tuples. This is OK because
1878 * we won't mark the index valid until all transactions that might be able
1879 * to see those tuples are gone. The reason for doing that is to avoid
1880 * bogus unique-index failures due to concurrent UPDATEs (we might see
1881 * different versions of the same row as being valid when we pass over them,
1882 * if we used HeapTupleSatisfiesVacuum). This leaves us with an index that
1883 * does not contain any tuples added to the table while we built the index.
1884 *
1885 * Next, we mark the index "indisready" (but still not "indisvalid") and
1886 * commit the second transaction and start a third. Again we wait for all
1887 * transactions that could have been modifying the table to terminate. Now
1888 * we know that any subsequently-started transactions will see the index and
1889 * insert their new tuples into it. We then take a new reference snapshot
1890 * which is passed to validate_index(). Any tuples that are valid according
1891 * to this snap, but are not in the index, must be added to the index.
1892 * (Any tuples committed live after the snap will be inserted into the
1893 * index by their originating transaction. Any tuples committed dead before
1894 * the snap need not be indexed, because we will wait out all transactions
1895 * that might care about them before we mark the index valid.)
1896 *
1897 * validate_index() works by first gathering all the TIDs currently in the
1898 * index, using a bulkdelete callback that just stores the TIDs and doesn't
1899 * ever say "delete it". (This should be faster than a plain indexscan;
1900 * also, not all index AMs support full-index indexscan.) Then we sort the
1901 * TIDs, and finally scan the table doing a "merge join" against the TID list
1902 * to see which tuples are missing from the index. Thus we will ensure that
1903 * all tuples valid according to the reference snapshot are in the index.
1904 *
1905 * Building a unique index this way is tricky: we might try to insert a
1906 * tuple that is already dead or is in process of being deleted, and we
1907 * mustn't have a uniqueness failure against an updated version of the same
1908 * row. We could try to check the tuple to see if it's already dead and tell
1909 * index_insert() not to do the uniqueness check, but that still leaves us
1910 * with a race condition against an in-progress update. To handle that,
1911 * we expect the index AM to recheck liveness of the to-be-inserted tuple
1912 * before it declares a uniqueness error.
1913 *
1914 * After completing validate_index(), we wait until all transactions that
1915 * were alive at the time of the reference snapshot are gone; this is
1916 * necessary to be sure there are none left with a serializable snapshot
1917 * older than the reference (and hence possibly able to see tuples we did
1918 * not index). Then we mark the index "indisvalid" and commit. Subsequent
1919 * transactions will be able to use it for queries.
1920 *
1921 * Doing two full table scans is a brute-force strategy. We could try to be
1922 * cleverer, eg storing new tuples in a special area of the table (perhaps
1923 * making the table append-only by setting use_fsm). However that would
1924 * add yet more locking issues.
1925 */
1926 void
1928 {
1929 Relation heapRelation,
1930 indexRelation;
1932 IndexVacuumInfo ivinfo;
1933 v_i_state state;
1934 Oid save_userid;
1937 /* Open and lock the parent heap relation */
1939 /* And the target index relation */
1942 /*
1943 * Fetch info needed for index_insert. (You might think this should be
1944 * passed in from DefineIndex, but its copy is long gone due to having
1945 * been built in a previous transaction.)
1946 */
1949 /* mark build is concurrent just for consistency */
1952 /*
1953 * Switch to the table owner's userid, so that any index functions are
1954 * run as that user.
1955 */
1959 /*
1960 * Scan the index and gather up all the TIDs into a tuplesort object.
1961 */
1970 maintenance_work_mem,
1977 /* Execute the sort */
1980 /*
1981 * Now scan the heap and "merge" it with the index
1982 */
1984 indexRelation,
1985 indexInfo,
1986 snapshot,
1989 /* Done with tuplesort object */
1996 /* Restore userid */
1999 /* Close rels, but keep locks */
2002 }
2004 /*
2005 * validate_index_callback - bulkdelete callback to collect the index TIDs
2006 */
2007 static bool
2009 {
2015 }
2017 /*
2018 * validate_index_heapscan - second table scan for concurrent index build
2019 *
2020 * This has much code in common with IndexBuildHeapScan, but it's enough
2021 * different that it seems cleaner to have two routines not one.
2022 */
2023 static void
2025 Relation indexRelation,
2027 Snapshot snapshot,
2029 {
2030 HeapScanDesc scan;
2031 HeapTuple heapTuple;
2042 /* state variables for the merge */
2046 /*
2047 * sanity checks
2048 */
2051 /*
2052 * Need an EState for evaluation of index expressions and partial-index
2053 * predicates. Also a slot to hold the current tuple.
2054 */
2059 /* Arrange for econtext's scan tuple to be the tuple under test */
2062 /* Set up execution state for predicate, if any. */
2065 estate);
2067 /*
2068 * Prepare for scan of the base relation. We need just those tuples
2069 * satisfying the passed-in reference snapshot. We must disable syncscan
2070 * here, because it's critical that we read from block zero forward to
2071 * match the sorted TIDs.
2072 */
2080 /*
2081 * Scan all tuples matching the snapshot.
2082 */
2084 {
2086 ItemPointerData rootTuple;
2087 OffsetNumber root_offnum;
2093 /*
2094 * As commented in IndexBuildHeapScan, we should index heap-only
2095 * tuples under the TIDs of their root tuples; so when we advance onto
2096 * a new heap page, build a map of root item offsets on the page.
2097 *
2098 * This complicates merging against the tuplesort output: we will
2099 * visit the live tuples in order by their offsets, but the root
2100 * offsets that we need to compare against the index contents might be
2101 * ordered differently. So we might have to "look back" within the
2102 * tuplesort output, but only within the current page. We handle that
2103 * by keeping a bool array in_index[] showing all the
2104 * already-passed-over tuplesort output TIDs of the current page. We
2105 * clear that array here, when advancing onto a new heap page.
2106 */
2108 {
2118 }
2120 /* Convert actual tuple TID to root TID */
2125 {
2129 }
2131 /*
2132 * "merge" by skipping through the index tuples until we find or pass
2133 * the current root tuple.
2134 */
2138 {
2139 Datum ts_val;
2143 {
2144 /*
2145 * Remember index items seen earlier on the current heap page
2146 */
2150 }
2156 }
2158 /*
2159 * If the tuplesort has overshot *and* we didn't see a match earlier,
2160 * then this tuple is missing from the index, so insert it.
2161 */
2165 {
2168 /* Set up for predicate or expression evaluation */
2171 /*
2172 * In a partial index, discard tuples that don't satisfy the
2173 * predicate.
2174 */
2176 {
2179 }
2181 /*
2182 * For the current heap tuple, extract all the attributes we use
2183 * in this index, and note which are null. This also performs
2184 * evaluation of any expressions needed.
2185 */
2187 slot,
2188 estate,
2189 values,
2190 isnull);
2192 /*
2193 * You'd think we should go ahead and build the index tuple here,
2194 * but some index AMs want to do further processing on the data
2195 * first. So pass the values[] and isnull[] arrays, instead.
2196 */
2198 /*
2199 * If the tuple is already committed dead, you might think we
2200 * could suppress uniqueness checking, but this is no longer true
2201 * in the presence of HOT, because the insert is actually a proxy
2202 * for a uniqueness check on the whole HOT-chain. That is, the
2203 * tuple we have here could be dead because it was already
2204 * HOT-updated, and if so the updating transaction will not have
2205 * thought it should insert index entries. The index AM will
2206 * check the whole HOT-chain and correctly detect a conflict if
2207 * there is one.
2208 */
2211 values,
2212 isnull,
2214 heapRelation,
2218 }
2219 }
2227 /* These may have been pointing to the now-gone estate */
2230 }
2233 /*
2234 * IndexGetRelation: given an index's relation OID, get the OID of the
2235 * relation it is an index on. Uses the system cache.
2236 */
2237 static Oid
2239 {
2240 HeapTuple tuple;
2241 Form_pg_index index;
2242 Oid result;
2255 }
2257 /*
2258 * reindex_index - This routine is used to recreate a single index
2259 */
2260 void
2262 {
2263 Relation iRel,
2264 heapRelation,
2265 pg_index;
2266 Oid heapId;
2268 HeapTuple indexTuple;
2269 Form_pg_index indexForm;
2271 /*
2272 * Open and lock the parent heap relation. ShareLock is sufficient since
2273 * we only need to be sure no schema or data changes are going on.
2274 */
2278 /*
2279 * Open the target index relation and get an exclusive lock on it, to
2280 * ensure that no one else is touching this particular index.
2281 */
2284 /*
2285 * Don't allow reindex on temp tables of other backends ... their local
2286 * buffer manager is not going to cope.
2287 */
2293 /*
2294 * Also check for active uses of the index in the current transaction;
2295 * we don't want to reindex underneath an open indexscan.
2296 */
2299 /*
2300 * If it's a shared index, we must do inplace processing (because we have
2301 * no way to update relfilenode in other databases). Otherwise we can do
2302 * it the normal transaction-safe way.
2303 *
2304 * Since inplace processing isn't crash-safe, we only allow it in a
2305 * standalone backend. (In the REINDEX TABLE and REINDEX DATABASE cases,
2306 * the caller should have detected this.)
2307 */
2317 {
2320 /* Suppress use of the target index while rebuilding it */
2323 /* Fetch info needed for index_build */
2327 {
2328 /*
2329 * Truncate the actual file (and discard buffers). The indexam
2330 * is responsible for truncating the FSM, if applicable
2331 */
2333 }
2334 else
2335 {
2336 /*
2337 * We'll build a new physical relation for the index.
2338 */
2340 }
2342 /* Initialize the index and rebuild */
2343 /* Note: we do not need to re-establish pkey setting */
2345 }
2347 {
2348 /* Make sure flag gets cleared on error exit */
2351 }
2355 /*
2356 * If the index is marked invalid or not ready (ie, it's from a failed
2357 * CREATE INDEX CONCURRENTLY), we can now mark it valid. This allows
2358 * REINDEX to be used to clean up in such cases.
2359 */
2370 {
2375 }
2378 /* Close rels, but keep locks */
2381 }
2383 /*
2384 * reindex_relation - This routine is used to recreate all indexes
2385 * of a relation (and optionally its toast relation too, if any).
2386 *
2387 * Returns true if any indexes were rebuilt. Note that a
2388 * CommandCounterIncrement will occur after each index rebuild.
2389 */
2390 bool
2392 {
2393 Relation rel;
2394 Oid toast_relid;
2401 /*
2402 * Open and lock the relation. ShareLock is sufficient since we only need
2403 * to prevent schema and data changes in it.
2404 */
2409 /*
2410 * Get the list of index OIDs for this relation. (We trust to the
2411 * relcache to get this with a sequential scan if ignoring system
2412 * indexes.)
2413 */
2416 /*
2417 * reindex_index will attempt to update the pg_class rows for the relation
2418 * and index. If we are processing pg_class itself, we want to make sure
2419 * that the updates do not try to insert index entries into indexes we
2420 * have not processed yet. (When we are trying to recover from corrupted
2421 * indexes, that could easily cause a crash.) We can accomplish this
2422 * because CatalogUpdateIndexes will use the relcache's index list to know
2423 * which indexes to update. We just force the index list to be only the
2424 * stuff we've processed.
2425 *
2426 * It is okay to not insert entries into the indexes we have not processed
2427 * yet because all of this is transaction-safe. If we fail partway
2428 * through, the updated rows are dead and it doesn't matter whether they
2429 * have index entries. Also, a new pg_class index will be created with an
2430 * entry for its own pg_class row because we do setNewRelfilenode() before
2431 * we do index_build().
2432 *
2433 * Note that we also clear pg_class's rd_oidindex until the loop is done,
2434 * so that that index can't be accessed either. This means we cannot
2435 * safely generate new relation OIDs while in the loop; shouldn't be a
2436 * problem.
2437 */
2440 /* Ensure rd_indexattr is valid; see comments for RelationSetIndexList */
2444 /* Reindex all the indexes. */
2447 {
2459 }
2464 /*
2465 * Close rel, but continue to hold the lock.
2466 */
2471 /*
2472 * If the relation has a secondary toast rel, reindex that too while we
2473 * still hold the lock on the master table.
2474 */
2479 }