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を呼び出すマクロです。
非常に古いプログラムへの後方互換性のために提供されています。
PQconnectStartParamsPQconnectStartPQconnectPoll #ブロックしない方法で、データベースサーバへの接続を作成します。
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ポインタがNULLとなる項目が配列の末尾にきます。
メモリが確保できなかった場合にはNULLポインタを返します。
現在のデフォルト値(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構造体の配列を指し示し、それはNULLの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);
この関数はサーバへの接続を閉じ、以前使用したパラメータをすべて使用して、同一のサーバへ新しく接続を確立します。 これは、作業中の接続が失われた場合のエラーの修復に役立つでしょう。
PQresetStartPQresetPoll #非ブロッキング方式で、サーバへの通信チャネルをリセットします。
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に格納されたパスワードのNULL終端子を除いた長さを返さなければなりません。
失敗した場合、コールバックは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という２種類の書式が受け付けられます。 URIは通常RFC 3986に従いますが、以下で詳細を説明する複数ホスト接続文字列が使用できるところが例外です。
キーワード／値書式では、各パラメータ設定は、各設定の間に空白文字があり、keyword = valueという形式です。
等号記号の前後の空白文字は省略可能です。
空の値を書く、または空白文字を含む値を書くためには、keyword = 'a value'のように単一引用符で値を括ります。
値内部の単一引用符とバックスラッシュはバックスラッシュでエスケープしなければなりません。
つまり\'と\\です。
以下に例を示します。
host=localhost port=5432 dbname=mydb connect_timeout=10
有効なパラメータキーワードを34.1.2に示します。
接続URIの一般的な形式を以下に示します。
postgresql://[userspec@][hostspec][/dbname][?paramspec] whereuserspecis:user[:password] andhostspecis: [host][:port][,...] andparamspecis: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ドメインのソケットに接続することです。
Windowsでは、デフォルトはlocalhostに接続することです。
カンマで区切ったホスト名も受け付けます。 この場合、リスト中のホスト名が順に試されます。 リスト中の空の項目には、上で説明したデフォルトの挙動が適用されます。 詳細は34.1.1.3をご覧ください。
hostaddr #
接続するホストのIPアドレスを指定します。
これは、172.28.40.9といった標準的なIPv4アドレス書式でなければなりません。
使用するマシンでIPv6をサポートする場合は、そのアドレスを使用することもできます。
このパラメータに空以外の文字列が指定されると、TCP/IP通信が常に使用されます。
パラメータが指定されない場合、対応するIPアドレスを探すためにhostの値が調べられます。あるいは、hostでIPアドレスを指定している場合、その値が直接使われます。
hostaddrを使用することで、アプリケーションがホスト名の検索を行なわずに済みます。
特に時間的制約があるアプリケーションでは重要になるでしょう。
しかし、GSSAPI、SSPI認証方式では、ホスト名が必要になります。
verify-fullSSL証明書検証を行う場合も同様です。
以下の規則が使用されます。
hostaddrを使わずにhostを指定した場合は、ホスト名の検索が発生します。
（PQconnectPollを使う場合、PQconnectPollが最初にホスト名を考慮するときに、PQconnectPollをかなり長い時間、ブロックさせてしまうかもしれません。）
hostを使わずにhostaddrを指定した場合、hostaddrの値はサーバのネットワークアドレスとなります。
認証方式がホスト名を必要する場合は接続試行が失敗します。
hostとhostaddrの両方を指定した場合、hostaddrがサーバのネットワークアドレスとなります。
hostの値は認証方式で必要とされない限り無視され、必要とされる場合にはホスト名として使用されます。
hostがhostaddrネットワークアドレスに対応するマシンの名前と一致しない場合は、認証に失敗する可能性があるので注意してください。
また、hostとhostaddrの両方が指定されると、hostがパスワードファイル(34.16を参照)での接続の識別に使用されます。
カンマ区切りのhostaddr値のリストも受け付けます。
この場合、リスト中のホストが順に試されます。
リスト中の空の項目には、対応するホスト名が使用されます。
そのホスト名も空の場合は、デフォルトのホスト名が使用されます。
詳細は34.1.1.3をご覧ください。
ホスト名もホストのアドレスも用いない場合、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サポートを有効にしてコンパイルした場合のデフォルトです。
requireGSSAPI暗号化接続のみ試行
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-caSSL接続のみ試行し、サーバ証明書が信用された認証局（CA）から発行されたかを検証
verify-fullSSL接続のみ試行し、サーバ証明書が信用された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 #
このパラメータは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と組み合わせて使用できます。 接続に成功すると、返された接続に対する後続の問い合わせはすべて同じサーバへ送られます。 以下の2つのモードがあります。
disable (default)ホスト間の負荷分散は実行されません。 ホストは与えられた順に試行され、アドレスはDNSやホストファイルから受け取った順に試行されます。
randomホストとアドレスはランダムな順序で試行されます。 この値は、主に同時に複数の接続を開こうとする場合、おそらく異なるマシンからの接続を開こうとする場合に便利です。 このようにして、複数のPostgreSQLサーバ間で接続を負荷分散できます。
ランダム負荷分散は、そのランダムな性質のために、完全に均一な分布になることはほとんどありませんが、統計的には非常に近くなります。 ここで重要な側面の1つは、このアルゴリズムが2つのレベルのランダム選択を使用することです。 まず、ホストはランダムな順序で解決されます。 次に、次のホストを解決する前に、現在のホストのすべての解決済みアドレスがランダムな順序で試されます。 この動作は、特定のケースで各ノードが取得する接続の数を大幅に歪める可能性があります。たとえば、一部のホストが他のホストより多くのアドレスを解決する場合などです。 しかし、このような歪曲は、特定の目的で意図的に使用することもできます。たとえば、ホスト文字列で複数回ホスト名を指定することによって、大きなサーバーが取得する接続数を増やすことができます。
この値を使用する場合、connect_timeoutにも妥当な値を設定することをお勧めします。 なぜならそうすれば、負荷分散に使用されているノードの1つが応答しない場合、新しいノードが試されるからです。