他のバージョンの文書 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

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

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

警告

信頼できないユーザが、安全なスキーマ使用パターンを適用していないデータベースへアクセスする際には、セッション開始時にsearch_pathから、第三者が書き込みができるスキーマを削除してください。 これはoptionsパラメータキーワードに値-csearch_path=を設定することで可能となります。 別の方法としては、接続後にPQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")を発行しても構いません。 このような配慮は、libpqに限ったことではありません。 任意のSQLコマンドを実行するすべてのインタフェースに当てはまります。

警告

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

注記

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

PQconnectdbParams

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

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

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

現在有効なパラメータキーワードを33.1.2に示します。

expand_dbnameが非ゼロの場合、dbnameキーワードの値を接続文字列として認識させることができます。 最初に出現したdbnameだけがこのように展開され、後続のdbname値は通常のデータベース名として処理されます。 接続文字列の取り得る書式に関する詳細については33.1.1を参照してください。

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

パラメータがNULLや空文字列の場合には、対応する環境変数(33.14参照)が検査されます。 環境変数も設定されていない場合は、組み込みのデフォルト値が使用されます。

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

PQconnectdb

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

PGconn *PQconnectdb(const char *conninfo);

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

空の文字列を渡してすべてデフォルトパラメータを使用することができます。 また空白文字で区切ることで1つ以上のパラメータ設定を持たせることもできます。 さらにURIを含めることができます。 詳細については33.1.1を参照してください。

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内に=記号が含まれる場合、または有効な接続URI接頭辞を持つ場合、PQconnectdbに渡された場合とまったく同じ扱いでconninfo文字列として扱われます。 その後残りのパラメータがPQconnectdbParamsの指定のように適用されます。

PQsetdb

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

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

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

PQconnectStartParams
PQconnectStart
PQconnectPoll

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

PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *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文字列から取得されたパラメータを使用してデータベース接続を確立します。

PQconnectStartParamsPQconnectStartPQconnectPollのどちらも以下の制限に適合する場合ブロックしません。

  • hostaddrパラメータは、DNS問い合わせが発生するのを防ぐように適切に使用されなければいけません。 詳細については33.1.2内のパラメータ説明を参照してください。

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

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

非ブロック接続要求を始めるにはまず、PQconnectStartPQconnectStartParamsを呼び出します。 その結果がNULLの場合、libpqは新たなPGconn構造体を割り当てられませんでした。 そうでない場合は、適切なPGconnへのポインタが返されます (ただし、未だデータベースへの有効な接続を示しているわけではありません)。 次にPQstatus(conn)を呼び出します。 もし、結果がCONNECTION_BADであった場合、接続の試みは失敗しています。典型的には無効な接続パラメータに因ります。

PQconnectStartあるいはPQconnectStartParamsが成功したら、次は接続シーケンスを進めるために、libpqをポーリングします。 データベース接続の背後にあるソケットの記述子を取り出すには、PQsocket(conn)を使用します。 (注意:複数のPQconnectPoll呼び出しでソケットが同じままであると思わないでください。) 以下の繰り返しです。 直前のPQconnectPoll(conn)PGRES_POLLING_READINGの場合、(select()poll()などのシステム関数で示されて)ソケットの読み込み準備が整うまで待機します。 そして、再度PQconnectPoll(conn)を呼び出します。 反対に直前のPQconnectPoll(conn)PGRES_POLLING_WRITINGの場合、ソケットの書き込み準備が整うまで待機し、その後、PQconnectPoll(conn)を再度呼び出します。 繰り返しの最初、すなわち、未だPQconnectPollを呼び出していない場合、最後に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

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

CONNECTION_CHECK_WRITABLE

接続が書き込みトランザクションを扱えるかどうかを調べています。

CONNECTION_CONSUME

接続の残りの応答メッセージを消費しています。

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

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と同じになります。

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

PQconninfo

所在する接続で使用される接続オプションを返します。

PQconninfoOption *PQconninfo(PGconn *conn);

接続オプション配列を返します。これは全ての可能性のあるPQconnectdbオプションとサーバに接続するのに使用される値を確定するために使用することができます。 返り値はPQconninfoOption構造体の配列を指し示します。それはnull keyword ポインタを持つ項目で終結します。PQconndefaultsに対する上記の全ての注釈はまたPQconninfoの結果に適用されます。

PQconninfoParse

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

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

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

