/*-------------------------------------------------------------------------

 *

 * prepare.c

 *    Prepareable SQL statements via PREPARE, EXECUTE and DEALLOCATE

 *

 * This module also implements storage of prepared statements that are

 * accessed via the extended FE/BE query protocol.

 *

 *

 * Copyright (c) 2002-2025, PostgreSQL Global Development Group

 *

 * IDENTIFICATION

 *    src/backend/commands/prepare.c

 *

 *-------------------------------------------------------------------------

 */

#include "postgres.h"

#include <limits.h>

#include "access/xact.h"

#include "catalog/pg_type.h"

#include "commands/createas.h"

#include "commands/explain.h"

#include "commands/explain_format.h"

#include "commands/explain_state.h"

#include "commands/prepare.h"

#include "funcapi.h"

#include "nodes/nodeFuncs.h"

#include "parser/parse_coerce.h"

#include "parser/parse_collate.h"

#include "parser/parse_expr.h"

#include "parser/parse_type.h"

#include "tcop/pquery.h"

#include "tcop/utility.h"

#include "utils/builtins.h"

#include "utils/snapmgr.h"

#include "utils/timestamp.h"

/*

 * The hash table in which prepared queries are stored. This is

 * per-backend: query plans are not shared between backends.

 * The keys for this hash table are the arguments to PREPARE and EXECUTE

 * (statement names); the entries are PreparedStatement structs.

 */

static HTAB *prepared_queries = NULL;

static void InitQueryHashTable(void);

static ParamListInfo EvaluateParams(ParseState *pstate,

                  PreparedStatement *pstmt, List *params,

                  EState *estate);

static Datum build_regtype_array(Oid *param_types, int num_params);

/*

 * Implements the 'PREPARE' utility statement.

 */

void

PrepareQuery(ParseState *pstate, PrepareStmt *stmt,

       int stmt_location, int stmt_len)

{

  RawStmt    *rawstmt;

  CachedPlanSource *plansource;

  Oid      *argtypes = NULL;

  int     nargs;

  List     *query_list;

  /*

   * Disallow empty-string statement name (conflicts with protocol-level

   * unnamed statement).

   */

  if (!stmt->name || stmt->name[0] == '\0')

    ereport(ERROR,

        (errcode(ERRCODE_INVALID_PSTATEMENT_DEFINITION),

         errmsg("invalid statement name: must not be empty")));

  /*

   * Need to wrap the contained statement in a RawStmt node to pass it to

   * parse analysis.

   */

  rawstmt = makeNode(RawStmt);

  rawstmt->stmt = stmt->query;

  rawstmt->stmt_location = stmt_location;

  rawstmt->stmt_len = stmt_len;

  /*

   * Create the CachedPlanSource before we do parse analysis, since it needs

   * to see the unmodified raw parse tree.

   */

  plansource = CreateCachedPlan(rawstmt, pstate->p_sourcetext,

                  CreateCommandTag(stmt->query));

  /* Transform list of TypeNames to array of type OIDs */

  nargs = list_length(stmt->argtypes);

  if (nargs)

  {

    int     i;

    ListCell   *l;

    argtypes = palloc_array(Oid, nargs);

    i = 0;

    foreach(l, stmt->argtypes)

    {

      TypeName   *tn = lfirst(l);

      Oid     toid = typenameTypeId(pstate, tn);

      argtypes[i++] = toid;

    }

  }

  /*

   * Analyze the statement using these parameter types (any parameters

   * passed in from above us will not be visible to it), allowing

   * information about unknown parameters to be deduced from context.

   * Rewrite the query. The result could be 0, 1, or many queries.

   */

  query_list = pg_analyze_and_rewrite_varparams(rawstmt, pstate->p_sourcetext,

                          &argtypes, &nargs, NULL);

  /* Finish filling in the CachedPlanSource */

  CompleteCachedPlan(plansource,

             query_list,

             NULL,

             argtypes,

             nargs,

             NULL,

             NULL,

             CURSOR_OPT_PARALLEL_OK, /* allow parallel mode */

             true); /* fixed result */

  /*

   * Save the results.

   */

  StorePreparedStatement(stmt->name,

               plansource,

               true);

}

