heap_surgery.c

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * heap_surgery.c
 *    Functions to perform surgery on the damaged heap table.
 *
 * Copyright (c) 2020-2026, PostgreSQL Global Development Group
 *
 * IDENTIFICATION
 *    contrib/pg_surgery/heap_surgery.c
 *
 *-------------------------------------------------------------------------
 */
#include "postgres.h"
 
#include "access/htup_details.h"
#include "access/relation.h"
#include "access/visibilitymap.h"
#include "access/xloginsert.h"
#include "catalog/pg_am_d.h"
#include "miscadmin.h"
#include "storage/bufmgr.h"
#include "utils/acl.h"
#include "utils/array.h"
#include "utils/rel.h"
 
PG_MODULE_MAGIC_EXT(
                    .name = "pg_surgery",
                    .version = PG_VERSION
);
 
/* Options to forcefully change the state of a heap tuple. */
typedef enum HeapTupleForceOption
{
    HEAP_FORCE_KILL,
    HEAP_FORCE_FREEZE,
} HeapTupleForceOption;
 
PG_FUNCTION_INFO_V1(heap_force_kill);
PG_FUNCTION_INFO_V1(heap_force_freeze);
 
static int32 tidcmp(const void *a, const void *b);
static Datum heap_force_common(FunctionCallInfo fcinfo,
                               HeapTupleForceOption heap_force_opt);
static void sanity_check_tid_array(ArrayType *ta, int *ntids);
static BlockNumber find_tids_one_page(ItemPointer tids, int ntids,
                                      OffsetNumber *next_start_ptr);
 
/*-------------------------------------------------------------------------
 * heap_force_kill()
 *
 * Force kill the tuple(s) pointed to by the item pointer(s) stored in the
 * given TID array.
 *
 * Usage: SELECT heap_force_kill(regclass, tid[]);
 *-------------------------------------------------------------------------
 */
Datum
heap_force_kill(PG_FUNCTION_ARGS)
{
    PG_RETURN_DATUM(heap_force_common(fcinfo, HEAP_FORCE_KILL));
}
 
/*-------------------------------------------------------------------------
 * heap_force_freeze()
 *
 * Force freeze the tuple(s) pointed to by the item pointer(s) stored in the
 * given TID array.
 *
 * Usage: SELECT heap_force_freeze(regclass, tid[]);
 *-------------------------------------------------------------------------
 */
Datum
heap_force_freeze(PG_FUNCTION_ARGS)
{
    PG_RETURN_DATUM(heap_force_common(fcinfo, HEAP_FORCE_FREEZE));
}
 
/*-------------------------------------------------------------------------
 * heap_force_common()
 *
 * Common code for heap_force_kill and heap_force_freeze
 *-------------------------------------------------------------------------
 */
