CXXVII. PostgreSQL 関数

導入

PostgreSQL データベースはオープンソースの製品であり、無料で 使用可能です。Postgres は元々 UCB(カリフォルニア大学バークレイ校) コンピュータ・サイエンス学部で開発されたものです。この Postgres は、 現在いくつかの商用データベースにおいてサポートされつつある オブジェクトリレーショナルデータベース的概念の多くの先駆けでした。 Postgres は、SQL92/SQL99 言語サポート・トランザクション・参照整合性・ ストアドプロシージャ・拡張可能な型を提供しています。PostgreSQL は、 バークレイ校での Postgres のオリジナルコードの、オープンソースの 子孫にあたります。

要件

PostgreSQL サポートを使用するには、PostgreSQL 6.5 以降が必要です。 PostgreSQL 8.0 以降では PostgreSQL モジュールの全ての機能を使用可能 です。PostgreSQL は、マルチバイト文字エンコーディングを含む多くの 文字エンコーディングをサポートしています。現在のバージョン及び PostgreSQLに関するより詳細な情報は、 http://www.postgresql.org/PostgreSQL Documentation で入手可能です。

インストール手順

PostgreSQLサポートを利用可能とするには、PHPコンパイル時に --with-pgsql[=DIR] を指定することが必要です。 共有オブジェクトモジュールが利用可能な場合、php.iniextension ディレクティブ または dl() 関数によりPostgreSQLモジュール をロードすることが可能です。

実行時設定

php.ini の設定により動作が変化します。

表 1. PostgreSQL設定オプション

名前デフォルト変更の可否変更履歴
pgsql.allow_persistent"1"PHP_INI_SYSTEM 
pgsql.max_persistent"-1"PHP_INI_SYSTEM 
pgsql.max_links"-1"PHP_INI_SYSTEM 
pgsql.auto_reset_persistent"0"PHP_INI_SYSTEMPHP 4.2.0 以降で有効です。
pgsql.ignore_notice"0"PHP_INI_ALLPHP 4.3.0 以降で有効です。
pgsql.log_notice"0"PHP_INI_ALLPHP 4.3.0 以降で有効です。
PHP_INI_* 定数の詳細および定義については 付録I を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pgsql.allow_persistent boolean

持続的な Postgres 接続を可能にするかどうか。

pgsql.max_persistent integer

プロセス毎の持続的 Postgres 接続の最大数。

pgsql.max_links integer

持続的接続を含むプロセス毎の Postgres 接続の最大数。

pgsql.auto_reset_persistent integer

pg_pconnect() で作成した持続的接続の障害を 検出する。少々のオーバーヘッドを要します。

pgsql.ignore_notice integer

PostgreSQL バックエンドの通知メッセージを無視するかどうか。

pgsql.log_notice integer

PostgreSQL バックエンドの通知メッセージをログに記録するかしないか。 ログに記録するには、PHP ディレクティブ pgsql.ignore_notice を off にする必要があります。

リソース型

PostgreSQL モジュールで使用されるリソース型は 2 種類あります。ひとつは データベース接続のリンク ID で、もうひとつはクエリの結果を保持する リソースです。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PGSQL_ASSOC (integer)

pg_fetch_array() に渡します。 フィールド名と値の連想配列を返します。

PGSQL_NUM (integer)

pg_fetch_array() に渡します。 フィールド番号と値の数値添字配列を返します。

PGSQL_BOTH (integer)

pg_fetch_array() に渡します。 フィールド値の配列を、数値添字(フィールド番号で)と 連想配列(フィールド名で)の両方で返します。

PGSQL_CONNECT_FORCE_NEW (integer)

pg_connect() に渡し、既存の同一接続を無視して 新しい接続を確立させるようにします。

PGSQL_CONNECTION_BAD (integer)

pg_connection_status() から返され、データベースとの 接続が不正な状態になっていることを示します。

PGSQL_CONNECTION_OK (integer)

pg_connection_status() から返され、データベースとの 接続が正常であることを示します。

PGSQL_SEEK_SET (integer)

pg_lo_seek() に渡します。シーク操作は オブジェクトの先頭から始められます。

PGSQL_SEEK_CUR (integer)

pg_lo_seek() に渡します。シーク操作は カレントの位置から始められます。

PGSQL_SEEK_END (integer)

pg_lo_seek() に渡します。シーク操作は オブジェクトの最後から始められます。

PGSQL_EMPTY_QUERY (integer)