/*

 * ExecuteQuery --- implement the 'EXECUTE' utility statement.

 *

 * This code also supports CREATE TABLE ... AS EXECUTE.  That case is

 * indicated by passing a non-null intoClause.  The DestReceiver is already

 * set up correctly for CREATE TABLE AS, but we still have to make a few

 * other adjustments here.

 */

void

ExecuteQuery(ParseState *pstate,

       ExecuteStmt *stmt, IntoClause *intoClause,

       ParamListInfo params,

       DestReceiver *dest, QueryCompletion *qc)

{

  PreparedStatement *entry;

  CachedPlan *cplan;

  List     *plan_list;

  ParamListInfo paramLI = NULL;

  EState     *estate = NULL;

  Portal    portal;

  char     *query_string;

  int     eflags;

  long    count;

  /* Look it up in the hash table */

  entry = FetchPreparedStatement(stmt->name, true);

  /* Shouldn't find a non-fixed-result cached plan */

  if (!entry->plansource->fixed_result)

    elog(ERROR, "EXECUTE does not support variable-result cached plans");

  /* Evaluate parameters, if any */

  if (entry->plansource->num_params > 0)

  {

    /*

     * Need an EState to evaluate parameters; must not delete it till end

     * of query, in case parameters are pass-by-reference.  Note that the

     * passed-in "params" could possibly be referenced in the parameter

     * expressions.

     */

    estate = CreateExecutorState();

    estate->es_param_list_info = params;

    paramLI = EvaluateParams(pstate, entry, stmt->params, estate);

  }

  /* Create a new portal to run the query in */

  portal = CreateNewPortal();

  /* Don't display the portal in pg_cursors, it is for internal use only */

  portal->visible = false;

  /* Copy the plan's saved query string into the portal's memory */

  query_string = MemoryContextStrdup(portal->portalContext,

                     entry->plansource->query_string);

  /* Replan if needed, and increment plan refcount for portal */

  cplan = GetCachedPlan(entry->plansource, paramLI, NULL, NULL);

  plan_list = cplan->stmt_list;

  /*

   * DO NOT add any logic that could possibly throw an error between

   * GetCachedPlan and PortalDefineQuery, or you'll leak the plan refcount.

   */

  PortalDefineQuery(portal,

            NULL,

            query_string,

            entry->plansource->commandTag,

            plan_list,

            cplan);

  /*

   * For CREATE TABLE ... AS EXECUTE, we must verify that the prepared

   * statement is one that produces tuples.  Currently we insist that it be

   * a plain old SELECT.  In future we might consider supporting other

   * things such as INSERT ... RETURNING, but there are a couple of issues

   * to be settled first, notably how WITH NO DATA should be handled in such

   * a case (do we really want to suppress execution?) and how to pass down

   * the OID-determining eflags (PortalStart won't handle them in such a

   * case, and for that matter it's not clear the executor will either).

   *

   * For CREATE TABLE ... AS EXECUTE, we also have to ensure that the proper

   * eflags and fetch count are passed to PortalStart/PortalRun.

   */

  if (intoClause)

  {

    PlannedStmt *pstmt;

    if (list_length(plan_list) != 1)

      ereport(ERROR,

          (errcode(ERRCODE_WRONG_OBJECT_TYPE),

           errmsg("prepared statement is not a SELECT")));

    pstmt = linitial_node(PlannedStmt, plan_list);

    if (pstmt->commandType != CMD_SELECT)

      ereport(ERROR,

          (errcode(ERRCODE_WRONG_OBJECT_TYPE),

           errmsg("prepared statement is not a SELECT")));

    /* Set appropriate eflags */

    eflags = GetIntoRelEFlags(intoClause);

    /* And tell PortalRun whether to run to completion or not */

    if (intoClause->skipData)

      count = 0;

    else

      count = FETCH_ALL;

  }

  else

  {

    /* Plain old EXECUTE */

    eflags = 0;

    count = FETCH_ALL;

  }

  /*

   * Run the portal as appropriate.

   */

  PortalStart(portal, paramLI, eflags, GetActiveSnapshot());

  (void) PortalRun(portal, count, false, dest, dest, qc);

  PortalDrop(portal, false);

  if (estate)

    FreeExecutorState(estate);

  /* No need to pfree other memory, MemoryContext will be reset */

}

