pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — Envia uma solicitação ao servidor para criar uma instrução preparada com os parâmetros fornecidos e aguarda a conclusão

Descrição

pg_prepare(PgSql\Connection $connection = ?, string $stmtname, string $query): PgSql\Result|false

pg_prepare() cria uma instrução preparada para execução posterior com pg_execute() ou pg_send_execute(). Este recurso permite que comandos que serão usados repetidamente sejam analisados e planejados apenas uma vez, em vez de cada vez que forem executados. pg_prepare() é suportado apenas em conexões PostgreSQL 7.4 ou superior; falhará ao usar versões anteriores.

A função cria uma instrução preparada chamada stmtname a partir da string query, que deve conter um único comando SQL. stmtname pode ser "" para criar uma instrução sem nome, caso em que qualquer instrução sem nome pré-existente é automaticamente substituída; caso contrário, será um erro se o nome da instrução já estiver definido na sessão atual. Se algum parâmetro for usado, ele será referido na query como $1, $2 etc.

Instruções preparadas para uso com pg_prepare() também podem ser criadas executando instruções SQL PREPARE. (Mas pg_prepare() é mais flexível, pois não requer que os tipos de parâmetros sejam pré-especificados.) Além disso, embora não exista uma função PHP para excluir uma instrução preparada, a declaração SQL DEALLOCATE pode ser usada para esse propósito.

Parâmetros

connection: Uma instância de PgSql\Connection. Quando o parâmetro connection não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().
Warning
A partir do PHP 8.1.0, usar a conexão padrão tornou-se defasado.
stmtname: O nome para dar a declaração preparada. Deve ser exclusivo por conexão. Se "" for especificado, uma instrução sem nome será criada, substituindo qualquer instrução sem nome definida anteriormente.
query: A instrução SQL parametrizada. Deve conter apenas uma única instrução (múltiplas instruções separadas por ponto e vírgula não são permitidas). Se algum parâmetro for usado, ele será chamado de $1, $2 etc.

Valor Retornado

Uma instância PgSql\Result em caso de sucesso, ou false em caso de falha.

Registro de Alterações

Versão	Descrição
8.1.0	Agora retorna uma instância de PgSql\Result; anteriormente, um resource era retornado.
8.1.0	O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

Exemplos

Example #1 Usando pg_prepare()

<?php

// Conecta a um banco de dados chamado "mary"
$dbconn = pg_connect("dbname=mary");

// Prepara uma consulta para execução
$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

// Executa a consulta preparada. Observe que não é necessário escapar
// a string "Joe's Widgets" de forma alguma
$result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

// Executa a mesma consulta preparada, desta vez com um parâmetro diferente
$result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

?>

Veja Também

pg_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado
pg_send_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros, sem esperar pelo(s) resultado(s)