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

PGconn *PQconnectdb(const char *conninfo);

この関数は、conninfo 文字列から取得したパラメータを使用して、データベースとの接続を新たに1つ確立します。 後述の PQsetdbLogin とは異なり、関数のプロトタイプを変更せずにパラメータを拡張できますので、アプリケーションプログラムを作成する際には、このルーチン(もしくは非ブロックモードでよく似た処理をする PQconnectStartとPQconnectPoll )を使用することをお勧めします。

空の文字列を渡すことで、全てのパラメータはデフォルトを使用できます。 また、空白文字で区切ることで1つ以上のパラメータを設定することができます。 それぞれのパラメータは、keyword = value という形で設定します。 （空の値や空白文字を含む値を書く場合は、単一引用符で囲みます。 例えば、keyword = 'a value' といった具合です。 値中の単一引用符とバックスラッシュは \' や \\ というように、バックスラッシュでエスケープしなければなりません。) 等号の前後のスペースは、任意で付けられます。

現時点で有効なパラメータのキーワードは以下に示すとおりです。

パラメータが指定されなかった場合には、対応する環境変数がチェックされます （項27.10 を参照してください）。 環境変数も設定されていない場合は、組み込みのデフォルト値が使用されます。

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

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もしくは空文字列とすると、それはデフォルトを使用することになります。

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

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

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

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

PGconn *PQconnectStart(const char *conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);

これら2つの関数を使用して、リモートI/Oの実行時にアプリケーションスレッドの実行がブロックされないように、データベースサーバへの接続を作成します。

PQconnectStart に渡された conninfo 文字列からパラメータを取得し、データベース接続が確立されます。 この文字列は、上述の PQconnectdb の場合と同じ形式で記述されています。

PQconnectStart と PQconnectPoll は、以下の制限下ではブロックしません。

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

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

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

非ブロック接続を始めるにはまず、conn=PQconnectStart("connection_info_string") を呼び出します。 conn がヌルである場合、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 が非ヌルポインタを返した場合、処理を終了する際には、構造体や関連するメモリブロックを始末するために、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 が呼び出されるたびに少しずつメモリリークが発生します。

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

void PQfinish(PGconn *conn);

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

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

void PQreset(PGconn *conn);

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

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

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

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

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