無料スクリプト配布のPHP.TO   PHPの実用的なtips PHPマニュアル MySQLマニュアル Apacheマニュアル PostgreSQLマニュアル マニュアル検索    

31.2. 接続状態関数

これらの関数を使用して、既存のデータベース接続オブジェクトの状態を調べることができます。

ティップ: libpq アプリケーションのプログラマは注意して PGconn という抽象化を維持してください。 PGconn の内容は以下に挙げるアクセス用関数を使って取り出してください。 PGconn 構造体中のフィールドは将来予告なく変更されることがありますので、 libpq-int.h を使用したフィールドの参照は避けてください。

以下の関数は、接続で確立したパラメータの値を返します。 これらの値は PGconn の存続期間中で固定されます。

PQdb

接続したデータベース名を返します。

char *PQdb(const PGconn *conn);

PQuser

接続したユーザ名を返します。

char *PQuser(const PGconn *conn);

PQpass

接続したパスワードを返します。

char *PQpass(const PGconn *conn);

PQhost

接続したサーバホスト名を返します。

char *PQhost(const PGconn *conn);

PQport

接続したポートを返します。

char *PQport(const PGconn *conn);

PQtty

接続のデバッグ用 TTY を返します。 (これは廃れたものです。サーバはもはや TTY 設定を参照しません。 後方互換性のためにこの関数が残っています。)

char *PQtty(const PGconn *conn);

PQoptions

接続要求時に渡されたコマンドラインオプションを返します。

char *PQoptions(const PGconn *conn);

以下の関数は、 PGconn オブジェクトに対して操作を行うことで変更可能な状態データを返します。

PQstatus

接続の状態を返します。

ConnStatusType PQstatus(const PGconn *conn);

この状態は多くの値の中の1つとなるはずです。 しかし非同期接続手順の外部からは、その中でたった2つ、 CONNECTION_OK CONNECTION_BAD だけが現れます。 データベースへの接続に問題がなければ、 CONNECTION_OK 状態になります。 接続に失敗している場合は CONNECTION_BAD 状態となります。 通常、OK状態は PQfinish まで維持されますが、通信失敗のために早まって CONNECTION_BAD になることもあります。 その場合、アプリケーションは PQreset を呼び出して修復を試みることができます。

返される可能性があるその他の状態コードについては PQconnectStartParams PQconnectStart および PQconnectPoll の項目を参照してください。

PQtransactionStatus

サーバの現在のトランザクション内部状態を返します。

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

この状態は、 PQTRANS_IDLE (現在待機中)、 PQTRANS_ACTIVE (コマンド実行中)、 PQTRANS_INTRANS (有効なトランザクションブロック内で待機中)、 PQTRANS_INERROR (無効なトランザクションブロック内で待機中)となり得ます。 接続に問題がある場合のみ PQTRANS_UNKNOWN が報告されます。 サーバへ問い合わせが送信されたが、まだ完了していない場合のみ PQTRANS_ACTIVE が報告されます。

注意

autocommit パラメータを無効にした PostgreSQL 7.3サーバを使用する場合、 PQtransactionStatus は間違った結果を返します。 サーバサイドでの自動コミットは廃止され、その後のバージョンのサーバでは存在しません。

PQparameterStatus

サーバの現在のパラメータ設定を検索します。

const char *PQparameterStatus(const PGconn *conn, const char *paramName);

あるパラメータ値は、接続開始時にサーバによって自動的に、もしくは、その値が変更された時は常に報告されます。 PQparameterStatus はそれらの設定の調査に役立ちます。 パラメータの現在値がわかればその値を、わからない場合は NULL を返します。

現在のリリースで報告されるパラメータには、 server_version server_encoding client_encoding application_name is_superuser session_authorization DateStyle IntervalStyle TimeZone integer_datetimes および standard_conforming_strings があります。 (8.0より前では server_encoding TimeZone および integer_datetimes が、8.1より前では standard_conforming_strings が、そして8.4より前では IntervalStyle が、9.0より前では application_name が報告されませんでした。 ) server_version server_encoding および integer_datetimes は起動後変更することができないことに注意してください。

プロトコル3.0より前のサーバはパラメータ設定を報告しません。 しかし、 libpq には server_version client_encoding の値を取り出す仕組みがとりあえずあります。 アプリケーションは、 付け焼き刃な コードでこれらの値を決定するのではなく、 PQparameterStatus を使用することが求められています。 (しかし、3.0より前の接続では、接続開始後に SET による client_encoding の変更は PQparameterStatus に反映されないことに注意してください。) server_version については、この情報をより比較し易い数値形式で返す PQserverVersion も参照してください。

