Descrição

A função SPI_prepare cria e retorna uma instrução preparada para o comando especificado, mas não executa o comando. A instrução preparada poderá ser executada posteriormente usando repetidamente a função SPI_execute_plan.

Quando o mesmo comando, ou um comando semelhante, deve ser executado repetidamente, é geralmente vantajoso realizar a fase de análise apenas uma vez e, além disso, pode ser vantajoso reutilizar um plano de execução para o comando. A função SPI_prepare converte uma cadeia de caracteres de comando em uma instrução preparada que encapsula os resultados da fase de análise. A instrução preparada também irá fornecer um local para armazenar em cache um plano de execução, se for descoberto que gerar um plano individualizado para cada execução não será útil.

Um comando preparado pode ser generalizado escrevendo parâmetros ($1, $2, etc.) no lugar do que seriam constantes em um comando normal. Os valores reais dos parâmetros são então especificados quando SPI_execute_plan é chamado. Isto permite que o comando preparado seja usado em uma gama mais ampla de situações do que seria possível sem parâmetros.

A instrução retornada por SPI_prepare poderá ser usada apenas na chamada corrente da função C, porque SPI_finish libera a memória alocada para esta instrução. Mas a instrução pode ser salva por mais tempo usando as funções SPI_keepplan e SPI_saveplan.

Argumentos

Valor retornado

A função SPI_prepare retorna um ponteiro não-nulo para SPIPlan, que é uma estrutura opaca que representa uma instrução preparada. Em caso de erro, será retornado NULL e SPI_result será definido com um dos mesmos códigos de erro usados por SPI_execute, exceto que será definido como SPI_ERROR_ARGUMENT se command for NULL, ou se nargs for menor que 0, ou se nargs for maior que 0 e argtypes for NULL.

Notas

Se não for definido nenhum parâmetro, será criado um plano genérico no primeiro uso de SPI_execute_plan usado também para todas as execuções subsequentes. Se houver parâmetros, os primeiros usos da função SPI_execute_plan vão gerar planos individualizados específicos para os valores dos parâmetros fornecidos. Após usos suficientes da mesma instrução preparada, a função SPI_execute_plan irá construir um plano genérico e, se não for muito mais caro que os planos individualizados, começará a usar o plano genérico em vez de replanejar a cada vez. Se este comportamento padrão não for adequado, pode-se alterá-lo passando o sinalizador CURSOR_OPT_GENERIC_PLAN ou CURSOR_OPT_CUSTOM_PLAN para a função SPI_prepare_cursor, para forçar o uso de planos genéricos ou personalizados, respectivamente.

Embora o ponto principal de uma instrução preparada seja evitar a repetição de fases de análise e planejamento da declaração, o PostgreSQL irá forçar a reanálise e o replanejamento da instrução antes de usá-la, sempre que os objetos de banco de dados usados na instrução tiverem sofrido alterações de definição (DDL) desde o uso anterior da instrução preparada. Além disso, se o valor de search_path mudar de um uso para outro, a instrução será analisada novamente usando o novo search_path. (Este último comportamento é novo, iniciado a partir do PostgreSQL 9.3.) Veja PREPARE para obter mais informações sobre o comportamento de instruções preparadas.

Esta função só deve ser chamada a partir de uma função C conectada.

SPIPlanPtr é declarado como um ponteiro para um tipo de estrutura opaca em spi.h. Não é aconselhável tentar acessar seu conteúdo diretamente, porque isto aumenta a probabilidade do código quebrar em futuras revisões do PostgreSQL.

O nome SPIPlanPtr é um tanto histórico, porque a estrutura de dados não contém mais necessariamente um plano de execução.