他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

33.2. 接続状態関数

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

ヒント

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

以下の関数は、接続で確立したパラメータの値を返します。 これらの値は接続期間中固定されます。 複数ホストの接続文字列が使用されている場合、同じPGconnオブジェクトを使用して新しい接続が確立されると、PQhostPQportPQpassの値は変わる可能性があります。 他の変数はPGconnの存在期間中固定されます。

PQdb

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

char *PQdb(const PGconn *conn);

PQuser

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

char *PQuser(const PGconn *conn);

PQpass

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

char *PQpass(const PGconn *conn);

PQpassは、接続パラメーターで指定されたパスワードを返します。 もし接続パラメータにパスワードがなくて、パスワードファイルからパスワードを取得できる場合には、そのパスワードを返します。 この場合、接続パラメータに複数のホストが指定されていると、接続が確立するまでは、PQpassの結果を当てにすることはできません。 接続の状態は、関数PQstatusで確認できます。

PQhost

実際に接続したサーバホスト名を返します。 これはホスト名、IPアドレス、あるいはUnixソケット経由で接続している場合はディレクトリパスになります。 (パスの場合は必ず/で始まる絶対パスになるので、他と区別できます。)

char *PQhost(const PGconn *conn);

hosthostaddrの両方が指定されると、PQhostは、そのhost情報を返します。 hostaddrだけが指定されると、それが返されます。 接続パラメータ中に複数のホストが指定された場合には、PQhostは実際に接続しているホストの情報を返します。

conn引数がNULLならば、PQhostNULLを返します。 そうでない場合、もしホスト情報の生成中エラーとなったら(おそらくコネクションまだ完全には確立されていないか、なんらかのエラーがある場合です)、空文字が返ります。

接続パラメーター中に複数のホストが指定されると、接続が確立するまではPQhostの結果を当てにすることはできません。 接続の状態は、PQstatus関数で確認できます。

PQport

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

char *PQport(const PGconn *conn);

接続パラメータ中に複数のポートが指定された場合には、PQportは実際に接続しているポートを返します。

conn引数がNULLならば、PQportNULLを返します。 そうでない場合、もしホスト情報の生成がエラーとなったら(おそらくコネクションまだ完全には確立されていないか、なんらかのエラーがある場合です)、空文字が返ります。

接続パラメーター中に複数のポートが指定されると、接続が確立するまではPQportの結果を当てにすることはできません。 接続の状態は、PQstatus関数で確認できます。

PQtty

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

char *PQtty(const PGconn *conn);

PQoptions

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

char *PQoptions(const PGconn *conn);

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

PQstatus

接続の状態を返します。

ConnStatusType PQstatus(const PGconn *conn);

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

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

PQtransactionStatus

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

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

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

PQparameterStatus

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

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

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

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

プロトコル3.0より前のサーバはパラメータ設定を報告しません。 しかし、libpqにはserver_versionclient_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);

この関数を使用してアプリケーションは接続したデータベースサーバのバージョンを決定することができます。 返却値の形式は、メジャーバージョン番号に10000を掛け、マイナーバージョン番号を加えたものです。 例えば、バージョン10.1では100001を返し、バージョン11.0では110000を返します。 接続不良の場合は0が返されます。

バージョン10よりも前では、PostgreSQLでは、最初の2つの部分がメジャーバージョンを表す、3つの部分からなるバージョン番号が使われていました。 これらのバージョンでは、PQserverVersionはそれぞれの部分に2桁の数字を使います。 たとえば、バージョン9.1.5では90105が返され、バージョン9.2.0では90200が返されます。

ですから、機能の互換性を見極めるのが目的なら、アプリケーションはPQserverVersionの結果を10000ではなく、100で割り、論理的なメジャーバージョンを求めるべきです。 すべてのリリースで、最後の2桁だけがマイナーリリースで異なります。 (バグ修正リリースです。)

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);

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

以下の関数はSSLに関連した情報を返します。 この情報は通常、接続の確立後には変更されません。

PQsslInUse

接続がSSLを使っていれば真(1)、使っていなければ偽(0)を返します。

int PQsslInUse(const PGconn *conn);

PQsslAttribute

接続におけるSSL関連の情報を返します。

const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);

利用可能な属性のリストは使用されているSSLライブラリおよび接続の種類に依存して変わります。 属性が利用可能でないときはNULLが返されます。

一般的には、以下の属性が利用可能です。

library

使用されているSSLの実装の名前です。 (現在は"OpenSSL"だけが実装されています。)

protocol

使用されているSSL/TLSのバージョンです。 一般的な値は、"TLSv1""TLSv1.1""TLSv1.2"ですが、他のプロトコルが使用されれば、異なる文字列が返されるかもしれません。

key_bits

暗号アルゴリズムで使用されている鍵のビット数です。

cipher

使用されている暗号スイートの短縮名、例えば"DHE-RSA-DES-CBC3-SHA"です。 この名前は各SSLの実装に固有のものです。

compression

SSL圧縮が使用されている場合、圧縮アルゴリズムの名前を返します。 圧縮は使われているがアルゴリズムが不明という場合を"on"を返します。 圧縮が使われていない場合は"off"を返します。

PQsslAttributeNames

利用可能なSSL属性名の配列を返します。 配列の最後のメンバにはNULLポインタが入ります。

const char * const * PQsslAttributeNames(const PGconn *conn);

PQsslStruct

接続を説明するSSLの実装に固有のオブジェクトへのポインタを返します。

void *PQsslStruct(const PGconn *conn, const char *struct_name);

利用可能な構造体は、使用されるSSLの実装に依存します。 OpenSSLでは、"OpenSSL"の名前の下に利用可能な構造体が1つあり、OpenSSLのSSL構造体へのポインタを返します。 この関数を使用するには、以下のようなプログラムが利用できます。

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

...

    SSL *ssl;

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

    ssl = PQsslStruct(dbconn, "OpenSSL");
    if (ssl)
    {
        /* sslにアクセスするためOpenSSLの関数を使う */
    }

この構造体は、暗号化レベルの確認、サーバ証明書の検証、その他に使用できます。 この構造体に関する情報についてはOpenSSLのドキュメントを参照して下さい。

PQgetssl

接続で使用されているSSLの構造体を返します。 SSLが使われていなければNULLを返します。

void *PQgetssl(const PGconn *conn);

この関数はPQsslStruct(conn, "OpenSSL")と同等です。 返される構造体はOpenSSLに固有のもので他のSSL実装が利用されていると使用できないので、新しく作成するアプリケーションでは使うべきではありません。 接続がSSLを使用しているかどうかを調べるには、代わりにPQsslInUseを呼び出して下さい。 また、接続に関するより詳細についてはPQsslAttributeを使って下さい。