pg_result_status() から返されます。 サーバに送信された文字列が空でした。

PGSQL_COMMAND_OK (integer)

pg_result_status() から返されます。 コマンドは正常に終了し、何もデータを返しませんでした。

PGSQL_TUPLES_OK (integer)

pg_result_status() から返されます。 コマンドは正常に終了し、データを返しました (SELECTSHOW など)。

PGSQL_COPY_OUT (integer)

pg_result_status() から返されます。 (サーバからの)データのコピーが始まりました。

PGSQL_COPY_IN (integer)

pg_result_status() から返されます。 (サーバへの)データのコピーが始まりました。

PGSQL_BAD_RESPONSE (integer)

pg_result_status() から返されます。 サーバからの応答を判別できませんでした。

PGSQL_NONFATAL_ERROR (integer)

pg_result_status() から返されます。 致命的ではないエラー(通知や警告など)が発生しました。

PGSQL_FATAL_ERROR (integer)

pg_result_status() から返されます。 致命的なエラーが発生しました。

PGSQL_TRANSACTION_IDLE (integer)

pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクション内ではありません。

PGSQL_TRANSACTION_ACTIVE (integer)

pg_transaction_status() から返されます。 接続内でコマンドを実行中です。クエリが接続を通じて送信され、 まだ完了していません。

PGSQL_TRANSACTION_INTRANS (integer)

pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクションブロック内にあります。

PGSQL_TRANSACTION_INERROR (integer)

pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクション処理に失敗しています。

PGSQL_TRANSACTION_UNKNOWN (integer)

pg_transaction_status() から返されます。 接続が正常ではありません。

PGSQL_DIAG_SEVERITY (integer)

pg_result_error_field() に渡します。 深刻度です。その内容は ERRORFATAL、あるいは PANIC (エラーメッセージ内)、あるいは WARNINGNOTICEDEBUGINFO、あるいは LOG (通知メッセージ内)、あるいはこれらの各国語版のうちのどれかです。 常に存在します。

PGSQL_DIAG_SQLSTATE (integer)

pg_result_error_field() に渡します。 エラーの SQLSTATE コードです。SQLSTATE コードは発生したエラーの種別を 特定します。これは、データベースエラーに対してフロントエンドの アプリケーションが適切な操作(エラー処理など)をできるようにするために 使用されます。このフィールドはローカライズされていません。また、 常に存在します。

PGSQL_DIAG_MESSAGE_PRIMARY (integer)

pg_result_error_field() に渡します。 人間が判読できる最初のエラーメッセージ(たいてい 1 行)です。常に存在します。

PGSQL_DIAG_MESSAGE_DETAIL (integer)

pg_result_error_field() に渡します。 オプションの 2 番目のエラーメッセージで、問題に対する詳細な情報を 含みます。複数行にまたがることもあります。

PGSQL_DIAG_MESSAGE_HINT (integer)

pg_result_error_field() に渡します。 オプションのメッセージで、問題に対してどのように対応すべきかを指摘 します。エラーの詳細情報と違う点は、発生した事実ではなくアドバイス (時に不適切な場合もある)をするところです。複数行にまたがることも あります。

PGSQL_DIAG_STATEMENT_POSITION (integer)

pg_result_error_field() に渡します。 エラーカーソルの位置を、もとのステートメント中の位置として表す 整数値を保持する文字列です。 最初の文字の位置は 1 で、それ以降(バイト数ではなく)文字数で 位置を数えます。

PGSQL_DIAG_INTERNAL_POSITION (integer)

pg_result_error_field() に渡します。 PG_DIAG_STATEMENT_POSITION と同じ定義ですが、 こちらはカーソル位置が内部で生成されたコマンドを参照している場合に 使用されます。このフィールドが存在する場合は、常に PG_DIAG_INTERNAL_QUERY フィールドも存在します。

PGSQL_DIAG_INTERNAL_QUERY (integer)

pg_result_error_field() に渡します。 失敗した内部生成コマンドのテキストです。例としては、PL/pgSQL 関数で 発行された SQL クエリなどがあてはまります。

PGSQL_DIAG_CONTEXT (integer)

pg_result_error_field() に渡します。 エラーが発生した状況を指定します。現在ここに含まれているのは、 アクティブなプロシージャの関数や内部生成クエリのコール履歴です。 これはエントリごとに 1 行のデータとなっており、直近のデータが 先頭にきます。

