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-2021, 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 "catalog/pg_class.h"
19 #include "catalog/pg_statistic.h"
20 #include "catalog/pg_type.h"
21 #include "parser/parse_node.h"
22 #include "storage/buf.h"
23 #include "storage/lock.h"
24 #include "utils/relcache.h"
25 
26 /*
27  * Flags for amparallelvacuumoptions to control the participation of bulkdelete
28  * and vacuumcleanup in parallel vacuum.
29  */
30 
31 /*
32  * Both bulkdelete and vacuumcleanup are disabled by default. This will be
33  * used by IndexAM's that don't want to or cannot participate in parallel
34  * vacuum. For example, if an index AM doesn't have a way to communicate the
35  * index statistics allocated by the first ambulkdelete call to the subsequent
36  * ones until amvacuumcleanup, the index AM cannot participate in parallel
37  * vacuum.
38  */
39 #define VACUUM_OPTION_NO_PARALLEL 0
40 
41 /*
42  * bulkdelete can be performed in parallel. This option can be used by
43  * index AMs that need to scan indexes to delete tuples.
44  */
45 #define VACUUM_OPTION_PARALLEL_BULKDEL (1 << 0)
46 
47 /*
48  * vacuumcleanup can be performed in parallel if bulkdelete is not performed
49  * yet. This will be used by IndexAM's that can scan the index if the
50  * bulkdelete is not performed.
51  */
52 #define VACUUM_OPTION_PARALLEL_COND_CLEANUP (1 << 1)
53 
54 /*
55  * vacuumcleanup can be performed in parallel even if bulkdelete has already
56  * processed the index. This will be used by IndexAM's that scan the index
57  * during the cleanup phase of index irrespective of whether the index is
58  * already scanned or not during bulkdelete phase.
59  */
60 #define VACUUM_OPTION_PARALLEL_CLEANUP (1 << 2)
61 
62 /* value for checking vacuum flags */
63 #define VACUUM_OPTION_MAX_VALID_VALUE ((1 << 3) - 1)
64 
65 /*----------
66  * ANALYZE builds one of these structs for each attribute (column) that is
67  * to be analyzed. The struct and subsidiary data are in anl_context,
68  * so they live until the end of the ANALYZE operation.
69  *
70  * The type-specific typanalyze function is passed a pointer to this struct
71  * and must return true to continue analysis, false to skip analysis of this
72  * column. In the true case it must set the compute_stats and minrows fields,
73  * and can optionally set extra_data to pass additional info to compute_stats.
74  * minrows is its request for the minimum number of sample rows to be gathered
75  * (but note this request might not be honored, eg if there are fewer rows
76  * than that in the table).
77  *
78  * The compute_stats routine will be called after sample rows have been
79  * gathered. Aside from this struct, it is passed:
80  * fetchfunc: a function for accessing the column values from the
81  * sample rows
82  * samplerows: the number of sample tuples
83  * totalrows: estimated total number of rows in relation
84  * The fetchfunc may be called with rownum running from 0 to samplerows-1.
85  * It returns a Datum and an isNull flag.
86  *
87  * compute_stats should set stats_valid true if it is able to compute
88  * any useful statistics. If it does, the remainder of the struct holds
89  * the information to be stored in a pg_statistic row for the column. Be
90  * careful to allocate any pointed-to data in anl_context, which will NOT
91  * be CurrentMemoryContext when compute_stats is called.
92  *
93  * Note: all comparisons done for statistical purposes should use the
94  * underlying column's collation (attcollation), except in situations
95  * where a noncollatable container type contains a collatable type;
96  * in that case use the type's default collation. Be sure to record
97  * the appropriate collation in stacoll.
98  *----------
99  */
100 typedef struct VacAttrStats *VacAttrStatsP;
101 
102 typedef Datum (*AnalyzeAttrFetchFunc) (VacAttrStatsP stats, int rownum,
103  bool *isNull);
104 
106  AnalyzeAttrFetchFunc fetchfunc,
107  int samplerows,
108  double totalrows);
109 
110 typedef struct VacAttrStats
111 {
112  /*
113  * These fields are set up by the main ANALYZE code before invoking the
114  * type-specific typanalyze function.
115  *
116  * Note: do not assume that the data being analyzed has the same datatype
117  * shown in attr, ie do not trust attr->atttypid, attlen, etc. This is
118  * because some index opclasses store a different type than the underlying
119  * column/expression. Instead use attrtypid, attrtypmod, and attrtype for
120  * information about the datatype being fed to the typanalyze function.
121  * Likewise, use attrcollid not attr->attcollation.
122  */
123  Form_pg_attribute attr; /* copy of pg_attribute row for column */
124  Oid attrtypid; /* type of data being analyzed */
125  int32 attrtypmod; /* typmod of data being analyzed */
126  Form_pg_type attrtype; /* copy of pg_type row for attrtypid */
127  Oid attrcollid; /* collation of data being analyzed */
128  MemoryContext anl_context; /* where to save long-lived data */
129 
130  /*
131  * These fields must be filled in by the typanalyze routine, unless it
132  * returns false.
133  */
135  int minrows; /* Minimum # of rows wanted for stats */
136  void *extra_data; /* for extra type-specific data */
137 
138  /*
139  * These fields are to be filled in by the compute_stats routine. (They
140  * are initialized to zero when the struct is created.)
141  */
143  float4 stanullfrac; /* fraction of entries that are NULL */
144  int32 stawidth; /* average width of column values */
145  float4 stadistinct; /* # distinct values */
153 
154  /*
155  * These fields describe the stavalues[n] element types. They will be
156  * initialized to match attrtypid, but a custom typanalyze function might
157  * want to store an array of something other than the analyzed column's
158  * elements. It should then overwrite these fields.
159  */
164 
165  /*
166  * These fields are private to the main ANALYZE code and should not be
167  * looked at by type-specific functions.
168  */
169  int tupattnum; /* attribute number within tuples */
170  HeapTuple *rows; /* access info for std fetch function */
172  Datum *exprvals; /* access info for index fetch function */
173  bool *exprnulls;
176 
177 /* flag bits for VacuumParams->options */
178 #define VACOPT_VACUUM 0x01 /* do VACUUM */
179 #define VACOPT_ANALYZE 0x02 /* do ANALYZE */
180 #define VACOPT_VERBOSE 0x04 /* print progress info */
181 #define VACOPT_FREEZE 0x08 /* FREEZE option */
182 #define VACOPT_FULL 0x10 /* FULL (non-concurrent) vacuum */
183 #define VACOPT_SKIP_LOCKED 0x20 /* skip if cannot get lock */
184 #define VACOPT_PROCESS_TOAST 0x40 /* process the TOAST table, if any */
185 #define VACOPT_DISABLE_PAGE_SKIPPING 0x80 /* don't skip any pages */
186 
187 /*
188  * Values used by index_cleanup and truncate params.
189  *
190  * VACOPTVALUE_UNSPECIFIED is used as an initial placeholder when VACUUM
191  * command has no explicit value. When that happens the final usable value
192  * comes from the corresponding reloption (though the reloption default is
193  * usually used).
194  */
195 typedef enum VacOptValue
196 {
202 
203 /*
204  * Parameters customizing behavior of VACUUM and ANALYZE.
205  *
206  * Note that at least one of VACOPT_VACUUM and VACOPT_ANALYZE must be set
207  * in options.
208  */
209 typedef struct VacuumParams
210 {
211  bits32 options; /* bitmask of VACOPT_* */
212  int freeze_min_age; /* min freeze age, -1 to use default */
213  int freeze_table_age; /* age at which to scan whole table */
214  int multixact_freeze_min_age; /* min multixact freeze age, -1 to
215  * use default */
216  int multixact_freeze_table_age; /* multixact age at which to scan
217  * whole table */
218  bool is_wraparound; /* force a for-wraparound vacuum */
219  int log_min_duration; /* minimum execution threshold in ms at
220  * which verbose logs are activated, -1
221  * to use default */
222  VacOptValue index_cleanup; /* Do index vacuum and cleanup */
223  VacOptValue truncate; /* Truncate empty pages at the end */
224 
225  /*
226  * The number of parallel vacuum workers. 0 by default which means choose
227  * based on the number of indexes. -1 indicates parallel vacuum is
228  * disabled.
229  */
230  int nworkers;
232 
233 /* GUC parameters */
234 extern PGDLLIMPORT int default_statistics_target; /* PGDLLIMPORT for PostGIS */
235 extern int vacuum_freeze_min_age;
236 extern int vacuum_freeze_table_age;
239 extern int vacuum_failsafe_age;
241 
242 /* Variables for cost-based parallel vacuum */
245 extern int VacuumCostBalanceLocal;
246 
247 
248 /* in commands/vacuum.c */
249 extern void ExecVacuum(ParseState *pstate, VacuumStmt *vacstmt, bool isTopLevel);
250 extern void vacuum(List *relations, VacuumParams *params,
251  BufferAccessStrategy bstrategy, bool isTopLevel);
252 extern void vac_open_indexes(Relation relation, LOCKMODE lockmode,
253  int *nindexes, Relation **Irel);
254 extern void vac_close_indexes(int nindexes, Relation *Irel, LOCKMODE lockmode);
255 extern double vac_estimate_reltuples(Relation relation,
256  BlockNumber total_pages,
257  BlockNumber scanned_pages,
258  double scanned_tuples);
259 extern void vac_update_relstats(Relation relation,
260  BlockNumber num_pages,
261  double num_tuples,
262  BlockNumber num_all_visible_pages,
263  bool hasindex,
264  TransactionId frozenxid,
265  MultiXactId minmulti,
266  bool in_outer_xact);
267 extern void vacuum_set_xid_limits(Relation rel,
268  int freeze_min_age, int freeze_table_age,
269  int multixact_freeze_min_age,
270  int multixact_freeze_table_age,
271  TransactionId *oldestXmin,
272  TransactionId *freezeLimit,
273  TransactionId *xidFullScanLimit,
274  MultiXactId *multiXactCutoff,
275  MultiXactId *mxactFullScanLimit);
276 extern bool vacuum_xid_failsafe_check(TransactionId relfrozenxid,
277  MultiXactId relminmxid);
278 extern void vac_update_datfrozenxid(void);
279 extern void vacuum_delay_point(void);
280 extern bool vacuum_is_relation_owner(Oid relid, Form_pg_class reltuple,
281  bits32 options);
282 extern Relation vacuum_open_relation(Oid relid, RangeVar *relation,
283  bits32 options, bool verbose,
284  LOCKMODE lmode);
285 
286 /* in commands/analyze.c */
287 extern void analyze_rel(Oid relid, RangeVar *relation,
288  VacuumParams *params, List *va_cols, bool in_outer_xact,
289  BufferAccessStrategy bstrategy);
290 extern bool std_typanalyze(VacAttrStats *stats);
291 
292 /* in utils/misc/sampling.c --- duplicate of declarations in utils/sampling.h */
293 extern double anl_random_fract(void);
294 extern double anl_init_selection_state(int n);
295 extern double anl_get_next_S(double t, int n, double *stateptr);
296 
297 #endif /* VACUUM_H */
uint32 BlockNumber
Definition: block.h:31
#define PGDLLIMPORT
Definition: c.h:1318
signed short int16
Definition: c.h:428
signed int int32
Definition: c.h:429
TransactionId MultiXactId
Definition: c.h:597
uint32 bits32
Definition: c.h:450
float float4
Definition: c.h:564
uint32 TransactionId
Definition: c.h:587
int LOCKMODE
Definition: lockdefs.h:26
FormData_pg_attribute * Form_pg_attribute
Definition: pg_attribute.h:207
static int verbose
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:411
unsigned int Oid
Definition: postgres_ext.h:31
Definition: pg_list.h:51
int32 attrtypmod
Definition: vacuum.h:125
bool stats_valid
Definition: vacuum.h:142
float4 stanullfrac
Definition: vacuum.h:143
Form_pg_type attrtype
Definition: vacuum.h:126
int16 stakind[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:146
int tupattnum
Definition: vacuum.h:169
MemoryContext anl_context
Definition: vacuum.h:128
Oid statypid[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:160
Oid staop[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:147
Oid stacoll[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:148
char statypalign[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:163
float4 * stanumbers[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:150
int rowstride
Definition: vacuum.h:174
Oid attrtypid
Definition: vacuum.h:124
HeapTuple * rows
Definition: vacuum.h:170
int minrows
Definition: vacuum.h:135
Form_pg_attribute attr
Definition: vacuum.h:123
int32 stawidth
Definition: vacuum.h:144
void * extra_data
Definition: vacuum.h:136
bool statypbyval[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:162
int16 statyplen[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:161
bool * exprnulls
Definition: vacuum.h:173
TupleDesc tupDesc
Definition: vacuum.h:171
Datum * exprvals
Definition: vacuum.h:172
int numvalues[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:151
Datum * stavalues[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:152
float4 stadistinct
Definition: vacuum.h:145
int numnumbers[STATISTIC_NUM_SLOTS]
Definition: vacuum.h:149
AnalyzeAttrComputeStatsFunc compute_stats
Definition: vacuum.h:134
Oid attrcollid
Definition: vacuum.h:127
int nworkers
Definition: vacuum.h:230
int freeze_table_age
Definition: vacuum.h:213
VacOptValue truncate
Definition: vacuum.h:223
bits32 options
Definition: vacuum.h:211
int freeze_min_age
Definition: vacuum.h:212
bool is_wraparound
Definition: vacuum.h:218
int multixact_freeze_min_age
Definition: vacuum.h:214
int multixact_freeze_table_age
Definition: vacuum.h:216
int log_min_duration
Definition: vacuum.h:219
VacOptValue index_cleanup
Definition: vacuum.h:222
void ExecVacuum(ParseState *pstate, VacuumStmt *vacstmt, bool isTopLevel)
Definition: vacuum.c:100
void vac_update_relstats(Relation relation, BlockNumber num_pages, double num_tuples, BlockNumber num_all_visible_pages, bool hasindex, TransactionId frozenxid, MultiXactId minmulti, bool in_outer_xact)
Definition: vacuum.c:1306
pg_atomic_uint32 * VacuumActiveNWorkers
Definition: vacuum.c:79
int vacuum_freeze_min_age
Definition: vacuum.c:61
bool std_typanalyze(VacAttrStats *stats)
Definition: analyze.c:1858
void vac_open_indexes(Relation relation, LOCKMODE lockmode, int *nindexes, Relation **Irel)
Definition: vacuum.c:2085
int VacuumCostBalanceLocal
Definition: vacuum.c:80
void vacuum(List *relations, VacuumParams *params, BufferAccessStrategy bstrategy, bool isTopLevel)
Definition: vacuum.c:291
int vacuum_multixact_freeze_table_age
Definition: vacuum.c:64
bool vacuum_xid_failsafe_check(TransactionId relfrozenxid, MultiXactId relminmxid)
Definition: vacuum.c:1163
double anl_get_next_S(double t, int n, double *stateptr)
Definition: sampling.c:296
int vacuum_freeze_table_age
Definition: vacuum.c:62
int vacuum_multixact_failsafe_age
Definition: vacuum.c:66
struct VacAttrStats VacAttrStats
int vacuum_multixact_freeze_min_age
Definition: vacuum.c:63
Relation vacuum_open_relation(Oid relid, RangeVar *relation, bits32 options, bool verbose, LOCKMODE lmode)
Definition: vacuum.c:633
void vac_close_indexes(int nindexes, Relation *Irel, LOCKMODE lockmode)
Definition: vacuum.c:2128
void vacuum_delay_point(void)
Definition: vacuum.c:2149
Datum(* AnalyzeAttrFetchFunc)(VacAttrStatsP stats, int rownum, bool *isNull)
Definition: vacuum.h:102
bool vacuum_is_relation_owner(Oid relid, Form_pg_class reltuple, bits32 options)
Definition: vacuum.c:559
void vac_update_datfrozenxid(void)
Definition: vacuum.c:1433
VacOptValue
Definition: vacuum.h:196
@ VACOPTVALUE_AUTO
Definition: vacuum.h:198
@ VACOPTVALUE_ENABLED
Definition: vacuum.h:200
@ VACOPTVALUE_UNSPECIFIED
Definition: vacuum.h:197
@ VACOPTVALUE_DISABLED
Definition: vacuum.h:199
pg_atomic_uint32 * VacuumSharedCostBalance
Definition: vacuum.c:78
PGDLLIMPORT int default_statistics_target
Definition: analyze.c:83
void vacuum_set_xid_limits(Relation rel, int freeze_min_age, int freeze_table_age, int multixact_freeze_min_age, int multixact_freeze_table_age, TransactionId *oldestXmin, TransactionId *freezeLimit, TransactionId *xidFullScanLimit, MultiXactId *multiXactCutoff, MultiXactId *mxactFullScanLimit)
Definition: vacuum.c:957
struct VacAttrStats * VacAttrStatsP
Definition: vacuum.h:100
int vacuum_failsafe_age
Definition: vacuum.c:65
double vac_estimate_reltuples(Relation relation, BlockNumber total_pages, BlockNumber scanned_pages, double scanned_tuples)
Definition: vacuum.c:1223
double anl_init_selection_state(int n)
Definition: sampling.c:281
void(* AnalyzeAttrComputeStatsFunc)(VacAttrStatsP stats, AnalyzeAttrFetchFunc fetchfunc, int samplerows, double totalrows)
Definition: vacuum.h:105
void analyze_rel(Oid relid, RangeVar *relation, VacuumParams *params, List *va_cols, bool in_outer_xact, BufferAccessStrategy bstrategy)
Definition: analyze.c:121
struct VacuumParams VacuumParams
double anl_random_fract(void)
Definition: sampling.c:266