/*-------------------------------------------------------------------------

 *

 * indexing.c

 *    This file contains routines to support indexes defined on system

 *    catalogs.

 *

 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group

 * Portions Copyright (c) 1994, Regents of the University of California

 *

 *

 * IDENTIFICATION

 *    src/backend/catalog/indexing.c

 *

 *-------------------------------------------------------------------------

 */

#include "postgres.h"

#include "access/genam.h"

#include "access/heapam.h"

#include "access/htup_details.h"

#include "access/xact.h"

#include "catalog/index.h"

#include "catalog/indexing.h"

#include "executor/executor.h"

#include "utils/rel.h"

/*

 * CatalogOpenIndexes - open the indexes on a system catalog.

 *

 * When inserting or updating tuples in a system catalog, call this

 * to prepare to update the indexes for the catalog.

 *

 * In the current implementation, we share code for opening/closing the

 * indexes with execUtils.c.  But we do not use ExecInsertIndexTuples,

 * because we don't want to create an EState.  This implies that we

 * do not support partial or expressional indexes on system catalogs,

 * nor can we support generalized exclusion constraints.

 * This could be fixed with localized changes here if we wanted to pay

 * the extra overhead of building an EState.

 */

CatalogIndexState

CatalogOpenIndexes(Relation heapRel)

{

  ResultRelInfo *resultRelInfo;

  resultRelInfo = makeNode(ResultRelInfo);

  resultRelInfo->ri_RangeTableIndex = 0;  /* dummy */

  resultRelInfo->ri_RelationDesc = heapRel;

  resultRelInfo->ri_TrigDesc = NULL; /* we don't fire triggers */

  ExecOpenIndices(resultRelInfo, false);

  return resultRelInfo;

}

/*

 * CatalogCloseIndexes - clean up resources allocated by CatalogOpenIndexes

 */

void

CatalogCloseIndexes(CatalogIndexState indstate)

{

  ExecCloseIndices(indstate);

  pfree(indstate);

}

/*

 * CatalogIndexInsert - insert index entries for one catalog tuple

 *

 * This should be called for each inserted or updated catalog tuple.

 *

 * This is effectively a cut-down version of ExecInsertIndexTuples.

 */

static void

CatalogIndexInsert(CatalogIndexState indstate, HeapTuple heapTuple,

           TU_UpdateIndexes updateIndexes)

{

  int     i;

  int     numIndexes;

  RelationPtr relationDescs;

  Relation  heapRelation;

  TupleTableSlot *slot;

  IndexInfo **indexInfoArray;

  Datum   values[INDEX_MAX_KEYS];

  bool    isnull[INDEX_MAX_KEYS];

  bool    onlySummarized = (updateIndexes == TU_Summarizing);

  /*

   * HOT update does not require index inserts. But with asserts enabled we

   * want to check that it'd be legal to currently insert into the

   * table/index.

   */

#ifndef USE_ASSERT_CHECKING

  if (HeapTupleIsHeapOnly(heapTuple) && !onlySummarized)

    return;

#endif

  /* When only updating summarized indexes, the tuple has to be HOT. */

  Assert((!onlySummarized) || HeapTupleIsHeapOnly(heapTuple));

  /*

   * Get information from the state structure.  Fall out if nothing to do.

   */

  numIndexes = indstate->ri_NumIndices;

  if (numIndexes == 0)

    return;

  relationDescs = indstate->ri_IndexRelationDescs;

  indexInfoArray = indstate->ri_IndexRelationInfo;

  heapRelation = indstate->ri_RelationDesc;

  /* Need a slot to hold the tuple being examined */

  slot = MakeSingleTupleTableSlot(RelationGetDescr(heapRelation),

                  &TTSOpsHeapTuple);

  ExecStoreHeapTuple(heapTuple, slot, false);

  /*

   * for each index, form and insert the index tuple

   */

  for (i = 0; i < numIndexes; i++)

  {

    IndexInfo  *indexInfo;

    Relation  index;

    indexInfo = indexInfoArray[i];

    index = relationDescs[i];

    /* If the index is marked as read-only, ignore it */

    if (!indexInfo->ii_ReadyForInserts)

      continue;

    /*

     * Expressional and partial indexes on system catalogs are not

     * supported, nor exclusion constraints, nor deferred uniqueness

     */

    Assert(indexInfo->ii_Expressions == NIL);

    Assert(indexInfo->ii_Predicate == NIL);

    Assert(indexInfo->ii_ExclusionOps == NULL);

    Assert(index->rd_index->indimmediate);

    Assert(indexInfo->ii_NumIndexKeyAttrs != 0);

    /* see earlier check above */

#ifdef USE_ASSERT_CHECKING

    if (HeapTupleIsHeapOnly(heapTuple) && !onlySummarized)

    {

      Assert(!ReindexIsProcessingIndex(RelationGetRelid(index)));

      continue;

    }

#endif              /* USE_ASSERT_CHECKING */

    /*

     * Skip insertions into non-summarizing indexes if we only need to

     * update summarizing indexes.

     */

    if (onlySummarized && !indexInfo->ii_Summarizing)

      continue;

    /*

     * FormIndexDatum fills in its values and isnull parameters with the

     * appropriate values for the column(s) of the index.

     */

    FormIndexDatum(indexInfo,

             slot,

             NULL, /* no expression eval to do */

             values,

             isnull);

    /*

     * The index AM does the rest.

     */

    index_insert(index,   /* index relation */

           values,  /* array of index Datums */

           isnull,  /* is-null flags */

           &(heapTuple->t_self),  /* tid of heap tuple */

           heapRelation,

           index->rd_index->indisunique ?

           UNIQUE_CHECK_YES : UNIQUE_CHECK_NO,

           false,

           indexInfo);

  }

  ExecDropSingleTupleTableSlot(slot);

}