正規なオプションはすべて、結果配列内に現れます。 しかし接続文字列内に現れない、何らかのオプション用のPQconninfoOptionNULLに設定されたvalを持ちます。 デフォルトは挿入されません。

errmsgが非NULLであれば、成功した場合*errmsgNULLに設定され、そうでなければ、問題を説明したmallocされたエラー文字列になります。 (*errmsgNULLに設定され、かつ、この関数が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つの関数が非ブロック方式で動作することです。 また、これらの関数はPQconnectStartParamsPQconnectStartおよびPQconnectPollと同じ制限を受けます。

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

PQpingParams

PQpingParamsはサーバの状態を報告します。 この関数は上述のPQconnectdbParamsと同じ接続パラメータを受け付けます。 サーバの状態を得るために正しいユーザ名、パスワード、データベース名を提供する必要はありません。 しかし、不適切な値が供給されると、サーバは不成功に終わった接続の試みをログに残します。

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

この関数は以下の値のいずれかを返します。

PQPING_OK

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

PQPING_REJECT

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

PQPING_NO_RESPONSE

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

PQPING_NO_ATTEMPT

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

PQping

PQpingはサーバの状態を報告します。 この関数は上述のPQconnectdbと同じ接続パラメータを受け付けます。 サーバの状態を得るために正しいユーザ名、パスワード、データベース名を提供する必要はありません。 しかし、不適切な値が供給されると、サーバは不成功に終わった接続の試みをログに残します。

PGPing PQping(const char *conninfo);

戻り値はPQpingParamsと同じです。

33.1.1. 接続文字列

複数のlibpq関数は、接続パラメータを得るためにユーザが指定した文字列の解析を行います。 この文字列として、単純なkeyword = value文字列とURIという2種類の書式が受け付けられます。 URIは通常RFC3986に従いますが、以下で詳細を説明する複数ホスト接続文字列が使用できるところが例外です。

33.1.1.1. キーワード/値形式の接続文字列

最初の書式では、各パラメータ設定はkeyword = valueという形式です。 等号記号の前後の空白文字は省略可能です。 空の値を書く、または空白文字を含む値を書くためには、keyword = 'a value'のように単一引用符で値を括ります。 値内部の単一引用符とバックスラッシュはバックスラッシュでエスケープしなければなりません。 つまり\'\\です。

以下に例を示します。

host=localhost port=5432 dbname=mydb connect_timeout=10

有効なパラメータキーワードを33.1.2に示します。

33.1.1.2. 接続URI

接続URIの一般的な形式を以下に示します。

postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]

URIスキーム指示子はpostgresql://またはpostgres://のいずれかを取ることができます。 個々のURI部品は省略可能です。 以下の例で有効なURI構文の使用例を示します。

postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp

URIの階層部品の要素をパラメータとして与えることができます。 以下に例を示します。

postgresql:///mydb?host=localhost&port=5433

パーセント符号化を使用して、URI部品のいずれかに特殊な意味を持つ記号を含めることができます。 たとえば=%3Dで置き換えます。

33.1.2に示されたキーワードに対応しない接続パラメータは無視され、これに関する警告メッセージがstderrに書き出されます。

JDBCの接続URI構文との互換性を高めるために、ssl=trueパラメータインスタンスはsslmode=requireに変換されます。

ホスト部分にはホスト名またはIPアドレスを書くことができます。 IPv6ホストアドレスを指定するためには角括弧で括ります。

postgresql://[2001:db8::1234]/database

ホスト要素はhostで説明したように解釈されます。 具体的には、ホスト部品が空またはスラッシュで始まる場合Unixドメインソケット接続が選択され、さもなければTCP/IP接続で初期化されます。 しかしURIの階層部ではスラッシュが予約された文字であることに注意してください。 このため、標準以外のUnixドメインソケットディレクトリを指定するためには、URIからホスト指定を省き、パラメータとしてホストを指定するか、URIのホスト要素内のパスをパーセントエスケープするかどちらかを行ってください。

postgresql:///dbname?host=/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname

単一のURIの中に、オプションのポート要素を伴う複数のホスト要素を指定することができます。 postgresql://host1:port1,host2:port2,host3:port3/という形式のURIは、host=host1,host2,host3 port=port1,port2,port3という形式の接続文字列と同じです。 接続の確立に成功するまで、各々のホストが順番に試されます。

