Chapter 45. Server Programming Interface

Table of Contents

45.1. Funciones de interfaz
SPI_connect — conecta una función en C al gestor SPI
SPI_finish — desconecta una función en C del gestor SPI
SPI_execute — ejecuta un comando
SPI_exec — ejecuta un comando de lectura/escritura
SPI_execute_extended — ejecuta un comando con parámetros externos (out-of-line)
SPI_execute_with_args — ejecuta un comando con parámetros externos (out-of-line)
SPI_prepare — prepara una sentencia, sin ejecutarla todavía
SPI_prepare_cursor — prepara una sentencia, sin ejecutarla todavía
SPI_prepare_extended — prepara una sentencia, sin ejecutarla todavía
SPI_prepare_params — prepara una sentencia, sin ejecutarla todavía
SPI_getargcount — devuelve el número de argumentos necesarios para una sentencia preparada por SPI_prepare
SPI_getargtypeid — devuelve el OID del tipo de datos para un argumento de una sentencia preparada por SPI_prepare
SPI_is_cursor_plan — devuelve true si una sentencia preparada por SPI_prepare se puede utilizar con SPI_cursor_open
SPI_execute_plan — ejecuta una sentencia preparada por SPI_prepare
SPI_execute_plan_extended — ejecuta una sentencia preparada por SPI_prepare
SPI_execute_plan_with_paramlist — ejecuta una sentencia preparada por SPI_prepare
SPI_execp — ejecuta una sentencia en modo de lectura/escritura
SPI_cursor_open — configura un cursor usando una sentencia creada con SPI_prepare
SPI_cursor_open_with_args — configura un cursor usando una consulta y parámetros
SPI_cursor_open_with_paramlist — configura un cursor usando parámetros
SPI_cursor_parse_open — configura un cursor usando una cadena de consulta y parámetros
SPI_cursor_find — busca un cursor existente por su nombre
SPI_cursor_fetch — recupera algunas filas de un cursor
SPI_cursor_move — mueve un cursor
SPI_scroll_cursor_fetch — recupera algunas filas de un cursor
SPI_scroll_cursor_move — mueve un cursor
SPI_cursor_close — cierra un cursor
SPI_keepplan — guarda una sentencia preparada
SPI_saveplan — guarda una sentencia preparada
SPI_register_relation — hace que una relación con nombre efímera esté disponible por su nombre en las consultas SPI
SPI_unregister_relation — elimina una relación con nombre efímera del registro
SPI_register_trigger_data — hace que los datos de disparador (trigger) efímeros estén disponibles en las consultas SPI
45.2. Funciones de soporte de la interfaz
SPI_fname — determina el nombre de la columna para el número de columna especificado
SPI_fnumber — determina el número de columna para el nombre de columna especificado
SPI_getvalue — devuelve el valor en cadena de la columna especificada
SPI_getbinval — devuelve el valor binario de la columna especificada
SPI_gettype — devuelve el nombre del tipo de datos de la columna especificada
SPI_gettypeid — devuelve el OID del tipo de datos de la columna especificada
SPI_getrelname — devuelve el nombre de la relación especificada
SPI_getnspname — devuelve el espacio de nombres de la relación especificada
SPI_result_code_string — devuelve el código de error como una cadena de texto
45.3. Gestión de memoria
SPI_palloc — asigna memoria en el contexto superior del ejecutor
SPI_repalloc — reasigna memoria en el contexto superior del ejecutor
SPI_pfree — libera memoria en el contexto superior del ejecutor
SPI_copytuple — hace una copia de una fila en el contexto superior del ejecutor
SPI_returntuple — se prepara para devolver una tupla como un Datum
SPI_modifytuple — crea una fila reemplazando campos seleccionados de una fila dada
SPI_freetuple — libera una fila asignada en el contexto superior del ejecutor
SPI_freetuptable — libera un conjunto de filas creado por SPI_execute o una función similar
SPI_freeplan — libera una sentencia preparada guardada previamente
45.4. Gestión de transacciones
SPI_commit — confirma la transacción actual
SPI_rollback — aborta la transacción actual
SPI_start_transaction — función obsoleta
45.5. Visibilidad de los cambios de datos
45.6. Ejemplos

La Interfaz de Programación del Servidor (SPI, por sus siglas en inglés) ofrece a los desarrolladores de funciones en C definidas por el usuario la capacidad de ejecutar comandos SQL dentro de sus funciones o procedimientos. SPI es un conjunto de funciones de interfaz para simplificar el acceso al parser, planificador (planner) y ejecutor. SPI también realiza cierta gestión de memoria.

Note

Los lenguajes procedimentales disponibles proporcionan diversos medios para ejecutar comandos SQL desde funciones. La mayoría de estas facilidades se basan en SPI, por lo que esta documentación también podría ser de utilidad para los usuarios de dichos lenguajes.

Tenga en cuenta que si un comando invocado a través de SPI falla, el control no se devolverá a su función en C. En su lugar, la transacción o subtransacción en la que se ejecuta su función en C se revertirá (rollback). (Esto puede parecer sorprendente dado que las funciones de SPI en su mayoría tienen convenciones documentadas de retorno de error. Sin embargo, esas convenciones solo se aplican para errores detectados dentro de las propias funciones de SPI). Es posible recuperar el control después de un error estableciendo su propia subtransacción alrededor de las llamadas de SPI que podrían fallar.

Las funciones de SPI devuelven un resultado no negativo en caso de éxito (ya sea mediante un valor entero devuelto o en la variable global SPI_result, como se describe a continuación). En caso de error, se devolverá un resultado negativo o NULL.

Los archivos de código fuente que utilizan SPI deben incluir el archivo de cabecera executor/spi.h.