31.1. データベース接続制御関数

新たにデータベースサーバへの接続を作成します。

PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);

この関数は、2つのNULL終端の配列から取得したパラメータを使用して、データベースとの接続を新たに1つ確立します。 1つ目は文字列配列として定義されるkeywordsで、それぞれがキーワードとなります。 2つ目はvaluesで、各キーワードの値を提供します。 後述のPQsetdbLoginとは異なり、関数のシグネチャを変更せずにパラメータ集合を拡張できますので、アプリケーションプログラムを新たに作成する際には、この関数(もしくは非ブロックモードでよく似た処理をするPQconnectStartParamsとPQconnectPoll)を使用することをお勧めします。

現在有効なパラメータキーワードを項31.1.2に示します。

expand_dbnameが非ゼロの場合、dbnameキーワードの値を接続文字列として認識させることができます。 最初に出現したdbnameだけがこのように展開され、後続のdbname値は通常のデータベース名として処理されます。 接続文字列の取り得る書式に関する詳細については項31.1.1を参照してください。

空の配列を渡してすべてデフォルトパラメータを使用することができます。 また渡される配列に1つ以上のパラメータ設定を持たせることもできます。 これらの長さは一致しなければなりません。 keywords配列の最初のNULL要素で処理は停止します。

パラメータがNULLや空文字列の場合には、対応する環境変数が検査されます（項31.14を参照してください）。 環境変数も設定されていない場合は、指定された組み込みのデフォルト値が使用されます。

一般的にキーワードはこれらの配列の先頭からインデックス順で処理されます。 この影響はキーワードが繰り返された場合で、最後に処理された値が残ることになります。 このため、dbnameキーワードの記述場所に注意することで、conninfo文字列により何が上書きされるか、何が上書きされないかを決定することができます。

新たにデータベースサーバへの接続を作成します。

PGconn *PQconnectdb(const char *conninfo);

この関数はconninfo文字列から取得されるパラメータを使用して、新しいデータベース接続を開きます。

空の文字列を渡してすべてデフォルトパラメータを使用することができます。 また空白文字で区切ることで1つ以上のパラメータ設定を持たせることもできます。 さらにURIを含めることができます。 詳細については項31.1.1を参照してください。

新たにデータベースサーバへの接続を作成します。

PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);

これはパラメータ群を固定したPQconnectdbの前身です。 設定できないパラメータが常にデフォルト値になる点を除き、同一の機能を持ちます。 固定のパラメータに対してNULLもしくは空文字列とすると、それはデフォルトを使用することになります。

dbName内に=記号が含まれる場合、または有効な接続URI接頭辞を持つ場合、PQconnectdbに渡された場合とまったく同じ扱いでconninfo文字列として扱われます。 その後残りのパラメータがPQconnectdbParamsの指定のように適用されます。

新たにデータベースサーバへの接続を作成します。

PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);

これは、loginとpwdにNULLポインタを設定するPQsetdbLoginを呼び出すマクロです。 非常に古いプログラムへの後方互換性のために提供されています。

ブロックしない方法で、データベースサーバへの接続を作成します。

PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                             int expand_dbname);

PGconn *PQconnectStart(const char *conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);

これら3つの関数は、リモートI/Oの実行時にアプリケーションスレッドの実行がブロックされないようなデータベースサーバへの接続を作成するために使われます。 この手法の利点は、I/Oの終了待ちがPQconnectdbParamsまたはPQconnectdb内部ではなく、アプリケーションプログラムのメインループでできることにあります。 これによって、アプリケーションは他の処理と並行してこの処理を管理することができます。

PQconnectStartParamsでは、上でPQconnectdbParamsで説明したように、データベース接続はkeywordsおよびvalues配列から取得され、expand_dbnameによって制御されたパラメータを使用して確立します。

PQconnectStartでは、上でPQconnectdbで説明したように、conninfo文字列から取得されたパラメータを使用してデータベース接続を確立します。

PQconnectStartParams、PQconnectStartとPQconnectPollのどちらも以下の制限に適合する場合ブロックしません。

• hostaddrとhostパラメータは、ホスト名からのIPアドレス検索やホスト名の逆引きが起こらないように適切に使用されなければいけません。 詳細に付いては項31.1.2内のパラメータ説明を参照してください。

• PQtraceを呼び出す場合は、トレースに使用するストリームオブジェクトがブロックされないことが保証されていなくてはなりません。