static Datum
heap_force_common(FunctionCallInfo fcinfo, HeapTupleForceOption heap_force_opt)
{
    Oid         relid = PG_GETARG_OID(0);
    ArrayType  *ta = PG_GETARG_ARRAYTYPE_P_COPY(1);
    ItemPointer tids;
    int         ntids,
                nblocks;
    Relation    rel;
    OffsetNumber curr_start_ptr,
                next_start_ptr;
    bool        include_this_tid[MaxHeapTuplesPerPage];
 
    if (RecoveryInProgress())
        ereport(ERROR,
                (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
                 errmsg("recovery is in progress"),
                 errhint("Heap surgery functions cannot be executed during recovery.")));
 
    /* Check inputs. */
    sanity_check_tid_array(ta, &ntids);
 
    rel = relation_open(relid, RowExclusiveLock);
 
    /*
     * Check target relation.
     */
    if (!RELKIND_HAS_TABLE_AM(rel->rd_rel->relkind))
        ereport(ERROR,
                (errcode(ERRCODE_WRONG_OBJECT_TYPE),
                 errmsg("cannot operate on relation \"%s\"",
                        RelationGetRelationName(rel)),
                 errdetail_relkind_not_supported(rel->rd_rel->relkind)));
 
    if (rel->rd_rel->relam != HEAP_TABLE_AM_OID)
        ereport(ERROR,
                (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                 errmsg("only heap AM is supported")));
 
    /* Must be owner of the table or superuser. */
    if (!object_ownercheck(RelationRelationId, RelationGetRelid(rel), GetUserId()))
        aclcheck_error(ACLCHECK_NOT_OWNER,
                       get_relkind_objtype(rel->rd_rel->relkind),
                       RelationGetRelationName(rel));
 
    tids = ((ItemPointer) ARR_DATA_PTR(ta));
 
    /*
     * If there is more than one TID in the array, sort them so that we can
     * easily fetch all the TIDs belonging to one particular page from the
     * array.
     */
    if (ntids > 1)
        qsort(tids, ntids, sizeof(ItemPointerData), tidcmp);
 
    curr_start_ptr = next_start_ptr = 0;
    nblocks = RelationGetNumberOfBlocks(rel);
 
    /*
     * Loop, performing the necessary actions for each block.
     */
    while (next_start_ptr != ntids)
    {
        Buffer      buf;
        Buffer      vmbuf = InvalidBuffer;
        Page        page;
        BlockNumber blkno;
        OffsetNumber curoff;
        OffsetNumber maxoffset;
        int         i;
        bool        did_modify_page = false;
        bool        did_modify_vm = false;
 
        CHECK_FOR_INTERRUPTS();
 
        /*
         * Find all the TIDs belonging to one particular page starting from
         * next_start_ptr and process them one by one.
         */
        blkno = find_tids_one_page(tids, ntids, &next_start_ptr);
 
        /* Check whether the block number is valid. */
        if (blkno >= nblocks)
        {
            /* Update the current_start_ptr before moving to the next page. */
            curr_start_ptr = next_start_ptr;
 
            ereport(NOTICE,
                    (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                     errmsg("skipping block %u for relation \"%s\" because the block number is out of range",
                            blkno, RelationGetRelationName(rel))));
            continue;
        }
 
        buf = ReadBuffer(rel, blkno);
        LockBufferForCleanup(buf);
 
        page = BufferGetPage(buf);
 
        maxoffset = PageGetMaxOffsetNumber(page);
 
        /*
         * Figure out which TIDs we are going to process and which ones we are
         * going to skip.
         */
        memset(include_this_tid, 0, sizeof(include_this_tid));
        for (i = curr_start_ptr; i < next_start_ptr; i++)
        {
            OffsetNumber offno = ItemPointerGetOffsetNumberNoCheck(&tids[i]);
            ItemId      itemid;
 
            /* Check whether the offset number is valid. */
            if (offno == InvalidOffsetNumber || offno > maxoffset)
            {
                ereport(NOTICE,
                        errmsg("skipping tid (%u, %u) for relation \"%s\" because the item number is out of range",
                               blkno, offno, RelationGetRelationName(rel)));
                continue;
            }
 
            itemid = PageGetItemId(page, offno);
 
            /* Only accept an item ID that is used. */
            if (ItemIdIsRedirected(itemid))
            {
                ereport(NOTICE,
                        errmsg("skipping tid (%u, %u) for relation \"%s\" because it redirects to item %u",
                               blkno, offno, RelationGetRelationName(rel),
                               ItemIdGetRedirect(itemid)));
                continue;
            }
            else if (ItemIdIsDead(itemid))
            {
                ereport(NOTICE,
                        (errmsg("skipping tid (%u, %u) for relation \"%s\" because it is marked dead",
                                blkno, offno, RelationGetRelationName(rel))));
                continue;
            }
            else if (!ItemIdIsUsed(itemid))
            {
                ereport(NOTICE,
                        (errmsg("skipping tid (%u, %u) for relation \"%s\" because it is marked unused",
                                blkno, offno, RelationGetRelationName(rel))));
                continue;
            }
 
            /* Mark it for processing. */
            Assert(offno < MaxHeapTuplesPerPage);
            include_this_tid[offno] = true;
        }
 
        /*
         * Before entering the critical section, pin the visibility map page
         * if it appears to be necessary.
         */
        if (heap_force_opt == HEAP_FORCE_KILL && PageIsAllVisible(page))
            visibilitymap_pin(rel, blkno, &vmbuf);
 
        /* No ereport(ERROR) from here until all the changes are logged. */
        START_CRIT_SECTION();
 
        for (curoff = FirstOffsetNumber; curoff <= maxoffset;
             curoff = OffsetNumberNext(curoff))
        {
            ItemId      itemid;
 
            if (!include_this_tid[curoff])
                continue;
 
            itemid = PageGetItemId(page, curoff);
            Assert(ItemIdIsNormal(itemid));
 
            did_modify_page = true;
 
            if (heap_force_opt == HEAP_FORCE_KILL)
            {
                ItemIdSetDead(itemid);
 
                /*
                 * If the page is marked all-visible, we must clear
                 * PD_ALL_VISIBLE flag on the page header and an all-visible
                 * bit on the visibility map corresponding to the page.
                 */
                if (PageIsAllVisible(page))
                {
                    PageClearAllVisible(page);
                    visibilitymap_clear(rel, blkno, vmbuf,
                                        VISIBILITYMAP_VALID_BITS);
                    did_modify_vm = true;
                }
            }
            else
            {
                HeapTupleHeader htup;
 
                Assert(heap_force_opt == HEAP_FORCE_FREEZE);
 
                htup = (HeapTupleHeader) PageGetItem(page, itemid);
 
                /*
                 * Reset all visibility-related fields of the tuple. This
                 * logic should mimic heap_execute_freeze_tuple(), but we
                 * choose to reset xmin and ctid just to be sure that no
                 * potentially-garbled data is left behind.
                 */
                ItemPointerSet(&htup->t_ctid, blkno, curoff);
                HeapTupleHeaderSetXmin(htup, FrozenTransactionId);
                HeapTupleHeaderSetXmax(htup, InvalidTransactionId);
                if (htup->t_infomask & HEAP_MOVED)
                {
                    if (htup->t_infomask & HEAP_MOVED_OFF)
                        HeapTupleHeaderSetXvac(htup, InvalidTransactionId);
                    else
                        HeapTupleHeaderSetXvac(htup, FrozenTransactionId);
                }
 
                /*
                 * Clear all the visibility-related bits of this tuple and
                 * mark it as frozen. Also, get rid of HOT_UPDATED and
                 * KEYS_UPDATES bits.
                 */
                htup->t_infomask &= ~HEAP_XACT_MASK;
                htup->t_infomask |= (HEAP_XMIN_FROZEN | HEAP_XMAX_INVALID);
                htup->t_infomask2 &= ~HEAP_HOT_UPDATED;
                htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
            }
        }
 
        /*
         * If the page was modified, only then, we mark the buffer dirty or do
         * the WAL logging.
         */
        if (did_modify_page)
        {
            /* Mark buffer dirty before we write WAL. */
            MarkBufferDirty(buf);
 
            /* XLOG stuff */
            if (RelationNeedsWAL(rel))
                log_newpage_buffer(buf, true);
        }
 
        /* WAL log the VM page if it was modified. */
        if (did_modify_vm && RelationNeedsWAL(rel))
            log_newpage_buffer(vmbuf, false);
 
        END_CRIT_SECTION();
 
        UnlockReleaseBuffer(buf);
 
        if (vmbuf != InvalidBuffer)
            ReleaseBuffer(vmbuf);
 
        /* Update the current_start_ptr before moving to the next page. */
        curr_start_ptr = next_start_ptr;
    }
 
    relation_close(rel, RowExclusiveLock);
 
    pfree(ta);
 
    PG_RETURN_VOID();
}
 