/*

 * Subroutine to verify that catalog constraints are honored.

 *

 * Tuples inserted via CatalogTupleInsert/CatalogTupleUpdate are generally

 * "hand made", so that it's possible that they fail to satisfy constraints

 * that would be checked if they were being inserted by the executor.  That's

 * a coding error, so we only bother to check for it in assert-enabled builds.

 */

#ifdef USE_ASSERT_CHECKING

static void

CatalogTupleCheckConstraints(Relation heapRel, HeapTuple tup)

{

  /*

   * Currently, the only constraints implemented for system catalogs are

   * attnotnull constraints.

   */

  if (HeapTupleHasNulls(tup))

  {

    TupleDesc tupdesc = RelationGetDescr(heapRel);

    bits8    *bp = tup->t_data->t_bits;

    for (int attnum = 0; attnum < tupdesc->natts; attnum++)

    {

      Form_pg_attribute thisatt = TupleDescAttr(tupdesc, attnum);

      Assert(!(thisatt->attnotnull && att_isnull(attnum, bp)));

    }

  }

}

#else             /* !USE_ASSERT_CHECKING */

#define CatalogTupleCheckConstraints(heapRel, tup)  ((void) 0)

#endif              /* USE_ASSERT_CHECKING */

/*

 * CatalogTupleInsert - do heap and indexing work for a new catalog tuple

 *

 * Insert the tuple data in "tup" into the specified catalog relation.

 *

 * This is a convenience routine for the common case of inserting a single

 * tuple in a system catalog; it inserts a new heap tuple, keeping indexes

 * current.  Avoid using it for multiple tuples, since opening the indexes

 * and building the index info structures is moderately expensive.

 * (Use CatalogTupleInsertWithInfo in such cases.)

 */

void

CatalogTupleInsert(Relation heapRel, HeapTuple tup)

{

  CatalogIndexState indstate;

  CatalogTupleCheckConstraints(heapRel, tup);

  indstate = CatalogOpenIndexes(heapRel);

  simple_heap_insert(heapRel, tup);

  CatalogIndexInsert(indstate, tup, TU_All);

  CatalogCloseIndexes(indstate);

}

/*

 * CatalogTupleInsertWithInfo - as above, but with caller-supplied index info

 *

 * This should be used when it's important to amortize CatalogOpenIndexes/

 * CatalogCloseIndexes work across multiple insertions.  At some point we

 * might cache the CatalogIndexState data somewhere (perhaps in the relcache)

 * so that callers needn't trouble over this ... but we don't do so today.

 */