• プログラマ自身が、後に示すように、PQconnectPollを呼び出す前にソケットが適切な状態にあることを保証しなくてはいけません。

注意：PQconnectStartParamsの使用は後述のPQconnectStartと類似しています。

非ブロック接続要求を始めるにはまず、conn=PQconnectStart("connection_info_string")を呼び出します。 connがNULLの場合、libpqが新たにPGconn構造体を割り当てられなかったことを表します。 そうでない場合は、適切なPGconnへのポインタが返されます （ただし、データベースに正しく接続されていることを表しているわけではありません）。 PQconnectStartから値が返ってきた段階で、status=PQstatus(conn)を呼び出します。 もし、statusがCONNECTION_BADと等しい場合には、PQconnectStartが失敗しています。

PQconnectStartが成功したら、次は接続シーケンスを進めるために、libpqをポーリングします。 データベース接続の背後にあるソケットの記述子を取り出すには、PQsocket(conn)を使用します。 以下の繰り返しです。 直前のPQconnectPoll(conn)がPGRES_POLLING_READINGの場合、ソケットの読み込み準備が整うまで待機します。 （select()やpoll()などのシステム関数で示されます。） そして、再度PQconnectPoll(conn)を呼び出します。 反対に直前のPQconnectPoll(conn)がPGRES_POLLING_WRITINGの場合、ソケットの書き込み準備が整うまで待機し、その後、PQconnectPoll(conn)を再度呼び出します。 まだPQconnectPollを呼び出していない場合、つまり、PQconnectStartの呼び出し直後では、直前がPGRES_POLLING_WRITINGであった場合と同様の処理を行ないます。 この繰り返しをPQconnectPoll(conn)が、接続手続きの失敗を示すPGRES_POLLING_FAILED、もしくは、接続確立に成功したことを示すPGRES_POLLING_OKを返すまで継続します。

接続している間は、いつでもPQstatusを呼び出すことで、接続の状態を検査することができます。 この関数呼び出しがCONNECTION_BADを返す場合、接続手続きは失敗しており、CONNECTION_OKを返す場合、接続が確立しています。 上述のように、このいずれの状態も、PQconnectPollの戻り値から同様に検出できます。 これ以外の状態は、非同期の接続手続きの間（のみに）現れることがあります。 これらは、接続手続きの現在の段階を示すものであり、例えばユーザへのフィードバックを提供することに使用できます。 以下の状態があります。

これらの定数は（互換性を保つため）なくなることはありませんが、アプリケーションは、これらが特定の順で出現したり、本書に書いてある値のどれかに必ずステータス値が該当するということを決して当てにしてはいけません。 アプリケーションは、以下に示すようにするべきです。

switch(PQstatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}

PQconnectPollを使用する場合、connect_timeout接続パラメータは無視されます。 経過時間が長過ぎるかどうかの判定はアプリケーションの責任で行ないます。 さもないと、PQconnectStartの後のPQconnectPollの繰り返しがPQconnectdbと同じになります。

PQconnectStartが非NULLポインタを返した場合、処理を終了する際には、構造体や関連するメモリブロックを始末するために、PQfinishを呼び出さなくてはならないことに注意してください。 この処理は、接続試行が失敗した場合やその試行を中断する場合にも、必ず実行されなければいけません。

デフォルトの接続オプションを返します。

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* このオプションのキーワード */
    char   *envvar;    /* 代替となる環境変数の名前 */
    char   *compiled;  /* 代替となるコンパイル時に組み込まれたデフォルト値 */
    char   *val;       /* オプションの現在値、もしくは、NULL */
    char   *label;     /* 接続ダイアログ内の当該フィールドのラベル */
    char   *dispchar;  /* 接続ダイアログ内の当該フィールドをどのように表示するかの指示
                          値:
                          ""        入力された値をそのまま表示
                          "*"       値を隠すパスワードフィールド用
                          "D"       デバッグオプション。デフォルトで何も表示しません */
    int     dispsize;  /* ダイアログ用のフィールドの大きさ(文字数単位) */
} PQconninfoOption;