33.1.1.3. 複数ホストの指定

接続先に複数のホストを指定することができ、指定された順に試されます。 キーワード/値形式では、hosthostaddrportオプションは、カンマで区切った値のリストを受け付けます。 指定された各々のオプションでは、同じ数の要素を与えなければなりません。 たとえば、最初のhostaddrは最初のホスト名に関連付けられ、二番目のhostaddrは二番目のホスト名に関連付けられる、という具合です。 例外として、一つのportだけが指定された場合には、すべてのホストにそれが適用されます。

接続URI形式では、host要素中にカンマで区切って複数のhost:portペアを指定できます。

いずれの形式でも、単一ホスト名は複数のネットワークアドレスに変換されることがあります。 これの一般的な例はIPv4とIPv6のアドレスを両方持つホストです。

複数のホスト名が指定された場合、あるいは単一のホスト名が複数のアドレスに変換された場合、そのうちの一つが成功するまで、すべてのホストとアドレスがその順に試されます。 どのホストも到達可能でなければ、接続は失敗します。 接続の確立に成功しても、認証に失敗すると、リスト中の残りのホストは試されません。

パスワードファイルが使用される場合は、異なるホストに対して異なるパスワードを使用できます。 他の接続オプションは、リスト中のすべてのホストで同じです。 たとえば、異なるユーザ名を異なるホストに指定することはできません。

33.1.2. パラメータキーワード

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

host

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

カンマで区切ったホスト名も受け付けます。 この場合、リスト中のホスト名が順に試されます。 リスト中の空の項目には、上で説明したデフォルトの挙動が適用されます。 詳細は33.1.1.3をご覧ください。

hostaddr

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

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

  • hostaddrを使わずにhostを指定した場合は、ホスト名の検索が発生します。 (PQconnectPollを使う場合、PQconnectPollが最初にホスト名を考慮するときに、PQconnectPollをかなり長い時間、ブロックさせてしまうかもしれません。)

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

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

hosthostaddrネットワークアドレスに対応するマシンの名前と一致しない場合は、認証に失敗する可能性があるので注意してください。 また、hosthostaddrの両方が指定されると、hostがパスワードファイル(33.15を参照)での接続の識別に使用されます。

カンマ区切りのhostaddrs値のリストも受け付けます。 この場合、リスト中のホストが順に試されます。 リスト中の空の項目には、対応するホスト名が使用されます。 そのホスト名も空の場合は、デフォルトのホスト名が使用されます。 詳細は33.1.1.3をご覧ください。

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

port

サーバホストでの接続用のポート番号、または、Unixドメイン接続の場合は、ソケットファイルの拡張子を指定します。 もし複数のホストがhostあるいはhostaddrパラメータで与えられると、このパラメータで同じ長さのポートのリストを与えることができます。 あるいは、一つのポート番号をすべてのホストに指定することもできます。 空文字、あるいはカンマ区切りリスト中の空の項目は、PostgreSQLが構築されたときに設定されたデフォルトポート番号を指定します。

dbname

データベース名を指定します。 デフォルトはユーザ名と同じです。 特定の文脈では、この値は拡張書式で検査されます。 詳細については33.1.1を参照してください。

user

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

password

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

passfile

パスワードを格納するファイル名を指定します。(33.15参照。) デフォルトは~/.pgpassまたは、Microsoft Windowsでは%APPDATA%\postgresql\pgpass.confです。 (このファイルが存在しなくてもエラーは報告されません。)

connect_timeout

接続用の最大待機を秒単位(10進整数で記述してください、10など)で指定します。 ゼロ、負値、もしくは未設定は、無期限の待機を意味します。 許容される最小のタイムアウトは2秒です。 したがって、12と解釈されます。 このタイムアウトは各ホスト名やIPアドレスに別々に適用されます。 例えば、二つのホストを指定して、connect_timeoutが5であるなら、各ホストが5秒以内に接続できないときにタイムアウトして、接続を待つ合計所要時間は10秒近くになるかもしれません。

client_encoding

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

options

接続開始時にサーバに送信するコマンドラインオプションを指定します。 例えば、これを-c geqo=offに設定すると、geqoパラメータのセッション値はoffになります。 この文字列中の空白はバックスラッシュ(\)でエスケープされていなければコマンド行引数の区切りであるとみなされます。 リテラルのバックスラッシュを表すには\\と書いて下さい。 利用可能なオプションに関する詳細については第19章を参照してください。

