CascadiaPHP 2024

pg_prepare

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

pg_prepareEnvia uma solicitação 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().

Aviso

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

Exemplo #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)

add a note

User Contributed Notes 6 notes

up
5
david at fetter dot org
19 years ago
SQL is often a complicated piece of code by itself, so you may wish put it inside a "here doc." This will help you read it wherever it appears and test it by itself via a command-line or gui client.

$sql = <<<SQL
SELECT a.foo, b.bar, c.baz
FROM
table_a a
LEFT JOIN
table_b b
ON (
a.a_id = b.a_id
)
JOIN
table_c c
ON (
b.c_id = c.c_id
)
WHERE c.name = $1
SQL;
up
1
mike at musskopf dot com
16 years ago
I had some problems with this function. When you use pg_prepare() with a function like date_trunc('day', $1) you need to specify the data type.

The solution was use the Pear MDB2 but with some changes in code. The original code try to use pg_prepare() too, with errors.
up
2
rodrigo at fabricadeideias dot com
17 years ago
If you decide to deallocate (unprepare) a previously prepared sql command it might be better to quote the sql name as in

DEALLOCATE "theNameOfMySQL"

instead of (the more natural)

DEALLOCATE theNameOfMySQL

PostgerSQL preserves the case of your identifiers if, and only if, you quote them. The pg_prepare function preserves the case of the sql name you use.

A complete example would be

$sql = 'SELECT * FROM user WHERE cod_user = $1';
$sqlName = 'selectUserByCode';
if (!pg_prepare ($sqlName, $sql)) {
die("Can't prepare '$sql': " . pg_last_error());
}
$rs = pg_execute($sqlName, array(1));
do whatever you want with $rs and finally
$sql = sprintf(
'DEALLOCATE "%s"',
pg_escape_string($sqlName)
);
if(!pg_query($sql)) {
die("Can't query '$sql': " . pg_last_error());
}
up
1
geompse at gmail dot com
12 years ago
The given name cannot be the statement itself.
It has a maximum length and will truncate.

If two queries begin the same way, only the first one will be used.
up
0
scott dot marlowe at gmail dot com
18 years ago
Note that if you are preparing a query with an in clause with a list of items, you will need to prepare each item separately.

$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name IN($1,$2,$3)');

$result = pg_execute($dbconn, "my_query", array("coffee", "beer", "hard"));

This means that you can't just prepare a query with an arbitrary in() list.
up
-3
andy at petdance dot com
16 years ago
Any error in the prepare is available from pg_last_error().
To Top