PostgreSQL のバックエンドサーバとの接続を作成するには、以下のルーチンを使用します。 アプリケーションプログラムは、バックエンドとの接続を一度に複数個開くことができます （1 つの理由として、複数のデータベースへのアクセスが挙げられます）。 個々の接続は、PQconnectdb または PQsetdbLogin を呼び出すことで得られる PGconn オブジェクトによって表されます。 なおこれらの関数は、PGconn オブジェクトに割り当てるほんのわずかなメモリの余裕さえもない場合を除き、NULL ではなく常にオブジェクトのポインタを返します。 またこの接続オブジェクトを通じて問い合わせを送る前に、PQstatus 関数を呼び出して、データベースとの接続に成功したかどうかをチェックすべきでしょう。
PQconnectdb は新たにデータベースサーバとの接続を確立します。
PGconn *PQconnectdb(const char *conninfo)
このルーチンは、conninfo 文字列から取得したパラメータを使用して、データベースとの接続を新たに 1 つ確立します。 後述の PQsetdbLogin とは異なり、関数のプロトタイプを変更せずにパラメータを拡張できるので、アプリケーションプログラムを作成する際には、このルーチンか、もしくは非ブロックモードでよく似た処理をする PQconnectStart/PQconnectPoll を使用することをお勧めします。 空の文字列を渡すことで、全てのパラメータはデフォルトを使用できます。また、空白文字で区切ることで1つ以上のパラメータを設定することができます。
それぞれのパラメータは、keyword = value という形で設定します。 （空の値や空白文字を含む値を書く場合は、単一引用符で囲みます。例えば、keyword = 'a value' といった具合です。 値中の単一引用符とバックスラッシュは \' や \\ というように、バックスラッシュでエスケープしなければなりません)。 等号の前後のスペースは、任意で付けられます。 現時点で有効なパラメータのキーワードは以下に示すとおりです。
接続するホスト名を指定します。 この引数をスラッシュで始めた場合、TCP/IP による通信ではなく、Unix ドメインの通信を明示することになります。 host の値はソケットファイルが保存されているディレクトリの名前になります。 デフォルトでは、/tmp にある Unix ドメインのソケットに接続します。
接続するホストの IP アドレスを指定します。 これは、数字とピリオドを組み合わせた標準的な形式でなければなりません。BSD の inet_aton 関数やそれに相当するものが使用するものと同じ形式です。 長さが 0 でない文字列が指定されると、TCP/IP 通信が使用されます。
host の代わりに hostaddr を使用することで、アプリケーションがホスト名の検索をせずに済みます。 特に、時間に制約のあるアプリケーションでは、重要になるでしょう。 しかし、Kerberos 認証を行うアプリケーションでは、ホスト名が必要になります。 結局、以下のようになります。 hostaddr を使わずに host を指定した場合は、ホスト名からの IP アドレス検索が強制的に実行されます。 host 使わず、hostaddr を指定した場合、hostaddr はリモートマシンの IP アドレスとなります。 このとき、Kerberos を使用している場合は、IP アドレスからホスト名の逆引きが行われます。 host と hostaddr の両方を指定した場合、hostaddr がリモートマシンの IP アドレスとなります。 このとき、Kerberos が使用されていない場合は host に与えられた値は無視され、使用されている場合は Kerberos 認証に host の値が使用されます。 libpq に渡されたホスト名が、hostaddr に対応するマシンの名前と一致しない場合は、認証に失敗する可能性があるので、注意してください。
ホスト名もホストのアドレスも用いない場合、libpq はローカルの Unix ドメインのソケットを使用して接続します。
サーバホストでの接続用のポート番号、または、Unix ドメイン接続の場合は、ソケットファイルの拡張子を指定します。
データベース名を指定します。
データベースへ接続するユーザ名を指定します。
サーバがパスワードによる認証を必要とした場合に使用されるパスワードを指定します。
接続ルーチンに与える時間を秒数で指定します。ゼロまたは設定なしは無限を意味します。
サーバに送る、トレース / デバッグオプションを指定します。
バックエンドからのデバッグ出力のためのファイル、または tty を指定します。
1に設定することで、サーバへのSSL 接続が必要になります。 サーバがSSL 接続を受け付けない場合、Libpq は接続を拒絶します。 0(デフォルト)に設定することで、サーバと調停を行います。 SSLサポート付きでPostgreSQLをコンパイルした場合にのみ、このオプションが利用できます。
パラメータが指定されなかった場合には、該当する環境変数がチェックされます （Section 1.10 を参照）。 環境変数も設定されていない場合は、環境に組み込みのデフォルト値が使用されます。戻り値は、バックエンドとの接続を表す、抽象的な 構造体 へのポインタです。
PQsetdbLogin は新たにデータベースサーバとの接続を確立します。
PGconn *PQsetdbLogin(const char *pghost,
const char *pgport,
const char *pgoptions,
const char *pgtty,
const char *dbName,
const char *login,
const char *pwd)これは、PQconnectdb の前にあったもので、パラメータの数が固定ですが、機能的には同じものです。
PQsetdb は新たにデータベースサーバとの接続を確立します。
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName)これは PQsetdbLogin を、login と pwd パラメータに NULL ポインタを指定して呼び出すマクロです。 これは主に古いプログラムとの互換性を提供するものです。
PQconnectStart、PQconnectPoll は非ブロック形式でデータベースサーバとの接続を確立します。
PGconn *PQconnectStart(const char *conninfo)
PostgresPollingStatusType PQconnectPoll(PGconn *conn)
これら 2 つのルーチンを使用すると、ネットワーク経由の入出力処理をしている間もアプリケーションの実行スレッドがブロックされないように、データベースサーバとの接続を開始することができます。
PQconnectStart に渡された conninfo 文字列からパラメータを取得し、データベース接続が確立されます。 この文字列は、上述の PQconnectdb の場合と同じ形式で記述されています。
PQconnectStart と PQconnectPoll は、以下の制限下ではブロックしません。
hostaddr と host パラメータは、ホスト名からの IP アドレス検索やホスト名の逆引きが起こらないように適切に使用されなければいけません。 これらのパラメータについての詳細は、前述の PQconnectdb の節を参照してください。
PQtrace を呼び出す場合は、トレースに使用するストリームオブジェクトがブロックされないことが保証されていなくてはなりません。
プログラマ自身が、後に示すように、PQconnectPoll を呼び出す前にソケットが適切な状態にあることを保証しなくてはいけません。
まず始めに、conn=PQconnectStart("connection_info_string") を呼び出します。 conn が NULL である場合、libpq が新たに PGconn 構造体を割り当てられなかったことを表します。 そうでない場合は、適切な PGconn へのポインタが返されます（ただし、データベースに正しく接続されていることを表しているわけではありません）。 PQconnectStart から値が返ってきた段階で、status=PQstatus(conn) を呼び出します。 もし、status が CONNECTION_BAD と等しい場合には、PQconnectStart が失敗しています。
PQconnectStart が成功したら、次は接続シーケンスを進めるために、libpq をポーリングします。 以下のくり返しです。 接続はデフォルトでは "非アクティブ" 状態だと判断されます。 もし、直前の PQconnectPoll が PGRES_POLLING_ACTIVE を返したら、接続が "アクティブ" 状態だと判断します。 もし、直前の PQconnectPoll(conn) が PGRES_POLLING_READING を返したら、PQsocket(conn) での読み込みをチェックする select() を実行します。 もし返り値が PGRES_POLLING_WRITING であれば、PQsocket(conn) での書き込みをチェックする select() を実行します。 また PQconnectPoll をまだ呼び出していないとき、つまり、PQconnectStart を呼び出した後は、直前の返り値が PGRES_POLLING_WRITING の場合と同じようにします。 select() を実行した結果、ソケットの準備ができているようであれば、接続が "アクティブ" になったと思ってください。 接続が "アクティブ" になったと判断されたら、もう一度 PQconnectPoll(conn) を呼び出します。 もし、この返り値が PGRES_POLLING_FAILED の場合は、接続プロシージャは失敗しています。 PGRES_POLLING_OK の場合は、接続に成功しています。
ソケットの準備ができたことを保証するために select() が実行されるのは、単純な例（のようなもの）であることに注意してください。 他の機能を持ったもの （例えば poll() 呼び出し） が使用できるのであれば、そちらを使用することができます。
接続している間は、いつでも PQstatus を呼び出すことで、接続の状態をチェックすることができます。 もし、CONNECTION_BAD であるならば、接続プロシージャは失敗しており、CONNECTION_OK なら、成功しています。 上述のように、このいずれの状態も、PQconnectPoll の戻り値から同様に検出できます。 これ以外の状態は、非同期の接続プロシージャの間（のみに）現れることがあります。 これらは、接続プロシージャの現在の段階を示すものであり、例えばユーザへのフィードバックを提供することに使用できます。 以下のステータスがあります。
接続が確立するのを待っています。
接続は OK です。 送信されるのを待っています。
サーバからの応答を待っています。
認証済みです。 バックエンドが起動するのを待っています。
環境とやりとりしています (接続開始処理の一部です)。
これらの定数は消えることはありません （互換性を保つため） が、アプリケーションは、これらが特定の順で出現したり、ドキュメントに書いてある値のどれかに必ずステータス値が該当するということを決して当てにしてはいけません。 アプリケーションは、以下に示すようにするべきです。
switch(PQstatus(conn))
{
case CONNECTION_STARTED:
feedback = "Connecting...";
break;
case CONNECTION_MADE:
feedback = "Connected to server...";
break;
.
.
.
default:
feedback = "Connecting...";
}
PQconnectStart が NULL でないポインタを返した場合、処理を終了する際には、構造体や関連するメモリブロックを始末するために、PQfinish を呼び出さなくてはいけません。 この処理は、PQconnectStart や PQconnectPoll の呼び出しに失敗した場合にも、必ず実行されなければいけません。
libpq が USE_SSL を定義してコンパイルされた場合、現在は PQconnectPoll は使用できません。 この制限はなくなる予定です。
これらの関数は、あたかも PQsetnonblocking が呼び出されたかのように、非ブロック状態のソケットを残します。
PQconndefaults はデフォルトの接続オプションを返します。
PQconninfoOption *PQconndefaults(void)
struct PQconninfoOption
{
char *keyword; /* オプションのキーワード */
char *envvar; /* 代替となる環境変数の名前 */
char *compiled; /* コンパイル時に組み込まれた代替となるデフォルト値 */
char *val; /* オプションの現在値か NULL */
char *label; /* 接続ダイアログの当該フィールドのラベル */
char *dispchar; /* 接続ダイアログの当該フィールドに表示する文字
値：
"" 入力されたとおりの文字列を表示
"*" パスワードフィールド：値を隠す
"D" デバッグ用オプション：デフォルトでは表示されない */
int dispsize; /* ダイアログ上のフィールドの大きさ （文字数） */
}接続オプションの配列を返します。 これは、使用可能な PQconnectdb のオプションのすべてや、その時点でのデフォルト値を決定するために使用することができます。戻り値は、PQconninfoOption 構造体 の配列へのポインタで、keyword ポインタが NULL となる項目が配列の末尾にきます。 (val フィールドの）デフォルト値は、環境変数や他のコンテキストに依存します。 呼び出し側では、接続オプションの情報は、読み込み専用として取り扱わなければいけません。
オプションの配列を処理した後は、PQconninfoFree を使用して解放します。 この処理をしないと、PQconndefaults が呼び出されるたびに少しずつメモリを浪費します。
バージョン 7.0 よりも前の PostgreSQL では、PQconndefaults は動的に割り当てられた配列ではなく、静的な配列へのポインタを返していました。 これはスレッドセーフではなかったので、変更されました。
PQfinish はバックエンドとの接続を閉じます。 同時に PGconn オブジェクトに使われていたメモリを解放します。
void PQfinish(PGconn *conn)
たとえバックエンドとの接続が失敗したとしても（PQstatus で調べます）、アプリケーションは PQfinish を呼び出し PGconn オブジェクトが占めるメモリを解放するべきです。 そして PQfinish を呼び出したら、もう PGconnへのポインタを使ってはいけません。
PQreset はバックエンドとの通信用ポートをリセットします。
void PQreset(PGconn *conn)
この関数はバックエンドとの接続を閉じ、それから再度同じサーバと新たな接続を確立しようとします。 パラメータは前回と同じものを使います。これらは稼働中の接続が失われた場合のエラーリカバリに役立つでしょう。
PQresetStart PQresetPoll ブロックしない方法で、バックエンドとの通信用ポートをリセットします。
int PQresetStart(PGconn *conn);
PostgresPollingStatusType PQresetPoll(PGconn *conn);
これらの関数はバックエンドとの接続を閉じ、それから再度同じサーバと新たな接続を確立しようとします。 パラメータは前回と同じものを使います。これらは稼働中の接続が失われた場合のエラーリカバリに役立つでしょう。 PQreset（前述） との違いは、この 2 つの関数が非ブロック作法で動作することです。 また、PQconnectStart や PQconnectPoll と同じ制限を受けます。
PQresetStart を呼び出して、0 が返される場合、リセットに失敗しています。 戻り値が 1 ならば、PQconnectPoll を使って接続を確立したときと同じように、PQresetPoll を使用してリセットをします。
libpq アプリケーションプログラマは PGconn による抽象化に注意を払うべきです。 PGconn の内容は以下に挙げるアクセッサ関数を使って取り出してください。 PGconn 構造体中のフィールドは将来予告なく変更されることがありますので、直接フィールドを参照することは避けてください。（PostgreSQL リリース 6.4 から、PGconn 構造体 の定義を libpq-fe.h の中から外しました。 以前作成したプログラムが PGconn のフィールドを直接操作している場合、libpq-int.h をインクルードすれば使い続けることができます。 しかしそのプログラムは是非とも修正してください。）
PQdb その接続のデータベース名を返します。
char *PQdb(const PGconn *conn)
PQdb と以下のいくつかの関数は、接続時に確定される値を返します。 これらの値は PGconn オブジェクトの寿命の間一定です。
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 を返します。
char *PQtty(const PGconn *conn)
PQoptions その接続で使用されるバックエンドオプションを返します。
char *PQoptions(const PGconn *conn)
PQstatus その接続のステータスを返します。
ConnStatusType PQstatus(const PGconn *conn)
ステータスは、数多くの値の中の 1 つをとります。 しかし、CONNECTION_OK と CONNECTION_BAD の 2 つのステータス値だけは、非同期の接続プロシージャの側面を見せます。 データベースへの接続が良好なときはステータスが CONNECTION_OK となります。 接続の失敗は、CONNECTION_BAD で通知されます。 通常、OK ステータスは、PQfinish が呼び出されるまで残りますが、バックエンドとの通信失敗によって、その前にステータスが途中で CONNECTION_BAD に変わることがあります。 そのような場合、アプリケーションで PQreset を呼び出すことで、復旧を試みることができます。
他の表示される可能性のあるステータスコードについては、PQconnectStart と PQconnectPoll の節を参照してください。
PQerrorMessage 接続操作において生成された最も新しいエラーメッセージを返します。
char *PQerrorMessage(const PGconn* conn);
ほぼすべての libpq 関数は動作に失敗したとき PQerrorMessageの内容を設定します。なお PQerrorMessage は libpq の慣習に従い、空文字列でなければ末尾に改行を含みます。
PQbackendPID 接続を処理するバックエンドサーバのプロセス ID を返します。
int PQbackendPID(const PGconn *conn);
バックエンドの PID は、デバッグする場合や通知（NOTIFY）メッセージ （これは通知を発行したバックエンドの PID を含んでいます） の比較に便利です。 この PID はデータベースサーバホスト上で実行されているプロセスのものであり、ローカルホスト側のものではありません！ 注意してください。
PQgetssl その接続で使用されている SSL 構造体を返します。 SSL が使用されていない場合は、NULL を返します。
SSL *PQgetssl(const PGconn *conn);
この構造体は、暗号化のレベルの照合やサーバの認証のチェックなどに役立ちます。 この構造体については、SSL のドキュメントを参照してください。
この関数のプロトタイプを得るには、USE_SSL を定義してください。 こうすると、OpenSSL の ssl.h も自動的にインクルードされます。