2002-06-20 22:39:04 +02:00
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
*
|
|
|
|
* funcapi.h
|
|
|
|
* Definitions for functions which return composite type and/or sets
|
2017-10-25 13:13:11 +02:00
|
|
|
* or work on VARIADIC inputs.
|
2002-06-20 22:39:04 +02:00
|
|
|
*
|
|
|
|
* This file must be included by all Postgres modules that either define
|
|
|
|
* or call FUNCAPI-callable functions or macros.
|
|
|
|
*
|
|
|
|
*
|
2022-01-08 01:04:57 +01:00
|
|
|
* Copyright (c) 2002-2022, PostgreSQL Global Development Group
|
2002-06-20 22:39:04 +02:00
|
|
|
*
|
2010-09-20 22:08:53 +02:00
|
|
|
* src/include/funcapi.h
|
2002-06-20 22:39:04 +02:00
|
|
|
*
|
|
|
|
*-------------------------------------------------------------------------
|
|
|
|
*/
|
|
|
|
#ifndef FUNCAPI_H
|
|
|
|
#define FUNCAPI_H
|
|
|
|
|
|
|
|
#include "access/tupdesc.h"
|
|
|
|
#include "executor/executor.h"
|
|
|
|
#include "executor/tuptable.h"
|
2019-11-25 03:38:57 +01:00
|
|
|
#include "fmgr.h"
|
2002-06-20 22:39:04 +02:00
|
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
* Support to ease writing Functions returning composite types
|
|
|
|
*-------------------------------------------------------------------------
|
|
|
|
*
|
|
|
|
* This struct holds arrays of individual attribute information
|
|
|
|
* needed to create a tuple from raw C strings. It also requires
|
|
|
|
* a copy of the TupleDesc. The information carried here
|
|
|
|
* is derived from the TupleDesc, but it is stored here to
|
|
|
|
* avoid redundant cpu cycles on each call to an SRF.
|
|
|
|
*/
|
2002-08-29 02:17:06 +02:00
|
|
|
typedef struct AttInMetadata
|
2002-06-20 22:39:04 +02:00
|
|
|
{
|
|
|
|
/* full TupleDesc */
|
2002-09-04 22:31:48 +02:00
|
|
|
TupleDesc tupdesc;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2002-08-29 02:17:06 +02:00
|
|
|
/* array of attribute type input function finfo */
|
2002-09-04 22:31:48 +02:00
|
|
|
FmgrInfo *attinfuncs;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2004-06-06 02:41:28 +02:00
|
|
|
/* array of attribute type i/o parameter OIDs */
|
|
|
|
Oid *attioparams;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2002-08-29 02:17:06 +02:00
|
|
|
/* array of attribute typmod */
|
2002-09-04 22:31:48 +02:00
|
|
|
int32 *atttypmods;
|
|
|
|
} AttInMetadata;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
* Support struct to ease writing Set Returning Functions (SRFs)
|
|
|
|
*-------------------------------------------------------------------------
|
2002-09-04 22:31:48 +02:00
|
|
|
*
|
2002-06-20 22:39:04 +02:00
|
|
|
* This struct holds function context for Set Returning Functions.
|
|
|
|
* Use fn_extra to hold a pointer to it across calls
|
|
|
|
*/
|
2002-08-29 02:17:06 +02:00
|
|
|
typedef struct FuncCallContext
|
2002-06-20 22:39:04 +02:00
|
|
|
{
|
2002-07-18 06:40:30 +02:00
|
|
|
/*
|
2004-04-01 23:28:47 +02:00
|
|
|
* Number of times we've been called before
|
2002-09-04 22:31:48 +02:00
|
|
|
*
|
2002-07-18 06:40:30 +02:00
|
|
|
* call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and
|
|
|
|
* incremented for you every time SRF_RETURN_NEXT() is called.
|
|
|
|
*/
|
Widen query numbers-of-tuples-processed counters to uint64.
This patch widens SPI_processed, EState's es_processed field, PortalData's
portalPos field, FuncCallContext's call_cntr and max_calls fields,
ExecutorRun's count argument, PortalRunFetch's result, and the max number
of rows in a SPITupleTable to uint64, and deals with (I hope) all the
ensuing fallout. Some of these values were declared uint32 before, and
others "long".
I also removed PortalData's posOverflow field, since that logic seems
pretty useless given that portalPos is now always 64 bits.
The user-visible results are that command tags for SELECT etc will
correctly report tuple counts larger than 4G, as will plpgsql's GET
GET DIAGNOSTICS ... ROW_COUNT command. Queries processing more tuples
than that are still not exactly the norm, but they're becoming more
common.
Most values associated with FETCH/MOVE distances, such as PortalRun's count
argument and the count argument of most SPI functions that have one, remain
declared as "long". It's not clear whether it would be worth promoting
those to int64; but it would definitely be a large dollop of additional
API churn on top of this, and it would only help 32-bit platforms which
seem relatively less likely to see any benefit.
Andreas Scherbaum, reviewed by Christian Ullrich, additional hacking by me
2016-03-12 22:05:10 +01:00
|
|
|
uint64 call_cntr;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2002-07-18 06:40:30 +02:00
|
|
|
/*
|
|
|
|
* OPTIONAL maximum number of calls
|
|
|
|
*
|
2005-11-22 19:17:34 +01:00
|
|
|
* max_calls is here for convenience only and setting it is optional. If
|
|
|
|
* not set, you must provide alternative means to know when the function
|
|
|
|
* is done.
|
2002-07-18 06:40:30 +02:00
|
|
|
*/
|
Widen query numbers-of-tuples-processed counters to uint64.
This patch widens SPI_processed, EState's es_processed field, PortalData's
portalPos field, FuncCallContext's call_cntr and max_calls fields,
ExecutorRun's count argument, PortalRunFetch's result, and the max number
of rows in a SPITupleTable to uint64, and deals with (I hope) all the
ensuing fallout. Some of these values were declared uint32 before, and
others "long".
I also removed PortalData's posOverflow field, since that logic seems
pretty useless given that portalPos is now always 64 bits.
The user-visible results are that command tags for SELECT etc will
correctly report tuple counts larger than 4G, as will plpgsql's GET
GET DIAGNOSTICS ... ROW_COUNT command. Queries processing more tuples
than that are still not exactly the norm, but they're becoming more
common.
Most values associated with FETCH/MOVE distances, such as PortalRun's count
argument and the count argument of most SPI functions that have one, remain
declared as "long". It's not clear whether it would be worth promoting
those to int64; but it would definitely be a large dollop of additional
API churn on top of this, and it would only help 32-bit platforms which
seem relatively less likely to see any benefit.
Andreas Scherbaum, reviewed by Christian Ullrich, additional hacking by me
2016-03-12 22:05:10 +01:00
|
|
|
uint64 max_calls;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2002-07-18 06:40:30 +02:00
|
|
|
/*
|
2004-04-01 23:28:47 +02:00
|
|
|
* OPTIONAL pointer to miscellaneous user-provided context information
|
2002-09-04 22:31:48 +02:00
|
|
|
*
|
2005-11-22 19:17:34 +01:00
|
|
|
* user_fctx is for use as a pointer to your own struct to retain
|
|
|
|
* arbitrary context information between calls of your function.
|
2002-07-18 06:40:30 +02:00
|
|
|
*/
|
2002-09-04 22:31:48 +02:00
|
|
|
void *user_fctx;
|
2002-07-18 06:40:30 +02:00
|
|
|
|
|
|
|
/*
|
2004-04-01 23:28:47 +02:00
|
|
|
* OPTIONAL pointer to struct containing attribute type input metadata
|
2002-09-04 22:31:48 +02:00
|
|
|
*
|
2005-11-22 19:17:34 +01:00
|
|
|
* attinmeta is for use when returning tuples (i.e. composite data types)
|
|
|
|
* and is not used when returning base data types. It is only needed if
|
|
|
|
* you intend to use BuildTupleFromCStrings() to create the return tuple.
|
2002-07-18 06:40:30 +02:00
|
|
|
*/
|
2002-09-04 22:31:48 +02:00
|
|
|
AttInMetadata *attinmeta;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2002-07-18 06:40:30 +02:00
|
|
|
/*
|
2005-10-15 04:49:52 +02:00
|
|
|
* memory context used for structures that must live for multiple calls
|
2002-07-18 06:40:30 +02:00
|
|
|
*
|
2005-11-22 19:17:34 +01:00
|
|
|
* multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
|
|
|
|
* by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
|
2005-10-15 04:49:52 +02:00
|
|
|
* context for any memory that is to be reused across multiple calls of
|
|
|
|
* the SRF.
|
2002-07-18 06:40:30 +02:00
|
|
|
*/
|
2002-09-04 22:31:48 +02:00
|
|
|
MemoryContext multi_call_memory_ctx;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2004-04-01 23:28:47 +02:00
|
|
|
/*
|
|
|
|
* OPTIONAL pointer to struct containing tuple description
|
|
|
|
*
|
2005-10-15 04:49:52 +02:00
|
|
|
* tuple_desc is for use when returning tuples (i.e. composite data types)
|
|
|
|
* and is only needed if you are going to build the tuples with
|
2009-06-11 16:49:15 +02:00
|
|
|
* heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that
|
2005-10-15 04:49:52 +02:00
|
|
|
* the TupleDesc pointer stored here should usually have been run through
|
|
|
|
* BlessTupleDesc() first.
|
2004-04-01 23:28:47 +02:00
|
|
|
*/
|
2004-08-29 07:07:03 +02:00
|
|
|
TupleDesc tuple_desc;
|
2004-04-01 23:28:47 +02:00
|
|
|
|
2002-09-04 22:31:48 +02:00
|
|
|
} FuncCallContext;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2002-08-29 02:17:06 +02:00
|
|
|
/*----------
|
2005-04-01 00:46:33 +02:00
|
|
|
* Support to ease writing functions returning composite types
|
|
|
|
*
|
|
|
|
* External declarations:
|
|
|
|
* get_call_result_type:
|
2005-10-15 04:49:52 +02:00
|
|
|
* Given a function's call info record, determine the kind of datatype
|
|
|
|
* it is supposed to return. If resultTypeId isn't NULL, *resultTypeId
|
|
|
|
* receives the actual datatype OID (this is mainly useful for scalar
|
2014-05-06 18:12:18 +02:00
|
|
|
* result types). If resultTupleDesc isn't NULL, *resultTupleDesc
|
2005-10-15 04:49:52 +02:00
|
|
|
* receives a pointer to a TupleDesc when the result is of a composite
|
|
|
|
* type, or NULL when it's a scalar result or the rowtype could not be
|
|
|
|
* determined. NB: the tupledesc should be copied if it is to be
|
|
|
|
* accessed over a long period.
|
2005-04-01 00:46:33 +02:00
|
|
|
* get_expr_result_type:
|
2005-10-15 04:49:52 +02:00
|
|
|
* Given an expression node, return the same info as for
|
|
|
|
* get_call_result_type. Note: the cases in which rowtypes cannot be
|
|
|
|
* determined are different from the cases for get_call_result_type.
|
2005-04-01 00:46:33 +02:00
|
|
|
* get_func_result_type:
|
2005-10-15 04:49:52 +02:00
|
|
|
* Given only a function's OID, return the same info as for
|
|
|
|
* get_call_result_type. Note: the cases in which rowtypes cannot be
|
|
|
|
* determined are different from the cases for get_call_result_type.
|
|
|
|
* Do *not* use this if you can use one of the others.
|
2017-10-26 19:47:45 +02:00
|
|
|
*
|
|
|
|
* See also get_expr_result_tupdesc(), which is a convenient wrapper around
|
|
|
|
* get_expr_result_type() for use when the caller only cares about
|
|
|
|
* determinable-rowtype cases.
|
2005-04-01 00:46:33 +02:00
|
|
|
*----------
|
|
|
|
*/
|
|
|
|
|
|
|
|
/* Type categories for get_call_result_type and siblings */
|
|
|
|
typedef enum TypeFuncClass
|
|
|
|
{
|
|
|
|
TYPEFUNC_SCALAR, /* scalar result type */
|
|
|
|
TYPEFUNC_COMPOSITE, /* determinable rowtype result */
|
2017-10-26 19:47:45 +02:00
|
|
|
TYPEFUNC_COMPOSITE_DOMAIN, /* domain over determinable rowtype result */
|
2005-04-01 00:46:33 +02:00
|
|
|
TYPEFUNC_RECORD, /* indeterminate rowtype result */
|
|
|
|
TYPEFUNC_OTHER /* bogus type, eg pseudotype */
|
|
|
|
} TypeFuncClass;
|
|
|
|
|
|
|
|
extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
|
2019-05-22 19:04:48 +02:00
|
|
|
Oid *resultTypeId,
|
|
|
|
TupleDesc *resultTupleDesc);
|
2005-04-01 00:46:33 +02:00
|
|
|
extern TypeFuncClass get_expr_result_type(Node *expr,
|
2019-05-22 19:04:48 +02:00
|
|
|
Oid *resultTypeId,
|
|
|
|
TupleDesc *resultTupleDesc);
|
2005-04-01 00:46:33 +02:00
|
|
|
extern TypeFuncClass get_func_result_type(Oid functionId,
|
2019-05-22 19:04:48 +02:00
|
|
|
Oid *resultTypeId,
|
|
|
|
TupleDesc *resultTupleDesc);
|
2005-04-01 00:46:33 +02:00
|
|
|
|
2017-10-26 19:47:45 +02:00
|
|
|
extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError);
|
|
|
|
|
2005-04-05 08:22:17 +02:00
|
|
|
extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
|
2019-05-22 19:04:48 +02:00
|
|
|
char *argmodes,
|
|
|
|
Node *call_expr);
|
2005-04-05 08:22:17 +02:00
|
|
|
|
2019-05-22 19:04:48 +02:00
|
|
|
extern int get_func_arg_info(HeapTuple procTup,
|
|
|
|
Oid **p_argtypes, char ***p_argnames,
|
|
|
|
char **p_argmodes);
|
2005-12-28 19:11:25 +01:00
|
|
|
|
Reconsider the handling of procedure OUT parameters.
Commit 2453ea142 redefined pg_proc.proargtypes to include the types of
OUT parameters, for procedures only. While that had some advantages
for implementing the SQL-spec behavior of DROP PROCEDURE, it was pretty
disastrous from a number of other perspectives. Notably, since the
primary key of pg_proc is name + proargtypes, this made it possible to
have multiple procedures with identical names + input arguments and
differing output argument types. That would make it impossible to call
any one of the procedures by writing just NULL (or "?", or any other
data-type-free notation) for the output argument(s). The change also
seems likely to cause grave confusion for client applications that
examine pg_proc and expect the traditional definition of proargtypes.
Hence, revert the definition of proargtypes to what it was, and
undo a number of complications that had been added to support that.
To support the SQL-spec behavior of DROP PROCEDURE, when there are
no argmode markers in the command's parameter list, we perform the
lookup both ways (that is, matching against both proargtypes and
proallargtypes), succeeding if we get just one unique match.
In principle this could result in ambiguous-function failures
that would not happen when using only one of the two rules.
However, overloading of procedure names is thought to be a pretty
rare usage, so this shouldn't cause many problems in practice.
Postgres-specific code such as pg_dump can defend against any
possibility of such failures by being careful to specify argmodes
for all procedure arguments.
This also fixes a few other bugs in the area of CALL statements
with named parameters, and improves the documentation a little.
catversion bump forced because the representation of procedures
with OUT arguments changes.
Discussion: https://postgr.es/m/3742981.1621533210@sss.pgh.pa.us
2021-06-10 23:11:36 +02:00
|
|
|
extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes,
|
2019-05-22 19:04:48 +02:00
|
|
|
char ***arg_names);
|
2009-10-08 04:39:25 +02:00
|
|
|
|
2015-05-24 03:35:49 +02:00
|
|
|
extern int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes);
|
2005-12-28 19:11:25 +01:00
|
|
|
extern char *get_func_result_name(Oid functionId);
|
|
|
|
|
2018-03-14 16:47:21 +01:00
|
|
|
extern TupleDesc build_function_result_tupdesc_d(char prokind,
|
2019-05-22 19:04:48 +02:00
|
|
|
Datum proallargtypes,
|
|
|
|
Datum proargmodes,
|
|
|
|
Datum proargnames);
|
2005-04-01 00:46:33 +02:00
|
|
|
extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple);
|
|
|
|
|
|
|
|
|
|
|
|
/*----------
|
|
|
|
* Support to ease writing functions returning composite types
|
2002-06-20 22:39:04 +02:00
|
|
|
*
|
|
|
|
* External declarations:
|
2004-04-01 23:28:47 +02:00
|
|
|
* TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple
|
|
|
|
* descriptor so that it can be used to return properly labeled tuples.
|
2008-11-02 02:45:28 +01:00
|
|
|
* You need to call this if you are going to use heap_form_tuple directly.
|
2004-04-01 23:28:47 +02:00
|
|
|
* TupleDescGetAttInMetadata does it for you, however, so no need to call
|
|
|
|
* it if you call TupleDescGetAttInMetadata.
|
2002-08-29 02:17:06 +02:00
|
|
|
* AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an
|
|
|
|
* AttInMetadata struct based on the given TupleDesc. AttInMetadata can
|
2002-06-20 22:39:04 +02:00
|
|
|
* be used in conjunction with C strings to produce a properly formed
|
2004-04-01 23:28:47 +02:00
|
|
|
* tuple.
|
2002-06-20 22:39:04 +02:00
|
|
|
* HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
|
|
|
|
* build a HeapTuple given user data in C string form. values is an array
|
|
|
|
* of C strings, one for each attribute of the return tuple.
|
Fix failure to detoast fields in composite elements of structured types.
If we have an array of records stored on disk, the individual record fields
cannot contain out-of-line TOAST pointers: the tuptoaster.c mechanisms are
only prepared to deal with TOAST pointers appearing in top-level fields of
a stored row. The same applies for ranges over composite types, nested
composites, etc. However, the existing code only took care of expanding
sub-field TOAST pointers for the case of nested composites, not for other
structured types containing composites. For example, given a command such
as
UPDATE tab SET arraycol = ARRAY[(ROW(x,42)::mycompositetype] ...
where x is a direct reference to a field of an on-disk tuple, if that field
is long enough to be toasted out-of-line then the TOAST pointer would be
inserted as-is into the array column. If the source record for x is later
deleted, the array field value would become a dangling pointer, leading
to errors along the line of "missing chunk number 0 for toast value ..."
when the value is referenced. A reproducible test case for this was
provided by Jan Pecek, but it seems likely that some of the "missing chunk
number" reports we've heard in the past were caused by similar issues.
Code-wise, the problem is that PG_DETOAST_DATUM() is not adequate to
produce a self-contained Datum value if the Datum is of composite type.
Seen in this light, the problem is not just confined to arrays and ranges,
but could also affect some other places where detoasting is done in that
way, for example form_index_tuple().
I tried teaching the array code to apply toast_flatten_tuple_attribute()
along with PG_DETOAST_DATUM() when the array element type is composite,
but this was messy and imposed extra cache lookup costs whether or not any
TOAST pointers were present, indeed sometimes when the array element type
isn't even composite (since sometimes it takes a typcache lookup to find
that out). The idea of extending that approach to all the places that
currently use PG_DETOAST_DATUM() wasn't attractive at all.
This patch instead solves the problem by decreeing that composite Datum
values must not contain any out-of-line TOAST pointers in the first place;
that is, we expand out-of-line fields at the point of constructing a
composite Datum, not at the point where we're about to insert it into a
larger tuple. This rule is applied only to true composite Datums, not
to tuples that are being passed around the system as tuples, so it's not
as invasive as it might sound at first. With this approach, the amount
of code that has to be touched for a full solution is greatly reduced,
and added cache lookup costs are avoided except when there actually is
a TOAST pointer that needs to be inlined.
The main drawback of this approach is that we might sometimes dereference
a TOAST pointer that will never actually be used by the query, imposing a
rather large cost that wasn't there before. On the other side of the coin,
if the field value is used multiple times then we'll come out ahead by
avoiding repeat detoastings. Experimentation suggests that common SQL
coding patterns are unaffected either way, though. Applications that are
very negatively affected could be advised to modify their code to not fetch
columns they won't be using.
In future, we might consider reverting this solution in favor of detoasting
only at the point where data is about to be stored to disk, using some
method that can drill down into multiple levels of nested structured types.
That will require defining new APIs for structured types, though, so it
doesn't seem feasible as a back-patchable fix.
Note that this patch changes HeapTupleGetDatum() from a macro to a function
call; this means that any third-party code using that macro will not get
protection against creating TOAST-pointer-containing Datums until it's
recompiled. The same applies to any uses of PG_RETURN_HEAPTUPLEHEADER().
It seems likely that this is not a big problem in practice: most of the
tuple-returning functions in core and contrib produce outputs that could
not possibly be toasted anyway, and the same probably holds for third-party
extensions.
This bug has existed since TOAST was invented, so back-patch to all
supported branches.
2014-05-01 21:19:06 +02:00
|
|
|
* Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - convert a
|
|
|
|
* HeapTupleHeader to a Datum.
|
2002-06-20 22:39:04 +02:00
|
|
|
*
|
2022-09-27 20:47:07 +02:00
|
|
|
* Inline declarations:
|
2004-04-01 23:28:47 +02:00
|
|
|
* HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum.
|
|
|
|
*
|
|
|
|
* Obsolete routines and macros:
|
2005-05-31 01:09:07 +02:00
|
|
|
* TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a
|
|
|
|
* TupleDesc based on a named relation.
|
|
|
|
* TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
|
|
|
|
* TupleDesc based on a type OID.
|
2002-06-20 22:39:04 +02:00
|
|
|
* TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
|
|
|
|
* given a tuple and a slot.
|
2002-08-29 02:17:06 +02:00
|
|
|
*----------
|
2002-06-20 22:39:04 +02:00
|
|
|
*/
|
|
|
|
|
2002-08-29 02:17:06 +02:00
|
|
|
extern TupleDesc RelationNameGetTupleDesc(const char *relname);
|
2002-06-20 22:39:04 +02:00
|
|
|
extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
|
|
|
|
|
|
|
|
/* from execTuples.c */
|
2004-04-01 23:28:47 +02:00
|
|
|
extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);
|
2002-06-20 22:39:04 +02:00
|
|
|
extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc);
|
|
|
|
extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
|
Fix failure to detoast fields in composite elements of structured types.
If we have an array of records stored on disk, the individual record fields
cannot contain out-of-line TOAST pointers: the tuptoaster.c mechanisms are
only prepared to deal with TOAST pointers appearing in top-level fields of
a stored row. The same applies for ranges over composite types, nested
composites, etc. However, the existing code only took care of expanding
sub-field TOAST pointers for the case of nested composites, not for other
structured types containing composites. For example, given a command such
as
UPDATE tab SET arraycol = ARRAY[(ROW(x,42)::mycompositetype] ...
where x is a direct reference to a field of an on-disk tuple, if that field
is long enough to be toasted out-of-line then the TOAST pointer would be
inserted as-is into the array column. If the source record for x is later
deleted, the array field value would become a dangling pointer, leading
to errors along the line of "missing chunk number 0 for toast value ..."
when the value is referenced. A reproducible test case for this was
provided by Jan Pecek, but it seems likely that some of the "missing chunk
number" reports we've heard in the past were caused by similar issues.
Code-wise, the problem is that PG_DETOAST_DATUM() is not adequate to
produce a self-contained Datum value if the Datum is of composite type.
Seen in this light, the problem is not just confined to arrays and ranges,
but could also affect some other places where detoasting is done in that
way, for example form_index_tuple().
I tried teaching the array code to apply toast_flatten_tuple_attribute()
along with PG_DETOAST_DATUM() when the array element type is composite,
but this was messy and imposed extra cache lookup costs whether or not any
TOAST pointers were present, indeed sometimes when the array element type
isn't even composite (since sometimes it takes a typcache lookup to find
that out). The idea of extending that approach to all the places that
currently use PG_DETOAST_DATUM() wasn't attractive at all.
This patch instead solves the problem by decreeing that composite Datum
values must not contain any out-of-line TOAST pointers in the first place;
that is, we expand out-of-line fields at the point of constructing a
composite Datum, not at the point where we're about to insert it into a
larger tuple. This rule is applied only to true composite Datums, not
to tuples that are being passed around the system as tuples, so it's not
as invasive as it might sound at first. With this approach, the amount
of code that has to be touched for a full solution is greatly reduced,
and added cache lookup costs are avoided except when there actually is
a TOAST pointer that needs to be inlined.
The main drawback of this approach is that we might sometimes dereference
a TOAST pointer that will never actually be used by the query, imposing a
rather large cost that wasn't there before. On the other side of the coin,
if the field value is used multiple times then we'll come out ahead by
avoiding repeat detoastings. Experimentation suggests that common SQL
coding patterns are unaffected either way, though. Applications that are
very negatively affected could be advised to modify their code to not fetch
columns they won't be using.
In future, we might consider reverting this solution in favor of detoasting
only at the point where data is about to be stored to disk, using some
method that can drill down into multiple levels of nested structured types.
That will require defining new APIs for structured types, though, so it
doesn't seem feasible as a back-patchable fix.
Note that this patch changes HeapTupleGetDatum() from a macro to a function
call; this means that any third-party code using that macro will not get
protection against creating TOAST-pointer-containing Datums until it's
recompiled. The same applies to any uses of PG_RETURN_HEAPTUPLEHEADER().
It seems likely that this is not a big problem in practice: most of the
tuple-returning functions in core and contrib produce outputs that could
not possibly be toasted anyway, and the same probably holds for third-party
extensions.
This bug has existed since TOAST was invented, so back-patch to all
supported branches.
2014-05-01 21:19:06 +02:00
|
|
|
extern Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple);
|
2002-06-20 22:39:04 +02:00
|
|
|
|
2022-09-27 20:47:07 +02:00
|
|
|
static inline Datum
|
|
|
|
HeapTupleGetDatum(const HeapTupleData *tuple)
|
|
|
|
{
|
|
|
|
return HeapTupleHeaderGetDatum(tuple->t_data);
|
|
|
|
}
|
|
|
|
/* obsolete version of above */
|
|
|
|
#define TupleGetDatum(_slot, _tuple) HeapTupleGetDatum(_tuple)
|
|
|
|
|
2002-08-29 02:17:06 +02:00
|
|
|
|
|
|
|
/*----------
|
2002-06-20 22:39:04 +02:00
|
|
|
* Support for Set Returning Functions (SRFs)
|
|
|
|
*
|
2020-03-17 02:05:28 +01:00
|
|
|
* The basic API for SRFs using ValuePerCall mode looks something like this:
|
2002-06-20 22:39:04 +02:00
|
|
|
*
|
|
|
|
* Datum
|
|
|
|
* my_Set_Returning_Function(PG_FUNCTION_ARGS)
|
|
|
|
* {
|
2002-09-04 22:31:48 +02:00
|
|
|
* FuncCallContext *funcctx;
|
|
|
|
* Datum result;
|
|
|
|
* MemoryContext oldcontext;
|
|
|
|
* <user defined declarations>
|
|
|
|
*
|
|
|
|
* if (SRF_IS_FIRSTCALL())
|
|
|
|
* {
|
|
|
|
* funcctx = SRF_FIRSTCALL_INIT();
|
2002-08-29 19:14:33 +02:00
|
|
|
* // switch context when allocating stuff to be used in later calls
|
|
|
|
* oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
|
2002-09-04 22:31:48 +02:00
|
|
|
* <user defined code>
|
|
|
|
* <if returning composite>
|
2019-07-01 03:00:23 +02:00
|
|
|
* <build TupleDesc, and perhaps AttInMetadata>
|
2002-09-04 22:31:48 +02:00
|
|
|
* <endif returning composite>
|
|
|
|
* <user defined code>
|
2002-08-29 19:14:33 +02:00
|
|
|
* // return to original context when allocating transient memory
|
|
|
|
* MemoryContextSwitchTo(oldcontext);
|
2002-09-04 22:31:48 +02:00
|
|
|
* }
|
|
|
|
* <user defined code>
|
|
|
|
* funcctx = SRF_PERCALL_SETUP();
|
|
|
|
* <user defined code>
|
|
|
|
*
|
|
|
|
* if (funcctx->call_cntr < funcctx->max_calls)
|
|
|
|
* {
|
|
|
|
* <user defined code>
|
|
|
|
* <obtain result Datum>
|
|
|
|
* SRF_RETURN_NEXT(funcctx, result);
|
|
|
|
* }
|
|
|
|
* else
|
|
|
|
* SRF_RETURN_DONE(funcctx);
|
2002-06-20 22:39:04 +02:00
|
|
|
* }
|
|
|
|
*
|
2020-03-17 02:05:28 +01:00
|
|
|
* NOTE: there is no guarantee that a SRF using ValuePerCall mode will be
|
|
|
|
* run to completion; for example, a query with LIMIT might stop short of
|
|
|
|
* fetching all the rows. Therefore, do not expect that you can do resource
|
|
|
|
* cleanup just before SRF_RETURN_DONE(). You need not worry about releasing
|
|
|
|
* memory allocated in multi_call_memory_ctx, but holding file descriptors or
|
|
|
|
* other non-memory resources open across calls is a bug. SRFs that need
|
|
|
|
* such resources should not use these macros, but instead populate a
|
Create routine able to set single-call SRFs for Materialize mode
Set-returning functions that use the Materialize mode, creating a
tuplestore to include all the tuples returned in a set rather than doing
so in multiple calls, use roughly the same set of steps to prepare
ReturnSetInfo for this job:
- Check if ReturnSetInfo supports returning a tuplestore and if the
materialize mode is enabled.
- Create a tuplestore for all the tuples part of the returned set in the
per-query memory context, stored in ReturnSetInfo->setResult.
- Build a tuple descriptor mostly from get_call_result_type(), then
stored in ReturnSetInfo->setDesc. Note that there are some cases where
the SRF's tuple descriptor has to be the one specified by the function
caller.
This refactoring is done so as there are (well, should be) no behavior
changes in any of the in-core functions refactored, and the centralized
function that checks and sets up the function's ReturnSetInfo can be
controlled with a set of bits32 options. Two of them prove to be
necessary now:
- SRF_SINGLE_USE_EXPECTED to use expectedDesc as tuple descriptor, as
expected by the function's caller.
- SRF_SINGLE_BLESS to validate the tuple descriptor for the SRF.
The same initialization pattern is simplified in 28 places per my
count as of src/backend/, shaving up to ~900 lines of code. These
mostly come from the removal of the per-query initializations and the
sanity checks now grouped in a single location. There are more
locations that could be simplified in contrib/, that are left for a
follow-up cleanup.
fcc2817, 07daca5 and d61a361 have prepared the areas of the code related
to this change, to ease this refactoring.
Author: Melanie Plageman, Michael Paquier
Reviewed-by: Álvaro Herrera, Justin Pryzby
Discussion: https://postgr.es/m/CAAKRu_azyd1Z3W_r7Ou4sorTjRCs+PxeHw1CWJeXKofkE6TuZg@mail.gmail.com
2022-03-07 02:26:29 +01:00
|
|
|
* tuplestore during a single call, as set up by SetSingleFuncCall() (see
|
|
|
|
* fmgr/README). Alternatively, set up a callback to release resources
|
|
|
|
* at query shutdown, using RegisterExprContextCallback().
|
2020-03-17 02:05:28 +01:00
|
|
|
*
|
2002-08-29 02:17:06 +02:00
|
|
|
*----------
|
2002-06-20 22:39:04 +02:00
|
|
|
*/
|
|
|
|
|
|
|
|
/* from funcapi.c */
|
Create routine able to set single-call SRFs for Materialize mode
Set-returning functions that use the Materialize mode, creating a
tuplestore to include all the tuples returned in a set rather than doing
so in multiple calls, use roughly the same set of steps to prepare
ReturnSetInfo for this job:
- Check if ReturnSetInfo supports returning a tuplestore and if the
materialize mode is enabled.
- Create a tuplestore for all the tuples part of the returned set in the
per-query memory context, stored in ReturnSetInfo->setResult.
- Build a tuple descriptor mostly from get_call_result_type(), then
stored in ReturnSetInfo->setDesc. Note that there are some cases where
the SRF's tuple descriptor has to be the one specified by the function
caller.
This refactoring is done so as there are (well, should be) no behavior
changes in any of the in-core functions refactored, and the centralized
function that checks and sets up the function's ReturnSetInfo can be
controlled with a set of bits32 options. Two of them prove to be
necessary now:
- SRF_SINGLE_USE_EXPECTED to use expectedDesc as tuple descriptor, as
expected by the function's caller.
- SRF_SINGLE_BLESS to validate the tuple descriptor for the SRF.
The same initialization pattern is simplified in 28 places per my
count as of src/backend/, shaving up to ~900 lines of code. These
mostly come from the removal of the per-query initializations and the
sanity checks now grouped in a single location. There are more
locations that could be simplified in contrib/, that are left for a
follow-up cleanup.
fcc2817, 07daca5 and d61a361 have prepared the areas of the code related
to this change, to ease this refactoring.
Author: Melanie Plageman, Michael Paquier
Reviewed-by: Álvaro Herrera, Justin Pryzby
Discussion: https://postgr.es/m/CAAKRu_azyd1Z3W_r7Ou4sorTjRCs+PxeHw1CWJeXKofkE6TuZg@mail.gmail.com
2022-03-07 02:26:29 +01:00
|
|
|
|
|
|
|
/* flag bits for SetSingleFuncCall() */
|
|
|
|
#define SRF_SINGLE_USE_EXPECTED 0x01 /* use expectedDesc as tupdesc */
|
|
|
|
#define SRF_SINGLE_BLESS 0x02 /* validate tuple for SRF */
|
|
|
|
extern void SetSingleFuncCall(FunctionCallInfo fcinfo, bits32 flags);
|
|
|
|
|
2002-06-20 22:39:04 +02:00
|
|
|
extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS);
|
2002-07-18 06:40:30 +02:00
|
|
|
extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS);
|
2002-06-20 22:39:04 +02:00
|
|
|
extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
|
|
|
|
|
2002-07-18 06:40:30 +02:00
|
|
|
#define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
|
2002-08-29 02:17:06 +02:00
|
|
|
|
2002-06-20 22:39:04 +02:00
|
|
|
#define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
|
2002-08-29 02:17:06 +02:00
|
|
|
|
2002-07-18 06:40:30 +02:00
|
|
|
#define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
|
2002-08-29 02:17:06 +02:00
|
|
|
|
2002-06-20 22:39:04 +02:00
|
|
|
#define SRF_RETURN_NEXT(_funcctx, _result) \
|
|
|
|
do { \
|
|
|
|
ReturnSetInfo *rsi; \
|
2002-08-29 02:17:06 +02:00
|
|
|
(_funcctx)->call_cntr++; \
|
2002-06-20 22:39:04 +02:00
|
|
|
rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
|
|
|
|
rsi->isDone = ExprMultipleResult; \
|
|
|
|
PG_RETURN_DATUM(_result); \
|
|
|
|
} while (0)
|
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
#define SRF_RETURN_NEXT_NULL(_funcctx) \
|
|
|
|
do { \
|
|
|
|
ReturnSetInfo *rsi; \
|
|
|
|
(_funcctx)->call_cntr++; \
|
|
|
|
rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
|
|
|
|
rsi->isDone = ExprMultipleResult; \
|
|
|
|
PG_RETURN_NULL(); \
|
|
|
|
} while (0)
|
|
|
|
|
2002-06-20 22:39:04 +02:00
|
|
|
#define SRF_RETURN_DONE(_funcctx) \
|
|
|
|
do { \
|
|
|
|
ReturnSetInfo *rsi; \
|
|
|
|
end_MultiFuncCall(fcinfo, _funcctx); \
|
|
|
|
rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
|
|
|
|
rsi->isDone = ExprEndResult; \
|
|
|
|
PG_RETURN_NULL(); \
|
|
|
|
} while (0)
|
|
|
|
|
2017-10-25 13:13:11 +02:00
|
|
|
/*----------
|
|
|
|
* Support to ease writing of functions dealing with VARIADIC inputs
|
|
|
|
*----------
|
|
|
|
*
|
|
|
|
* This function extracts a set of argument values, types and NULL markers
|
|
|
|
* for a given input function. This returns a set of data:
|
|
|
|
* - **values includes the set of Datum values extracted.
|
|
|
|
* - **types the data type OID for each element.
|
|
|
|
* - **nulls tracks if an element is NULL.
|
|
|
|
*
|
|
|
|
* variadic_start indicates the argument number where the VARIADIC argument
|
|
|
|
* starts.
|
|
|
|
* convert_unknown set to true will enforce the conversion of arguments
|
|
|
|
* with unknown data type to text.
|
|
|
|
*
|
|
|
|
* The return result is the number of elements stored, or -1 in the case of
|
|
|
|
* "VARIADIC NULL".
|
|
|
|
*/
|
2019-05-22 19:04:48 +02:00
|
|
|
extern int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start,
|
2022-09-20 22:09:30 +02:00
|
|
|
bool convert_unknown, Datum **args,
|
2019-05-22 19:04:48 +02:00
|
|
|
Oid **types, bool **nulls);
|
2017-10-25 13:13:11 +02:00
|
|
|
|
Phase 2 of pgindent updates.
Change pg_bsd_indent to follow upstream rules for placement of comments
to the right of code, and remove pgindent hack that caused comments
following #endif to not obey the general rule.
Commit e3860ffa4dd0dad0dd9eea4be9cc1412373a8c89 wasn't actually using
the published version of pg_bsd_indent, but a hacked-up version that
tried to minimize the amount of movement of comments to the right of
code. The situation of interest is where such a comment has to be
moved to the right of its default placement at column 33 because there's
code there. BSD indent has always moved right in units of tab stops
in such cases --- but in the previous incarnation, indent was working
in 8-space tab stops, while now it knows we use 4-space tabs. So the
net result is that in about half the cases, such comments are placed
one tab stop left of before. This is better all around: it leaves
more room on the line for comment text, and it means that in such
cases the comment uniformly starts at the next 4-space tab stop after
the code, rather than sometimes one and sometimes two tabs after.
Also, ensure that comments following #endif are indented the same
as comments following other preprocessor commands such as #else.
That inconsistency turns out to have been self-inflicted damage
from a poorly-thought-through post-indent "fixup" in pgindent.
This patch is much less interesting than the first round of indent
changes, but also bulkier, so I thought it best to separate the effects.
Discussion: https://postgr.es/m/E1dAmxK-0006EE-1r@gemulon.postgresql.org
Discussion: https://postgr.es/m/30527.1495162840@sss.pgh.pa.us
2017-06-21 21:18:54 +02:00
|
|
|
#endif /* FUNCAPI_H */
|