データベース接続関数

Postgres バックエンドサーバ との接続は以下のルーチンが処理します．アプリケーションはバックエンドへの 接続を同時に複数持つことが可能です．（このようなことをする 事情のひとつとして，複数のデータベースへのアクセスが挙げられます） 個々の接続は PQconnectdb() または PQsetdblogin() を呼び出すと得られる， PGConn オブジェクトによって表されます．なおこれらの関数はわずかでも PGconn オブジェクトを割り当てるメモリの余裕があれば，NULL ではなく常に オブジェクトのポインタを返します． またこのコネクションオブジェクトを通じて問い合わせを送る前に，接続が 成功したかどうか PQstatus 関数で確認しておくべきでしょう．

• PQsetdbLogin バックエンドとの接続を新たに確立します．

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

  もし引数のいずれかが NULL であった場合， 対応する環境変数を探します（「環境変数」セクションを参照）． 環境変数も設定されていなければシステムデフォルトの値が使われます． 戻り値はバックエンドへの接続を表現する抽象的な構造体へのポインタです．

• PQsetdb バックエンドとの接続を新たに確立します．

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

  これは login と pwd 引数に NULL を設定して PQsetdblogin() を呼び出す マクロです．これはそもそも古いプログラムに対する後方互換性のために 用意したものです．

• PQconnectdb バックエンドとの接続を新たに確立します．

  PGconn *PQconnectdb(const char *conninfo)

  このルーチンは，単一の文字列で与えられるパラメータを取ります． PQsetdbLogin() と違い，関数の書式を変えなくともパラメータセットを 拡張することができます．ですから，新しくアプリケーションを作成する 場合にはこのルーチンの使用をお勧めします． パラメータすべてをデフォルトの値とするのなら，渡す文字列は 空文字列でかまいません．そうでなければ，空白で区切った 一つ以上のパラメータ設定を含むのとします．個々のパラメータ設定は 「キーワード = 値」の形式です．（空文字列，あるいは空白を含む値を 記述する場合は，値を「キーワード =' 値 1' 」のように，シングル クオートで囲んでください．値として含まれるシングルクオートは， \' とエスケープして記述しなければなりません． 等号の前後のスペースはあってもなくても構いません） 現在認識されるパラメータは以下の通りです：

  • host -- 接続先ホスト 長さが 0 でない文字列が指定された場合，TCP/IP で接続します． ホスト名を省略した場合は，libpq はローカルの UNIX ドメインソケットを使って 接続しようとします．

  • port -- サーバホストのポート番号，または UNIX ドメインの 接続の場合はソケットファイルの拡張子

  • dbname -- データベース名

  • user -- 認証に使うユーザ名

  • password -- バックエンドがパスワード認証を必要とした場合に使われるパスワード

  • authtype -- 認証タイプ（現在はバックエンドが認証 方法を選択するのでこれは使われなくなっています． libpq は後方互換性のためにこのパラメータを受け取りますが，内容は無視します）

  • options -- バックエンドに送るトレース／デバッグオプション

  • tty -- バックエンドからのデバッグ出力のためのファイル， または tty

  PQconnectdb も PQsetdbLogin と同様，指定のないオプションに対して 環境変数かシステムにコーディングされたデフォルト値を使います．