/*

 * EvaluateParams: evaluate a list of parameters.

 *

 * pstate: parse state

 * pstmt: statement we are getting parameters for.

 * params: list of given parameter expressions (raw parser output!)

 * estate: executor state to use.

 *

 * Returns a filled-in ParamListInfo -- this can later be passed to

 * CreateQueryDesc(), which allows the executor to make use of the parameters

 * during query execution.

 */

static ParamListInfo

EvaluateParams(ParseState *pstate, PreparedStatement *pstmt, List *params,

         EState *estate)

{

  Oid      *param_types = pstmt->plansource->param_types;

  int     num_params = pstmt->plansource->num_params;

  int     nparams = list_length(params);

  ParamListInfo paramLI;

  List     *exprstates;

  ListCell   *l;

  int     i;

  if (nparams != num_params)

    ereport(ERROR,

        (errcode(ERRCODE_SYNTAX_ERROR),

         errmsg("wrong number of parameters for prepared statement \"%s\"",

            pstmt->stmt_name),

         errdetail("Expected %d parameters but got %d.",

               num_params, nparams)));

  /* Quick exit if no parameters */

  if (num_params == 0)

    return NULL;

  /*

   * We have to run parse analysis for the expressions.  Since the parser is

   * not cool about scribbling on its input, copy first.

   */

  params = copyObject(params);

  i = 0;

  foreach(l, params)

  {

    Node     *expr = lfirst(l);

    Oid     expected_type_id = param_types[i];

    Oid     given_type_id;

    expr = transformExpr(pstate, expr, EXPR_KIND_EXECUTE_PARAMETER);

    given_type_id = exprType(expr);

    expr = coerce_to_target_type(pstate, expr, given_type_id,

                   expected_type_id, -1,

                   COERCION_ASSIGNMENT,

                   COERCE_IMPLICIT_CAST,

                   -1);

    if (expr == NULL)

      ereport(ERROR,

          (errcode(ERRCODE_DATATYPE_MISMATCH),

           errmsg("parameter $%d of type %s cannot be coerced to the expected type %s",

              i + 1,

              format_type_be(given_type_id),

              format_type_be(expected_type_id)),

           errhint("You will need to rewrite or cast the expression."),

           parser_errposition(pstate, exprLocation(lfirst(l)))));

    /* Take care of collations in the finished expression. */

    assign_expr_collations(pstate, expr);

    lfirst(l) = expr;

    i++;

  }

  /* Prepare the expressions for execution */

  exprstates = ExecPrepareExprList(params, estate);

  paramLI = makeParamList(num_params);

  i = 0;

  foreach(l, exprstates)

  {

    ExprState  *n = (ExprState *) lfirst(l);

    ParamExternData *prm = &paramLI->params[i];

    prm->ptype = param_types[i];

    prm->pflags = PARAM_FLAG_CONST;

    prm->value = ExecEvalExprSwitchContext(n,

                         GetPerTupleExprContext(estate),

                         &prm->isnull);

    i++;

  }

  return paramLI;

}

/*

 * Initialize query hash table upon first use.

 */

static void

InitQueryHashTable(void)

{

  HASHCTL   hash_ctl;

  hash_ctl.keysize = NAMEDATALEN;

  hash_ctl.entrysize = sizeof(PreparedStatement);

  prepared_queries = hash_create("Prepared Queries",

                   32,

                   &hash_ctl,

                   HASH_ELEM | HASH_STRINGS);

}

