pg_prepare

Submits a request to the server to create a prepared statement with the given parameters, and waits for completion

&reftitle.description; ``PgSql\Result``false```pg_prepare` `PgSql\Connection` `connection` `string` `stmtname` `string` `query`

`pg_prepare` creates a prepared statement for later execution with `pg_execute` or `pg_send_execute`. This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed. `pg_prepare` is supported only against PostgreSQL 7.4 or higher connections; it will fail when using earlier versions.

The function creates a prepared statement named `stmtname` from the `query` string, which must contain a single SQL command. `stmtname` may be `""` to create an unnamed statement, in which case any pre-existing unnamed statement is automatically replaced; otherwise it is an error if the statement name is already defined in the current session. If any parameters are used, they are referred to in the `query` as `$1`, `$2`, etc.

Prepared statements for use with `pg_prepare` can also be created by executing SQL `PREPARE` statements. (But `pg_prepare` is more flexible since it does not require parameter types to be pre-specified.) Also, although there is no PHP function for deleting a prepared statement, the SQL `DEALLOCATE` statement can be used for that purpose.

&reftitle.parameters;

`connection`

- &pgsql.parameter.connection-with-unspecified-default;

`stmtname`

- The name to give the prepared statement. Must be unique per-connection. If `""` is specified, then an unnamed statement is created, overwriting any previously defined unnamed statement.

`query`

- The parameterized SQL statement. Must contain only a single statement (multiple statements separated by semi-colons are not allowed). If any parameters are used, they are referred to as `$1`, `$2`, etc.

&reftitle.returnvalues;

An `PgSql\Result` instance on success, &return.falseforfailure;.

&reftitle.changelog;

&Version; | &Description;
&pgsql.changelog.return-result-object; &pgsql.changelog.connection-object;

&reftitle.examples;

### Using `pg_prepare`

    <?php

    // Connect to a database named "mary"
    $dbconn = pg_connect("dbname=mary");

    // Prepare a query for execution
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Execute the prepared query.  Note that it is not necessary to escape
    // the string "Joe's Widgets" in any way
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Execute the same prepared query, this time with a different parameter
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

&reftitle.seealso;

- `pg_execute`
- `pg_send_execute`