本節簡單介紹了PostgreSQL手工執行vacuum的主處理流程,主要分析了ExecVacuum->vacuum函式的實現邏輯。該函式是VACUUM/ANALYZE命令的內部處理入口。

### 一、資料結構
**宏定義**
Vacuum和Analyze命令選項
```
/* ----------------------
 *      Vacuum and Analyze Statements
 *      Vacuum和Analyze命令選項
 * 
 * Even though these are nominally two statements, it's convenient to use
 * just one node type for both.  Note that at least one of VACOPT_VACUUM
 * and VACOPT_ANALYZE must be set in options.
 * 雖然在這裡有兩種不同的語句,但只需要使用統一的Node型別即可.
 * 注意至少VACOPT_VACUUM/VACOPT_ANALYZE在選項中設定.
 * ----------------------
 */
typedef enum VacuumOption
{
    VACOPT_VACUUM = 1 << 0,     /* do VACUUM */
    VACOPT_ANALYZE = 1 << 1,    /* do ANALYZE */
    VACOPT_VERBOSE = 1 << 2,    /* print progress info */
    VACOPT_FREEZE = 1 << 3,     /* FREEZE option */
    VACOPT_FULL = 1 << 4,       /* FULL (non-concurrent) vacuum */
    VACOPT_SKIP_LOCKED = 1 << 5,    /* skip if cannot get lock */
    VACOPT_SKIPTOAST = 1 << 6,  /* don't process the TOAST table, if any */
    VACOPT_DISABLE_PAGE_SKIPPING = 1 << 7   /* don't skip any pages */
} VacuumOption;

```

**VacuumStmt**
儲存vacuum命令的option&Relation連結串列
```
typedef struct VacuumStmt
{
    NodeTag     type;//Tag
    //VacuumOption位標記
    int         options;        /* OR of VacuumOption flags */
    //VacuumRelation連結串列,如為NIL-->所有Relation.
    List       *rels;           /* list of VacuumRelation, or NIL for all */
} VacuumStmt;
 
 
```

**VacuumParams**
vacuum命令引數
```
/*
 * Parameters customizing behavior of VACUUM and ANALYZE.
 * 客戶端呼叫VACUUM/ANALYZE時的定製化引數
 */
typedef struct VacuumParams
{
    //最小freeze age,-1表示使用預設
    int         freeze_min_age; /* min freeze age, -1 to use default */
    //掃描整個table的freeze age
    int         freeze_table_age;   /* age at which to scan whole table */
    //最小的multixact freeze age,-1表示預設
    int         multixact_freeze_min_age;   /* min multixact freeze age, -1 to
                                             * use default */
    //掃描全表的freeze age,-1表示預設
    int         multixact_freeze_table_age; /* multixact age at which to scan
                                             * whole table */
    //是否強制wraparound?
    bool        is_wraparound;  /* force a for-wraparound vacuum */
    //以毫秒為單位的最小執行閾值
    int         log_min_duration;   /* minimum execution threshold in ms at
                                     * which  verbose logs are activated, -1
                                     * to use default */
} VacuumParams;

```

**VacuumRelation**
VACUUM/ANALYZE命令的目標表資訊
```
/*
 * Info about a single target table of VACUUM/ANALYZE.
 * VACUUM/ANALYZE命令的目標表資訊.
 *  
 * If the OID field is set, it always identifies the table to process.
 * Then the relation field can be NULL; if it isn't, it's used only to report
 * failure to open/lock the relation.
 * 如設定了OID欄位,該值通常是將要處理的資料表.
 * 那麼關係欄位可以為空;如果不是，則僅用於報告未能開啟/鎖定關係。
 */
typedef struct VacuumRelation
{
    NodeTag     type;
    RangeVar   *relation;       /* table name to process, or NULL */
    Oid         oid;            /* table's OID; InvalidOid if not looked up */
    List       *va_cols;        /* list of column names, or NIL for all */
} VacuumRelation;
 
```

### 二、原始碼解讀
vacuum是VACUUM/ANALYZE命令的內部處理入口.
邏輯比較簡單:
1.配置vacuum處理的相關引數,如命令型別等
2.執行相關檢查
3.構造vacuum處理上下文
4.構造vacuum需處理的relation連結串列
5.迴圈遍歷relation連結串列
  5.1 獲取relation
  5.2 執行vacuum_rel
