28.2. 接続状態関数

これらの関数は、既存のデータベース接続オブジェクトの状態を調べるために役立ちます。

ティップ: libpqアプリケーションプログラマはPGconnによる抽象化に注意を払うべきです。 PGconnの内容は以下に挙げるアクセッサ関数を使って取り出してください。 PGconn構造体中のフィールドは将来予告なく変更されることがありますので、直接フィールドを参照することは避けてください。 (PostgreSQLリリース6.4から、PGconn構造体の定義を libpq-fe.hの中から外しました。 以前作成したプログラムが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);

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

その他の起こり得る状態コードについてはPQconnectStartPQconnectPollの項目を参照してください。

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_versionserver_encodingclient_encodingis_superusersession_authorizationDateStyleTimeZoneinteger_datetimes、およびstandard_conforming_stringsがあります。 (8.0以前ではserver_encodingTimeZone、およびinteger_datetimesが、8.1以前ではstandard_conforming_stringsが報告されませんでした。 ) server_versionserver_encoding、および、integer_datetimesは起動後変更することができないことに注意してください。

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

If no value for standard_conforming_strings is reported, applications may assume it is false, that is, backslashes are treated as escapes in string literals. Also, the presence of this parameter may be taken as an indication that the escape string syntax (E'...') is accepted.

standard_conforming_strings の値がないと報告された場合、アプリケーションは false と推測するでしょう。 つまり、バックスラッシュは文字リテラル中のエスケープ文字として扱います。 また、このパラメータが存在すると、エスケープ文字構文 (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進数に変換し、連結させたものです。 例えば、バージョン7.4.2では70402を返し、バージョン8.1では80100を返します。 (先頭の0は現れません。) 接続不良の場合は0が返されます。

PQerrorMessage

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

char *PQerrorMessage(const PGconn *conn);

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

PQsocket

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

int PQsocket(const PGconn *conn);

PQbackendPID

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

int PQbackendPID(const PGconn *conn);

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

PQgetssl

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

SSL *PQgetssl(const PGconn *conn);

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

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