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

PostgreSQL 9.1.1文書
前のページ | 巻戻し | 第 31章libpq - C ライブラリ | 早送り | 次のページ

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

PostgreSQLのバックエンドサーバとの接続を作成するには、以下の関数を使用します。 アプリケーションプログラムはバックエンドとの接続を一度に複数個開くことができます。 （1つの理由として、複数のデータベースへのアクセスが挙げられます。） 個々の接続は、`PQconnectdb`、`PQconnectdbParams`または`PQsetdbLogin`関数を呼び出すことで得られる`PGconn`オブジェクトによって表されます。 なお、これらの関数は、`PGconn`オブジェクトに割り当てるほんのわずかなメモリの余裕さえもない場合を除き、NULLではなく常にオブジェクトのポインタを返します。 また、この接続オブジェクトを通じて問い合わせを送る前に、`PQstatus`関数を呼び出して、データベースとの接続に成功したかどうかを検査しなければなりません。

警告
Unix上で、libpq接続を開いたプロセスのフォークは、親と子のプロセスが同じソケットとオペレーティングシステムの資源を共有するため、予期せぬ結果を招くことがあります。 この理由により、新規実行形式を子プロセスが読み込むため`exec`を行うことが安全と言っても、このような使用法は推奨されません。

> 注意: Windowsでは、単一のデータベース接続が反復して開始と終了を繰り返す場合、性能を向上させる方法があります。 内部的には、接続開始と終了に対して、libpqはそれぞれ`WSAStartup()`と`WSACleanup()`を呼び出します。 `WSAStartup()`は`WSACleanup()`で値が減少させられた内部Windowsライブラリ参照カウントを増加させます。 参照カウントがたった１の場合、`WSACleanup()`呼び出しは全てのリソースを解放し、全てのDLLはアンロードされます。 これは高価な操作です。 これを回避するには、最後のデータベース接続が閉じられる時、リソースが解放されないようにアプリケーションが手動で`WSAStartup()`を呼び出すことができます。

