PostgreSQLのバックエンドサーバとの接続を作成するには、以下の関数を使用します。
アプリケーションプログラムはバックエンドとの接続を一度に複数個開くことができます。
(そのようにする1つの理由として、複数のデータベースへのアクセスが挙げられます。)
個々の接続は、PQconnectdb
、PQconnectdbParams
またはPQsetdbLogin
関数を呼び出すことで得られるPGconn
オブジェクトによって表されます。
なお、これらの関数は、PGconn
オブジェクトに割り当てるほんのわずかなメモリの余裕さえもない場合を除き、NULLではなく常にオブジェクトのポインタを返します。
また、この接続オブジェクトを通じて問い合わせを送る前に、PQstatus
関数を呼び出して、データベースとの接続に成功したか戻り値を検査しなければなりません。
信頼できないユーザが、安全なスキーマ使用パターンを適用していないデータベースへアクセスする際には、セッション開始時にsearch_path
から、第三者が書き込みができるスキーマを削除してください。
これはoptions
パラメータキーワードに値-csearch_path=
を設定することで可能となります。
別の方法としては、接続後にPQexec(
を発行しても構いません。
このような配慮は、libpqに限ったことではありません。
任意のSQLコマンドを実行するすべてのインタフェースに当てはまります。
conn
, "SELECT pg_catalog.set_config('search_path', '', false)")
Unix上で、libpq接続を開いたプロセスのフォークは、親と子のプロセスが同じソケットとオペレーティングシステムの資源を共有するため、予期せぬ結果を招くことがあります。
この理由により、新規実行形式を子プロセスが読み込むためexec
を行うことが安全と言っても、このような使用方法は推奨されません。
PQconnectdbParams
#新たにデータベースサーバへの接続を作成します。
PGconn *PQconnectdbParams(const char * const *keywords, const char * const *values, int expand_dbname);
この関数は、2つのNULL
終端の配列から取得したパラメータを使用して、データベースとの接続を新たに1つ確立します。
1つ目は文字列配列として定義されるkeywords
で、それぞれがキーワードとなります。
2つ目はvalues
で、各キーワードの値を提供します。
後述のPQsetdbLogin
とは異なり、関数のシグネチャを変更せずにパラメータ集合を拡張できますので、アプリケーションプログラムを新たに作成する際には、この関数(もしくは非ブロックモードでよく似た処理をするPQconnectStartParams
とPQconnectPoll
)を使用することをお勧めします。
現在有効なパラメータキーワードを34.1.2に示します。
渡される配列は、すべてのデフォルトパラメータを使用するために空にするか、または1つ以上のパラメータ設定を含むことができます。
それらは長さが一致する必要があります。
処理はkeywords
配列内の最初のNULL
エントリで停止します。
また、非NULL
keywords
エントリに関連付けられたvalues
エントリがNULL
または空文字列である場合、そのエントリは無視され、処理は配列エントリの次のペアで続行されます。
expand_dbname
が0以外の場合、最初のdbname
キーワードの値が接続文字列かどうかチェックされます。
そうであれば、文字列から抽出された個々の接続パラメータに「拡張」されます。
等号(=
)が含まれている場合や、URIスキーム指定子で始まっている場合、値は単なるデータベース名ではなく接続文字列とみなされます。
(接続文字列フォーマットの詳細は34.1.1を参照してください。)
dbname
の最初の出現のみがこの方法で処理されます。
後続のdbname
パラメータはプレーンなデータベース名として処理されます。
一般的に、パラメータ配列は開始から終了まで処理されます。
キーワードが繰り返された場合、最後の値(NULL
または空ではない)が使用されます。
この規則は特に、接続文字列内で見つかったキーワードがkeywords
配列内で出現するキーワードと競合する場合に適用されます。
したがって、プログラマは、配列エントリが上書きするか、あるいは接続文字列から取得した値によって上書きされるかを判断できます。
拡張されたdbname
エントリの前に現れる配列エントリは、接続文字列のフィールドによって上書きされ、次にdbname
の後に現れる配列エントリによって上書きされます(ただし、これらのエントリが空でない値を提供する場合に限ります)。
すべての配列エントリと拡張された接続文字列を処理した後、未設定のままの接続パラメータはデフォルト値で埋められます。 未設定パラメータに対応する環境変数(34.15参照)が設定されている場合は、その値が使用されます。 環境変数も設定されていない場合は、パラメータに組み込まれているデフォルト値が使用されます。
PQconnectdb
#新たにデータベースサーバへの接続を作成します。
PGconn *PQconnectdb(const char *conninfo);
この関数はconninfo
文字列から取得されるパラメータを使用して、新しいデータベース接続を開きます。
空の文字列を渡してすべてデフォルトパラメータを使用することができます。 また空白文字で区切ることで1つ以上のパラメータ設定を持たせることもできます。 さらにURIを含めることができます。 詳細については34.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
の指定のように適用されます。
pgtty
は使用されなくなり、渡された値は無視されます。
PQsetdb
#新たにデータベースサーバへの接続を作成します。
PGconn *PQsetdb(char *pghost, char *pgport, char *pgoptions, char *pgtty, char *dbName);
これは、login
とpwd
に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
文字列から取得されたパラメータを使用してデータベース接続を確立します。
PQconnectStartParams
、PQconnectStart
とPQconnectPoll
のどちらも以下の制限に適合する場合ブロックしません。
非ブロック接続要求を始めるにはまず、PQconnectStart
かPQconnectStartParams
を呼び出します。
その結果が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
と同じになります。
PQconnectStart
やPQconnectStartParams
が非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
ポインタを持つ項目で終結します。
正規なオプションはすべて、結果配列内に現れます。
しかし接続文字列内に現れない、何らかのオプション用のPQconninfoOption
はNULL
に設定されたval
を持ちます。
デフォルトは挿入されません。
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 * 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
と同じです。
PQsetSSLKeyPassHook_OpenSSL
#
PQsetSSLKeyPassHook_OpenSSL
はアプリケーションにsslpasswordや対話的なプロンプトを使ってlibpqの暗号化されたクライアント証明書キーファイルのデフォルト処理を置き換えさせます。
void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
アプリケーションは以下のシグネチャを持つコールバック関数のポインタを渡します。
int callback_fn(char *buf, int size, PGconn *conn);
libpqはデフォルトのPQdefaultSSLKeyPassHook_OpenSSL
ハンドラの代わりに、これを呼び出します。
コールバックはキーに対するパスワードを決定して、それをsize
の大きさを持つ結果バッファbuf
にコピーすべきです。
buf
内の文字列はNULL終端でなければなりません。
コールバックはbuf
に格納されたパスワードのヌル終端子を除いた長さを返さなければなりません。
失敗した場合、コールバックはbuf[0] = '\0'
をセットし、0を返すべきです。
例として、libpqのソースコードのPQdefaultSSLKeyPassHook_OpenSSL
を参照してください。
ユーザが明示的なキー位置を指定した場合、コールバックが実行されたときにそのパスがconn->sslkey
に含まれます。
デフォルトのキーパスが使われている場合、これは空になります。
エンジン指定子であるキーに対して、OpenSSLパスワードコールバックを使うか固有の処理を定義するかは、エンジン実装によります。
アプリケーションのコールバックが対応していない場合についてPQdefaultSSLKeyPassHook_OpenSSL
に委託したり、最初に呼び出して0が返った場合に何らか他のことを試みたり、あるいは完全に上書きしたりすることにしても良いです。
コールバックは例外、longjmp(...)
などで通常のフロー制御から脱出してはいけません。
正常にリターンしなければなりません。
PQgetSSLKeyPassHook_OpenSSL
#
PQgetSSLKeyPassHook_OpenSSL
は現在のクライアント証明書のキーパスワードのフックを、あるいは、設定されていない場合にNULL
を返します。
PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
複数のlibpq関数は、接続パラメータを得るためにユーザが指定した文字列の解析を行います。 この文字列として、単純なキーワード/値文字列とURIという2種類の書式が受け付けられます。 URIは通常RFC3986に従いますが、以下で詳細を説明する複数ホスト接続文字列が使用できるところが例外です。
キーワード/値書式では、各パラメータ設定は、各設定の間に空白文字があり、keyword
=
value
という形式です。
等号記号の前後の空白文字は省略可能です。
空の値を書く、または空白文字を含む値を書くためには、keyword = 'a value'
のように単一引用符で値を括ります。
値内部の単一引用符とバックスラッシュはバックスラッシュでエスケープしなければなりません。
つまり\'
と\\
です。
以下に例を示します。
host=localhost port=5432 dbname=mydb connect_timeout=10
有効なパラメータキーワードを34.1.2に示します。
接続URIの一般的な形式を以下に示します。
postgresql://[userspec
@][hostspec
][/dbname
][?paramspec
] whereuserspec
is:user
[:password
] andhostspec
is: [host
][:port
][,...] andparamspec
is:name
=value
[&...]
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
JDBC接続URIとの互換性のために、ssl=true
のインスタンスがsslmode=require
に変換される点を除き、すべての名前付きパラメータは34.1.2に列挙されたキーワードと一致しなければなりません。
接続URIは、その中のどこかの部分に特別な意味を持つシンボルを含む場合、パーセントエンコーディングでエンコードされている必要があります。
以下は等号(=
)が%3D
、空白が%20
で置き換えられた例です。
postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
ホスト部分は、ホスト名または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
という形式の接続文字列と同じです。
更に以下に示すように、接続の確立に成功するまで、各々のホストが順番に試されます。
接続先に複数のホストを指定することができ、指定された順に試されます。
キーワード/値形式では、host
、hostaddr
、port
オプションは、カンマで区切った値のリストを受け付けます。
指定された各々のオプションでは、同じ数の要素を与えなければなりません。
たとえば、最初のhostaddr
は最初のホスト名に関連付けられ、二番目のhostaddr
は二番目のホスト名に関連付けられる、という具合です。
例外として、一つのport
だけが指定された場合には、すべてのホストにそれが適用されます。
接続URI形式では、host
要素中にカンマで区切って複数のhost:port
ペアを指定できます。
いずれの形式でも、単一ホスト名は複数のネットワークアドレスに変換されることがあります。 これの一般的な例はIPv4とIPv6のアドレスを両方持つホストです。
複数のホスト名が指定された場合、あるいは単一のホスト名が複数のアドレスに変換された場合、そのうちの一つが成功するまで、すべてのホストとアドレスがその順に試されます。 どのホストも到達可能でなければ、接続は失敗します。 接続の確立に成功しても、認証に失敗すると、リスト中の残りのホストは試されません。
パスワードファイルが使用される場合は、異なるホストに対して異なるパスワードを使用できます。 他の接続オプションは、リスト中のすべてのホストで同じです。 たとえば、異なるユーザ名を異なるホストに指定することはできません。
現時点で有効なパラメータのキーワードは以下に示す通りです。
host
#
《マッチ度[]》接続するホスト名を指定します。
ホスト名が絶対パス名のように見えるなら、それはTCP/IPによる通信ではなく、Unixドメインの通信を示します。
その場合、この値はソケットファイルを格納するディレクトリの名前になります。
(Unixでは絶対パス名はスラッシュから始まります。Windowsではドライブ文字から始まるパスも認められます。)
ホスト名が@
から始まっていると、抽象名前空間(今のところLinuxとWindowsでサポートされています)内のUnixドメインソケットとして扱われます。
host
が指定されなかったり、空の場合のデフォルトの振る舞いは、/tmp
(または、PostgreSQLの構築時に指定したソケットディレクトリ)にあるUnixドメインのソケットに接続することです。
Unixドメインソケットを持たないマシンにおけるデフォルトは、localhost
に接続することです。
カンマで区切ったホスト名も受け付けます。 この場合、リスト中のホスト名が順に試されます。 リスト中の空の項目には、上で説明したデフォルトの挙動が適用されます。 詳細は34.1.1.3をご覧ください。
hostaddr
#
接続するホストのIPアドレスを指定します。
これは、172.28.40.9
といった標準的なIPv4アドレス書式でなければなりません。
使用するマシンでIPv6をサポートする場合は、そのアドレスを使用することもできます。
このパラメータに空以外の文字列が指定されると、TCP/IP通信が常に使用されます。
パラメータが指定されない場合、対応するIPアドレスを探すためにhost
の値が調べられます。あるいは、host
でIPアドレスを指定している場合、その値が直接使われます。
hostaddr
を使用することで、アプリケーションがホスト名の検索を行なわずに済みます。
特に時間的制約があるアプリケーションでは重要になるでしょう。
しかし、GSSAPI、SSPI認証方式では、ホスト名が必要になります。
verify-full
SSL証明書検証を行う場合も同様です。
以下の規則が使用されます。
hostaddr
を使わずにhost
を指定した場合は、ホスト名の検索が発生します。
(PQconnectPoll
を使う場合、PQconnectPoll
が最初にホスト名を考慮するときに、PQconnectPoll
をかなり長い時間、ブロックさせてしまうかもしれません。)
host
を使わずにhostaddr
を指定した場合、hostaddr
の値はサーバのネットワークアドレスとなります。
認証方式がホスト名を必要する場合は接続試行が失敗します。
host
とhostaddr
の両方を指定した場合、hostaddr
がサーバのネットワークアドレスとなります。
host
の値は認証方式で必要とされない限り無視され、必要とされる場合にはホスト名として使用されます。
host
がhostaddr
ネットワークアドレスに対応するマシンの名前と一致しない場合は、認証に失敗する可能性があるので注意してください。
また、host
とhostaddr
の両方が指定されると、host
がパスワードファイル(34.16を参照)での接続の識別に使用されます。
カンマ区切りのhostaddr
値のリストも受け付けます。
この場合、リスト中のホストが順に試されます。
リスト中の空の項目には、対応するホスト名が使用されます。
そのホスト名も空の場合は、デフォルトのホスト名が使用されます。
詳細は34.1.1.3をご覧ください。
《マッチ度[61.616162]》ホスト名もホストのアドレスも用いない場合、libpqはローカルのUnixドメインソケットを使用して接続します。
ただし、WindowsとUnixドメインソケットを持たないマシンでは、localhost
への接続を試みます。
《機械翻訳》ホスト名またはホストアドレスのいずれかがない場合、libpqはローカルのUnixドメインソケットを使用して接続します。
または、Windowsでは、localhost
に接続します。
port
#
サーバホストでの接続用のポート番号、または、Unixドメイン接続の場合は、ソケットファイルの拡張子を指定します。
もし複数のホストがhost
あるいはhostaddr
パラメータで与えられると、このパラメータで同じ長さのポートのリストを与えることができます。
あるいは、一つのポート番号をすべてのホストに指定することもできます。
空文字、あるいはカンマ区切りリスト中の空の項目は、PostgreSQLが構築されたときに設定されたデフォルトポート番号を指定します。
dbname
#データベース名を指定します。 デフォルトはユーザ名と同じです。 特定の文脈では、この値は拡張書式で検査されます。 詳細については34.1.1を参照してください。
user
#データベースへ接続するPostgreSQLユーザ名を指定します。 デフォルトは、そのアプリケーションを実行しているユーザのオペレーティングシステム上の名前と同じです。
password
#サーバがパスワードによる認証を必要とした場合に使用されるパスワードを指定します。
passfile
#
パスワードを格納するファイル名を指定します(34.16参照)。
デフォルトは~/.pgpass
または、Microsoft Windowsでは%APPDATA%\postgresql\pgpass.conf
です。
(このファイルが存在しなくてもエラーは報告されません。)
require_auth
#《機械翻訳》クライアントがサーバーから要求する認証方法を指定します。 サーバーがクライアントの認証に必要なメソッドを使用しない場合、またはサーバーが認証ハンドシェイクを完全に完了しない場合、接続は失敗します。 必要なメソッドのコンマ区切りリストも指定できます。 このリストでは、サーバーは接続を正常に完了するために、そのうちの1つを使用する必要があります。 デフォルトでは、任意の認証方法が受け入れられ、サーバーは認証を完全にスキップできます。
《機械翻訳》メソッドは、!
接頭辞を付けて否定することができます。
その場合、サーバはリストされたメソッドを試みないことになります。
他のメソッドはすべて受け入れられます。
また、クライアントを全く認証しないこともできます。
コンマ区切りのリストが与えられた場合、サーバは、リストされた否定されたメソッドのいずれも試みてはならない。
否定された形式と否定されていない形式は、同じ設定では組み合わせることができません。
《機械翻訳》最後の特殊なケースとして、none
メソッドはサーバが認証チャレンジを使用しないことを要求します。
(また、何らかの形の認証を要求するために否定されることもあります。)
《機械翻訳》次のメソッドを指定できます。
password
《機械翻訳》サーバは、平文パスワード認証を要求する必要があります。
md5
《機械翻訳》サーバは、MD5ハッシュパスワード認証を要求する必要があります。
gss
《機械翻訳》サーバはGSSAPIを介してKerberosハンドシェイクを要求するか、GSSで暗号化されたチャネルを確立する必要があります(gssencmodeも参照してください)。
sspi
《機械翻訳》サーバは Windows SSPI認証を要求する必要があります。
scram-sha-256
《機械翻訳》サーバは、クライアントとのSCRAM-SHA-256認証交換を正常に完了する必要があります。
none
《機械翻訳》サーバはクライアントに認証交換を要求してはならない(これは、TLSによるクライアント証明書認証や、その暗号化されたトランスポートによるGSS認証を禁止するものではない)。
channel_binding
#
このオプションはクライアントのチャンネルバインディングの使用を制御します。
require
設定では接続はチャンネルバイデンディングを使わなければならず、prefer
ではクラアイントが可能であればチャンネルバインディングを使い、disable
ではチャンネルバイディングを使用させません。
PostgreSQLがSSLサポートを伴ってコンパイルされている場合のデフォルトはprefer
で、そうでなければデフォルトはdisable
です。
チャンネルバインディングはサーバが自身が信頼できることをクライアントに証明する方法です。
これは、SCRAM
認証方式を使ったPostgreSQL 11以降のサーバとのSSL接続上でのみサポートされます。
connect_timeout
#
接続中の最大待機時間を秒単位(10進整数で記述してください、10
など)で指定します。
ゼロ、負値、もしくは未設定は、無期限の待機を意味します。
許容される最小のタイムアウトは2秒です。
したがって、1
は2
と解釈されます。
このタイムアウトは各ホスト名やIPアドレスに別々に適用されます。
例えば、二つのホストを指定して、connect_timeout
が5であるなら、各ホストが5秒以内に接続できないときにタイムアウトして、接続を待つ合計所要時間は10秒近くになるかもしれません。
client_encoding
#
接続用のclient_encoding
設定パラメータを設定します。
対応するサーバオプションで受け付けられる値の他に、クライアントにおける現在のロケール(Unixシステムの場合はLC_CTYPE
環境変数)から正しい符号化方式を決定するauto
を使用することができます。
options
#
接続開始時にサーバに送信するコマンドラインオプションを指定します。
例えば、これを-c geqo=off
に設定すると、geqo
パラメータのセッション値はoff
になります。
この文字列中の空白はバックスラッシュ(\
)でエスケープされていなければコマンド行引数の区切りであるとみなされます。
リテラルのバックスラッシュを表すには\\
と書いて下さい。
利用可能なオプションに関する詳細については第20章を参照してください。
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
が利用可能なシステムでのみサポートされます。
他のシステムでは効果がありません。
replication
#このオプションは接続が通常プロトコルの代わりにレプリケーションプロトコルを使うかどうかを決めます。 これはPostgreSQLのレプリケーション接続やpg_basebackupなどのツールが内部的に使うものですが、サードパーティアプリケーションからも使われることがあります。 レプリケーションプロトコルについての説明は55.4を参照してください。
以下の値がサポートされます。これらは大文字小文字を区別しません。
true
, on
,
yes
, 1
接続は物理レプリケーションモードになります。
database
接続は論理レプリケーションモードになり、dbname
パラメータで指定されたデータベースに接続します。
false
, off
,
no
, 0
接続は通常のものになります。これがデフォルトの振る舞いです。
物理あるいは論理レプリケーションモードでは、簡易問い合わせプロトコルのみが使用できます。
gssencmode
#このオプションは、GSSによる安全なTCP/IP接続をサーバと調停するか、するのならどの優先度で調停するかを決定します。 3つのモードがあります。
disable
非GSSAPI暗号化接続のみ試行
prefer
(デフォルト)GSSAPI認証情報が(すなわち認証情報キャッシュに)存在すれば、まずGSSAPI暗号化接続を試行します。 その試行に失敗した場合、もしくは認証情報がない場合には非GSSAPI暗号化接続を試行します。 これがPostgreSQLをGSSAPIサポートを有効にしてコンパイルした場合のデフォルトです。
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から発行されたか、およびそのサーバホスト名が証明書内のものと一致するかを検証
これらのオプションがどのように動くのかについては34.19を参照してください。
sslmode
はUnixドメインソケット通信では無視されます。
SSLサポートなしでPostgreSQLがコンパイルされた場合に、require
、verify-ca
、verify-full
を使用するとエラーになります。
一方、allow
とprefer
は使用できますが、実際にlibpqはSSL接続を受け付けません。
GSSAPI暗号化が可能な場合、sslmode
の値に関係なく、SSL暗号化よりも優先して使用されることに注意してください。
GSSAPIインフラストラクチャが動作している環境(Kerberosサーバなど)でSSL暗号化を強制的に使用するには、gssencmode
をdisable
に設定します。
requiressl
#
このオプションはsslmode
設定を支持する観点から廃止予定になっています。
1に設定することで、サーバへのSSL接続が必要になります
(これはsslmode
のrequire
と同じです)。
サーバがSSL接続を受け付けない場合、libpqは接続を拒絶します。
0(デフォルト)に設定することで、libpqはサーバと接続形式の調停を行います。
(sslmode
のprefer
と同じです。)
SSLサポート付きでPostgreSQLをコンパイルした場合にのみ、このオプションが利用できます。
sslcompression
#1に設定することで、SSL接続越えで送信されるデータは圧縮されます。 0に設定すると、圧縮が無効になります。 デフォルトは0です。 このパラメータはSSLを使わない接続では無視されます。
SSL圧縮は今日では安全ではないと考えられていて、もはや使用は推奨されません。 OpenSSL 1.1.0はデフォルトでは圧縮を無効にしており、多くのOSディストリビューションでもこれまでのバージョンで無効化しています。そのため、サーバが圧縮を受け付けない場合、本パラメータをonに設定しても効果がありません。 PostgreSQL 14はバックエンドでの圧縮を完全に無効にしています。
セキュリティが主要な関心でないなら、ネットワークがボトルネックであるとき圧縮でスループットを改善できます。 CPU性能が律速要素であるなら、圧縮を無効化することで応答時間とスループットを改善できます。
sslcert
#
このパラメータは、~/.postgresql/postgresql.crt
というデフォルトを置き換えるクライアントSSL証明書のファイル名を指定します。
このパラメータはSSL接続が確立していない場合は無視されます。
sslkey
#
このパラメータはクライアント証明書に対して使用される秘密鍵の場所を指定します。
デフォルトの~/.postgresql/postgresql.key
の代わりに使用されるファイル名、または外部「エンジン」(エンジンとはOpenSSLロード可能なモジュール)から得られるキーを指定することも可能です。
外部エンジンの指定にはコロンで区切ったエンジン名とエンジン特有の鍵識別子を含んでいなければなりません。
SSL接続が確立していない場合このパラメータは無視されます。
sslpassword
#
このパラメータはsslkey
で指定される秘密鍵に対するパスワードを指定して、対話的なパスフレーズ入力が現実的でないときにも、クライアント証明書のプライベートキーを暗号化された形式でディスクに格納できるようにします。
空でない値でこのパラメータを指定することで、暗号化されたクライアント証明書キーがlibpq
に供給されるときにOpenSSLがデフォルトで出すEnter PEM pass phrase:
プロンプトを抑止します。
キーが暗号化されていない場合、このパラメータは無視されます。 OpenSSLエンジンがプロンプトにOpenSSLパスワードコールバックの仕組みを使わない限り、このパラメータはエンジンで指定されたキーに影響しません。
このオプションと同等の環境変数、および、パスワードを.pgpass
から探す機能はありません。
このオプションはサービスファイルの接続定義で使用できます。
より高度な使用法を用いるユーザは、OpenSSLエンジンとPKCS#11やUSB暗号オフロードデバイスといったツールの利用を検討すべきです。
sslcertmode
#《機械翻訳》このオプションは、クライアント証明書をサーバに送信するかどうか、およびサーバがそれを要求する必要があるかどうかを決定します。 以下の3つのモードがあります。
disable
《機械翻訳》クライアント証明書は、使用可能であっても(デフォルトの場所またはsslcertで提供されている場合)、決して送信されません。
allow
(default)《機械翻訳》サーバが証明書を要求し、クライアントが送信する証明書を持っている場合は、証明書を送信することができます。
require
《機械翻訳》サーバは証明書を要求する必要があります。 クライアントが証明書を送信しない場合でも、サーバはクライアントを認証するため、接続は失敗します。
《機械翻訳》sslcertmode=require
は、サーバが証明書を正しく検証しているかどうかを保証しないため、追加のセキュリティを追加するものではありません。
PostgreSQLサーバは、一般に、有効にするかどうかに関係なく、クライアントからTLS証明書を要求します。
このオプションは、より複雑なTLS設定のトラブルシューティングに役立つ場合があります。
sslrootcert
#
このパラメータはSSL認証局(CA)の証明書のファイル名を指定します。
このファイルが存在する場合、サーバ証明書はこれらの認証局の1つで署名されているかどうか検証されます。
デフォルトは~/.postgresql/root.crt
です。
《機械翻訳》特別な値system
を指定することもできます。
この場合、システムの信頼できるCAルートがロードされます。
これらのルート証明書の正確な位置は、SSL実装とプラットフォームによって異なります。
OpenSSLの場合、特に、SSL_CERT_DIR
とSSL_CERT_FILE
環境変数によって位置がさらに変更される可能性があります。
《機械翻訳》sslrootcert=system
を使用すると、デフォルトのsslmode
はverify-full
に変更され、より弱い設定はエラーになります。
ほとんどの場合、誰かが制御するホスト名に対してシステムが信頼できる証明書を取得することは簡単であり、verify-ca
や他の弱いモードはすべて無意味になります。
《機械翻訳》マジック値 system
は、同じ名前のローカル証明書ファイルよりも優先されます。
何らかの理由でこのような状況になった場合は、代わりに sslrootcert=./system
のような別のパスを使用してください。
sslcrl
#
《マッチ度[82.005141]》このパラメータはSSLサーバ証明書失効リスト(CRL)のファイル名を指定します。
このファイルに列挙された証明書が存在した場合、それはサーバ証明書を承認しようとする時に拒絶されます。
sslcrlもsslcrldirも設定されていなければ、設定は~/.postgresql/root.crl
から取得されます。
《機械翻訳》このパラメータは、SSLサーバ証明書失効リスト(CRL)のファイル名を指定します。
このファイルが存在する場合、サーバの証明書を認証しようとするときに拒否されます。
sslcrlもsslcrldirも設定されていない場合、この設定は~/.postgresql/root.crl
として取られます。
sslcrldir
#このパラメータは、SSLサーバ証明書失効リスト(CRL)のディレクトリ名を指定します。 このディレクトリのファイルにリストされている証明書が存在する場合は、サーバーの証明書の認証中に拒否されます。
ディレクトリは、OpenSSLコマンドopenssl rehash
またはc_rehash
を使用して準備する必要があります。
詳細はそのドキュメントを参照してください。
sslcrl
とsslcrldir
の両方を同時に指定できます。
sslsni
#1(デフォルト)に設定されている場合、libpqはTLS拡張「Server Name Indication」(SNI)をSSL使用可能な接続に設定します。 このパラメータを0に設定することにより、これはオフになります。
Server Name Indicationは、SSLストリームを復号化することなく接続をルーティングするために、SSL対応プロキシによって使用できます(これには、SSLプロキシだけでなく、PostgreSQLプロトコルハンドシェイクを認識するプロキシが必要であることに注意してください)。 しかし、SNIは宛先ホスト名をネットワークトラフィック中に平文で表示しますので、場合によっては望ましくないかもしれません。
requirepeer
#
このパラメータは、例えばrequirepeer=postgres
のようにサーバのオペレーティングシステムのユーザ名を指定します。
Unixドメインソケット接続を確立する時に、このパラメータが設定された場合、クライアントは接続開始時にサーバプロセスが指定されたユーザ名で稼働しているか検査し、稼働していない場合は接続をエラーとして中断します。
このパラメータは、TCP/IP接続においてSSL証明書で実現するようなサーバ認証を実現するために使用することができます。
(Unixドメインソケットが/tmp
などの誰にでも書き込むことができる場所にある場合、誰でもそこで接続を監視するサーバを起動できることに注意してください。
信頼できるユーザが起動したサーバに接続することを確実に行うために、このパラメータを使用してください。)
このオプションはpeer
認証方式が実装されたプラットフォームでのみでサポートされます。
21.9を参照してください。
ssl_min_protocol_version
#
このパラメータは接続で許容されるSSL/TLSプロトコルの最小バージョンを指定します。
有効な値はTLSv1
、TLSv1.1
、TLSv1.2
、および、TLSv1.3
です。
対応しているプロトコルは使われているOpenSSLバージョンに依存し、より古いバージョンでは最新プトロコルバージョンに対応していません。
指定しない場合、デフォルトはTLSv1.2
で、これは執筆時点では業界標準を満たします。
ssl_max_protocol_version
#
このパラメータは接続で許容されるSSL/TLSプロトコルの最大バージョンを指定します。
有効な値はTLSv1
、TLSv1.1
、TLSv1.2
、および、TLSv1.3
です。
対応しているプロトコルは使われているOpenSSLバージョンに依存し、より古いバージョンでは最新のプロトコルバージョンに対応していません。
設定しない場合、このパラメータは無視されて、接続ではバックエンドで定義されている最大範囲が、もし定義されているなら、使われます。
テストや、一部コンポーネントがより新しいプロトコルでの動作に問題がある場合に対して、大概はプロトコルの最大バージョンを設定することが有用です。
krbsrvname
#
GSSAPIの認証時に使われるKerberosサービス名です。
成功するためには、これはサーバのKerberos認証設定のサービス名と一致していなければなりません。
(21.6も参照してください。)
デフォルト値は通常postgres
ですが、PostgreSQLをconfigureの--with-krb-srvnam
オプションを使ってビルドすることにより変更できます。
大抵の環境ではこのパラメータは滅多に変更の必要がありません。
サービス名が大文字(POSTGRES
)であることを要求するMicrosoft Active Directoryのように、ある種のKerberos実装では異なるサービス名が必要になるかもしれません。
gsslib
#
GSSAPI認証で使用されるGSSライブラリです。
これは今のところ、GSSAPIとSSPIの両方のサポートを含むWindowsビルド版を除いて無視されます。
その場合、認証にデフォルトのSSPIではなく、GSSAPIライブラリを使うようlibpqに強制するには、これをgssapi
に設定してください。
gssdelegation
#
《機械翻訳》GSS 資格証明をサーバに転送 (委任) します。
デフォルトは 0
で、これは資格証明がサーバに転送されないことを意味します。
可能な場合は資格証明を転送するには 1
に設定します。
service
#
追加のパラメータ用に使用されるサービス名です。
pg_service.conf
内の追加的な接続パラメータを保持するサービス名を指定します。
これによりアプリケーションはサービス名だけを指定でき、接続パラメータを集中的に保守できるようになります。
34.17を参照してください。
target_session_attrs
#このオプションは、セッションが受け入れられるために特定のプロパティを持つ必要があるかどうかを決定します。 これは通常、複数のホスト名と組み合わせて使用され、いくつかのホストの中から最初に受け入れられる代替を選択します。 6つのモードがあります:
any
(default)成功した接続は受け入れられます
read-write
セッションはデフォルトで読み書きトランザクションを受け入れなければなりません(つまり、サーバはホットスタンバイモードであってはならず、default_transaction_read_only
パラメータはoff
でなければなりません)。
read-only
セッションはデフォルトで読み書きトランザクションを受け入れてはなりません(逆)
primary
サーバーはホット・スタンバイ・モードであってはなりません
standby
サーバーはホット・スタンバイ・モードでなければなりません
prefer-standby
最初にスタンバイサーバを見つけようとしますが、リストされているホストがいずれもスタンバイサーバでない場合は、any
モードで再試行します。
load_balance_hosts
#《機械翻訳》使用可能なホストおよびアドレスへの接続試行をクライアントが試行する順序を制御します。 接続が成功すると、他のホストおよびアドレスへの試行は行われません。 このパラメータは、通常、複数のホスト名または複数のIPを返すDNSレコードと組み合わせて使用されます。 このパラメータは、例えばロードバランシングを実行するためにtarget_session_attrsと組み合わせて使用できます。 接続に成功すると、返された接続に対するすべての負荷分散は同じサーバで実行されます。 クライアントが提供されたホストからの接続を試行し、DNSまたはホストファイルからIPを受信する順序でアドレスが試行されます。
disable
(default)No load balancing across hosts is performed. Hosts are tried in the order in which they are provided and addresses are tried in the order they are received from DNS or a hosts file.
random
《機械翻訳》ホストとアドレスはランダムな順序で試されます。 この値は、同時に複数の接続を開こうとする場合、おそらく異なるマシンからの接続を開こうとする場合に便利です。 このようにして、複数のPostgreSQLサーバ間で接続をロードバランスできます。
《機械翻訳》ランダム負荷分散は、そのランダムな性質のために、完全に均一な分布になることはほとんどありませんが、統計的には非常に近くなります。 ここで重要な側面の1つは、このアルゴリズムが2つのレベルのランダム選択を使用することである。 まず、ホストはランダムな順序で解決される。 次に、次のホストを解決する前に、現在のホストのすべての解決済みアドレスがランダムな順序で試される。 この動作は、特定のケースで各ノードが取得する接続の数を大幅に歪める可能性があります。たとえば、一部のホストが他のホストより多くのアドレスを解決する場合などです。 しかし、このようなスキューは、特定の目的で意図的に使用することもできます。たとえば、ホスト文字列で複数回ホスト名を指定することによって、大きなサーバーが取得する接続数を増やすことができます。
《機械翻訳》この値を使用する場合、connect_timeoutにも妥当な値を設定することをお勧めします。 なぜなら、負荷分散に使用されているノードの1つが応答しない場合、新しいノードが試されるからです。