/*

 * Store all the data pertaining to a query in the hash table using

 * the specified key.  The passed CachedPlanSource should be "unsaved"

 * in case we get an error here; we'll save it once we've created the hash

 * table entry.

 */

void

StorePreparedStatement(const char *stmt_name,

             CachedPlanSource *plansource,

             bool from_sql)

{

  PreparedStatement *entry;

  TimestampTz cur_ts = GetCurrentStatementStartTimestamp();

  bool    found;

  /* Initialize the hash table, if necessary */

  if (!prepared_queries)

    InitQueryHashTable();

  /* Add entry to hash table */

  entry = (PreparedStatement *) hash_search(prepared_queries,

                        stmt_name,

                        HASH_ENTER,

                        &found);

  /* Shouldn't get a duplicate entry */

  if (found)

    ereport(ERROR,

        (errcode(ERRCODE_DUPLICATE_PSTATEMENT),

         errmsg("prepared statement \"%s\" already exists",

            stmt_name)));

  /* Fill in the hash table entry */

  entry->plansource = plansource;

  entry->from_sql = from_sql;

  entry->prepare_time = cur_ts;

  /* Now it's safe to move the CachedPlanSource to permanent memory */

  SaveCachedPlan(plansource);

}

/*

 * Lookup an existing query in the hash table. If the query does not

 * actually exist, throw ereport(ERROR) or return NULL per second parameter.

 *

 * Note: this does not force the referenced plancache entry to be valid,

 * since not all callers care.

 */

PreparedStatement *

FetchPreparedStatement(const char *stmt_name, bool throwError)

{

  PreparedStatement *entry;

  /*

   * If the hash table hasn't been initialized, it can't be storing

   * anything, therefore it couldn't possibly store our plan.

   */

  if (prepared_queries)

    entry = (PreparedStatement *) hash_search(prepared_queries,

                          stmt_name,

                          HASH_FIND,

                          NULL);

  else

    entry = NULL;

  if (!entry && throwError)

    ereport(ERROR,

        (errcode(ERRCODE_UNDEFINED_PSTATEMENT),

         errmsg("prepared statement \"%s\" does not exist",

            stmt_name)));

  return entry;

}

/*

 * Given a prepared statement, determine the result tupledesc it will

 * produce.  Returns NULL if the execution will not return tuples.

 *

 * Note: the result is created or copied into current memory context.

 */

TupleDesc

FetchPreparedStatementResultDesc(PreparedStatement *stmt)

{

  /*

   * Since we don't allow prepared statements' result tupdescs to change,

   * there's no need to worry about revalidating the cached plan here.

   */

  Assert(stmt->plansource->fixed_result);

  if (stmt->plansource->resultDesc)

    return CreateTupleDescCopy(stmt->plansource->resultDesc);

  else

    return NULL;

}

/*

 * Given a prepared statement that returns tuples, extract the query

 * targetlist.  Returns NIL if the statement doesn't have a determinable

 * targetlist.

 *

 * Note: this is pretty ugly, but since it's only used in corner cases like

 * Describe Statement on an EXECUTE command, we don't worry too much about

 * efficiency.

 */

List *

FetchPreparedStatementTargetList(PreparedStatement *stmt)

{

  List     *tlist;

  /* Get the plan's primary targetlist */

  tlist = CachedPlanGetTargetList(stmt->plansource, NULL);

  /* Copy into caller's context in case plan gets invalidated */

  return copyObject(tlist);

}

/*

 * Implements the 'DEALLOCATE' utility statement: deletes the

 * specified plan from storage.

 */

void

DeallocateQuery(DeallocateStmt *stmt)

{

  if (stmt->name)

    DropPreparedStatement(stmt->name, true);

  else

    DropAllPreparedStatements();

}

/*

 * Internal version of DEALLOCATE

 *

 * If showError is false, dropping a nonexistent statement is a no-op.

 */

void

DropPreparedStatement(const char *stmt_name, bool showError)

