指定したパラメータでプリペアドステートメントを作成するリクエストを サーバーに送信し、その完了を待つ

# pg_prepare

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

pg_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを サーバーに送信し、その完了を待つ

### 説明

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

pg_prepare() は、 pg_execute() あるいは pg_send_execute() で後に実行するためのプリペアドステートメントを作成します。これにより、 繰り返し使用されるコマンドについての構文解析や実行計画作成が最初の 一度だけですみます。

この関数は `statement_name` という名前の プリペアドステートメントを `query` 文字列から作成します。 この文字列には 1 つの SQL コマンドが含まれている必要があります。 `statement_name` を `""` にすることで無名ステートメントを 作成することが可能で、既存の無名ステートメントは自動的に上書きされます。 それ以外の場合、もしカレントのセッションで既に定義済みのステートメント名を 使用した場合にはエラーとなります。パラメータを使用する際は、 `query` 内で `$1`、`$2` のような形式で参照されます。

pg_prepare() で使用するプリペアドステートメントは、 SQLの `PREPARE` 文を実行することでも作成可能です （しかし、パラメータの型を事前に指定する必要がないという点で pg_prepare() のほうがより柔軟です）。 また、PHP にはプリペアドステートメントを削除する関数がありませんが、 この目的のためには SQLの `DEALLOCATE` 文が使用可能です。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`statement_name`

  プリペアドステートメントにつける名前。接続内で一意である必要があります。 `""` が指定された場合は無名ステートメントが作成され、以前に定義された 無名ステートメントを上書きします。

`query`

  パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は `$1`、`$2` などの形式で参照されます。

### 戻り値

成功した場合に PgSql\Result クラスのインスタンスを返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例1 pg_prepare() の使用法

    <?php

    // "mary"という名前のデータベースに接続
    $dbconn = pg_connect("dbname=mary");

    // 実行するクエリの準備
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // プリペアドクエリを実行する。文字列 "Joe's Widgets" は
    // エスケープの必要がないことに注意
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // 同一プリペアドクエリを別のパラメータで実行する
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### 参考

- pg_execute() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
- pg_send_execute() - 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open