27.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 (有効なトランザクションブロック内で待機中)、or 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 (開始後変更できません)、client_encodingis_superusersession_authorizationDateStyleがあります。

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

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ではサポートされていません。)

PQerrorMessage

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

char *PQerrorMessage(const PGconn* conn);

ほとんどすべてのlibpq関数は、失敗時にPQerrorMessage用のメッセージを設定します。 libpqでの決まりとして、空文字でなければ改行が含まれることに注意してください。

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 も自動的にインクルードされます。

アダルトレンタルサーバー