/*-------------------------------------------------------------------------
 * tidcmp()
 *
 * Compare two item pointers, return -1, 0, or +1.
 *
 * See ItemPointerCompare for details.
 * ------------------------------------------------------------------------
 */
static int32
tidcmp(const void *a, const void *b)
{
    const ItemPointerData *iptr1 = a;
    const ItemPointerData *iptr2 = b;
 
    return ItemPointerCompare(iptr1, iptr2);
}
 
/*-------------------------------------------------------------------------
 * sanity_check_tid_array()
 *
 * Perform sanity checks on the given tid array, and set *ntids to the
 * number of items in the array.
 * ------------------------------------------------------------------------
 */
static void
sanity_check_tid_array(ArrayType *ta, int *ntids)
{
    if (ARR_HASNULL(ta) && array_contains_nulls(ta))
        ereport(ERROR,
                (errcode(ERRCODE_NULL_VALUE_NOT_ALLOWED),
                 errmsg("array must not contain nulls")));
 
    if (ARR_NDIM(ta) > 1)
        ereport(ERROR,
                (errcode(ERRCODE_DATA_EXCEPTION),
                 errmsg("argument must be empty or one-dimensional array")));
 
    *ntids = ArrayGetNItems(ARR_NDIM(ta), ARR_DIMS(ta));
}
 
/*-------------------------------------------------------------------------
 * find_tids_one_page()
 *
 * Find all the tids residing in the same page as tids[next_start_ptr], and
 * update next_start_ptr so that it points to the first tid in the next page.
 *
 * NOTE: The input tids[] array must be sorted.
 * ------------------------------------------------------------------------
 */
static BlockNumber
find_tids_one_page(ItemPointer tids, int ntids, OffsetNumber *next_start_ptr)
{
    int         i;
    BlockNumber prev_blkno,
                blkno;
 
    prev_blkno = blkno = InvalidBlockNumber;
 
    for (i = *next_start_ptr; i < ntids; i++)
    {
        ItemPointerData tid = tids[i];
 
        blkno = ItemPointerGetBlockNumberNoCheck(&tid);
 
        if (i == *next_start_ptr)
            prev_blkno = blkno;
 
        if (prev_blkno != blkno)
            break;
    }
 
    *next_start_ptr = i;
    return prev_blkno;
}