`PQconnectdbParams`

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

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

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

  `expand_dbname`が非ゼロの場合、`dbname`キーワードの値を`conninfo`文字列として認識させることができます。 以下を参照してください。

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

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

  `host`

    接続するホスト名を指定します。 この引数をスラッシュで始めた場合、TCP/IPによる通信ではなく、Unixドメインの通信を明示することになります。 その場合、この値はソケットファイルを格納するディレクトリの名前になります。 `host`が指定されなかった場合のデフォルトは、`/tmp`にあるUnixドメインのソケットに接続することです。 （または、PostgreSQLの構築時に指定した別のディレクトリにあるソケットです。） Unixドメインソケットを持たないマシンにおけるデフォルトは、`localhost`に接続することです。

  `hostaddr`

    接続するホストのIPアドレスを指定します。 これは、`172.28.40.9`といった標準的なIPv4アドレス書式でなければなりません。 使用するマシンでIPv6をサポートする場合は、そのアドレスを使用することもできます。 このパラメータに非空の文字列が指定されると、TCP/IP通信が常に使用されます。

    `host`の代わりに`hostaddr`を使用することで、アプリケーションがホスト名の検索を行なわずに済みます。 特に時間的制約があるアプリケーションでは重要になるでしょう。 しかし、Kerberos、GSSAP、SSPI認証方式では、ホスト名が必要になります。 `verify-full`SSL証明書検証を行う場合も同様です。 以下の規則が使用されます。

    - `hostaddr`を使わずに`host`を指定した場合は、ホスト名の検索が発生します。

    - `host`を使わずに`hostaddr`を指定した場合、`hostaddr`の値はサーバのネットワークアドレスとなります。 認証方式がホスト名を必要する場合は接続試行が失敗します。

    - `host`と`hostaddr`の両方を指定した場合、`hostaddr`がサーバのネットワークアドレスとなります。 `host`の値は認証方式で必要とされない限り無視され、必要とされる場合にはホスト名として使用されます。

    `host`が`hostaddr`ネットワークアドレスに対応するマシンの名前と一致しない場合は、認証に失敗する可能性があるので注意してください。 また、`hostaddr`ではなく`host`が`~/.pgpass`(項31.14を参照)での接続の識別に使用されます。

    ホスト名もホストのアドレスも用いない場合、libpqはローカルのUnixドメインソケットを使用して接続します。 ただし、Unixドメインソケットを持たないマシンでは、`localhost`への接続を試みます。

  `port`

    サーバホストでの接続用のポート番号、または、Unixドメイン接続の場合は、ソケットファイルの拡張子を指定します。

  `dbname`

    データベース名を指定します。 デフォルトはユーザ名と同じです。

  `user`

    データベースへ接続するPostgreSQLユーザ名を指定します。 デフォルトは、そのアプリケーションを実行しているユーザのオペレーティングシステム上の名前と同じです。

  `password`

    サーバがパスワードによる認証を必要とした場合に使用されるパスワードを指定します。

  `connect_timeout`

    接続用の最大待機時間を秒単位(10進数整数で表した文字列として記述してください)で指定します。 ゼロもしくは未設定は、無限時間の待機を意味します。 2秒未満の待機時間を使用することは勧めません。

  `client_encoding`

    接続用の`client_encoding`設定パラメータを設定します。 対応するサーバオプションで受け付けられる値の他に、クライアントにおける現在のロケール（Unixシステムの場合は`LC_CTYPE`環境変数）から正しい符号化方式を決定する`auto`を使用することができます。

  `options`

    実行時にサーバに送信するコマンドラインオプションを追加します。 例えば、これを`-c geqo=off`に設定すると、`geqo`パラメータのセッション値は`off`になります。 有効なオプションに関する詳細は第18章を調べてください。

  `application_name`

    application_name設定パラメータの値を指定します。

  `fallback_application_name`

    application_name設定パラメータの予備値を指定します。 接続パラメータまたは`PGAPPNAME`環境変数により`application_name`の値が指定されない場合に、この値が使用されます。 予備の名前を指定することは、デフォルトのアプリケーション名を設定したいが、ユーザにもそれを上書きできるようにしておきたい、一般的なユーティリティプログラムで有用です。

  `keepalives`

    クライアント側におけるTCPキープアライブの使用を制御します。 デフォルト値は1であり、有効であることを意味します。 しかしキープアライブを望まない場合は、無効であることを意味するゼロに設定することができます。 このパラメータはUnixドメインソケット経由の接続では無視されます。

  `keepalives_idle`

    TCPがサーバにキープアライブメッセージを送信した後に活動を行わない期間を秒単位で制御します。 ゼロという値ではシステムのデフォルトを使用します。 Unixドメインソケット経由でなされた接続の場合もしくはキープアライブが無効な場合、このパラメータは無視されます。 これは`TCP_KEEPIDLE`ソケットオプションまたは`TCP_KEEPALIVE`ソケットオプションが利用できるシステムおよびWindowsでのみサポートされます。 他のシステムでは効果がありません。

  `keepalives_interval`

    TCPキープアライブメッセージに対する応答がサーバからない場合に、何秒後に再送を行うかを制御します。 ゼロという値ではシステムのデフォルトを使用します。 Unixドメインソケット経由でなされた接続の場合、またはキープアライブを無効にしている場合、このパラメータは無視されます。 これは`TCP_KEEPINTVL`ソケットオプションが利用できるシステムおよびWindowsでのみサポートされます。 他のシステムでは効果がありません。

  `keepalives_count`

    サーバへのクライアント接続が不要になったとみなすまで、何回キープアライブの欠落を認めるかを制御します。 ゼロという値ではシステムのデフォルトを使用します。 Unixドメインソケット経由でなされた接続の場合、またはキープアライブを無効にしている場合、このパラメータは無視されます。 これは`TCP_KEEPCNT`ソケットオプションが利用できるシステムでのみサポートされます。 他のシステムでは効果がありません。

  `tty`

    無視されます(以前は、これはサーバデバッグ出力を送信する場所を指定するものでした)。

  `sslmode`

    このオプションは、どのSSLによる安全なTCP/IP接続の優先度でサーバと調停するかを決定します。 6つのモードがあります。

    `disable`

      非SSL接続のみ試行

    `allow`

      最初に非SSL接続を試行し、失敗したら、SSL接続を試行

    `prefer`（デフォルト）

      最初にSSL接続を試行し、失敗したら、非SSL接続を試行

    `require`

      SSL接続のみ試行

    `verify-ca`

      SSL接続のみ試行し、サーバ証明書が信用された認証局（CA）から発行されたかを検証

    `verify-full`

      SSL接続のみ試行し、サーバ証明書が信用されたCAから発行されたか、およびそのサーバホスト名が証明書内のものと一致するかを検証

    これらのオプションがどのように動くのかについては項31.17を参照してください。

    `sslmode`はUnixドメインソケット通信では無視されます。 SSLサポートなしでPostgreSQLがコンパイルされた場合に、`require`、`verify-ca`、`verify-full`を使用するとエラーになります。 一方、`allow`と`prefer`は使用できますが、実際にlibpqはSSL接続を受け付けません。

  `requiressl`

    このオプションは`sslmode`設定を支持する観点から廃止予定になっています。

    1に設定することで、サーバへのSSL接続が必要になります (これは`sslmode`の`require`と同じです)。 サーバがSSL接続を受け付けない場合、libpqは接続を拒絶します。 0(デフォルト)に設定することで、サーバと接続形式の調停を行います。 (`sslmode`の`prefer`と同じです。) SSLサポート付きでPostgreSQLをコンパイルした場合にのみ、このオプションが利用できます。

  `sslcert`

    このパラメータは、`~/.postgresql/postgresql.crt`というデフォルトを置き換えるクライアントSSL証明書のファイル名を指定します。 このパラメータはSSL接続が確立していない場合は無視されます。

  `sslkey`

    このパラメータはクライアント証明書に対して使用される秘密鍵の場所を指定します。 デフォルトの`~/.postgresql/postgresql.key`の代わりに使用されるファイル名、または外部"エンジン"（エンジンとはOpenSSLロード可能なモジュール）から得られるキーを指定することも可能です。 外部エンジンの指定にはコロンで区切ったエンジン名とエンジン特有の鍵識別子を含んでいなければなりません。 SSL接続が確立していない場合このパラメータは無視されます。

  `sslrootcert`

    このパラメータはSSL認証局(CA)の証明書のファイル名を指定します。 このファイルが存在する場合、サーバ証明書はこれらの認証局の1つで署名されているかどうか検証されます。 デフォルトは`~/.postgresql/root.crt`です。

  `sslcrl`

    このパラメータはSSL証明書失効リスト（CRL）のファイル名を指定します。 このファイルに列挙された証明書が存在した場合、それはサーバ証明書を承認しようとする時に拒絶されます。 デフォルトは`~/.postgresql/root.crl`です。

  `requirepeer`

    このパラメータは、例えば`requirepeer=postgres`のようにサーバのオペレーティングシステムのユーザ名を指定します。 Unixドメインソケット接続を確立する時に、このパラメータが設定された場合、クライアントは接続開始時にサーバプロセスが指定されたユーザ名で稼動しているか検査し、稼動していない場合は接続をエラーとして中断します。 このパラメータは、TCP/IP接続においてSSL証明書で実現するようなサーバ認証を実現するために使用することができます。 （Unixドメインソケットが`/tmp`などの誰にでも書き込むことができる場所にある場合、誰でもそこで接続を監視するサーバを起動できることに注意してください。 信頼できるユーザが起動したサーバに接続することを確実に行うために、このパラメータを使用してください。） このオプションは`peer`認証方式が実装されたプラットフォームでのみでサポートされます。 項19.3.7を参照してください。

  `krbsrvname`

    Kerberos5またはGSSAPIの認証時に使われるKerberosサービス名です。 成功するためには、これはサーバのKerberos認証設定のサービス名と一致していなければなりません。 (項19.3.5および項19.3.3も参照してください。)

  `gsslib`

    GSSAPI認証で使用されるGSSライブラリです。 Windows上のみで使用されます。 libpqの認証がデフォルトのSSPIではなく、強制的にGSSAPIライブラリを使用させるには`gssapi`を設定してください。

  `service`

    追加のパラメータ用に使用されるサービス名です。 `pg_service.conf`内の追加的な接続パラメータを保持するサービス名を指定します。 これによりアプリケーションはサービス名だけを指定でき、接続パラメータを集中的に保守できるようになります。 項31.15を参照してください。

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

  `expand_dbname`が非ゼロ、かつ、`dbname`に`=`記号が含まれる場合、 `PQconnectdb`に渡された場合(後述)とまったく同じ方法で`conninfo`として解釈されます。 これまで処理されたキーワードは`conninfo`文字列内のキーワードで上書きされます。

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

