PostgreSQL 7.2.1 Documentation
Prev |  | Next

# SPI_prepare

## Name

SPI_prepare -- Prepares a plan for a query, without executing it yet

## Synopsis

    SPI_prepare(query, nargs, argtypes)

### Inputs

`query`

  Query string

`nargs`

  Number of input parameters ($1 ... $nargs - as in SQL-functions)

`argtypes`

  Pointer to array of type OIDs for input parameter types

### Outputs

void *

  Pointer to an execution plan (parser+planner+optimizer)

## Description

`SPI_prepare` creates and returns an execution plan (parser+planner+optimizer) but doesn't execute the query. Should only be called from a connected procedure.

## Usage

When the same or similar query is to be executed repeatedly, it may be advantageous to perform query planning only once. `SPI_prepare` converts a query string into an execution plan that can be passed repeatedly to `SPI_execp`.

A prepared query can be generalized by writing parameters ($1, $2, etc) in place of what would be constants in a normal query. The values of the parameters are then specified when `SPI_execp` is called. This allows the prepared query to be used over a wider range of situations than would be possible without parameters.

> Note: However, there is a disadvantage: since the planner does not know the values that will be supplied for the parameters, it may make worse query planning choices than it would make for a simple query with all constants visible.

If the query uses parameters, their number and datatypes must be specified in the call to `SPI_prepare`.

The plan returned by `SPI_prepare` may be used only in current invocation of the procedure since `SPI_finish` frees memory allocated for a plan. But see `SPI_saveplan` to save a plan for longer.

If successful, a non-null pointer will be returned. Otherwise, you'll get a NULL plan. In both cases SPI_result will be set like the value returned by SPI_exec, except that it is set to SPI_ERROR_ARGUMENT if query is NULL or nargs < 0 or nargs > 0 && argtypes is NULL.

Prev | Home | Next
SPI_exec | Up | SPI_execp