standard_conforming_strings の値がないと報告された場合、アプリケーションは off と推測することができます。 つまり、バックスラッシュは文字リテラル中のエスケープ文字として扱います。 また、このパラメータが存在すると、エスケープ文字構文( E'...' )が受付けられることを意味するものと取られます。

返されるポインタは const と宣言されていますが、実際には PGconn 構造体に関連付けされた変化する領域を指し示します。 このポインタが諸問い合わせに渡って有効なままであるとは考えないでください。

PQprotocolVersion

使用されるフロントエンド/バックエンドプロトコルを調査します。

int PQprotocolVersion(const PGconn *conn);

ある機能がサポートされているかどうかを決定するために、アプリケーションはこの関数を使用することができます。 現在、取り得る値は2(2.0プロトコル)、3(3.0プロトコル)、あるいは0(接続不良)です。 このプロトコルバージョンは接続の開始が完了した後で変更することはできません。 しかし、理論的には接続のリセット時に変更可能です。 PostgreSQL 7.4以降での通信時、通常3.0プロトコルが使用されます。 7.4より前のサーバでは2.0プロトコルのみをサポートします。 (1.0プロトコルは廃止され、 libpq ではサポートされていません。)

PQserverVersion

バックエンドのバージョンの整数表現を返します。

int PQserverVersion(const PGconn *conn);

この関数を使用してアプリケーションは接続したデータベースサーバのバージョンを決定することができます。 この数値の形式は、メジャー、マイナー、リビジョン番号を2桁の10進数に変換し、連結させたものです。 例えば、バージョン8.1.5では80105を返し、バージョン8.2では80200を返します。 (先頭の0は現れません。) 接続不良の場合は0が返されます。

PQerrorMessage

接続における操作において、最も最近に生成されたエラーメッセージを返します。

char *PQerrorMessage(const PGconn *conn);

ほとんどすべての libpq 関数は、失敗時に PQerrorMessage 用のメッセージを設定します。 libpq での決まりとして、空でない PQerrorMessage の結果は複数行に渡ることも可能で、最後に改行が含まれることがある点に注意してください。 呼び出し元はこの結果を直接解放してはいけません。 関連する PGconn ハンドルが PQfinish に渡された時にこれは解放されます。 PGconn 構造体への操作を跨って、この結果文字列が同一であると想定してはいけません。

PQsocket

サーバとの接続ソケットに対するファイル記述子番号を得ます。 有効な記述子なら値は0以上です。 -1の場合は、サーバとの接続がまだ開いていないことを示します。 (これは通常の操作では変更することはできません。 接続設定中やリセット中に変更されます。)

int PQsocket(const PGconn *conn);

PQbackendPID

接続を処理するバックエンドのプロセス ID (PID)を返します。

int PQbackendPID(const PGconn *conn);

バックエンドの PID は、デバッグする場合や NOTIFY メッセージ(これは通知を発行したバックエンドプロセスの PID を含んでいます)の比較に便利です。 この PID はデータベースサーバホスト上で実行されているプロセスのものであり、ローカルホスト側のものではありません! 注意してください。

PQconnectionNeedsPassword

接続認証方式がパスワードを要求し、利用可能なパスワードがない場合真(1)を返します。 さもなくば偽(0)を返します。

int PQconnectionNeedsPassword(const PGconn *conn);

この関数を、接続試行に失敗した後でユーザにパスワード入力を促すかどうかを決定するために適用することができます。

PQconnectionUsedPassword

接続認証方式でパスワードを使用する場合は真(1)、さもなくば偽(0)を返します。

int PQconnectionUsedPassword(const PGconn *conn);

この関数は、接続の試みが失敗したか成功したかの後に、サーバがパスワードを要求したかどうかを検出するために適用できます。

PQgetssl

接続で使用されているSSL構造体を返します。 SSLが使用されていない場合はヌルを返します。

SSL *PQgetssl(const PGconn *conn);

この構造体は暗号化レベルの検証やサーバ証明書の検査などに役立ちます。 この構造体については OpenSSL の文書を参照してください。

実際の返り値は SSL * であって、ここで SSL OpenSSL ライブラリで定義された型です。しかし OpenSSL ヘッダファイルでの要求を回避するためこのように宣言されません。この関数を使用するためには以下に示す行の並びに従ってコードを書いてください。

#include <libpq-fe.h>
#include <openssl/ssl.h>

...

    SSL *ssl;

    dbconn = PQconnectdb(...);
    ...

    ssl = PQgetssl(dbconn);
    if (ssl)
    {
        /* use OpenSSL functions to access ssl */
    }

この関数の正しいプロトタイプを得るには、 USE_SSL を定義する必要があります。 こうすると、 OpenSSL ssl.h も自動的にインクルードされます。


powered by SEO.CUG.NET