Capítulo 47. Interface de programação servidor

Índice

47.1. Funções da interface
SPI_connect — conecta uma função C ao gerenciador SPI
SPI_finish — desconecta uma função C do gerenciador SPI
SPI_execute — executa um comando
SPI_exec — executa um comando de leitura/escrita
SPI_execute_​extended — executa um comando com parâmetros fora de linha
SPI_execute_​with_args — executa um comando com parâmetros fora de linha
SPI_prepare — prepara uma instrução, sem executá-la ainda
SPI_prepare_​cursor — prepara uma instrução, sem executá-la ainda
SPI_prepare_​extended — prepara uma instrução, sem executá-la ainda
SPI_prepare_​params — prepara uma instrução, sem executá-la ainda
SPI_getargcount — retorna o número de argumentos necessários para uma instrução preparada por SPI_prepare
SPI_getargtypeid — retorna o OID do tipo de dados para um argumento de uma instrução preparada por SPI_prepare
SPI_is_cursor_​plan — retorna verdade se a instrução preparada por SPI_prepare puder ser usada por SPI_cursor_open
SPI_execute_​plan — executa uma instrução preparada por SPI_prepare
SPI_execute_​plan_extended — executa uma instrução preparada por SPI_prepare
SPI_execute_plan_​with_paramlist — executa uma instrução preparada por SPI_prepare
SPI_execp — executa uma instrução no modo leitura/escrita
SPI_cursor_​open — configura um cursor usando uma instrução preparada por SPI_prepare
SPI_cursor_open_​with_args — configura um cursor usando uma consulta e parâmetros
SPI_cursor_open_​with_paramlist — configura um cursor usando parâmetros
SPI_cursor_​parse_open — configura um cursor usando uma cadeia de caracteres de consulta e parâmetros
SPI_cursor_​find — encontra um cursor existente pelo nome
SPI_cursor_​fetch — busca algumas linhas do cursor
SPI_cursor_​move — move o cursor
SPI_scroll_​cursor_fetch — busca algumas linhas do cursor
SPI_scroll_​cursor_move — move o cursor
SPI_cursor_​close — fecha o cursor
SPI_keepplan — salva uma instrução preparada
SPI_saveplan — salva uma instrução preparada
SPI_register_​relation — constrói uma relação efêmera com nome disponível pelo nome em consultas da SPI
SPI_unregister_​relation — remove do registro uma relação efêmera com nome
SPI_register_​trigger_data — torna dados de gatilhos efêmeros disponíveis em consultas da SPI
47.2. Funções de suporte da interface
SPI_fname — determina o nome da coluna para o número de coluna especificado
SPI_fnumber — determina o número da coluna para o nome de coluna especificado
SPI_getvalue — retorna o valor da coluna especificada em uma cadeia de caracteres
SPI_getbinval — retorna o valor binário da coluna especificada
SPI_gettype — retorna o nome do tipo de dados da coluna especificada
SPI_gettypeid — retorna o OID do tipo de dados da coluna especificada
SPI_getrelname — retorna o nome da relação especificada
SPI_getnspname — retorna o espaço de nomes da relação especificada
SPI_result_code_string — retorna o código de erro como cadeia de caracteres
47.3. Gerenciamento de memória
SPI_palloc — aloca memória no contexto do executor superior
SPI_repalloc — realoca memória no contexto do executor superior
SPI_pfree — libera a memória no contexto do executor superior
SPI_copytuple — faz a cópia de uma linha no contexto do executor superior
SPI_returntuple — prepara para retornar uma tupla como um Datum
SPI_modifytuple — cria uma linha substituindo os campos selecionados de uma determinada linha
SPI_freetuple — libera uma linha alocada no contexto do executor superior
SPI_freetuptable — libera um conjunto de linhas criado por SPI_execute ou uma função semelhante
SPI_freeplan — libera uma instrução preparada salva anteriormente
47.4. Gerenciamento de transações
SPI_commit — efetiva a transação corrente
SPI_rollback — interrompe a transação corrente
SPI_start_transaction — função obsoleta
47.5. Visibilidade das alterações dos dados
47.6. Exemplo

A interface de programação servidor (Server Programming Interface/SPI) dá aos desenvolvedores de funções C definidas pelo usuário a capacidade de executar comandos SQL dentro suas funções ou procedimentos. A SPI é um conjunto de funções de interface para simplificar o acesso ao analisador, planejador e executor. A SPI também faz algum gerenciamento de memória.

Nota

As linguagens procedurais disponíveis fornecem vários meios para executar comandos SQL a partir de funções. A maioria desses recursos é baseado na SPI, portanto essa documentação também pode ser útil para os usuários dessas linguagens.

Note que se um comando chamado via SPI falhar, o controle não será retornado para a função C. Em vez disso, a transação ou subtransação na qual a função C é executada será desfeita. (Isso pode parecer surpreendente, visto que a maioria das funções da SPI possui convenções de retorno de erro documentadas. No entanto, essas convenções se aplicam apenas a erros detectados pelas próprias funções da SPI.) É possível recuperar o controle após um erro estabelecendo uma subtransação própria em torno das chamadas à SPI que podem falhar.

As funções da SPI retornam um resultado não negativo em caso de sucesso (por meio de um valor inteiro retornado, ou na variável global SPI_result, conforme descrito abaixo). Em caso de erro, será retornado um resultado negativo ou NULL.

Os arquivos de código-fonte que usam a SPI devem incluir o arquivo de cabeçalho executor/spi.h.

Contato

CSS válido!