`PQconnectdb`

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

      PGconn *PQconnectdb(const char *conninfo);

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

  空の文字列を渡してすべてデフォルトパラメータを使用することができます。 また空白文字で区切ることで1つ以上のパラメータ設定を持たせることもできます。 各パラメータは`keyword = value`という形式で設定されます。 等号記号の前後の空白文字は省略可能です。 空の値を記述する、もしくは、空白文字を含む値を記述するためには、例えば`keyword = 'a value'`のように単一引用符でくくってください。 値内の単一引用符およびバックスラッシュはバックスラッシュでエスケープ、つまり`\'`および`\\`のようにしなければなりません。

  現在認識されるパラメータキーワードは前述の通りです。

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

  `dbName`内に`=`記号が含まれる場合、`PQconnectdb`に渡された場合とまったく同じ扱いで`conninfo`文字列として扱われます。 その後残りのパラメータが上のように適用されます。

`PQsetdb`

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

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

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

`PQconnectStartParams`
`PQconnectStart`
`PQconnectPoll`

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

      PGconn *PQconnectStartParams(const char **keywords,
                                   const char **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アドレス検索やホスト名の逆引きが起こらないように適切に使用されなければいけません。 これらのパラメータについての詳細は、前述の`PQconnectdbParams`の節を参照してください。

  - `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`の戻り値から同様に検出できます。 これ以外の状態は、非同期の接続手続きの間（のみに）現れることがあります。 これらは、接続手続きの現在の段階を示すものであり、例えばユーザへのフィードバックを提供することに使用できます。 以下の状態があります。

  `CONNECTION_STARTED`

    接続の確立待ち状態です。

  `CONNECTION_MADE`

    接続はOKです。送信待ち状態です。

  `CONNECTION_AWAITING_RESPONSE`

    サーバからの応答待ち状態です。

  `CONNECTION_AUTH_OK`

    認証済みです。バックエンドの起動待ち状態です。

  `CONNECTION_SSL_STARTUP`

    SSL暗号化の調停状態です。

  `CONNECTION_SETENV`

    環境が提供するパラメータ設定の調停状態です。

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

      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`を呼び出さなくてはならないことに注意してください。 この処理は、接続試行が失敗した場合やその試行を中断する場合にも、必ず実行されなければいけません。

`PQconndefaults`

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

      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`が呼び出されるたびに少しずつメモリリークが発生します。

`PQconninfoParse`

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

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

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

  文字列内で明示的に指定されたオプションのみ結果配列の中で値集合を持つことに注意してください。 いかなるデフォルトも挿入されません。

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

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

`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つの関数が非ブロック方式で動作することです。 また、これらの関数は`PQconnectStartParams`、`PQconnectStart`および`PQconnectPoll`と同じ制限を受けます。

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

`PQpingParams`

  `PQpingParams`はサーバの状態を報告します。 この関数は上述の`PQconnectdbParams`と同じ接続パラメータを受け付けます。 しかし、サーバの状態を得るために正しいユーザ名、パスワード、データベース名を提供する必要はありません。

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

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

  `PQPING_OK`

    サーバは稼動中で、接続を受け付けているようです。

  `PQPING_REJECT`

    サーバは稼動中ですが、接続を許可しない状態（起動処理中、停止処理中、クラッシュリカバリ中）です。

  `PQPING_NO_RESPONSE`

    サーバと通信できません。 これは、サーバが稼動中ではない、指定した接続パラメータの何か（例えばポート番号の間違い）が間違っている、ネットワーク接続性の問題（例えば接続要求をブロックするファイアウォール）があることを示しているかもしれません。

  `PQPING_NO_ATTEMPT`

    指定されたパラメータが明らかに間違っている、または、（メモリ不足など）クライアント側の問題があったため、サーバとの通信を試行しませんでした。

`PQping`

  `PQping`はサーバの状態を報告します。 この関数は上述の`PQconnectdb`と同じ接続パラメータを受け付けます。 しかし、サーバの状態を得るために正しいユーザ名、パスワード、データベース名を提供する必要はありません。

      PGPing PQping(const char *conninfo);

  戻り値は`PQpingParams`と同じです。

前のページ | ホーム | 次のページ
libpq - C ライブラリ | 上に戻る | 接続状態関数