PGSQL_DIAG_SOURCE_FILE (integer)

pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでのファイル名です。

PGSQL_DIAG_SOURCE_LINE (integer)

pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでの行番号です。

PGSQL_DIAG_SOURCE_FUNCTION (integer)

pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでの関数名です。

PGSQL_ERRORS_TERSE (integer)

pg_set_error_verbosity() に渡します。 返されるメッセージを指定します。ここには深刻度・短い説明および 発生位置のみを含めます。通常は 1 行に収まるでしょう。

PGSQL_ERRORS_DEFAULT (integer)

pg_set_error_verbosity() に渡します。 デフォルトで返されるメッセージで、上の内容に加えて詳細・ ヒントあるいは詳細情報を含めます(複数行にまたがるかもしれません)。

PGSQL_ERRORS_VERBOSE (integer)

pg_set_error_verbosity() に渡します。 詳細モードでのメッセージで、有効なフィールドをすべて含めます。

PGSQL_STATUS_LONG (integer)

pg_result_status() に渡します。 結果として数値が要求されていることを示します。

PGSQL_STATUS_STRING (integer)

pg_result_status() に渡します。 結果としてテキストのコマンドタグが要求されていることを示します。

PGSQL_CONV_IGNORE_DEFAULT (integer)

pg_convert() に渡します。 変換時に、テーブルのデフォルト値を無視します。

PGSQL_CONV_FORCE_NULL (integer)

pg_convert() に渡します。 空文字列に対して、SQL の NULL を使用します。

PGSQL_CONV_IGNORE_DEFAULT (integer)

pg_convert() に渡します。 NULL を SQL の NOT NULL に変換しないように します。

注意

注意: すべての関数がすべての構築環境でサポートされるわけではありません。 サポートされる関数は、使用する libpq(PostgreSQL の C クライアント ライブラリ)のバージョンと libpq のコンパイル方法に依存します。 もし PHP の PostgreSQL 拡張モジュールに足りない関数がある場合、 その原因は libpq はその関数をサポートしていないことです。

注意: ほとんどの PostgreSQL 関数は、オプションの第 1 引数として connection を受け付けます。もしこれを 指定しなかった場合、直近にオープンされた接続を使用します。 そのような接続が存在しなかった場合、関数は FALSE を返します。

注意: PostgreSQL は、オブジェクトの生成時やクエリの実行時に 識別子(例: テーブル名・カラム名)を自動的に小文字に変換します。 この自動変換を防ぐには、識別子をダブルクォート("")でエスケープする 必要があります。

注意: PostgreSQL には、データベースのスキーマ情報(例: データベース内の すべてのテーブルなど)を取得するための特別なコマンドがありません。 その代わりに、PostgreSQL 7.4 以降では information_schema という標準スキーマが存在し、必要な情報が検索しやすい形式で格納されています。 詳しい情報は PostgreSQL ドキュメンテーション を参照ください。

この例では、PostgreSQL への接続・クエリの実行・結果の表示 そして切断の方法を説明します。

例 1. PostgreSQL 拡張モジュールの概要

<?php
// 接続し、データベースを選択する
$dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
     or die(
'Could not connect: ' . pg_last_error());

// SQL クエリを実行する
$query = 'SELECT * FROM authors';
$result = pg_query($query) or die('Query failed: ' . pg_last_error());

// 結果を HTML で表示する
echo "<table>\n";
while (
$line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
    echo
"\t<tr>\n";
    foreach (
$line as $col_value) {
        echo
"\t\t<td>$col_value</td>\n";
    }
    echo
"\t</tr>\n";
}
echo
"</table>\n";

// 結果セットを開放する
pg_free_result($result);

// 接続をクローズする
pg_close($dbconn);
?>

