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