application_name

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

fallback_application_name

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

keepalives

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

keepalives_idle

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

keepalives_interval

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

keepalives_count

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

tcp_user_timeout

接続が強制的に閉じられるまで、送信されたデータに対して応答がない状況をどれだけ認めるかをミリ秒単位で制御します。 値0はシステムのデフォルトを使用します。 Unixドメインソケット経由でなされた接続の場合、このパラメータは無視されます。 TCP_USER_TIMEOUTが利用可能なシステムでのみサポートされます。 他のシステムでは効果がありません。

tty

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

replication

このオプションは接続が通常プロトコルの代わりにレプリケーションプロトコルを使うかどうかを決めます。 これはPostgreSQLのレプリケーション接続やpg_basebackupなどのツールが内部的に使うものですが、サードパーティアプリケーションからも使われることがあります。 レプリケーションプロトコルについての説明は52.4を参照してください。

以下の値がサポートされます。これらは大文字小文字を区別しません。

true, on, yes, 1

接続は物理レプリケーションモードになります。

database

接続は論理レプリケーションモードになり、dbnameパラメータで指定されたデータベースに接続します。

false, off, no, 0

接続は通常のものになります。これがデフォルトの振る舞いです。

物理あるいは論理レプリケーションモードでは、簡易問い合わせプロトコルのみが使用できます。

gssencmode

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

disable

GSSAPI暗号化接続のみ試行

prefer (デフォルト)

GSSAPI認証情報が(すなわち認証情報キャッシュに)存在すれば、まずGSSAPI暗号化接続を試行します。 その試行に失敗した場合、もしくは認証情報がない場合には非GSSAPI暗号化接続を試行します。 これがPostgreSQLGSSAPIサポートを有効にしてコンパイルした場合のデフォルトです。

require

GSSAPI暗号化接続のみ試行

gssencmodeはUnixドメインソケット通信では無視されます。 PostgreSQLがGSSAPIなしでコンパイルされた場合、requireオプションを使うとエラーになります。一方、preferは受け付けられますが、libpqは実際にはGSSAPI暗号化接続を試行しません。

sslmode

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

disable

SSL接続のみ試行

allow

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

prefer (デフォルト)

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

require

SSL接続のみ試行。 ルートCAファイルが存在する場合、verify-caが指定された場合と同じ方法で証明書が検証されます。

verify-ca

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

verify-full

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

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

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

requiressl

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

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

sslcompression

1に設定することで、SSL接続越えで送信されるデータは圧縮されます。 0に設定すると、圧縮が無効になります。 デフォルトは0です。 このパラメータはSSLを使わない接続では無視されます。

SSL圧縮は今日では安全ではないと考えられていて、もはや使用は推奨されません。 OpenSSL 1.1.0はデフォルトでは圧縮を無効にしており、多くのOSディストリビューションでもこれまでのバージョンで無効化しています。そのため、サーバが圧縮を受け付けない場合、本パラメータをonに設定しても効果がありません。 一方で、1.0.0以前のOpenSSLは圧縮の無効化をサポートしていませんので、これらのバージョンでは本パラメータは無視されて、圧縮が使用されるかはサーバ次第です。

セキュリティが主要な関心でないなら、ネットワークがボトルネックであるとき圧縮でスループットを改善できます。 CPU性能が律速要素であるなら、圧縮を無効化することで応答時間とスループットを改善できます。

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認証方式が実装されたプラットフォームでのみでサポートされます。 20.9を参照してください。

krbsrvname

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

gsslib

GSSAPI認証で使用されるGSSライブラリです。 これは今のところ、GSSAPIとSSPIの両方のサポートを含むWindowsビルド版を除いて無視されます。 その場合、認証にデフォルトのSSPIではなく、GSSAPIライブラリを使うようlibpqに強制するには、これをgssapiに設定してください。

service

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

target_session_attrs

このパラメータがread-writeなら、読み書きトランザクションがデフォルトで許容される接続だけが受付可能になります。 接続に成功すると、問合せSHOW transaction_read_onlyが送られ、onが返ると接続は閉じられます。 接続文字列で複数のホストが指定されている場合は、あたかも接続の試みが失敗したかのように、残りのサーバが試されます。 このパラメータのデフォルト値はanyで、すべての接続が受付可能であると見なされます。