これらの関数を使用して、既存のデータベース接続オブジェクトの状態を調べることができます。
libpqアプリケーションのプログラマは注意してPGconn
という抽象化を維持してください。
PGconn
の内容は以下に挙げるアクセス用関数を使って取り出してください。
PGconn
構造体中のフィールドは将来予告なく変更されることがありますので、libpq-int.h
を使用したフィールドの参照は避けてください。
以下の関数は、接続で確立したパラメータの値を返します。
これらの値は接続期間中固定されます。
複数ホストの接続文字列が使用されている場合、同じPGconn
オブジェクトを使用して新しい接続が確立されると、PQhost
、PQport
、PQpass
の値は変わる可能性があります。
他の変数は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);
host
とhostaddr
の両方が指定されると、PQhost
は、そのhost
情報を返します。
hostaddr
だけが指定されると、それが返されます。
接続パラメータ中に複数のホストが指定された場合には、PQhost
は実際に接続しているホストの情報を返します。
conn
引数がNULL
ならば、PQhost
はNULL
を返します。
そうでない場合、もしホスト情報の生成中エラーとなったら(おそらくコネクションがまだ完全には確立されていないか、なんらかのエラーがある場合です)、空文字が返ります。
接続パラメータ中に複数のホストが指定されると、接続が確立するまではPQhost
の結果を当てにすることはできません。
接続の状態は、PQstatus
関数で確認できます。
PQhostaddr
実際に接続したサーバIPアドレスを返します。
これはホスト名を解決したアドレス、あるいはhostaddr
パラメータ経由で与えられたIPアドレスになります。
char *PQhostaddr(const PGconn *conn);
conn
引数がNULL
ならば、PQhostaddr
はNULL
を返します。
そうでない場合、もしホスト情報の生成がエラーとなったら(おそらくコネクションがまだ完全には確立されていないか、なんらかのエラーがある場合です)、空文字が返ります。
PQport
実際に接続したポートを返します。
char *PQport(const PGconn *conn);
接続パラメータ中に複数のポートが指定された場合には、PQport
は実際に接続しているポートを返します。
conn
引数がNULL
ならば、PQport
はNULL
を返します。
そうでない場合、もしホスト情報の生成がエラーとなったら(おそらくコネクションがまだ完全には確立されていないか、なんらかのエラーがある場合です)、空文字が返ります。
接続パラメータ中に複数のポートが指定されると、接続が確立するまではPQport
の結果を当てにすることはできません。
接続の状態は、PQstatus
関数で確認できます。
PQtty
この関数はもう何もしませんが、後方互換性のために残っています。
この関数は常に空の文字列を返します。
conn
引数がNULL
の場合はNULL
を返します。
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
が報告されます。
PQparameterStatus
サーバの現在のパラメータ設定を検索します。
const char *PQparameterStatus(const PGconn *conn, const char *paramName);
あるパラメータ値は、接続開始時に、もしくは、その値が変更された時は常にサーバによって自動的に報告されます。
PQparameterStatus
はそれらの設定の調査に役立ちます。
パラメータの現在値がわかればその値を、わからない場合はNULL
を返します。
現在のリリースで報告されるパラメータには、server_version
、server_encoding
、client_encoding
、application_name
、default_transaction_read_only
、in_hot_standby
、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
が報告されませんでした。
14より前ではdefault_transaction_read_only
とin_hot_standby
が報告されませんでした。)
server_version
、server_encoding
およびinteger_datetimes
は起動後変更できないことに注意してください。
standard_conforming_strings
の値がないと報告された場合、アプリケーションはoff
と推測することができます。
つまり、バックスラッシュは文字リテラル中のエスケープ文字として扱います。
また、このパラメータが存在すると、エスケープ文字構文(E'...'
)が受付けられることを意味するものと取られます。
返されるポインタはconst
と宣言されていますが、実際にはPGconn
構造体に関連付けされた変化する領域を指し示します。
このポインタが諸問い合わせに渡って有効なままであるとみなすのは賢明ではありません。
PQprotocolVersion
使用されるフロントエンド/バックエンドプロトコルを調査します。
int PQprotocolVersion(const PGconn *conn);
ある機能がサポートされているかどうかを決定するために、アプリケーションはこの関数を使用することができます。 現在、取り得る値は3(3.0プロトコル)、あるいは0(接続不良)です。 このプロトコルバージョンは接続の開始が完了した後で変更することはできません。 しかし、理論的には接続のリセット時に変更可能です。 3.0プロトコルはPostgreSQLサーババージョン7.4以降でサポートされています。
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ライブラリおよび接続の種類によって異なります。 接続で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"を返します。
特殊なケースとして、library
属性は、conn
引数としてNULLを渡すことによって接続なしで照会することができます。
結果はデフォルトのSSLライブラリ名、またはlibpqがSSLサポートなしでコンパイルされた場合にNULLになります。
(PostgreSQLバージョン15より前では、conn
引数としてNULLを渡すと常にNULLになりました。
このケースの新しい実装と古い実装を区別する必要があるクライアントプログラムは、LIBPQ_HAS_SSL_LIBRARY_DETECTION
機能マクロをチェックしてください。)
PQsslAttributeNames
利用可能なSSL属性名の配列を返します。 配列の最後のメンバにはNULLポインタが入ります。
const char * const * PQsslAttributeNames(const PGconn *conn);
PQsslStruct
SSLの実装に固有な接続を説明するオブジェクトへのポインタを返します。 接続が暗号化されていないか、要求されたタイプのオブジェクトが接続のSSLの実装から利用できない場合はNULLを返します。
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
を使って下さい。