void

CatalogTupleInsertWithInfo(Relation heapRel, HeapTuple tup,

               CatalogIndexState indstate)

{

  CatalogTupleCheckConstraints(heapRel, tup);

  simple_heap_insert(heapRel, tup);

  CatalogIndexInsert(indstate, tup, TU_All);

}

/*

 * CatalogTuplesMultiInsertWithInfo - as above, but for multiple tuples

 *

 * Insert multiple tuples into the given catalog relation at once, with an

 * amortized cost of CatalogOpenIndexes.

 */

void

CatalogTuplesMultiInsertWithInfo(Relation heapRel, TupleTableSlot **slot,

                 int ntuples, CatalogIndexState indstate)

{

  /* Nothing to do */

  if (ntuples <= 0)

    return;

  heap_multi_insert(heapRel, slot, ntuples,

            GetCurrentCommandId(true), 0, NULL);

  /*

   * There is no equivalent to heap_multi_insert for the catalog indexes, so

   * we must loop over and insert individually.

   */

  for (int i = 0; i < ntuples; i++)

  {

    bool    should_free;

    HeapTuple tuple;

    tuple = ExecFetchSlotHeapTuple(slot[i], true, &should_free);

    tuple->t_tableOid = slot[i]->tts_tableOid;

    CatalogIndexInsert(indstate, tuple, TU_All);

    if (should_free)

      heap_freetuple(tuple);

  }

}

/*

 * CatalogTupleUpdate - do heap and indexing work for updating a catalog tuple

 *

 * Update the tuple identified by "otid", replacing it with the data in "tup".

 *

 * This is a convenience routine for the common case of updating a single

 * tuple in a system catalog; it updates one heap tuple, keeping indexes

 * current.  Avoid using it for multiple tuples, since opening the indexes

 * and building the index info structures is moderately expensive.

 * (Use CatalogTupleUpdateWithInfo in such cases.)

 */

void

CatalogTupleUpdate(Relation heapRel, ItemPointer otid, HeapTuple tup)

{

  CatalogIndexState indstate;

  TU_UpdateIndexes updateIndexes = TU_All;

  CatalogTupleCheckConstraints(heapRel, tup);

  indstate = CatalogOpenIndexes(heapRel);

  simple_heap_update(heapRel, otid, tup, &updateIndexes);

  CatalogIndexInsert(indstate, tup, updateIndexes);

  CatalogCloseIndexes(indstate);

}

/*

 * CatalogTupleUpdateWithInfo - as above, but with caller-supplied index info

 *

 * This should be used when it's important to amortize CatalogOpenIndexes/

 * CatalogCloseIndexes work across multiple updates.  At some point we

 * might cache the CatalogIndexState data somewhere (perhaps in the relcache)

 * so that callers needn't trouble over this ... but we don't do so today.

 */

void

CatalogTupleUpdateWithInfo(Relation heapRel, ItemPointer otid, HeapTuple tup,

               CatalogIndexState indstate)

{

  TU_UpdateIndexes updateIndexes = TU_All;

  CatalogTupleCheckConstraints(heapRel, tup);

  simple_heap_update(heapRel, otid, tup, &updateIndexes);

  CatalogIndexInsert(indstate, tup, updateIndexes);

}

/*

 * CatalogTupleDelete - do heap and indexing work for deleting a catalog tuple

 *

 * Delete the tuple identified by "tid" in the specified catalog.

 *

 * With Postgres heaps, there is no index work to do at deletion time;

 * cleanup will be done later by VACUUM.  However, callers of this function

 * shouldn't have to know that; we'd like a uniform abstraction for all

 * catalog tuple changes.  Hence, provide this currently-trivial wrapper.

 *

 * The abstraction is a bit leaky in that we don't provide an optimized

 * CatalogTupleDeleteWithInfo version, because there is currently nothing to

 * optimize.  If we ever need that, rather than touching a lot of call sites,

 * it might be better to do something about caching CatalogIndexState.

 */

void

CatalogTupleDelete(Relation heapRel, ItemPointer tid)

{

  simple_heap_delete(heapRel, tid);

}