Descripción

SPI_prepare crea y devuelve una sentencia preparada para el comando especificado, pero no la ejecuta. La sentencia preparada se puede ejecutar repetidamente más adelante usando SPI_execute_plan.

Cuando se va a ejecutar un mismo comando o uno similar de forma repetida, generalmente resulta ventajoso realizar el análisis sintáctico una sola vez, y además puede ser beneficioso reutilizar un plan de ejecución para el comando. SPI_prepare convierte una cadena de comando en una sentencia preparada que encapsula los resultados del análisis sintáctico. La sentencia preparada también proporciona un lugar para almacenar en caché un plan de ejecución si se determina que generar un plan personalizado para cada ejecución no resulta útil.

Un comando preparado se puede generalizar escribiendo parámetros ($1, $2, etc.) en lugar de lo que serían constantes en un comando normal. Los valores reales de los parámetros se especifican luego cuando se llama a SPI_execute_plan. Esto permite que el comando preparado se utilice en una gama más amplia de situaciones de lo que sería posible sin parámetros.

La sentencia devuelta por SPI_prepare solo se puede utilizar en la invocación actual de la función en C, ya que SPI_finish libera la memoria asignada para dicha sentencia. Sin embargo, la sentencia se puede guardar por más tiempo utilizando las funciones SPI_keepplan o SPI_saveplan.

Argumentos

Valor de retorno

SPI_prepare devuelve un puntero no nulo a un SPIPlan, que es una estructura opaca que representa una sentencia preparada. En caso de error, se devolverá NULL y SPI_result se establecerá en uno de los mismos códigos de error utilizados por SPI_execute, excepto que se establece en SPI_ERROR_ARGUMENT si command es NULL, o si nargs es menor que 0, o si nargs es mayor que 0 y argtypes es NULL.

Notas

Si no se definen parámetros, se creará un plan genérico en el primer uso de SPI_execute_plan, y se utilizará también para todas las ejecuciones posteriores. Si hay parámetros, los primeros usos de SPI_execute_plan generarán planes personalizados que son específicos para los valores de los parámetros personalizados. Después de suficientes usos de la misma sentencia preparada, SPI_execute_plan construirá un plan genérico, y si este no es mucho más costoso que los planes personalizados, comenzará a usar el plan genérico en lugar de volver a planificar cada vez. Si este comportamiento por defecto no es adecuado, puede alterarlo pasando la bandera CURSOR_OPT_GENERIC_PLAN o CURSOR_OPT_CUSTOM_PLAN a SPI_prepare_cursor, para forzar el uso de planes genéricos o personalizados, respectivamente.

Aunque el propósito principal de una sentencia preparada es evitar el análisis sintáctico y la planificación repetidos de la sentencia, PostgreSQL forzará el reanálisis y la replanificación de la sentencia antes de usarla siempre que los objetos de la base de datos utilizados en la sentencia hayan sufrido cambios de definición (DDL) desde el uso anterior de la sentencia preparada. Además, si el valor de search_path cambia de un uso al siguiente, la sentencia se volverá a analizar utilizando el nuevo search_path. (Este último comportamiento es nuevo a partir de PostgreSQL 9.3). Consulte PREPARE para obtener más información sobre el comportamiento de las sentencias preparadas.

Esta función solo debe llamarse desde una función en C conectada.

SPIPlanPtr se declara como un puntero a un tipo de estructura opaca en spi.h. No es aconsejable intentar acceder a su contenido directamente, ya que esto hace que sea mucho más probable que su código se rompa en futuras revisiones de PostgreSQL.

El nombre SPIPlanPtr es en cierto modo histórico, ya que la estructura de datos ya no contiene necesariamente un plan de ejecución.