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-2024, 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"
22 #include "catalog/pg_statistic.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  */
106 typedef struct VacAttrStats *VacAttrStatsP;
107 
108 typedef Datum (*AnalyzeAttrFetchFunc) (VacAttrStatsP stats, int rownum,
109  bool *isNull);
110 
112  AnalyzeAttrFetchFunc fetchfunc,
113  int samplerows,
114  double totalrows);
115 
116 typedef 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 */
175  bool *exprnulls;
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  */
200 typedef 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  */
217 typedef 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  * The number of parallel vacuum workers. 0 by default which means choose
236  * based on the number of indexes. -1 indicates parallel vacuum is
237  * disabled.
238  */
239  int nworkers;
241 
242 /*
243  * VacuumCutoffs is immutable state that describes the cutoffs used by VACUUM.
244  * Established at the beginning of each VACUUM operation.
245  */
247 {
248  /*
249  * Existing pg_class fields at start of VACUUM
250  */
253 
254  /*
255  * OldestXmin is the Xid below which tuples deleted by any xact (that
256  * committed) should be considered DEAD, not just RECENTLY_DEAD.
257  *
258  * OldestMxact is the Mxid below which MultiXacts are definitely not seen
259  * as visible by any running transaction.
260  *
261  * OldestXmin and OldestMxact are also the most recent values that can
262  * ever be passed to vac_update_relstats() as frozenxid and minmulti
263  * arguments at the end of VACUUM. These same values should be passed
264  * when it turns out that VACUUM will leave no unfrozen XIDs/MXIDs behind
265  * in the table.
266  */
269 
270  /*
271  * FreezeLimit is the Xid below which all Xids are definitely frozen or
272  * removed in pages VACUUM scans and cleanup locks.
273  *
274  * MultiXactCutoff is the value below which all MultiXactIds are
275  * definitely removed from Xmax in pages VACUUM scans and cleanup locks.
276  */
279 };
280 
281 /*
282  * VacDeadItemsInfo stores supplemental information for dead tuple TID
283  * storage (i.e. TidStore).
284  */
285 typedef struct VacDeadItemsInfo
286 {
287  size_t max_bytes; /* the maximum bytes TidStore can use */
288  int64 num_items; /* current # of entries */
290 
291 /* GUC parameters */
292 extern PGDLLIMPORT int default_statistics_target; /* PGDLLIMPORT for PostGIS */
299 
300 /*
301  * Maximum value for default_statistics_target and per-column statistics
302  * targets. This is fairly arbitrary, mainly to prevent users from creating
303  * unreasonably large statistics that the system cannot handle well.
304  */
305 #define MAX_STATISTICS_TARGET 10000
306 
307 /* Variables for cost-based parallel vacuum */
311 
313 extern PGDLLIMPORT double vacuum_cost_delay;
314 extern PGDLLIMPORT int vacuum_cost_limit;
315 
316 /* in commands/vacuum.c */
317 extern void ExecVacuum(ParseState *pstate, VacuumStmt *vacstmt, bool isTopLevel);
318 extern void vacuum(List *relations, VacuumParams *params,
319  BufferAccessStrategy bstrategy, MemoryContext vac_context,
320  bool isTopLevel);
321 extern void vac_open_indexes(Relation relation, LOCKMODE lockmode,
322  int *nindexes, Relation **Irel);
323 extern void vac_close_indexes(int nindexes, Relation *Irel, LOCKMODE lockmode);
324 extern double vac_estimate_reltuples(Relation relation,
325  BlockNumber total_pages,
326  BlockNumber scanned_pages,
327  double scanned_tuples);
328 extern void vac_update_relstats(Relation relation,
329  BlockNumber num_pages,
330  double num_tuples,
331  BlockNumber num_all_visible_pages,
332  bool hasindex,
333  TransactionId frozenxid,
334  MultiXactId minmulti,
335  bool *frozenxid_updated,
336  bool *minmulti_updated,
337  bool in_outer_xact);
338 extern bool vacuum_get_cutoffs(Relation rel, const VacuumParams *params,
339  struct VacuumCutoffs *cutoffs);
340 extern bool vacuum_xid_failsafe_check(const struct VacuumCutoffs *cutoffs);
341 extern void vac_update_datfrozenxid(void);
342 extern void vacuum_delay_point(void);
343 extern bool vacuum_is_permitted_for_relation(Oid relid, Form_pg_class reltuple,
344  bits32 options);
345 extern Relation vacuum_open_relation(Oid relid, RangeVar *relation,
346  bits32 options, bool verbose,
347  LOCKMODE lmode);
349  IndexBulkDeleteResult *istat,
350  TidStore *dead_items,
351  VacDeadItemsInfo *dead_items_info);
353  IndexBulkDeleteResult *istat);
354 
355 /* In postmaster/autovacuum.c */
356 extern void AutoVacuumUpdateCostLimit(void);
357 extern void VacuumUpdateCosts(void);
358 
359 /* in commands/vacuumparallel.c */
361  int nindexes, int nrequested_workers,
362  int vac_work_mem, int elevel,
363  BufferAccessStrategy bstrategy);
366  VacDeadItemsInfo **dead_items_info_p);
369  long num_table_tuples,
370  int num_index_scans);
372  long num_table_tuples,
373  int num_index_scans,
374  bool estimated_count);
375 extern void parallel_vacuum_main(dsm_segment *seg, shm_toc *toc);
376 
377 /* in commands/analyze.c */
378 extern void analyze_rel(Oid relid, RangeVar *relation,
379  VacuumParams *params, List *va_cols, bool in_outer_xact,
380  BufferAccessStrategy bstrategy);
381 extern bool std_typanalyze(VacAttrStats *stats);
382 
383 /* in utils/misc/sampling.c --- duplicate of declarations in utils/sampling.h */
384 extern double anl_random_fract(void);
385 extern double anl_init_selection_state(int n);
386 extern double anl_get_next_S(double t, int n, double *stateptr);
387 
388 #endif /* VACUUM_H */
uint32 BlockNumber
Definition: block.h:31
#define PGDLLIMPORT
Definition: c.h:1316
signed short int16
Definition: c.h:493
signed int int32
Definition: c.h:494
TransactionId MultiXactId
Definition: c.h:662
uint32 bits32
Definition: c.h:515
float float4
Definition: c.h:629
uint32 TransactionId
Definition: c.h:652
int verbose
int LOCKMODE
Definition: lockdefs.h:26
FormData_pg_class * Form_pg_class
Definition: pg_class.h:153
#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:64
unsigned int Oid
Definition: postgres_ext.h:31
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:287
int64 num_items
Definition: vacuum.h:288
TransactionId FreezeLimit
Definition: vacuum.h:277
TransactionId OldestXmin
Definition: vacuum.h:267
TransactionId relfrozenxid
Definition: vacuum.h:251
MultiXactId relminmxid
Definition: vacuum.h:252
MultiXactId MultiXactCutoff
Definition: vacuum.h:278
MultiXactId OldestMxact
Definition: vacuum.h:268
int nworkers
Definition: vacuum.h:239
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
void ExecVacuum(ParseState *pstate, VacuumStmt *vacstmt, bool isTopLevel)
Definition: vacuum.c:147
void VacuumUpdateCosts(void)
Definition: autovacuum.c:1633
IndexBulkDeleteResult * vac_bulkdel_one_index(IndexVacuumInfo *ivinfo, IndexBulkDeleteResult *istat, TidStore *dead_items, VacDeadItemsInfo *dead_items_info)
Definition: vacuum.c:2494
PGDLLIMPORT int VacuumCostBalanceLocal
Definition: vacuum.c:104
PGDLLIMPORT int vacuum_freeze_table_age
Definition: vacuum.c:68
PGDLLIMPORT pg_atomic_uint32 * VacuumSharedCostBalance
Definition: vacuum.c:102
PGDLLIMPORT int vacuum_cost_limit
Definition: vacuum.c:81
bool std_typanalyze(VacAttrStats *stats)
Definition: analyze.c:1840
void vac_open_indexes(Relation relation, LOCKMODE lockmode, int *nindexes, Relation **Irel)
Definition: vacuum.c:2276
void vacuum(List *relations, VacuumParams *params, BufferAccessStrategy bstrategy, MemoryContext vac_context, bool isTopLevel)
Definition: vacuum.c:478
PGDLLIMPORT pg_atomic_uint32 * VacuumActiveNWorkers
Definition: vacuum.c:103
void vac_update_relstats(Relation relation, BlockNumber num_pages, double num_tuples, BlockNumber num_all_visible_pages, bool hasindex, TransactionId frozenxid, MultiXactId minmulti, bool *frozenxid_updated, bool *minmulti_updated, bool in_outer_xact)
Definition: vacuum.c:1398
PGDLLIMPORT double vacuum_cost_delay
Definition: vacuum.c:80
double anl_get_next_S(double t, int n, double *stateptr)
Definition: sampling.c:296
PGDLLIMPORT int vacuum_failsafe_age
Definition: vacuum.c:71
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:96
PGDLLIMPORT int vacuum_freeze_min_age
Definition: vacuum.c:67
void parallel_vacuum_bulkdel_all_indexes(ParallelVacuumState *pvs, long num_table_tuples, int num_index_scans)
Relation vacuum_open_relation(Oid relid, RangeVar *relation, bits32 options, bool verbose, LOCKMODE lmode)
Definition: vacuum.c:758
void parallel_vacuum_reset_dead_items(ParallelVacuumState *pvs)
void vac_close_indexes(int nindexes, Relation *Irel, LOCKMODE lockmode)
Definition: vacuum.c:2319
void vacuum_delay_point(void)
Definition: vacuum.c:2340
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:1565
bool vacuum_get_cutoffs(Relation rel, const VacuumParams *params, struct VacuumCutoffs *cutoffs)
Definition: vacuum.c:1072
bool vacuum_xid_failsafe_check(const struct VacuumCutoffs *cutoffs)
Definition: vacuum.c:1240
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:73
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:70
PGDLLIMPORT int vacuum_multixact_freeze_min_age
Definition: vacuum.c:69
double vac_estimate_reltuples(Relation relation, BlockNumber total_pages, BlockNumber scanned_pages, double scanned_tuples)
Definition: vacuum.c:1302
double anl_init_selection_state(int n)
Definition: sampling.c:281
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:111
void AutoVacuumUpdateCostLimit(void)
Definition: autovacuum.c:1702
IndexBulkDeleteResult * vac_cleanup_one_index(IndexVacuumInfo *ivinfo, IndexBulkDeleteResult *istat)
Definition: vacuum.c:2515
TidStore * parallel_vacuum_get_dead_items(ParallelVacuumState *pvs, VacDeadItemsInfo **dead_items_info_p)
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:706
PGDLLIMPORT int vacuum_multixact_failsafe_age
Definition: vacuum.c:72
double anl_random_fract(void)
Definition: sampling.c:266