接続オプションの配列を返します。 これは、使用可能なPQconnectdb用オプションのすべてや、その時点でのデフォルト値を決定するために使用することができます。 戻り値は、PQconninfoOption構造体の配列へのポインタで、keywordポインタがヌルとなる項目が配列の末尾にきます。 メモリが確保できなかった場合にはヌルポインタを返します。 現在のデフォルト値(val フィールド）は、環境変数や他のコンテキストに依存します。 呼び出し側では、接続オプションの情報は、読み込み専用として取り扱わなければいけません。

オプションの配列を処理した後は、それをPQconninfoFreeに渡して解放します。 この処理をしないと、PQconndefaultsが呼び出されるたびに少しずつメモリリークが発生します。

所在する接続で使用される接続オプションを返します。

PQconninfoOption *PQconninfo(PGconn *conn);

接続オプション配列を返します。これは全ての可能性のあるPQconnectdbオプションとサーバに接続するのに使用される値を確定するために使用することができます。 返り値はPQconninfoOption構造体の配列を指し示します。それはnull keyword ポインタを持つ項目で終結します。PQconndefaultsに対する上記の全ての注釈はまたPQconninfoの結果に適用されます。

提供された接続文字列から構文解析された接続オプションを返します。

PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);

接続文字列の構文解析を行い、配列として結果オプションを返すか、または接続文字列に問題があった場合にNULLを返します。 この関数を提供された接続文字列の中のPQconnectdbオプションを取り出すために使用することができます。 戻り値はPQconninfoOption構造体の配列を指し示し、それはヌルのkeywordポインタを持つ項目で終結します。

正規なオプションはすべて、結果配列内に現れます。 しかし接続文字列内に現れない、何らかのオプション用のPQconninfoOptionはNULLに設定されたvalを持ちます。 デフォルトは挿入されません。

errmsgが非NULLであれば、成功した場合*errmsgはNULLに設定され、そうでなければ、問題を説明したmallocされたエラー文字列になります。 （*errmsgがNULLに設定され、かつ、この関数がNULLを返すこともあり得ます。 これはメモリ不足状態を意味します。）

オプション配列を処理した後、それをPQconninfoFreeに渡して解放してください。 これが行われない場合、PQconninfoParseへのそれぞれの呼び出しに対してメモリーリークが起こります。 反対に、エラーが起こり、そしてerrmsgが非NULLであれば、PQfreememを使用してエラー文字列を必ず解放してください。

サーバとの接続を閉ざします。 また、PGconnオブジェクトが占めるメモリも解放します。

void PQfinish(PGconn *conn);

たとえサーバへの接続試行が失敗しても（PQstatusで調べます）、アプリケーションはPQfinishを呼び出しPGconnオブジェクトが占めるメモリを解放するべきです。 そしてPQfinishを呼び出したら、もうPGconnへのポインタを使ってはいけません。

サーバへの通信チャンネルをリセットします。

void PQreset(PGconn *conn);

この関数はサーバへの接続を閉じ、以前使用したパラメータをすべて使用して、同一のサーバへ新しく接続を確立します。 これは、作業中の接続が失われた場合のエラーの修復に役立つでしょう。

非ブロッキング方式で、サーバへの接続チャンネルをリセットします。

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

これらの関数はサーバへの接続を閉じ、それから再度、以前使用したパラメータをすべて使用して、同じサーバと新たな接続を確立しようとします。 これらは作業中の接続が失われた場合のエラー修復に役立つでしょう。 PQreset（前述）との違いは、この2つの関数が非ブロック方式で動作することです。 また、これらの関数はPQconnectStartParams、PQconnectStartおよびPQconnectPollと同じ制限を受けます。

接続のリセットを始めるためにはPQresetStartを呼び出します。 この関数がゼロを返す場合、リセットに失敗しています。 戻り値が1ならば、PQconnectPollを使って接続を確立した時とまったく同じに、PQresetPollを使用してリセットのポーリングを行います。

PQpingParamsはサーバの状態を報告します。 この関数は上述のPQconnectdbParamsと同じ接続パラメータを受け付けます。 サーバの状態を得るために正しいユーザ名、パスワード、データベース名を提供する必要はありません。 しかし、不適切な値が供給されると、サーバは不成功に終わった接続の試みをログに残します。

PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);

このサーバは以下の値のいずれかを返します。

PQpingはサーバの状態を報告します。 この関数は上述のPQconnectdbと同じ接続パラメータを受け付けます。 サーバの状態を得るために正しいユーザ名、パスワード、データベース名を提供する必要はありません。 しかし、不適切な値が供給されると、サーバは不成功に終わった接続の試みをログに残します。 サーバの状態を入手するためには現在のユーザ名、パスワード、またはデータベース名などの値を供給する必要はありませんが、不適切な値が供給されると、サーバは不成功に終わった接続の試みをログに残します。

PGPing PQping(const char *conninfo);

戻り値はPQpingParamsと同じです。