目次
pg_affected_rows -- 変更されたレコード(タプル)の数を返す
pg_cancel_query --  非同期クエリを取り消す
pg_client_encoding --  クライアントのエンコーディングを取得する
pg_close -- PostgreSQL 接続をクローズする
pg_connect -- PostgreSQL 接続をオープンする
pg_connection_busy --  接続がビジーかどうか調べる
pg_connection_reset --  接続をリセット(再接続)する
pg_connection_status --  接続ステータスを取得する
pg_convert --  連想配列の値を、SQL 文として実行可能な形式に変換する
pg_copy_from --  配列からテーブルに挿入する
pg_copy_to --  配列にテーブルをコピーする
pg_dbname -- データベース名を取得する
pg_delete --  レコードを削除する
pg_end_copy -- PostgreSQL バックエンドと同期する
pg_escape_bytea --  bytea フィールドに挿入するために文字列をエスケープする
pg_escape_string --  テキスト型フィールドに挿入するために、文字列をエスケープする
pg_execute --  指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
pg_fetch_all_columns -- 指定したカラムの全ての行を配列として取得する
pg_fetch_all -- 取得されたすべての行を配列として取得する
pg_fetch_array -- 行を配列として取得する
pg_fetch_assoc -- 行を連想配列として取得する
pg_fetch_object -- 行をオブジェクトとして得る
pg_fetch_result -- 結果リソースから値を返す
pg_fetch_row -- 数値添字の配列として行を得る
pg_field_is_null -- フィールドが SQL の NULL かどうか調べる
pg_field_name -- フィールドの名前を返す
pg_field_num -- 指定されたフィールドのフィールド番号を返す
pg_field_prtlen -- 表示される長さを返す
pg_field_size --  指定したフィールドの内部記憶領域におけるサイズを返す
pg_field_table -- tables フィールドの名前あるいは oid を返す
pg_field_type_oid --  フィールド番号に対応する型 ID(OID)を返す
pg_field_type --  フィールド番号に対応する型名を返す
pg_free_result -- メモリを開放する
pg_get_notify -- SQL NOTIFY メッセージを取得する
pg_get_pid -- バックエンドのプロセス ID を得る
pg_get_result --  非同期クエリの結果を取得する
pg_host --  接続に関連するホスト名を返す
pg_insert --  テーブルに配列を挿入する
pg_last_error -- 特定の接続から直近のエラーメッセージ文字列を取得する
pg_last_notice --  PostgreSQL サーバからの直近の通知メッセージを返す
pg_last_oid -- 直近の行のオブジェクト ID を返す
pg_lo_close -- ラージオブジェクトをクローズする
pg_lo_create -- ラージオブジェクトを生成する
pg_lo_export -- ラージオブジェクトをファイルにエクスポートする
pg_lo_import -- ファイルからラージオブジェクトをインポートする
pg_lo_open -- ラージオブジェクトをオープンする
pg_lo_read_all --  ラージオブジェクト全体を読み込みブラウザに直接送信する
pg_lo_read -- ラージオブジェクトを読み込む
pg_lo_seek --  ラージオブジェクトの位置をシークする
pg_lo_tell --  ラージオブジェクトのカレントのシーク位置を返す
pg_lo_unlink -- ラージオブジェクトを削除する
pg_lo_write -- ラージオブジェクトを書く
pg_meta_data --  テーブルからメタデータを取得する
pg_num_fields -- フィールド数を返す
pg_num_rows -- 行数を返す
pg_options -- 接続に関連するオプションを取得する
pg_parameter_status -- サーバのパラメータ設定を検索する
pg_pconnect -- 持続的な PostgreSQL 接続をオープンする
pg_ping -- データベース接続を調べる
pg_port --  接続に関連するポート番号を返す
pg_prepare --  指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ
pg_put_line -- NULL で終わる文字列を PostgreSQL バックエンドに送信する
pg_query_params --  SQL コマンドとパラメータを分割してサーバにを送信し、その結果を待つ
pg_query -- クエリを実行する
pg_result_error_field -- エラー報告の各フィールドを返す
pg_result_error --  結果に関連するエラーメッセージを取得する
pg_result_seek -- 結果リソースの内部行オフセットを設定する
pg_result_status --  クエリ結果のステータスを取得する
pg_select --  レコードを選択する
pg_send_execute --  指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
pg_send_prepare --  指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
pg_send_query_params -- コマンドとパラメータを分割してサーバに送信し、その結果を待たない
pg_send_query --  非同期クエリを送信する
pg_set_client_encoding --  クライアントのエンコーディングを設定する
pg_set_error_verbosity --  pg_last_error() および pg_result_error() が返すメッセージの詳細度を指定する
pg_trace -- PostgreSQL 接続のトレースを有効にする
pg_transaction_status -- サーバ上で実行中のトランザクションの状態を返す
pg_tty --  接続に関する TTY 名を返す
pg_unescape_bytea --  bytea 型のバイナリをアンエスケープする
pg_untrace -- PostgreSQL 接続のトレースを無効にする
pg_update --  テーブルを更新する
pg_version --  クライアント・プロトコル・サーバのバージョンを配列で返す