6.收尾工作
```
/*
 * Internal entry point for VACUUM and ANALYZE commands.
 * VACUUM/ANALYZE命令的內部處理入口
 *
 * options is a bitmask of VacuumOption flags, indicating what to do.
 * options是VacuumOption選項標記位,指示應該做什麼.
 *
 * relations, if not NIL, is a list of VacuumRelation to process; otherwise,
 * we process all relevant tables in the database.  For each VacuumRelation,
 * if a valid OID is supplied, the table with that OID is what to process;
 * otherwise, the VacuumRelation's RangeVar indicates what to process.
 * relations,如果不是空指標NIL,那麼儲存了待處理的VacuumRelation結構體連結串列.
 * 如為NIL,將處理資料庫中的所有相關資料表.
 * 對每一個VacuumRelation,如提供了有效OID,該OID對應table就會被處理,
 *   否則,VacuumRelation的RangeVar指示瞭如何處理.
 *
 * params contains a set of parameters that can be used to customize the
 * behavior.
 * params是客戶端定製的引數集合.
 *
 * bstrategy is normally given as NULL, but in autovacuum it can be passed
 * in to use the same buffer strategy object across multiple vacuum() calls.
 * bstrategy通常是NULL,但在autovacuum中,
 *   該引數可用於指示在多個vacuum()呼叫中使用同樣的快取strategy object
 *
 * isTopLevel should be passed down from ProcessUtility.
 * isTopLevel透過ProcessUtility向下傳遞
 *
 * It is the caller's responsibility that all parameters are allocated in a
 * memory context that will not disappear at transaction commit.
 * 呼叫者應確保所有的引數在同一個記憶體上下文分配記憶體,而不會在事務commit時突然消失.
 */
void
vacuum(int options, List *relations, VacuumParams *params,
       BufferAccessStrategy bstrategy, bool isTopLevel)
{
    static bool in_vacuum = false;//是否在vacuum

const char *stmttype;//語句型別,vacuum?analyze?
    volatile bool in_outer_xact,
                use_own_xacts;

Assert(params != NULL);

stmttype = (options & VACOPT_VACUUM) ? "VACUUM" : "ANALYZE";

/*
     * We cannot run VACUUM inside a user transaction block; if we were inside
     * a transaction, then our commit- and start-transaction-command calls
     * would not have the intended effect!  There are numerous other subtle
     * dependencies on this, too.
     * 不能在使用者事務塊中執行VACUUM,如果我們在事務塊中,
     *   那麼處理過程中的commit-和start-transaction-command呼叫不會有正確的效果.
     * 而且還有許多其他微妙的依賴關係。
     *
     * ANALYZE (without VACUUM) can run either way.
     * ANALYZE(不帶VACUUM)則沒有此問題.
     */
    if (options & VACOPT_VACUUM)
    {
        PreventInTransactionBlock(isTopLevel, stmttype);
        in_outer_xact = false;
    }
    else
        in_outer_xact = IsInTransactionBlock(isTopLevel);

/*
     * Due to static variables vac_context, anl_context and vac_strategy,
     * vacuum() is not reentrant.  This matters when VACUUM FULL or ANALYZE
     * calls a hostile index expression that itself calls ANALYZE.
     * 鑑於vac_context, anl_context and vac_strategy這是變數都是靜態變數,
     *   因此vacuum()函式是不能重入的(狀態已出現變化).
     * 在VACUUM FULL或者ANALYZE呼叫了hostile index expression,
     *   而此邏輯又呼叫了ANALYZE時會出現此情況,務必注意.
     */
    if (in_vacuum)
        ereport(ERROR,
                (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                 errmsg("%s cannot be executed from VACUUM or ANALYZE",
                        stmttype)));

/*
     * Sanity check DISABLE_PAGE_SKIPPING option.
     * 檢查
     */
    if ((options & VACOPT_FULL) != 0 &&
        (options & VACOPT_DISABLE_PAGE_SKIPPING) != 0)
        ereport(ERROR,
                (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                 errmsg("VACUUM option DISABLE_PAGE_SKIPPING cannot be used with FULL")));

/*
     * Send info about dead objects to the statistics collector, unless we are
     * in autovacuum --- autovacuum.c does this for itself.
     * 傳送dead objects的統計資訊給收集器,除非我們在autovacuum中
     * -- autovacuum.c會自己做這個事情.
     */
    if ((options & VACOPT_VACUUM) && !IsAutoVacuumWorkerProcess())
        pgstat_vacuum_stat();

/*
     * Create special memory context for cross-transaction storage.
     * 跨事務儲存,需要建立特別的記憶體上下文.
     *
     * Since it is a child of PortalContext, it will go away eventually even
     * if we suffer an error; there's no need for special abort cleanup logic.
     * 因為這是PortalContext的子物件,即使我們犯了錯誤，它最終也會消失;不需要特殊的中止清理邏輯。
     */
    vac_context = AllocSetContextCreate(PortalContext,
                                        "Vacuum",
                                        ALLOCSET_DEFAULT_SIZES);

/*
     * If caller didn't give us a buffer strategy object, make one in the
     * cross-transaction memory context.
     * 如果呼叫者沒有提供buffer strategy object,
     *   在跨事務的記憶體上下文中建立一個.
     */
    if (bstrategy == NULL)
    {
        MemoryContext old_context = MemoryContextSwitchTo(vac_context);

bstrategy = GetAccessStrategy(BAS_VACUUM);
        MemoryContextSwitchTo(old_context);
    }
    vac_strategy = bstrategy;

/*
     * Build list of relation(s) to process, putting any new data in
     * vac_context for safekeeping.
     * 構建要處理的關係列表，將所有新資料放入vac_context中以進行安全(位於vacuum上下文中)儲存。
     */
    if (relations != NIL)
    {
        List       *newrels = NIL;
        ListCell   *lc;

foreach(lc, relations)
        {
            VacuumRelation *vrel = lfirst_node(VacuumRelation, lc);
            List       *sublist;
            MemoryContext old_context;

sublist = expand_vacuum_rel(vrel, options);
            old_context = MemoryContextSwitchTo(vac_context);
            newrels = list_concat(newrels, sublist);
            MemoryContextSwitchTo(old_context);
        }
        relations = newrels;
    }
    else
        relations = get_all_vacuum_rels(options);

/*
     * Decide whether we need to start/commit our own transactions.
     * 確定是否需要start/commit自己的事務
     *
     * For VACUUM (with or without ANALYZE): always do so, so that we can
     * release locks as soon as possible.  (We could possibly use the outer
     * transaction for a one-table VACUUM, but handling TOAST tables would be
     * problematic.)
     * 對於VACUUM(包含或不包含ANALYZE):通常需要這樣處理,以便我們可以儘可能快的釋放鎖.
     * (對於一張表的VACUUM,我們可能使用外層事務,但處理TOAST表是會有問題)
     *
     * For ANALYZE (no VACUUM): if inside a transaction block, we cannot
     * start/commit our own transactions.  Also, there's no need to do so if
     * only processing one relation.  For multiple relations when not within a
     * transaction block, and also in an autovacuum worker, use own
     * transactions so we can release locks sooner.
     * 對於ANALYZE(沒有VACUUM選項):如果在事務塊中,我們不能start/commit自己的事務.
     * 同時,如果只需要處理一個relation,則不需要這樣處理.
     * 對於不在一個事務塊中的多個relations/在autovacuum worker中,
     *   使用自己的事務以便更快的釋放鎖.
     */
    if (options & VACOPT_VACUUM)
        use_own_xacts = true;
    else
    {
        Assert(options & VACOPT_ANALYZE);
        if (IsAutoVacuumWorkerProcess())
            use_own_xacts = true;
        else if (in_outer_xact)
            use_own_xacts = false;
        else if (list_length(relations) > 1)
            use_own_xacts = true;
        else
            use_own_xacts = false;
    }

/*
     * vacuum_rel expects to be entered with no transaction active; it will
     * start and commit its own transaction.  But we are called by an SQL
     * command, and so we are executing inside a transaction already. We
     * commit the transaction started in PostgresMain() here, and start
     * another one before exiting to match the commit waiting for us back in
     * PostgresMain().
     * 在進入vacuum_rel前,不希望存在事務活動.該函式會啟動和提交自己的事務.
     * 但由於我們是透過SQL命令呼叫的,因此我們已處於事務中執行.
     * 在這裡我們提交在PostgresMain()中啟動的事務,
     * 並在退出之前啟動另一個，以匹配在PostgresMain()中等待我們的提交。
     */
    if (use_own_xacts)
    {
        Assert(!in_outer_xact);

/* ActiveSnapshot is not set by autovacuum */
        //autovacuum不會設定ActiveSnapshot
        if (ActiveSnapshotSet())
            PopActiveSnapshot();

/* matches the StartTransaction in PostgresMain() */
        //匹配PostgresMain()中的StartTransaction
        CommitTransactionCommand();
    }

/* Turn vacuum cost accounting on or off, and set/clear in_vacuum */
    //設定vacuum成本計數on/off,並set/clear in_vacuum引數
    PG_TRY();
    {
        ListCell   *cur;

in_vacuum = true;
        VacuumCostActive = (VacuumCostDelay > 0);
        VacuumCostBalance = 0;
        VacuumPageHit = 0;
        VacuumPageMiss = 0;
        VacuumPageDirty = 0;

/*
         * Loop to process each selected relation.
         * 迴圈處理每一個已選中的relation.
         */
        foreach(cur, relations)
        {
            VacuumRelation *vrel = lfirst_node(VacuumRelation, cur);

if (options & VACOPT_VACUUM)
            {
                //執行vacuum處理
                if (!vacuum_rel(vrel->oid, vrel->relation, options, params))
                    continue;
            }

if (options & VACOPT_ANALYZE)
            {
                /*
                 * If using separate xacts, start one for analyze. Otherwise,
                 * we can use the outer transaction.
                 * 如果使用獨立的xacts,為analyze啟動一個何事務.
                 * 否則,我們可以使用外層事務.
                 */
                if (use_own_xacts)
                {
                    //使用自己的事務
                    StartTransactionCommand();
                    /* functions in indexes may want a snapshot set */
                    //快照壓棧
                    PushActiveSnapshot(GetTransactionSnapshot());
                }
                //分析relation
                analyze_rel(vrel->oid, vrel->relation, options, params,
                            vrel->va_cols, in_outer_xact, vac_strategy);

if (use_own_xacts)
                {
                    //使用自己的事務,出棧
                    PopActiveSnapshot();
                    //提交事務
                    CommitTransactionCommand();
                }
            }
        }
    }
    PG_CATCH();
    {
        in_vacuum = false;
        VacuumCostActive = false;
        PG_RE_THROW();
    }
    PG_END_TRY();

in_vacuum = false;
    VacuumCostActive = false;

/*
     * Finish up processing.
     * 完成處理過程
     */
    if (use_own_xacts)
    {
        /* here, we are not in a transaction */
        //在這裡,沒有處於事務中

/*
         * This matches the CommitTransaction waiting for us in
         * PostgresMain().
         * 匹配在PostgresMain()函式中等待我們的CommitTransaction.
         */
        StartTransactionCommand();
    }

if ((options & VACOPT_VACUUM) && !IsAutoVacuumWorkerProcess())
    {
        /*
         * Update pg_database.datfrozenxid, and truncate pg_xact if possible.
         * (autovacuum.c does this for itself.)
         * 更新pg_database.datfrozenxid,如可能截斷pg_xact.
         * (autovacuum.c不會處理這事情)
         */
        vac_update_datfrozenxid();
    }

/*
     * Clean up working storage --- note we must do this after
     * StartTransactionCommand, else we might be trying to delete the active
     * context!
     * 清除工作儲存 --- 注意必須在StartTransactionCommand命令後執行清除過程,
     *   否則我們可能會嘗試刪除活動的上下文.
     */
    MemoryContextDelete(vac_context);
    vac_context = NULL;
}

```

