PostgreSQL Source Code  git master
brinfuncs.c
Go to the documentation of this file.
1 /*
2  * brinfuncs.c
3  * Functions to investigate BRIN indexes
4  *
5  * Copyright (c) 2014-2022, PostgreSQL Global Development Group
6  *
7  * IDENTIFICATION
8  * contrib/pageinspect/brinfuncs.c
9  */
10 #include "postgres.h"
11 
12 #include "access/brin.h"
13 #include "access/brin_internal.h"
14 #include "access/brin_page.h"
15 #include "access/brin_revmap.h"
16 #include "access/brin_tuple.h"
17 #include "access/htup_details.h"
18 #include "catalog/index.h"
19 #include "catalog/pg_am_d.h"
20 #include "catalog/pg_type.h"
21 #include "funcapi.h"
22 #include "lib/stringinfo.h"
23 #include "miscadmin.h"
24 #include "pageinspect.h"
25 #include "utils/array.h"
26 #include "utils/builtins.h"
27 #include "utils/lsyscache.h"
28 #include "utils/rel.h"
29 
34 
35 #define IS_BRIN(r) ((r)->rd_rel->relam == BRIN_AM_OID)
36 
37 typedef struct brin_column_state
38 {
39  int nstored;
42 
43 
44 static Page verify_brin_page(bytea *raw_page, uint16 type,
45  const char *strtype);
46 
47 Datum
49 {
50  bytea *raw_page = PG_GETARG_BYTEA_P(0);
51  Page page;
52  char *type;
53 
54  if (!superuser())
55  ereport(ERROR,
56  (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
57  errmsg("must be superuser to use raw page functions")));
58 
59  page = get_page_from_raw(raw_page);
60 
61  if (PageIsNew(page))
63 
64  /* verify the special space has the expected size */
65  if (PageGetSpecialSize(page) != MAXALIGN(sizeof(BrinSpecialSpace)))
66  ereport(ERROR,
67  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
68  errmsg("input page is not a valid %s page", "BRIN"),
69  errdetail("Expected special size %d, got %d.",
70  (int) MAXALIGN(sizeof(BrinSpecialSpace)),
71  (int) PageGetSpecialSize(page))));
72 
73  switch (BrinPageType(page))
74  {
75  case BRIN_PAGETYPE_META:
76  type = "meta";
77  break;
79  type = "revmap";
80  break;
82  type = "regular";
83  break;
84  default:
85  type = psprintf("unknown (%02x)", BrinPageType(page));
86  break;
87  }
88 
90 }
91 
92 /*
93  * Verify that the given bytea contains a BRIN page of the indicated page
94  * type, or die in the attempt. A pointer to the page is returned.
95  */
96 static Page
97 verify_brin_page(bytea *raw_page, uint16 type, const char *strtype)
98 {
99  Page page = get_page_from_raw(raw_page);
100 
101  if (PageIsNew(page))
102  return page;
103 
104  /* verify the special space has the expected size */
105  if (PageGetSpecialSize(page) != MAXALIGN(sizeof(BrinSpecialSpace)))
106  ereport(ERROR,
107  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
108  errmsg("input page is not a valid %s page", "BRIN"),
109  errdetail("Expected special size %d, got %d.",
110  (int) MAXALIGN(sizeof(BrinSpecialSpace)),
111  (int) PageGetSpecialSize(page))));
112 
113  /* verify the special space says this page is what we want */
114  if (BrinPageType(page) != type)
115  ereport(ERROR,
116  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
117  errmsg("page is not a BRIN page of type \"%s\"", strtype),
118  errdetail("Expected special type %08x, got %08x.",
119  type, BrinPageType(page))));
120 
121  return page;
122 }
123 
124 
125 /*
126  * Extract all item values from a BRIN index page
127  *
128  * Usage: SELECT * FROM brin_page_items(get_raw_page('idx', 1), 'idx'::regclass);
129  */
130 Datum
132 {
133  bytea *raw_page = PG_GETARG_BYTEA_P(0);
134  Oid indexRelid = PG_GETARG_OID(1);
135  ReturnSetInfo *rsinfo = (ReturnSetInfo *) fcinfo->resultinfo;
136  Relation indexRel;
137  brin_column_state **columns;
138  BrinDesc *bdesc;
139  BrinMemTuple *dtup;
140  Page page;
141  OffsetNumber offset;
142  AttrNumber attno;
143  bool unusedItem;
144 
145  if (!superuser())
146  ereport(ERROR,
147  (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
148  errmsg("must be superuser to use raw page functions")));
149 
150  SetSingleFuncCall(fcinfo, 0);
151 
152  indexRel = index_open(indexRelid, AccessShareLock);
153 
154  if (!IS_BRIN(indexRel))
155  ereport(ERROR,
156  (errcode(ERRCODE_WRONG_OBJECT_TYPE),
157  errmsg("\"%s\" is not a %s index",
158  RelationGetRelationName(indexRel), "BRIN")));
159 
160  bdesc = brin_build_desc(indexRel);
161 
162  /* minimally verify the page we got */
163  page = verify_brin_page(raw_page, BRIN_PAGETYPE_REGULAR, "regular");
164 
165  if (PageIsNew(page))
166  {
167  brin_free_desc(bdesc);
168  index_close(indexRel, AccessShareLock);
169  PG_RETURN_NULL();
170  }
171 
172  /*
173  * Initialize output functions for all indexed datatypes; simplifies
174  * calling them later.
175  */
176  columns = palloc(sizeof(brin_column_state *) * RelationGetDescr(indexRel)->natts);
177  for (attno = 1; attno <= bdesc->bd_tupdesc->natts; attno++)
178  {
179  Oid output;
180  bool isVarlena;
181  BrinOpcInfo *opcinfo;
182  int i;
183  brin_column_state *column;
184 
185  opcinfo = bdesc->bd_info[attno - 1];
186  column = palloc(offsetof(brin_column_state, outputFn) +
187  sizeof(FmgrInfo) * opcinfo->oi_nstored);
188 
189  column->nstored = opcinfo->oi_nstored;
190  for (i = 0; i < opcinfo->oi_nstored; i++)
191  {
192  getTypeOutputInfo(opcinfo->oi_typcache[i]->type_id, &output, &isVarlena);
193  fmgr_info(output, &column->outputFn[i]);
194  }
195 
196  columns[attno - 1] = column;
197  }
198 
199  offset = FirstOffsetNumber;
200  unusedItem = false;
201  dtup = NULL;
202  for (;;)
203  {
204  Datum values[7];
205  bool nulls[7];
206 
207  /*
208  * This loop is called once for every attribute of every tuple in the
209  * page. At the start of a tuple, we get a NULL dtup; that's our
210  * signal for obtaining and decoding the next one. If that's not the
211  * case, we output the next attribute.
212  */
213  if (dtup == NULL)
214  {
215  ItemId itemId;
216 
217  /* verify item status: if there's no data, we can't decode */
218  itemId = PageGetItemId(page, offset);
219  if (ItemIdIsUsed(itemId))
220  {
221  dtup = brin_deform_tuple(bdesc,
222  (BrinTuple *) PageGetItem(page, itemId),
223  NULL);
224  attno = 1;
225  unusedItem = false;
226  }
227  else
228  unusedItem = true;
229  }
230  else
231  attno++;
232 
233  MemSet(nulls, 0, sizeof(nulls));
234 
235  if (unusedItem)
236  {
237  values[0] = UInt16GetDatum(offset);
238  nulls[1] = true;
239  nulls[2] = true;
240  nulls[3] = true;
241  nulls[4] = true;
242  nulls[5] = true;
243  nulls[6] = true;
244  }
245  else
246  {
247  int att = attno - 1;
248 
249  values[0] = UInt16GetDatum(offset);
250  switch (TupleDescAttr(rsinfo->setDesc, 1)->atttypid)
251  {
252  case INT8OID:
253  values[1] = Int64GetDatum((int64) dtup->bt_blkno);
254  break;
255  case INT4OID:
256  /* support for old extension version */
257  values[1] = UInt32GetDatum(dtup->bt_blkno);
258  break;
259  default:
260  elog(ERROR, "incorrect output types");
261  }
262  values[2] = UInt16GetDatum(attno);
263  values[3] = BoolGetDatum(dtup->bt_columns[att].bv_allnulls);
264  values[4] = BoolGetDatum(dtup->bt_columns[att].bv_hasnulls);
265  values[5] = BoolGetDatum(dtup->bt_placeholder);
266  if (!dtup->bt_columns[att].bv_allnulls)
267  {
268  BrinValues *bvalues = &dtup->bt_columns[att];
269  StringInfoData s;
270  bool first;
271  int i;
272 
273  initStringInfo(&s);
274  appendStringInfoChar(&s, '{');
275 
276  first = true;
277  for (i = 0; i < columns[att]->nstored; i++)
278  {
279  char *val;
280 
281  if (!first)
282  appendStringInfoString(&s, " .. ");
283  first = false;
284  val = OutputFunctionCall(&columns[att]->outputFn[i],
285  bvalues->bv_values[i]);
287  pfree(val);
288  }
289  appendStringInfoChar(&s, '}');
290 
292  pfree(s.data);
293  }
294  else
295  {
296  nulls[6] = true;
297  }
298  }
299 
300  tuplestore_putvalues(rsinfo->setResult, rsinfo->setDesc, values, nulls);
301 
302  /*
303  * If the item was unused, jump straight to the next one; otherwise,
304  * the only cleanup needed here is to set our signal to go to the next
305  * tuple in the following iteration, by freeing the current one.
306  */
307  if (unusedItem)
308  offset = OffsetNumberNext(offset);
309  else if (attno >= bdesc->bd_tupdesc->natts)
310  {
311  pfree(dtup);
312  dtup = NULL;
313  offset = OffsetNumberNext(offset);
314  }
315 
316  /*
317  * If we're beyond the end of the page, we're done.
318  */
319  if (offset > PageGetMaxOffsetNumber(page))
320  break;
321  }
322 
323  brin_free_desc(bdesc);
324  index_close(indexRel, AccessShareLock);
325 
326  return (Datum) 0;
327 }
328 
329 Datum
331 {
332  bytea *raw_page = PG_GETARG_BYTEA_P(0);
333  Page page;
334  BrinMetaPageData *meta;
335  TupleDesc tupdesc;
336  Datum values[4];
337  bool nulls[4];
338  HeapTuple htup;
339 
340  if (!superuser())
341  ereport(ERROR,
342  (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
343  errmsg("must be superuser to use raw page functions")));
344 
345  page = verify_brin_page(raw_page, BRIN_PAGETYPE_META, "metapage");
346 
347  if (PageIsNew(page))
348  PG_RETURN_NULL();
349 
350  /* Build a tuple descriptor for our result type */
351  if (get_call_result_type(fcinfo, NULL, &tupdesc) != TYPEFUNC_COMPOSITE)
352  elog(ERROR, "return type must be a row type");
353  tupdesc = BlessTupleDesc(tupdesc);
354 
355  /* Extract values from the metapage */
356  meta = (BrinMetaPageData *) PageGetContents(page);
357  MemSet(nulls, 0, sizeof(nulls));
358  values[0] = CStringGetTextDatum(psprintf("0x%08X", meta->brinMagic));
359  values[1] = Int32GetDatum(meta->brinVersion);
360  values[2] = Int32GetDatum(meta->pagesPerRange);
361  values[3] = Int64GetDatum(meta->lastRevmapPage);
362 
363  htup = heap_form_tuple(tupdesc, values, nulls);
364 
366 }
367 
368 /*
369  * Return the TID array stored in a BRIN revmap page
370  */
371 Datum
373 {
374  struct
375  {
376  ItemPointerData *tids;
377  int idx;
378  } *state;
379  FuncCallContext *fctx;
380 
381  if (!superuser())
382  ereport(ERROR,
383  (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
384  errmsg("must be superuser to use raw page functions")));
385 
386  if (SRF_IS_FIRSTCALL())
387  {
388  bytea *raw_page = PG_GETARG_BYTEA_P(0);
389  MemoryContext mctx;
390  Page page;
391 
392  /* create a function context for cross-call persistence */
393  fctx = SRF_FIRSTCALL_INIT();
394 
395  /* switch to memory context appropriate for multiple function calls */
397 
398  /* minimally verify the page we got */
399  page = verify_brin_page(raw_page, BRIN_PAGETYPE_REVMAP, "revmap");
400 
401  if (PageIsNew(page))
402  {
403  MemoryContextSwitchTo(mctx);
404  PG_RETURN_NULL();
405  }
406 
407  state = palloc(sizeof(*state));
408  state->tids = ((RevmapContents *) PageGetContents(page))->rm_tids;
409  state->idx = 0;
410 
411  fctx->user_fctx = state;
412 
413  MemoryContextSwitchTo(mctx);
414  }
415 
416  fctx = SRF_PERCALL_SETUP();
417  state = fctx->user_fctx;
418 
419  if (state->idx < REVMAP_PAGE_MAXITEMS)
420  SRF_RETURN_NEXT(fctx, PointerGetDatum(&state->tids[state->idx++]));
421 
422  SRF_RETURN_DONE(fctx);
423 }
Datum idx(PG_FUNCTION_ARGS)
Definition: _int_op.c:259
int16 AttrNumber
Definition: attnum.h:21
static Datum values[MAXATTR]
Definition: bootstrap.c:156
void brin_free_desc(BrinDesc *bdesc)
Definition: brin.c:1237
BrinDesc * brin_build_desc(Relation rel)
Definition: brin.c:1182
#define BRIN_PAGETYPE_REVMAP
Definition: brin_page.h:52
#define BRIN_PAGETYPE_REGULAR
Definition: brin_page.h:53
#define BRIN_PAGETYPE_META
Definition: brin_page.h:51
#define BrinPageType(page)
Definition: brin_page.h:42
#define REVMAP_PAGE_MAXITEMS
Definition: brin_page.h:93
BrinMemTuple * brin_deform_tuple(BrinDesc *brdesc, BrinTuple *tuple, BrinMemTuple *dMemtuple)
Definition: brin_tuple.c:546
Datum brin_revmap_data(PG_FUNCTION_ARGS)
Definition: brinfuncs.c:372
PG_FUNCTION_INFO_V1(brin_page_type)
struct brin_column_state brin_column_state
Datum brin_metapage_info(PG_FUNCTION_ARGS)
Definition: brinfuncs.c:330
#define IS_BRIN(r)
Definition: brinfuncs.c:35
Datum brin_page_type(PG_FUNCTION_ARGS)
Definition: brinfuncs.c:48
static Page verify_brin_page(bytea *raw_page, uint16 type, const char *strtype)
Definition: brinfuncs.c:97
Datum brin_page_items(PG_FUNCTION_ARGS)
Definition: brinfuncs.c:131
Pointer Page
Definition: bufpage.h:78
#define PageGetSpecialSize(page)
Definition: bufpage.h:299
#define PageGetMaxOffsetNumber(page)
Definition: bufpage.h:356
#define PageGetItemId(page, offsetNumber)
Definition: bufpage.h:234
#define PageGetItem(page, itemId)
Definition: bufpage.h:339
#define PageIsNew(page)
Definition: bufpage.h:228
#define PageGetContents(page)
Definition: bufpage.h:245
#define CStringGetTextDatum(s)
Definition: builtins.h:85
unsigned short uint16
Definition: c.h:440
#define MAXALIGN(LEN)
Definition: c.h:757
#define offsetof(type, field)
Definition: c.h:727
#define FLEXIBLE_ARRAY_MEMBER
Definition: c.h:350
#define MemSet(start, val, len)
Definition: c.h:1008
int errdetail(const char *fmt,...)
Definition: elog.c:1037
int errcode(int sqlerrcode)
Definition: elog.c:693
int errmsg(const char *fmt,...)
Definition: elog.c:904
#define ERROR
Definition: elog.h:33
#define elog(elevel,...)
Definition: elog.h:218
#define ereport(elevel,...)
Definition: elog.h:143
TupleDesc BlessTupleDesc(TupleDesc tupdesc)
Definition: execTuples.c:2071
void fmgr_info(Oid functionId, FmgrInfo *finfo)
Definition: fmgr.c:126
Datum Int64GetDatum(int64 X)
Definition: fmgr.c:1683
char * OutputFunctionCall(FmgrInfo *flinfo, Datum val)
Definition: fmgr.c:1559
#define PG_GETARG_OID(n)
Definition: fmgr.h:275
#define PG_RETURN_NULL()
Definition: fmgr.h:345
#define PG_RETURN_TEXT_P(x)
Definition: fmgr.h:372
#define PG_RETURN_DATUM(x)
Definition: fmgr.h:353
#define PG_GETARG_BYTEA_P(n)
Definition: fmgr.h:335
#define PG_FUNCTION_ARGS
Definition: fmgr.h:193
void SetSingleFuncCall(FunctionCallInfo fcinfo, bits32 flags)
Definition: funcapi.c:76
TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:276
#define SRF_IS_FIRSTCALL()
Definition: funcapi.h:299
#define SRF_PERCALL_SETUP()
Definition: funcapi.h:303
@ TYPEFUNC_COMPOSITE
Definition: funcapi.h:149
#define HeapTupleGetDatum(tuple)
Definition: funcapi.h:220
#define SRF_RETURN_NEXT(_funcctx, _result)
Definition: funcapi.h:305
#define SRF_FIRSTCALL_INIT()
Definition: funcapi.h:301
#define SRF_RETURN_DONE(_funcctx)
Definition: funcapi.h:323
HeapTuple heap_form_tuple(TupleDesc tupleDescriptor, Datum *values, bool *isnull)
Definition: heaptuple.c:1020
void index_close(Relation relation, LOCKMODE lockmode)
Definition: indexam.c:158
Relation index_open(Oid relationId, LOCKMODE lockmode)
Definition: indexam.c:132
long val
Definition: informix.c:664
int i
Definition: isn.c:73
#define ItemIdIsUsed(itemId)
Definition: itemid.h:92
#define AccessShareLock
Definition: lockdefs.h:36
void getTypeOutputInfo(Oid type, Oid *typOutput, bool *typIsVarlena)
Definition: lsyscache.c:2864
void pfree(void *pointer)
Definition: mcxt.c:1175
void * palloc(Size size)
Definition: mcxt.c:1068
#define OffsetNumberNext(offsetNumber)
Definition: off.h:52
uint16 OffsetNumber
Definition: off.h:24
#define FirstOffsetNumber
Definition: off.h:27
Page get_page_from_raw(bytea *raw_page)
Definition: rawpage.c:215
static MemoryContext MemoryContextSwitchTo(MemoryContext context)
Definition: palloc.h:109
static void output(uint64 loop_count)
#define UInt32GetDatum(X)
Definition: postgres.h:537
uintptr_t Datum
Definition: postgres.h:411
#define BoolGetDatum(X)
Definition: postgres.h:446
#define Int32GetDatum(X)
Definition: postgres.h:523
#define UInt16GetDatum(X)
Definition: postgres.h:509
#define PointerGetDatum(X)
Definition: postgres.h:600
unsigned int Oid
Definition: postgres_ext.h:31
char * psprintf(const char *fmt,...)
Definition: psprintf.c:46
#define RelationGetDescr(relation)
Definition: rel.h:515
#define RelationGetRelationName(relation)
Definition: rel.h:523
void appendStringInfoString(StringInfo str, const char *s)
Definition: stringinfo.c:176
void appendStringInfoChar(StringInfo str, char ch)
Definition: stringinfo.c:188
void initStringInfo(StringInfo str)
Definition: stringinfo.c:59
uint32 brinVersion
Definition: brin_page.h:67
uint32 brinMagic
Definition: brin_page.h:66
BlockNumber lastRevmapPage
Definition: brin_page.h:69
BlockNumber pagesPerRange
Definition: brin_page.h:68
TypeCacheEntry * oi_typcache[FLEXIBLE_ARRAY_MEMBER]
Definition: brin_internal.h:37
uint16 oi_nstored
Definition: brin_internal.h:28
Datum * bv_values
Definition: brin_tuple.h:34
Definition: fmgr.h:57
void * user_fctx
Definition: funcapi.h:82
MemoryContext multi_call_memory_ctx
Definition: funcapi.h:101
TupleDesc setDesc
Definition: execnodes.h:317
Tuplestorestate * setResult
Definition: execnodes.h:316
FmgrInfo outputFn[FLEXIBLE_ARRAY_MEMBER]
Definition: brinfuncs.c:40
Definition: regguts.h:318
Definition: c.h:622
bool superuser(void)
Definition: superuser.c:46
#define TupleDescAttr(tupdesc, i)
Definition: tupdesc.h:92
void tuplestore_putvalues(Tuplestorestate *state, TupleDesc tdesc, Datum *values, bool *isnull)
Definition: tuplestore.c:750
text * cstring_to_text(const char *s)
Definition: varlena.c:188