PostgreSQL Source Code git master
vacuum.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * vacuum.h
4 * header file for postgres vacuum cleaner and statistics analyzer
5 *
6 *
7 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
9 *
10 * src/include/commands/vacuum.h
11 *
12 *-------------------------------------------------------------------------
13 */
14#ifndef VACUUM_H
15#define VACUUM_H
16
17#include "access/htup.h"
18#include "access/genam.h"
19#include "access/parallel.h"
20#include "access/tidstore.h"
21#include "catalog/pg_class.h"
23#include "catalog/pg_type.h"
24#include "parser/parse_node.h"
25#include "storage/buf.h"
26#include "storage/lock.h"
27#include "utils/relcache.h"
28
29/*
30 * Flags for amparallelvacuumoptions to control the participation of bulkdelete
31 * and vacuumcleanup in parallel vacuum.
32 */
33
34/*
35 * Both bulkdelete and vacuumcleanup are disabled by default. This will be
36 * used by IndexAM's that don't want to or cannot participate in parallel
37 * vacuum. For example, if an index AM doesn't have a way to communicate the
38 * index statistics allocated by the first ambulkdelete call to the subsequent
39 * ones until amvacuumcleanup, the index AM cannot participate in parallel
40 * vacuum.
41 */
42#define VACUUM_OPTION_NO_PARALLEL 0
43
44/*
45 * bulkdelete can be performed in parallel. This option can be used by
46 * index AMs that need to scan indexes to delete tuples.
47 */
48#define VACUUM_OPTION_PARALLEL_BULKDEL (1 << 0)
49
50/*
51 * vacuumcleanup can be performed in parallel if bulkdelete is not performed
52 * yet. This will be used by IndexAM's that can scan the index if the
53 * bulkdelete is not performed.
54 */
55#define VACUUM_OPTION_PARALLEL_COND_CLEANUP (1 << 1)
56
57/*
58 * vacuumcleanup can be performed in parallel even if bulkdelete has already
59 * processed the index. This will be used by IndexAM's that scan the index
60 * during the cleanup phase of index irrespective of whether the index is
61 * already scanned or not during bulkdelete phase.
62 */
63#define VACUUM_OPTION_PARALLEL_CLEANUP (1 << 2)
64
65/* value for checking vacuum flags */
66#define VACUUM_OPTION_MAX_VALID_VALUE ((1 << 3) - 1)
67
68/* Abstract type for parallel vacuum state */
70
71/*----------
72 * ANALYZE builds one of these structs for each attribute (column) that is
73 * to be analyzed. The struct and subsidiary data are in anl_context,
74 * so they live until the end of the ANALYZE operation.
75 *
76 * The type-specific typanalyze function is passed a pointer to this struct
77 * and must return true to continue analysis, false to skip analysis of this
78 * column. In the true case it must set the compute_stats and minrows fields,
79 * and can optionally set extra_data to pass additional info to compute_stats.
80 * minrows is its request for the minimum number of sample rows to be gathered
81 * (but note this request might not be honored, eg if there are fewer rows
82 * than that in the table).
83 *
84 * The compute_stats routine will be called after sample rows have been
85 * gathered. Aside from this struct, it is passed:
86 * fetchfunc: a function for accessing the column values from the
87 * sample rows
88 * samplerows: the number of sample tuples
89 * totalrows: estimated total number of rows in relation
90 * The fetchfunc may be called with rownum running from 0 to samplerows-1.
91 * It returns a Datum and an isNull flag.
92 *
93 * compute_stats should set stats_valid true if it is able to compute
94 * any useful statistics. If it does, the remainder of the struct holds
95 * the information to be stored in a pg_statistic row for the column. Be
96 * careful to allocate any pointed-to data in anl_context, which will NOT
97 * be CurrentMemoryContext when compute_stats is called.
98 *
99 * Note: all comparisons done for statistical purposes should use the
100 * underlying column's collation (attcollation), except in situations
101 * where a noncollatable container type contains a collatable type;
102 * in that case use the type's default collation. Be sure to record
103 * the appropriate collation in stacoll.
104 *----------
105 */
107
108typedef Datum (*AnalyzeAttrFetchFunc) (VacAttrStatsP stats, int rownum,
109 bool *isNull);
110
112 AnalyzeAttrFetchFunc fetchfunc,
113 int samplerows,
114 double totalrows);
115
116typedef struct VacAttrStats
117{
118 /*
119 * These fields are set up by the main ANALYZE code before invoking the
120 * type-specific typanalyze function. They don't necessarily match what
121 * is in pg_attribute, because some index opclasses store a different type
122 * than the underlying column/expression. Therefore, use these fields for
123 * information about the datatype being fed to the typanalyze function.
124 */
125 int attstattarget; /* -1 to use default */
126 Oid attrtypid; /* type of data being analyzed */
127 int32 attrtypmod; /* typmod of data being analyzed */
128 Form_pg_type attrtype; /* copy of pg_type row for attrtypid */
129 Oid attrcollid; /* collation of data being analyzed */
130 MemoryContext anl_context; /* where to save long-lived data */
131
132 /*
133 * These fields must be filled in by the typanalyze routine, unless it
134 * returns false.
135 */
137 int minrows; /* Minimum # of rows wanted for stats */
138 void *extra_data; /* for extra type-specific data */
139
140 /*
141 * These fields are to be filled in by the compute_stats routine. (They
142 * are initialized to zero when the struct is created.)
143 */
145 float4 stanullfrac; /* fraction of entries that are NULL */
146 int32 stawidth; /* average width of column values */
147 float4 stadistinct; /* # distinct values */
155
156 /*
157 * These fields describe the stavalues[n] element types. They will be
158 * initialized to match attrtypid, but a custom typanalyze function might
159 * want to store an array of something other than the analyzed column's
160 * elements. It should then overwrite these fields.
161 */
166
167 /*
168 * These fields are private to the main ANALYZE code and should not be
169 * looked at by type-specific functions.
170 */
171 int tupattnum; /* attribute number within tuples */
172 HeapTuple *rows; /* access info for std fetch function */
174 Datum *exprvals; /* access info for index fetch function */
178
179/* flag bits for VacuumParams->options */
180#define VACOPT_VACUUM 0x01 /* do VACUUM */
181#define VACOPT_ANALYZE 0x02 /* do ANALYZE */
182#define VACOPT_VERBOSE 0x04 /* output INFO instrumentation messages */
183#define VACOPT_FREEZE 0x08 /* FREEZE option */
184#define VACOPT_FULL 0x10 /* FULL (non-concurrent) vacuum */
185#define VACOPT_SKIP_LOCKED 0x20 /* skip if cannot get lock */
186#define VACOPT_PROCESS_MAIN 0x40 /* process main relation */
187#define VACOPT_PROCESS_TOAST 0x80 /* process the TOAST table, if any */
188#define VACOPT_DISABLE_PAGE_SKIPPING 0x100 /* don't skip any pages */
189#define VACOPT_SKIP_DATABASE_STATS 0x200 /* skip vac_update_datfrozenxid() */
190#define VACOPT_ONLY_DATABASE_STATS 0x400 /* only vac_update_datfrozenxid() */
191
192/*
193 * Values used by index_cleanup and truncate params.
194 *
195 * VACOPTVALUE_UNSPECIFIED is used as an initial placeholder when VACUUM
196 * command has no explicit value. When that happens the final usable value
197 * comes from the corresponding reloption (though the reloption default is
198 * usually used).
199 */
200typedef enum VacOptValue
201{
207
208/*
209 * Parameters customizing behavior of VACUUM and ANALYZE.
210 *
211 * Note that at least one of VACOPT_VACUUM and VACOPT_ANALYZE must be set
212 * in options.
213 *
214 * When adding a new VacuumParam member, consider adding it to vacuumdb as
215 * well.
216 */
217typedef struct VacuumParams
218{
219 bits32 options; /* bitmask of VACOPT_* */
220 int freeze_min_age; /* min freeze age, -1 to use default */
221 int freeze_table_age; /* age at which to scan whole table */
222 int multixact_freeze_min_age; /* min multixact freeze age, -1 to
223 * use default */
224 int multixact_freeze_table_age; /* multixact age at which to scan
225 * whole table */
226 bool is_wraparound; /* force a for-wraparound vacuum */
227 int log_min_duration; /* minimum execution threshold in ms at
228 * which autovacuum is logged, -1 to use
229 * default */
230 VacOptValue index_cleanup; /* Do index vacuum and cleanup */
231 VacOptValue truncate; /* Truncate empty pages at the end */
232 Oid toast_parent; /* for privilege checks when recursing */
233
234 /*
235 * Fraction of pages in a relation that vacuum can eagerly scan and fail
236 * to freeze. Only applicable for table AMs using visibility maps. Derived
237 * from GUC or table storage parameter. 0 if disabled.
238 */
240
241 /*
242 * The number of parallel vacuum workers. 0 by default which means choose
243 * based on the number of indexes. -1 indicates parallel vacuum is
244 * disabled.
245 */
248
249/*
250 * VacuumCutoffs is immutable state that describes the cutoffs used by VACUUM.
251 * Established at the beginning of each VACUUM operation.
252 */
254{
255 /*
256 * Existing pg_class fields at start of VACUUM
257 */
260
261 /*
262 * OldestXmin is the Xid below which tuples deleted by any xact (that
263 * committed) should be considered DEAD, not just RECENTLY_DEAD.
264 *
265 * OldestMxact is the Mxid below which MultiXacts are definitely not seen
266 * as visible by any running transaction.
267 *
268 * OldestXmin and OldestMxact are also the most recent values that can
269 * ever be passed to vac_update_relstats() as frozenxid and minmulti
270 * arguments at the end of VACUUM. These same values should be passed
271 * when it turns out that VACUUM will leave no unfrozen XIDs/MXIDs behind
272 * in the table.
273 */
276
277 /*
278 * FreezeLimit is the Xid below which all Xids are definitely frozen or
279 * removed in pages VACUUM scans and cleanup locks.
280 *
281 * MultiXactCutoff is the value below which all MultiXactIds are
282 * definitely removed from Xmax in pages VACUUM scans and cleanup locks.
283 */
286};
287
288/*
289 * VacDeadItemsInfo stores supplemental information for dead tuple TID
290 * storage (i.e. TidStore).
291 */
292typedef struct VacDeadItemsInfo
293{
294 size_t max_bytes; /* the maximum bytes TidStore can use */
295 int64 num_items; /* current # of entries */
297
298/* GUC parameters */
299extern PGDLLIMPORT int default_statistics_target; /* PGDLLIMPORT for PostGIS */
307extern PGDLLIMPORT bool vacuum_truncate;
308
309/*
310 * Relevant for vacuums implementing eager scanning. Normal vacuums may
311 * eagerly scan some all-visible but not all-frozen pages. Since the goal
312 * is to freeze these pages, an eager scan that fails to set the page
313 * all-frozen in the VM is considered to have "failed". This is the
314 * fraction of pages in the relation vacuum may scan and fail to freeze
315 * before disabling eager scanning.
316 */
318
319/*
320 * Maximum value for default_statistics_target and per-column statistics
321 * targets. This is fairly arbitrary, mainly to prevent users from creating
322 * unreasonably large statistics that the system cannot handle well.
323 */
324#define MAX_STATISTICS_TARGET 10000
325
326/* Variables for cost-based parallel vacuum */
330
332extern PGDLLIMPORT double vacuum_cost_delay;
334
336
337/* in commands/vacuum.c */
338extern void ExecVacuum(ParseState *pstate, VacuumStmt *vacstmt, bool isTopLevel);
339extern void vacuum(List *relations, VacuumParams *params,
340 BufferAccessStrategy bstrategy, MemoryContext vac_context,
341 bool isTopLevel);
342extern void vac_open_indexes(Relation relation, LOCKMODE lockmode,
343 int *nindexes, Relation **Irel);
344extern void vac_close_indexes(int nindexes, Relation *Irel, LOCKMODE lockmode);
345extern double vac_estimate_reltuples(Relation relation,
346 BlockNumber total_pages,
347 BlockNumber scanned_pages,
348 double scanned_tuples);
349extern void vac_update_relstats(Relation relation,
350 BlockNumber num_pages,
351 double num_tuples,
352 BlockNumber num_all_visible_pages,
353 BlockNumber num_all_frozen_pages,
354 bool hasindex,
355 TransactionId frozenxid,
356 MultiXactId minmulti,
357 bool *frozenxid_updated,
358 bool *minmulti_updated,
359 bool in_outer_xact);
360extern bool vacuum_get_cutoffs(Relation rel, const VacuumParams *params,
361 struct VacuumCutoffs *cutoffs);
362extern bool vacuum_xid_failsafe_check(const struct VacuumCutoffs *cutoffs);
363extern void vac_update_datfrozenxid(void);
364extern void vacuum_delay_point(bool is_analyze);
365extern bool vacuum_is_permitted_for_relation(Oid relid, Form_pg_class reltuple,
367extern Relation vacuum_open_relation(Oid relid, RangeVar *relation,
368 bits32 options, bool verbose,
369 LOCKMODE lmode);
372 TidStore *dead_items,
373 VacDeadItemsInfo *dead_items_info);
375 IndexBulkDeleteResult *istat);
376
377/* In postmaster/autovacuum.c */
378extern void AutoVacuumUpdateCostLimit(void);
379extern void VacuumUpdateCosts(void);
380
381/* in commands/vacuumparallel.c */
383 int nindexes, int nrequested_workers,
384 int vac_work_mem, int elevel,
385 BufferAccessStrategy bstrategy);
388 VacDeadItemsInfo **dead_items_info_p);
391 long num_table_tuples,
392 int num_index_scans);
394 long num_table_tuples,
395 int num_index_scans,
396 bool estimated_count);
397extern void parallel_vacuum_main(dsm_segment *seg, shm_toc *toc);
398
399/* in commands/analyze.c */
400extern void analyze_rel(Oid relid, RangeVar *relation,
401 VacuumParams *params, List *va_cols, bool in_outer_xact,
402 BufferAccessStrategy bstrategy);
403extern bool std_typanalyze(VacAttrStats *stats);
404
405/* in utils/misc/sampling.c --- duplicate of declarations in utils/sampling.h */
406extern double anl_random_fract(void);
407extern double anl_init_selection_state(int n);
408extern double anl_get_next_S(double t, int n, double *stateptr);
409
410#endif /* VACUUM_H */
uint32 BlockNumber
Definition: block.h:31
#define PGDLLIMPORT
Definition: c.h:1291
int64_t int64
Definition: c.h:499
TransactionId MultiXactId
Definition: c.h:633
int16_t int16
Definition: c.h:497
uint32 bits32
Definition: c.h:511
int32_t int32
Definition: c.h:498
float float4
Definition: c.h:600
uint32 TransactionId
Definition: c.h:623
int verbose
int LOCKMODE
Definition: lockdefs.h:26
FormData_pg_class * Form_pg_class
Definition: pg_class.h:156
#define STATISTIC_NUM_SLOTS
Definition: pg_statistic.h:127
FormData_pg_type * Form_pg_type
Definition: pg_type.h:261
uintptr_t Datum
Definition: postgres.h:69
unsigned int Oid
Definition: postgres_ext.h:32
Definition: pg_list.h:54
int32 attrtypmod
Definition: vacuum.h:127
bool stats_valid
Definition: vacuum.h:144
float4 stanullfrac
Definition: vacuum.h:145
Form_pg_type attrtype
Definition: vacuum.h:128
int16 stakind[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:148
int tupattnum
Definition: vacuum.h:171
MemoryContext anl_context
Definition: vacuum.h:130
Oid statypid[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:162
Oid staop[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:149
Oid stacoll[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:150
char statypalign[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:165
float4 * stanumbers[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:152
int rowstride
Definition: vacuum.h:176
Oid attrtypid
Definition: vacuum.h:126
HeapTuple * rows
Definition: vacuum.h:172
int minrows
Definition: vacuum.h:137
int attstattarget
Definition: vacuum.h:125
int32 stawidth
Definition: vacuum.h:146
void * extra_data
Definition: vacuum.h:138
bool statypbyval[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:164
int16 statyplen[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:163
bool * exprnulls
Definition: vacuum.h:175
TupleDesc tupDesc
Definition: vacuum.h:173
Datum * exprvals
Definition: vacuum.h:174
int numvalues[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:153
Datum * stavalues[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:154
float4 stadistinct
Definition: vacuum.h:147
int numnumbers[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:151
AnalyzeAttrComputeStatsFunc compute_stats
Definition: vacuum.h:136
Oid attrcollid
Definition: vacuum.h:129
size_t max_bytes
Definition: vacuum.h:294
int64 num_items
Definition: vacuum.h:295
TransactionId FreezeLimit
Definition: vacuum.h:284
TransactionId OldestXmin
Definition: vacuum.h:274
TransactionId relfrozenxid
Definition: vacuum.h:258
MultiXactId relminmxid
Definition: vacuum.h:259
MultiXactId MultiXactCutoff
Definition: vacuum.h:285
MultiXactId OldestMxact
Definition: vacuum.h:275
int nworkers
Definition: vacuum.h:246
int freeze_table_age
Definition: vacuum.h:221
VacOptValue truncate
Definition: vacuum.h:231
bits32 options
Definition: vacuum.h:219
int freeze_min_age
Definition: vacuum.h:220
bool is_wraparound
Definition: vacuum.h:226
int multixact_freeze_min_age
Definition: vacuum.h:222
int multixact_freeze_table_age
Definition: vacuum.h:224
int log_min_duration
Definition: vacuum.h:227
Oid toast_parent
Definition: vacuum.h:232
VacOptValue index_cleanup
Definition: vacuum.h:230
double max_eager_freeze_failure_rate
Definition: vacuum.h:239
void ExecVacuum(ParseState *pstate, VacuumStmt *vacstmt, bool isTopLevel)
Definition: vacuum.c:160
void VacuumUpdateCosts(void)
Definition: autovacuum.c:1654
PGDLLIMPORT int VacuumCostBalanceLocal
Definition: vacuum.c:116
TidStore * parallel_vacuum_get_dead_items(ParallelVacuumState *pvs, VacDeadItemsInfo **dead_items_info_p)
PGDLLIMPORT int vacuum_freeze_table_age
Definition: vacuum.c:74
PGDLLIMPORT pg_atomic_uint32 * VacuumSharedCostBalance
Definition: vacuum.c:114
PGDLLIMPORT int vacuum_cost_limit
Definition: vacuum.c:90
bool std_typanalyze(VacAttrStats *stats)
Definition: analyze.c:1886
void vac_open_indexes(Relation relation, LOCKMODE lockmode, int *nindexes, Relation **Irel)
Definition: vacuum.c:2338
void vacuum(List *relations, VacuumParams *params, BufferAccessStrategy bstrategy, MemoryContext vac_context, bool isTopLevel)
Definition: vacuum.c:496
PGDLLIMPORT pg_atomic_uint32 * VacuumActiveNWorkers
Definition: vacuum.c:115
PGDLLIMPORT double vacuum_cost_delay
Definition: vacuum.c:89
double anl_get_next_S(double t, int n, double *stateptr)
Definition: sampling.c:296
PGDLLIMPORT int vacuum_failsafe_age
Definition: vacuum.c:77
IndexBulkDeleteResult * vac_cleanup_one_index(IndexVacuumInfo *ivinfo, IndexBulkDeleteResult *istat)
Definition: vacuum.c:2630
ParallelVacuumState * parallel_vacuum_init(Relation rel, Relation *indrels, int nindexes, int nrequested_workers, int vac_work_mem, int elevel, BufferAccessStrategy bstrategy)
struct VacAttrStats VacAttrStats
PGDLLIMPORT bool VacuumFailsafeActive
Definition: vacuum.c:108
PGDLLIMPORT int vacuum_freeze_min_age
Definition: vacuum.c:73
void parallel_vacuum_bulkdel_all_indexes(ParallelVacuumState *pvs, long num_table_tuples, int num_index_scans)
PGDLLIMPORT int64 parallel_vacuum_worker_delay_ns
Definition: vacuum.c:93
Relation vacuum_open_relation(Oid relid, RangeVar *relation, bits32 options, bool verbose, LOCKMODE lmode)
Definition: vacuum.c:773
void parallel_vacuum_reset_dead_items(ParallelVacuumState *pvs)
void vac_close_indexes(int nindexes, Relation *Irel, LOCKMODE lockmode)
Definition: vacuum.c:2381
void parallel_vacuum_cleanup_all_indexes(ParallelVacuumState *pvs, long num_table_tuples, int num_index_scans, bool estimated_count)
Datum(* AnalyzeAttrFetchFunc)(VacAttrStatsP stats, int rownum, bool *isNull)
Definition: vacuum.h:108
void vac_update_datfrozenxid(void)
Definition: vacuum.c:1610
void vacuum_delay_point(bool is_analyze)
Definition: vacuum.c:2402
PGDLLIMPORT bool vacuum_truncate
Definition: vacuum.c:81
bool vacuum_get_cutoffs(Relation rel, const VacuumParams *params, struct VacuumCutoffs *cutoffs)
Definition: vacuum.c:1102
bool vacuum_xid_failsafe_check(const struct VacuumCutoffs *cutoffs)
Definition: vacuum.c:1270
VacOptValue
Definition: vacuum.h:201
@ VACOPTVALUE_AUTO
Definition: vacuum.h:203
@ VACOPTVALUE_ENABLED
Definition: vacuum.h:205
@ VACOPTVALUE_UNSPECIFIED
Definition: vacuum.h:202
@ VACOPTVALUE_DISABLED
Definition: vacuum.h:204
PGDLLIMPORT int default_statistics_target
Definition: analyze.c:71
void parallel_vacuum_main(dsm_segment *seg, shm_toc *toc)
struct VacDeadItemsInfo VacDeadItemsInfo
struct VacAttrStats * VacAttrStatsP
Definition: vacuum.h:106
PGDLLIMPORT int vacuum_multixact_freeze_table_age
Definition: vacuum.c:76
PGDLLIMPORT int vacuum_multixact_freeze_min_age
Definition: vacuum.c:75
double vac_estimate_reltuples(Relation relation, BlockNumber total_pages, BlockNumber scanned_pages, double scanned_tuples)
Definition: vacuum.c:1332
double anl_init_selection_state(int n)
Definition: sampling.c:281
PGDLLIMPORT bool track_cost_delay_timing
Definition: vacuum.c:80
void(* AnalyzeAttrComputeStatsFunc)(VacAttrStatsP stats, AnalyzeAttrFetchFunc fetchfunc, int samplerows, double totalrows)
Definition: vacuum.h:111
void analyze_rel(Oid relid, RangeVar *relation, VacuumParams *params, List *va_cols, bool in_outer_xact, BufferAccessStrategy bstrategy)
Definition: analyze.c:109
void AutoVacuumUpdateCostLimit(void)
Definition: autovacuum.c:1723
struct VacuumParams VacuumParams
void parallel_vacuum_end(ParallelVacuumState *pvs, IndexBulkDeleteResult **istats)
bool vacuum_is_permitted_for_relation(Oid relid, Form_pg_class reltuple, bits32 options)
Definition: vacuum.c:721
PGDLLIMPORT int vacuum_multixact_failsafe_age
Definition: vacuum.c:78
void vac_update_relstats(Relation relation, BlockNumber num_pages, double num_tuples, BlockNumber num_all_visible_pages, BlockNumber num_all_frozen_pages, bool hasindex, TransactionId frozenxid, MultiXactId minmulti, bool *frozenxid_updated, bool *minmulti_updated, bool in_outer_xact)
Definition: vacuum.c:1428
double anl_random_fract(void)
Definition: sampling.c:266
IndexBulkDeleteResult * vac_bulkdel_one_index(IndexVacuumInfo *ivinfo, IndexBulkDeleteResult *istat, TidStore *dead_items, VacDeadItemsInfo *dead_items_info)
Definition: vacuum.c:2609
PGDLLIMPORT double vacuum_max_eager_freeze_failure_rate
Definition: vacuum.c:79