### 三、跟蹤分析
測試指令碼
```
17:19:28 (xdb@[local]:5432)testdb=# vacuum t1;

```

啟動gdb,設定斷點
```
(gdb) b vacuum
Breakpoint 1 at 0x6b9b8c: file vacuum.c, line 175.
(gdb) c
Continuing.

Breakpoint 1, vacuum (options=1, relations=0x2294988, params=0x7fff403d8880, bstrategy=0x0, isTopLevel=true) at vacuum.c:175
175     Assert(params != NULL);
(gdb) 
```
輸入引數
options=1 --> VACOPT_VACUUM
relations=0x2294988,relation連結串列,裡面只有一個item,即t1
params=0x7fff403d8880,預設引數
bstrategy=NULL,
isTopLevel=T,為頂層事務
```
(gdb) p *params
$2 = {freeze_min_age = -1, freeze_table_age = -1, multixact_freeze_min_age = -1, multixact_freeze_table_age = -1, 
  is_wraparound = false, log_min_duration = -1}
(gdb) 
```
變數賦值並執行相關判斷
```
(gdb) n
177     stmttype = (options & VACOPT_VACUUM) ? "VACUUM" : "ANALYZE";
(gdb) 
187     if (options & VACOPT_VACUUM)
(gdb) 
189         PreventInTransactionBlock(isTopLevel, stmttype);
(gdb) 
190         in_outer_xact = false;
(gdb) 
200     if (in_vacuum)
(gdb) 
209     if ((options & VACOPT_FULL) != 0 &&
(gdb) 
```
統計資訊
```
219     if ((options & VACOPT_VACUUM) && !IsAutoVacuumWorkerProcess())
(gdb) 
220         pgstat_vacuum_stat();
(gdb) 
```
建立並設定記憶體上下文
```
(gdb) n
228     vac_context = AllocSetContextCreate(PortalContext,
(gdb) 
236     if (bstrategy == NULL)
(gdb) 
238         MemoryContext old_context = MemoryContextSwitchTo(vac_context);
(gdb) 
240         bstrategy = GetAccessStrategy(BAS_VACUUM);
(gdb) 
241         MemoryContextSwitchTo(old_context);
(gdb) 
243     vac_strategy = bstrategy;
(gdb) 
249     if (relations != NIL)
(gdb) 
```
構造VacuumRelation連結串列
```
(gdb) 
251         List       *newrels = NIL;
(gdb) 
254         foreach(lc, relations)
(gdb) 
256             VacuumRelation *vrel = lfirst_node(VacuumRelation, lc);
(gdb) 
260             sublist = expand_vacuum_rel(vrel);
(gdb) p *vrel
$3 = {type = T_VacuumRelation, relation = 0x22948d0, oid = 0, va_cols = 0x0}
(gdb) p *vrel->relation
$4 = {type = T_RangeVar, catalogname = 0x0, schemaname = 0x0, relname = 0x22948b0 "t1", inh = true, 
  relpersistence = 112 'p', alias = 0x0, location = 7}
(gdb) 
(gdb) n
261             old_context = MemoryContextSwitchTo(vac_context);
(gdb) 
262             newrels = list_concat(newrels, sublist);
(gdb) 
263             MemoryContextSwitchTo(old_context);
(gdb) 
254         foreach(lc, relations)
(gdb) 
265         relations = newrels;
(gdb) 
```
使用自主事務
```
284     if (options & VACOPT_VACUUM)
(gdb) 
285         use_own_xacts = true;
(gdb) 
307     if (use_own_xacts)
(gdb) 
307     if (use_own_xacts)
(gdb) 
309         Assert(!in_outer_xact);
(gdb) 
312         if (ActiveSnapshotSet())
(gdb) 
313             PopActiveSnapshot();
(gdb) 
316         CommitTransactionCommand();
(gdb) 
320     PG_TRY();
(gdb) 
```
開始執行,設定vacuum成本計數on/off,並set/clear in_vacuum引數
```
(gdb) 
324         in_vacuum = true;
(gdb) 
325         VacuumCostActive = (VacuumCostDelay > 0);
(gdb) 
326         VacuumCostBalance = 0;
(gdb) 
327         VacuumPageHit = 0;
(gdb) 
328         VacuumPageMiss = 0;
(gdb) 
329         VacuumPageDirty = 0;
(gdb) 
```
迴圈relation,呼叫vacuum_rel
```
334         foreach(cur, relations)
(gdb) 
336             VacuumRelation *vrel = lfirst_node(VacuumRelation, cur);
(gdb) 
338             if (options & VACOPT_VACUUM)
(gdb) 
340                 if (!vacuum_rel(vrel->oid, vrel->relation, options, params))
(gdb) 
344             if (options & VACOPT_ANALYZE)
(gdb) 
334         foreach(cur, relations)
(gdb) 
374     PG_END_TRY();
(gdb) 
```
執行收尾工作
```
(gdb) 
376     in_vacuum = false;
(gdb) 
377     VacuumCostActive = false;
(gdb) 
382     if (use_own_xacts)
(gdb) 
390         StartTransactionCommand();
(gdb) 
393     if ((options & VACOPT_VACUUM) && !IsAutoVacuumWorkerProcess())
(gdb) 
399         vac_update_datfrozenxid();
(gdb) 
407     MemoryContextDelete(vac_context);
(gdb) 
408     vac_context = NULL;
(gdb) 
```
完成呼叫
```
409 }
(gdb) 
ExecVacuum (vacstmt=0x22949c0, isTopLevel=true) at vacuum.c:142
142 }
(gdb) 
```
DONE!

### 四、參考資料
[PG Source Code](https://doxygen.postgresql.org)

PostgreSQL 原始碼解讀（126）- MVCC#10（vacuum過程）

相關文章