データベース接続関数

5) The following routines deal with making a connection to a Postgres backend server. The application program can have several backend connections open at one time. (One reason to do that is to access more than one database.) Each connection is represented by a PGconn object which is obtained from PQconnectdb() or PQsetdbLogin(). NOTE that these functions will always return a non-null object pointer, unless perhaps there is too little memory even to allocate the PGconn object. The PQstatus function should be called to check whether a connection was successfully made before queries are sent via the connection object.

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

• PQsetdbLogin 6) Makes a new connection to a backend. バックエンドとの接続を新たに確立します．

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

  7) If any argument is NULL, then the corresponding environment variable (see "Environment Variables" section) is checked. If the environment variable is also not set, then hardwired defaults are used. The return value is a pointer to an abstract struct representing the connection to the backend. もし引数のいずれかが NULL であった場合， 対応する環境変数を探します（「環境変数」セクションを参照）． 環境変数も設定されていなければシステムデフォルトの値が使われます． 戻り値はバックエンドへの接続を表現する抽象的な構造体へのポインタです．

• PQsetdb 8) Makes a new connection to a backend. バックエンドとの接続を新たに確立します．

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

  9) This is a macro that calls PQsetdbLogin() with null pointers for the login and pwd parameters. It is provided primarily for backward compatibility with old programs. これは login と pwd 引数に NULL を設定して PQsetdblogin() を呼び出す マクロです．これはそもそも古いプログラムに対する後方互換性のために 用意したものです．

• PQconnectdb 10) Makes a new connection to a backend. バックエンドとの接続を新たに確立します．

  PGconn *PQconnectdb(const char *conninfo)

  11) This routine opens a new database connection using parameters taken from a string. Unlike PQsetdbLogin(), the parameter set can be extended without changing the function signature, so use of this routine is encouraged for new application programming. The passed string can be empty to use all default parameters, or it can contain one or more parameter settings separated by whitespace. Each parameter setting is in the form keyword = value. (To write a null value or a value containing spaces, surround it with single quotes, eg, keyword = 'a value'. Single quotes within the value must be written as \'. Spaces around the equal sign are optional.) The currently recognized parameter keywords are: このルーチンは，単一の文字列で与えられるパラメータを取ります． PQsetdbLogin() と違い，関数の書式を変えなくともパラメータセットを 拡張することができます．ですから，新しくアプリケーションを作成する 場合にはこのルーチンの使用をお勧めします． パラメータすべてをデフォルトの値とするのなら，渡す文字列は 空文字列でかまいません．そうでなければ，空白で区切った 一つ以上のパラメータ設定を含むのとします．個々のパラメータ設定は 「キーワード = 値」の形式です．（空文字列，あるいは空白を含む値を 記述する場合は，値を「キーワード =' 値 1' 」のように，シングル クオートで囲んでください．値として含まれるシングルクオートは， \' とエスケープして記述しなければなりません． 等号の前後のスペースはあってもなくても構いません） 現在認識されるパラメータは以下の通りです：

  • 12) host -- host to connect to. If a non-zero-length string is specified, TCP/IP communication is used. Without a host name, libpq will connect using a local Unix domain socket.

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

  • 13) port -- port number to connect to at the server host, or socket filename extension for Unix-domain connections.

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

  • 14) dbname -- database name.

    dbname -- データベース名

  • 15) user -- user name for authentication.

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

  • 16) password -- password used if the backend demands password authentication.

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

  • 17) authtype -- authorization type. (No longer used, since the backend now chooses how to authenticate users. libpq still accepts and ignores this keyword for backward compatibility.)

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

  • 18) options -- trace/debug options to send to backend.

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

  • 19) tty -- file or tty for optional debug output from backend.

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

  20) Like PQsetdbLogin, PQconnectdb uses environment variables or built-in default values for unspecified options. PQconnectdb も PQsetdbLogin と同様，指定のないオプションに対して 環境変数かシステムにコーディングされたデフォルト値を使います．