{

  PreparedStatement *entry;

  /* Find the query's hash table entry; raise error if wanted */

  entry = FetchPreparedStatement(stmt_name, showError);

  if (entry)

  {

    /* Release the plancache entry */

    DropCachedPlan(entry->plansource);

    /* Now we can remove the hash table entry */

    hash_search(prepared_queries, entry->stmt_name, HASH_REMOVE, NULL);

  }

}

/*

 * Drop all cached statements.

 */

void

DropAllPreparedStatements(void)

{

  HASH_SEQ_STATUS seq;

  PreparedStatement *entry;

  /* nothing cached */

  if (!prepared_queries)

    return;

  /* walk over cache */

  hash_seq_init(&seq, prepared_queries);

  while ((entry = hash_seq_search(&seq)) != NULL)

  {

    /* Release the plancache entry */

    DropCachedPlan(entry->plansource);

    /* Now we can remove the hash table entry */

    hash_search(prepared_queries, entry->stmt_name, HASH_REMOVE, NULL);

  }

}

/*

 * Implements the 'EXPLAIN EXECUTE' utility statement.

 *

 * "into" is NULL unless we are doing EXPLAIN CREATE TABLE AS EXECUTE,

 * in which case executing the query should result in creating that table.

 *

 * Note: the passed-in pstate's queryString is that of the EXPLAIN EXECUTE,

 * not the original PREPARE; we get the latter string from the plancache.

 */

void

ExplainExecuteQuery(ExecuteStmt *execstmt, IntoClause *into, ExplainState *es,

          ParseState *pstate, ParamListInfo params)

{

  PreparedStatement *entry;

  const char *query_string;

  CachedPlan *cplan;

  List     *plan_list;

  ListCell   *p;

  ParamListInfo paramLI = NULL;

  EState     *estate = NULL;

  instr_time  planstart;

  instr_time  planduration;

  BufferUsage bufusage_start,

        bufusage;

  MemoryContextCounters mem_counters;

  MemoryContext planner_ctx = NULL;

  MemoryContext saved_ctx = NULL;

  if (es->memory)

  {

    /* See ExplainOneQuery about this */

    Assert(IsA(CurrentMemoryContext, AllocSetContext));

    planner_ctx = AllocSetContextCreate(CurrentMemoryContext,

                      "explain analyze planner context",

                      ALLOCSET_DEFAULT_SIZES);

    saved_ctx = MemoryContextSwitchTo(planner_ctx);

  }

  if (es->buffers)

    bufusage_start = pgBufferUsage;

  INSTR_TIME_SET_CURRENT(planstart);

  /* Look it up in the hash table */

  entry = FetchPreparedStatement(execstmt->name, true);

  /* Shouldn't find a non-fixed-result cached plan */

  if (!entry->plansource->fixed_result)

    elog(ERROR, "EXPLAIN EXECUTE does not support variable-result cached plans");

  query_string = entry->plansource->query_string;

  /* Evaluate parameters, if any */

  if (entry->plansource->num_params)

  {

    ParseState *pstate_params;

    pstate_params = make_parsestate(NULL);

    pstate_params->p_sourcetext = pstate->p_sourcetext;

    /*

     * Need an EState to evaluate parameters; must not delete it till end

     * of query, in case parameters are pass-by-reference.  Note that the

     * passed-in "params" could possibly be referenced in the parameter

     * expressions.

     */

    estate = CreateExecutorState();

    estate->es_param_list_info = params;

    paramLI = EvaluateParams(pstate_params, entry, execstmt->params, estate);

  }

  /* Replan if needed, and acquire a transient refcount */

  cplan = GetCachedPlan(entry->plansource, paramLI,

              CurrentResourceOwner, pstate->p_queryEnv);

  INSTR_TIME_SET_CURRENT(planduration);

  INSTR_TIME_SUBTRACT(planduration, planstart);

  if (es->memory)

  {

    MemoryContextSwitchTo(saved_ctx);

    MemoryContextMemConsumed(planner_ctx, &mem_counters);

  }

  /* calc differences of buffer counters. */

  if (es->buffers)

  {

    memset(&bufusage, 0, sizeof(BufferUsage));

    BufferUsageAccumDiff(&bufusage, &pgBufferUsage, &bufusage_start);

  }

  plan_list = cplan->stmt_list;

  /* Explain each query */

  foreach(p, plan_list)

  {

    PlannedStmt *pstmt = lfirst_node(PlannedStmt, p);

    if (pstmt->commandType != CMD_UTILITY)

      ExplainOnePlan(pstmt, into, es, query_string, paramLI, pstate->p_queryEnv,

               &planduration, (es->buffers ? &bufusage : NULL),

               es->memory ? &mem_counters : NULL);

    else

      ExplainOneUtility(pstmt->utilityStmt, into, es, pstate, paramLI);

    /* No need for CommandCounterIncrement, as ExplainOnePlan did it */

    /* Separate plans with an appropriate separator */

    if (lnext(plan_list, p) != NULL)

      ExplainSeparatePlans(es);

  }

  if (estate)

    FreeExecutorState(estate);

  ReleaseCachedPlan(cplan, CurrentResourceOwner);

}