• PQconndefaults 接続オプションのデフォルト値を返します．

  PQconninfoOption *PQconndefaults(void)
  
  
  struct PQconninfoOption
          {
                  char   *keyword;   /* オプションのキーワード */
                  char   *envvar;    /* 代替となる環境変数の名前 */
                  char   *compiled;  /* コンパイル時に組み込まれた
                                        代替となるデフォルト値 */
                  char   *val;       /* オプションの値 */
                  char   *label;     /* 接続ダイアログの当該フィールドのラベル */
                  char   *dispchar;  /* 接続ダイアログの当該フィールドに表示
                                        する文字
                                        値 :
                                        ""        入力された通りの文字列を表示
                                        "*"       パスワードフィールド：値を隠す
                                        "D"       デバッグ用オプション - 
                                        デフォルトではフィールドを作成しない */
                  int     dispsize;  /* ダイアログ上のフィールドのサイズ（文字数）*/
          };
  

  接続オプション構造体のアドレスを返します．これは PQconnectdb の可能な全てのオプションと，現在のデフォルト値を確認するために使います． 戻り値は PQconninfoOption 構造体の配列を指すアドレスで，配列は keyword が NULL のエントリで終ります． デフォルト値 ("val" フィールド）は環境変数や， その他の状況に依存します． 呼び出し側はオプション値をリードオンリーで扱わなければなりません．

• PQfinish バックエンドとの接続を閉じます．同時に PGconn オブジェクトに使われていたメモリを開放します．

  void PQfinish(PGconn *conn)

  たとえ PQstatus がバックエンドとの接続の失敗を示したとしても， アプリケーションは PQfinish を呼び出し PGconn オブジェクトが占めるメモリを開放するべきです． そして PQfinish を呼び出したら，もう PGconn へのポインタを使ってはいけません．

• PQreset バックエンドとのコミュニケーションポートをリセットします．

  void PQreset(PGconn *conn)

  この関数はバックエンドとの接続を閉じ，それから再度同じ postmaster と新たな接続を確立しようとします．パラメータは前回と同じものを使います． これは稼働中の接続が失われた場合のエラーリカバリに役立つでしょう．

libpq アプリケーションプログラマは PGconn による抽象化に注意を払うべきです． PGconn の内容は以下に挙げるアクセッサ関数を使って取り出してください． PGconn 構造体中のフィールドは将来予告なく変更されることがあります． ですから直接フィールドを参照することは避けてください． （Postgres リリース 6.4 の初期の段階から， PGconn 構造体の定義を libpq-fe.h の中から外しました） 以前作成したプログラムが PGconn のフィールドを直接操作している場合， libpq-int.h をインクルードすれば使い続けることができます． しかしそのプログラムは是非とも修正してください．

• PQdb 当該接続のデータベース名を返します．

  char *PQdb(PGconn *conn)

  PQdb と以下のいくつかの関数は，接続時に確定した値を返します． これらの値は PGconn オブジェクトの寿命の間一定です．

• PQuser 当該接続のユーザ名を返します．

  char *PQuser(PGconn *conn)

• PQpass 当該接続のパスワードを返します．

  char *PQpass(PGconn *conn)

• PQhost 当該接続のサーバホスト名を返します．

  char *PQhost(PGconn *conn)

• PQport 当該接続のポート番号を返します．

  char *PQport(PGconn *conn)

• PQtty 当該接続のデバッグ用 tty を返します．

  char *PQtty(PGconn *conn)

• PQoptions 当該接続のバックエンドオプションを返します．

  char *PQoptions(PGconn *conn)

• PQstatus 当該接続のステータスを返します． このステータスは CONNECTION_OK か CONNECTION_BAD となります．

  ConnStatusType PQstatus(PGconn *conn)

  CONNECTION_BAD ステータスは接続の失敗を示します． CONNECTION_OK ステータスは通常 PQfinish 実行まで維持されますが， 通信の障害により，早まってステータスが CONNECTION_BAD に変わる かもしれません．このような場合は，アプリケーション側で PQreset を呼び出せば復旧することができます．

• PQerrorMessage 当該接続で最後に出力された操作上のエラーメッセージを返します．

  char *PQerrorMessage(PGconn* conn);

  ほぼすべての libpq 関数は動作に失敗したとき PQerrorMessage の内容を設定します． なお PQerrorMessage は libpq の慣習に従い，空文字列でなければ末尾に改行を含みます．

• PQbackendPID 当該接続を維持するバックエンドサーバのプロセス ID を返します．

  int PQbackendPID(PGconn *conn);

  バックエンドのプロセス ID はデバッグする場合，それと通知 (NOTIFY) メッセージの 比較（これは通知を発行したバックエンドのプロセス ID を含んでいます）に便利です． このプロセス ID はデータベースサーバ上で実行されているプロセスのものであり， ローカルホスト側のものではありません！　注意してください．