• PQconndefaults 21) Returns the default connection options. 接続オプションのデフォルト値を返します．

  PQconninfoOption *PQconndefaults(void)
  
  
  22)
  struct PQconninfoOption
          {
                  char   *keyword;   /* The keyword of the option */
                  char   *envvar;    /* Fallback environment variable name */
                  char   *compiled;  /* Fallback compiled in default value */
                  char   *val;       /* Option's value */
                  char   *label;     /* Label for field in connect dialog */
                  char   *dispchar;  /* Character to display for this field
                                        in a connect dialog. Values are:
                                        ""        Display entered value as is
                                        "*"       Password field - hide value
                                        "D"       Debug options - don't
                                        create a field by default */
                  int     dispsize;  /* Field size in characters for dialog */
          };
  
  struct PQconninfoOption
          {
                  char   *keyword;   /* オプションのキーワード */
                  char   *envvar;    /* 代替となる環境変数の名前 */
                  char   *compiled;  /* コンパイル時に組み込まれた
                                        代替となるデフォルト値 */
                  char   *val;       /* オプションの値 */
                  char   *label;     /* 接続ダイアログの当該フィールドのラベル */
                  char   *dispchar;  /* 接続ダイアログの当該フィールドに表示
                                        する文字
                                        値 :
                                        ""        入力された通りの文字列を表示
                                        "*"       パスワードフィールド：値を隠す
                                        "D"       デバッグ用オプション - 
                                        デフォルトではフィールドを作成しない */
                  int     dispsize;  /* ダイアログ上のフィールドのサイズ（文字数）*/
          };
  

  23) Returns the address of the connection options structure. This may be used to determine all possible PQconnectdb options and their current default values. The return value points to an array of PQconninfoOption structs, which ends with an entry having a NULL keyword pointer. Note that the default values ("val" fields) will depend on environment variables and other context. Callers must treat the connection options data as read-only. 接続オプション構造体のアドレスを返します．これは PQconnectdb の可能な全てのオプションと，現在のデフォルト値を確認するために使います． 戻り値は PQconninfoOption 構造体の配列を指すアドレスで，配列は keyword が NULL のエントリで終ります． デフォルト値 ("val" フィールド）は環境変数や， その他の状況に依存します． 呼び出し側はオプション値をリードオンリーで扱わなければなりません．

• PQfinish 24) Close the connection to the backend. Also frees memory used by the PGconn object. バックエンドとの接続を閉じます．同時に PGconn オブジェクトに使われていたメモリを開放します．

  void PQfinish(PGconn *conn)

  25) Note that even if the backend connection attempt fails (as indicated by PQstatus), the application should call PQfinish to free the memory used by the PGconn object. The PGconn pointer should not be used after PQfinish has been called. たとえ PQstatus がバックエンドとの接続の失敗を示したとしても， アプリケーションは PQfinish を呼び出し PGconn オブジェクトが占めるメモリを開放するべきです． そして PQfinish を呼び出したら，もう PGconn へのポインタを使ってはいけません．

• PQreset 26) Reset the communication port with the backend. バックエンドとのコミュニケーションポートをリセットします．

  void PQreset(PGconn *conn)

  27) This function will close the connection to the backend and attempt to reestablish a new connection to the same postmaster, using all the same parameters previously used. This may be useful for error recovery if a working connection is lost. この関数はバックエンドとの接続を閉じ，それから再度同じ postmaster と新たな接続を確立しようとします．パラメータは前回と同じものを使います． これは稼働中の接続が失われた場合のエラーリカバリに役立つでしょう．

28) libpq application programmers should be careful to maintain the PGconn abstraction. Use the accessor functions below to get at the contents of PGconn. Avoid directly referencing the fields of the PGconn structure because they are subject to change in the future. (Beginning in Postgres release 6.4, the definition of struct PGconn is not even provided in libpq-fe.h. If you have old code that accesses PGconn fields directly, you can keep using it by including libpq-int.h too, but you are encouraged to fix the code soon.)

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

• PQdb 29) Returns the database name of the connection. 当該接続のデータベース名を返します．

  char *PQdb(PGconn *conn)

  30) PQdb and the next several functions return the values established at connection. These values are fixed for the life of the PGconn object. PQdb と以下のいくつかの関数は，接続時に確定した値を返します． これらの値は PGconn オブジェクトの寿命の間一定です．

• PQuser 31) Returns the user name of the connection. 当該接続のユーザ名を返します．

  char *PQuser(PGconn *conn)

• PQpass 32) Returns the password of the connection. 当該接続のパスワードを返します．

  char *PQpass(PGconn *conn)

• PQhost 33) Returns the server host name of the connection. 当該接続のサーバホスト名を返します．

  char *PQhost(PGconn *conn)

• PQport 34) Returns the port of the connection. 当該接続のポート番号を返します．

  char *PQport(PGconn *conn)

• PQtty 35) Returns the debug tty of the connection. 当該接続のデバッグ用 tty を返します．

  char *PQtty(PGconn *conn)

• PQoptions 36) Returns the backend options used in the connection. 当該接続のバックエンドオプションを返します．

  char *PQoptions(PGconn *conn)

• PQstatus 37) Returns the status of the connection. The status can be CONNECTION_OK or CONNECTION_BAD. 当該接続のステータスを返します． このステータスは CONNECTION_OK か CONNECTION_BAD となります．

  ConnStatusType PQstatus(PGconn *conn)

  38) A failed connection attempt is signaled by status CONNECTION_BAD. Ordinarily, an OK status will remain so until PQfinish, but a communications failure might result in the status changing to CONNECTION_BAD prematurely. In that case the application could try to recover by calling PQreset.

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

• PQerrorMessage 39) Returns the error message most recently generated by an operation on the connection. 当該接続で最後に出力された操作上のエラーメッセージを返します．

  char *PQerrorMessage(PGconn* conn);

  40) Nearly all libpq functions will set PQerrorMessage if they fail. Note that by libpq convention, a non-empty PQerrorMessage will include a trailing newline.

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

• PQbackendPID 41) Returns the process ID of the backend server handling this connection. 当該接続を維持するバックエンドサーバのプロセス ID を返します．

  int PQbackendPID(PGconn *conn);

  42) The backend PID is useful for debugging purposes and for comparison to NOTIFY messages (which include the PID of the notifying backend). Note that the PID belongs to a process executing on the database server host, not the local host! バックエンドのプロセス ID はデバッグする場合，それと通知 (NOTIFY) メッセージの 比較（これは通知を発行したバックエンドのプロセス ID を含んでいます）に便利です． このプロセス ID はデータベースサーバ上で実行されているプロセスのものであり， ローカルホスト側のものではありません！　注意してください．