/*

 * This set returning function reads all the prepared statements and

 * returns a set of (name, statement, prepare_time, param_types, from_sql,

 * generic_plans, custom_plans).

 */

Datum

pg_prepared_statement(PG_FUNCTION_ARGS)

{

  ReturnSetInfo *rsinfo = (ReturnSetInfo *) fcinfo->resultinfo;

  /*

   * We put all the tuples into a tuplestore in one scan of the hashtable.

   * This avoids any issue of the hashtable possibly changing between calls.

   */

  InitMaterializedSRF(fcinfo, 0);

  /* hash table might be uninitialized */

  if (prepared_queries)

  {

    HASH_SEQ_STATUS hash_seq;

    PreparedStatement *prep_stmt;

    hash_seq_init(&hash_seq, prepared_queries);

    while ((prep_stmt = hash_seq_search(&hash_seq)) != NULL)

    {

      TupleDesc result_desc;

      Datum   values[8];

      bool    nulls[8] = {0};

      result_desc = prep_stmt->plansource->resultDesc;

      values[0] = CStringGetTextDatum(prep_stmt->stmt_name);

      values[1] = CStringGetTextDatum(prep_stmt->plansource->query_string);

      values[2] = TimestampTzGetDatum(prep_stmt->prepare_time);

      values[3] = build_regtype_array(prep_stmt->plansource->param_types,

                      prep_stmt->plansource->num_params);

      if (result_desc)

      {

        Oid      *result_types;

        result_types = palloc_array(Oid, result_desc->natts);

        for (int i = 0; i < result_desc->natts; i++)

          result_types[i] = TupleDescAttr(result_desc, i)->atttypid;

        values[4] = build_regtype_array(result_types, result_desc->natts);

      }

      else

      {

        /* no result descriptor (for example, DML statement) */

        nulls[4] = true;

      }

      values[5] = BoolGetDatum(prep_stmt->from_sql);

      values[6] = Int64GetDatumFast(prep_stmt->plansource->num_generic_plans);

      values[7] = Int64GetDatumFast(prep_stmt->plansource->num_custom_plans);

      tuplestore_putvalues(rsinfo->setResult, rsinfo->setDesc,

                 values, nulls);

    }

  }

  return (Datum) 0;

}

/*

 * This utility function takes a C array of Oids, and returns a Datum

 * pointing to a one-dimensional Postgres array of regtypes. An empty

 * array is returned as a zero-element array, not NULL.

 */

static Datum

build_regtype_array(Oid *param_types, int num_params)

{

  Datum    *tmp_ary;

  ArrayType  *result;

  int     i;

  tmp_ary = palloc_array(Datum, num_params);

  for (i = 0; i < num_params; i++)

    tmp_ary[i] = ObjectIdGetDatum(param_types[i]);

  result = construct_array_builtin(tmp_ary, num_params, REGTYPEOID);

  return PointerGetDatum(result);

}