postgresql

Postgresql スキル

公式ドキュメントから生成された、Postgresql 開発に関する包括的なサポートです。

このスキルを使用するタイミング

次の場合にこのスキルが起動されます：

• Postgresql を使用する場合
• Postgresql の機能や API について質問する場合
• Postgresql のソリューションを実装する場合
• Postgresql のコードをデバッグする場合
• Postgresql のベストプラクティスを学ぶ場合

クイックリファレンス

よくあるパターン

パターン 1： 32.1. データベース接続制御関数 # 32.1.1. 接続文字列 32.1.2. パラメーターキーワード 以下の関数は、PostgreSQL バックエンドサーバーへの接続に関するものです。アプリケーションプログラムは、一度に複数のバックエンド接続を開くことができます。（そうする理由の 1 つは、複数のデータベースにアクセスすることです。）各接続は PGconn オブジェクトで表され、PQconnectdb、PQconnectdbParams、または PQsetdbLogin 関数から取得します。これらの関数は、PGconn オブジェクトを確保するメモリーさえ不足している場合を除き、常に NULL 以外のオブジェクトポインターを返すことに注意してください。接続オブジェクトを介してクエリを送信する前に、PQstatus 関数を呼び出して、戻り値が接続成功を示すことを確認する必要があります。

警告

信頼できないユーザーが、安全なスキーマ使用パターンを採用していないデータベースにアクセスできる場合は、各セッションの開始時に、search_path から一般ユーザーが書き込み可能なスキーマを削除してください。パラメーターキーワードのオプションに -csearch_path= を設定できます。または、接続後に PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)") を実行することもできます。この注意事項は libpq に固有のものではなく、任意の SQL コマンドを実行するすべてのインターフェースに当てはまります。

警告

Unix では、libpq 接続を開いたままプロセスをフォークすると、親プロセスと子プロセスが同じソケットとオペレーティングシステムリソースを共有するため、予測不能な結果につながる可能性があります。このため、このような使い方は推奨されません。ただし、子プロセスから exec を実行して新しい実行ファイルを読み込むことは安全です。

PQconnectdbParams #

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

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

この関数は、NULL 終端の 2 つの配列から取得したパラメーターを使用して、新しいデータベース接続を開きます。1 つ目の配列 keywords は文字列の配列で、各要素がキーワードです。2 つ目の配列 values は、各キーワードに対応する値を指定します。以下の PQsetdbLogin とは異なり、関数のシグネチャーを変更せずにパラメーターセットを拡張できるため、新しいアプリケーションのプログラミングでは、この関数（またはそのノンブロッキング版である PQconnectStartParams および PQconnectPoll）の使用が推奨されます。現在認識されているパラメーターキーワードの一覧は、32.1.2 節に記載されています。

渡す配列は、すべてのデフォルトパラメーターを使用する場合は空にできます。また、1 つ以上のパラメーター設定を含めることもできます。2 つの配列の長さは一致していなければなりません。keywords 配列内の最初の NULL エントリーで処理が終了します。また、NULL 以外の keywords エントリーに対応する values エントリーが NULL または空文字列の場合、そのエントリーは無視され、次の配列要素の組の処理に進みます。

expand_dbname がゼロ以外の場合、最初の dbname キーワードの値が接続文字列かどうか確認されます。接続文字列であれば、その文字列から抽出された個々の接続パラメーターに「展開」されます。値に等号（=）が含まれる場合、または URI スキーム指定子で始まる場合、その値は単なるデータベース名ではなく接続文字列とみなされます。（接続文字列の形式の詳細は、32.1.1 節を参照してください。）この方法で処理されるのは最初の dbname のみです。それ以降の dbname パラメーターは、通常のデータベース名として処理されます。

通常、パラメーター配列は先頭から末尾に向けて処理されます。キーワードが重複している場合は、最後の値（NULL または空ではないもの）が使用されます。この規則は特に、接続文字列内のキーワードと keywords 配列内のキーワードが競合する場合に適用されます。したがって、接続文字列から取得した値を配列エントリーで上書きするか、配列エントリーが上書きされるかを、プログラマーが決定できます。展開された dbname エントリーより前にある配列エントリーは、接続文字列のフィールドで上書きされる可能性があります。また、そのフィールドは dbname の後にある配列エントリーで上書きされます（ただし、ここでも、そのエントリーが空でない値を指定している場合に限ります）。

すべての配列エントリーと展開された接続文字列の処理後、未設定の接続パラメーターにはデフォルト値が設定されます。未設定のパラメーターに対応する環境変数（32.15 節を参照）が設定されていれば、その値が使われます。環境変数も設定されていない場合は、パラメーターの組み込みデフォルト値が使われます。

PQconnectdb #

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

PGconn *PQconnectdb(const char *conninfo);

この関数は、conninfo 文字列から取得したパラメーターを使用して、新しいデータベース接続を開きます。すべてのデフォルトパラメーターを使用する場合は、渡す文字列を空にできます。また、空白で区切られた 1 つ以上のパラメーター設定、または URI を含めることもできます。詳細は 32.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 はいずれもブロックしません。

hostaddr パラメーターを適切に使用して、DNS クエリが発生しないようにする必要があります。詳細は、32.1.2 節のこのパラメーターの説明を参照してください。

PQtrace を呼び出す場合、トレース先のストリームオブジェクトがブロックしないようにしてください。

以下で説明するように、PQconnectPoll を呼び出す前に、ソケットが適切な状態にあることを確認してください。

ノンブロッキング接続要求を開始するには、PQconnectStart または PQconnectStartParams を呼び出します。結果が NULL の場合、libpq は新しい PGconn 構造体を割り当てられなかったことを意味します。それ以外の場合は、有効な PGconn ポインターが返されます（ただし、まだデータベースへの有効な接続を表しているわけではありません）。次に PQstatus(conn) を呼び出します。結果が CONNECTION_BAD の場合、通常は接続パラメーターが無効であるなどの理由で、接続の試行はすでに失敗しています。

PQconnectStart または PQconnectStartParams が成功した場合、次の段階では libpq をポーリングし、接続シーケンスを進められるようにします。PQsocket(conn) を使って、データベース接続の基盤となるソケットのディスクリプターを取得します。（注意：PQconnectPoll の呼び出しごとにソケットが同じであるとは限らないため、その前提で処理しないでください。）

次のようにループします。

PQconnectPoll(conn) が前回 PGRES_POLLING_READING を返した場合は、ソケットが読み取り可能になるまで待機します（select()、poll()、または同様のシステム関数で確認できます）。PQsocketPoll がシステムで利用可能な場合、select(2) または poll(2) の準備処理を抽象化して定型コードを減らすのに役立つことに注意してください。その後、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 を返した場合は、接続の準備が整っています。これら 2 つの状態は、前述の PQconnectPoll の戻り値からも同じように検出できます。

非同期接続処理中（かつ、その処理中に限り）には、ほかの状態も発生する場合があります。これらは接続処理の現在の段階を示しており、たとえばユーザーへのフィードバックに役立つことがあります。これらの状態は次のとおりです。

CONNECTION_STARTED # 接続が確立されるのを待機しています。

CONNECTION_MADE # 接続済みです。送信を待機しています。

CONNECTION_AWAITING_RESPONSE # サーバーからの応答を待機しています。

CONNECTION_AUTH_OK # 認証を受け付けました。バックエンドの起動完了を待機しています。

CONNECTION_SSL_STARTUP # SSL 暗号化をネゴシエートしています。

CONNECTION_GSS_STARTUP # GSS 暗号化をネゴシエートしています。

CONNECTION_CHECK_WRITABLE # 接続が書き込みトランザクションを処理できるか確認しています。

CONNECTION_CHECK_STANDBY # 接続先がスタンバイモードのサーバーか確認しています。

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

これらの定数は互換性維持のために残されますが、アプリケーションは、これらが特定の順序で発生すること、必ず発生すること、または状態が常にこれらの文書化された値のいずれかであることを前提にしてはいけません。アプリケーションでは、たとえば次のような処理を行えます。

switch(PQstatus(conn)) { case CONNECTION_STARTED: feedback = "接続中..."; break; case CONNECTION_MADE: feedback = "サーバーに接続しました..."; break; . . . default: feedback = "接続中..."; }

PQconnectPoll を使用する場合、connect_timeout 接続パラメーターは無視されます。過度に時間が経過したかどうかを判断するのは、アプリケーションの責任です。それ以外については、PQconnectStart の後に PQconnectPoll のループを実行することは、PQconnectdb と同等です。

PQconnectStart または PQconnectStartParams が NULL 以外のポインターを返した場合、その構造体と関連するメモリーブロックを解放するため、使い終わったら PQfinish を呼び出す必要があることに注意してください。接続の試行が失敗した場合や、中止した場合でも、呼び出さなければなりません。

PQsocketPoll #

PQsocket で取得した接続の基盤となるソケットディスクリプターをポーリングします。この関数は主に、PQconnectStartParams の説明にある接続シーケンスを反復するために使います。

typedef int64_t pg_usec_time_t;

int PQsocketPoll(int sock, int forRead, int forWrite, pg_usec_time_t end_time);

この関数は、オプションでタイムアウトを指定して、ファイルディスクリプターのポーリングを行います。forRead がゼロ以外の場合、ソケットが読み取り可能になると関数は終了します。forWrite がゼロ以外の場合、ソケットが書き込み可能になると関数は終了します。タイムアウトは end_time で指定します。これは、待機を終了する時刻を Unix エポックからのマイクロ秒数で表したものです（つまり、time_t × 1,000,000 です）。end_time が -1 の場合、タイムアウトは無限です。end_time が 0（または現在より前の任意の時刻）の場合、タイムアウトは即時となります（ブロックしません）。タイムアウト値は、PQgetCurrentTimeUSec の結果に必要なマイクロ秒数を加算すると簡単に計算できます。基盤となるシステムコールの精度がマイクロ秒未満の場合があるため、実際の遅延は不正確になることがあります。

関数は、指定した条件が満たされた場合は 0 より大きい値、タイムアウトした場合は 0、エラーが発生した場合は -1 を返します。errno(3) の値を確認すると、エラーを取得できます。forRead と forWrite の両方がゼロの場合、関数はタイムアウトを示して直ちに戻ります。

PQsocketPoll は、プラットフォームに応じて poll(2) または select(2) を使って実装されています。詳細は、poll(2) の POLLIN および POLLOUT、または select(2) の readfds および writefds を参照してください。

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 構造体の配列を指し、keyword ポインターが NULL のエントリーで終わります。PQconndefaults に関する上記の注意事項は、PQconninfo の結果にもすべて適用されます。

PQconninfoParse #

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

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

接続文字列を解析し、結果のオプションを配列として返します。接続文字列に問題がある場合は NULL を返します。この関数を使って、指定された接続文字列内の PQconnectdb オプションを抽出できます。戻り値は PQconninfoOption 構造体の配列を指し、keyword ポインターが NULL のエントリーで終わります。有効なオプションはすべて結果の配列に含まれますが、接続文字列に指定されていないオプションの PQconninfoOption では、val が NULL になります。デフォルト値は挿入されません。

errmsg が NULL 以外の場合、成功時は *errmsg が NULL に設定され、それ以外の場合は問題を説明する malloc で割り当てられたエラー文字列に設定されます。（*errmsg が NULL に設定されたまま関数が NULL を返すこともあります。この場合はメモリー不足を示します。）

オプション配列の処理後、PQconninfoFree に渡して解放してください。これを行わないと、PQconninfoParse の呼び出しごとにメモリーがリークします。反対に、エラーが発生し、errmsg が NULL 以外の場合は、PQfreemem を使ってエラー文字列を解放してください。

PQfinish #

サーバーへの接続を閉じます。また、PGconn オブジェクトが使用しているメモリーも解放します。

void PQfinish(PGconn *conn);

サーバーへの接続の試行が失敗した場合（PQstatus が示します）でも、PGconn オブジェクトが使用しているメモリーを解放するため、アプリケーションは PQfinish を呼び出す必要があることに注意してください。PQfinish の呼び出し後は、PGconn ポインターを再度使用してはいけません。

PQreset #

サーバーとの通信チャネルをリセットします。

void PQreset(PGconn *conn);

この関数はサーバーへの接続を閉じ、以前と同じパラメーターを使って新しい接続を確立しようとします。動作中の接続が失われた場合のエラー回復に役立つことがあります。

PQresetStartPQresetPoll #

ノンブロッキング方式で、サーバーとの通信チャネルをリセットします。

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

これらの関数はサーバーへの接続を閉じ、以前と同じパラメーターを使って新しい接続を確立しようとします。動作中の接続が失われた場合のエラー回復に役立ちます。これらの関数は、ノンブロッキング方式で動作する点で、上記の PQreset と異なります。

これらの関数には、PQconnectStartParams、PQconnectStart、PQconnectPoll と同じ制限事項があります。接続のリセットを開始するには、PQresetStart を呼び出します。0 が返された場合、リセットは失敗しています。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 終端でなければなりません。コールバックは、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);

32.1.1. 接続文字列 #

複数の libpq 関数は、ユーザー指定の文字列を解析して接続パラメーターを取得します。これらの文字列では、キーワード／値形式の文字列と URI の 2 つの形式が使用できます。URI は通常 RFC 3986 に従いますが、以下で詳述するように、複数ホスト接続文字列も使用できます。

32.1.1.1. キーワード／値形式の接続文字列 #

キーワード／値形式では、各パラメーター設定は keyword = value の形式で、設定間は空白で区切ります。設定の等号の前後に空白を入れるかどうかは任意です。空の値や空白を含む値を書く場合は、次の例のように単一引用符で囲みます：keyword = 'a value'。値の中の単一引用符とバックスラッシュは、バックスラッシュでエスケープする必要があります。つまり、' と \ を使います。

例：

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

認識されるパラメーターキーワードの一覧は、32.1.2 節に記載されています。

32.1.1.2. 接続 URI #

接続 URI の一般的な形式は次のとおりです。

postgresql://[userspec@][hostspec][/dbname][?paramspec]

ここで、userspec は次のとおりです。

user[:password]

hostspec は次のとおりです。

[host][:port][,...]

paramspec は次のとおりです。

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

すべての名前付きパラメーターは、32.1.2 節に記載されているキーワードと一致する必要があります。ただし、JDBC 接続 URI との互換性のため、ssl=true は sslmode=require に変換されます。

接続 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

1 つの URI で、ポート部分を省略可能な複数のホスト要素を指定できます。postgresql://host1:port1,host2:port2,host3:port3/ 形式の URI は、host=host1,host2,host3 port=port1,port2,port3 形式の接続文字列と同等です。以下で詳述するように、接続が確立するまで、各ホストへの接続が順番に試行されます。

32.1.1.3. 複数ホストの指定 #

指定した順序で試行する複数の接続先ホストを指定できます。キーワード／値形式では、host、hostaddr、port の各オプションに、カンマ区切りの値のリストを指定できます。指定する各オプションでは、同じ数の要素を指定する必要があります。たとえば、最初の hostaddr は最初のホスト名に、2 番目の hostaddr は 2 番目のホスト名に対応します。例外として、port を 1 つだけ指定した場合は、すべてのホストに適用されます。接続 URI 形式では、URI のホスト要素に複数の host:port の組をカンマ区切りで指定できます。

いずれの形式でも、1 つのホスト名が複数のネットワークアドレスに解決されることがあります。よくある例は、IPv4 アドレスと IPv6 アドレスの両方を持つホストです。複数のホストが指定されている場合、または 1 つのホスト名が複数のアドレスに解決される場合は、いずれかの接続が成功するまで、すべてのホストとアドレスが順番に試されます。いずれのホストにも到達できない場合、接続は失敗します。接続が確立されたものの、認証に失敗した場合は、リスト内の残りのホストは試行されません。パスワードファイルを使う場合は、ホストごとに異なるパスワードを設定できます。リスト内のすべてのホストで、ほかの接続オプションは同じです。たとえば、ホストごとに異なるユーザー名を指定することはできません。

32.1.2. パラメーターキーワード #

現在認識されているパラメーターキーワードは次のとおりです。

host #

接続先ホストの名前です。ホスト名が絶対パス名のように見える場合は、TCP/IP 通信ではなく Unix ドメイン通信を指定します。この値は、ソケットファイルが保存されているディレクトリー名です。（Unix では、絶対パス名はスラッシュで始まります。Windows では、ドライブ文字で始まるパスも認識されます。）ホスト名が @ で始まる場合は、抽象名前空間の Unix ドメインソケットとして扱われます（現在は Linux と Windows でサポートされています）。

host が指定されていない場合、または空の場合、デフォルトの動作では /tmp（または PostgreSQL のビルド時に指定されたソケットディレクトリー）にある Unix ドメインソケットに接続します。Windows では、デフォルトで localhost に接続します。カンマ区切りのホスト名リストも指定でき、この場合、リスト内のホスト名が順番に試されます。リスト内の空の要素は、前述のデフォルトの動作を選択します。詳細は 32.1.1.3 節を参照してください。

hostaddr #

接続先ホストの数値形式の IP アドレスです。標準的な IPv4 アドレス形式で指定します。たとえば、172.28.40.9 です。マシンが IPv6 をサポートしている場合は、IPv6 アドレスも使用できます。このパラメーターに空でない文字列を指定した場合は、常に TCP/IP 通信が使われます。

このパラメーターが指定されていない場合、host の値が検索され、対応する IP アドレスが取得されます。host が IP アドレスを指定している場合は、その値が直接使われます。hostaddr を使うと、アプリケーションはホスト名の検索を回避できます。これは、時間制約のあるアプリケーションでは重要な場合があります。ただし、GSSAPI または SSPI 認証方式や、verify-full SSL 証明書検証ではホスト名が必要です。

次の規則が適用されます。

hostaddr を指定せずに host を指定した場合、ホスト名の検索が行われます。（PQconnectPoll を使う場合、検索は PQconnectPoll がこのホスト名を最初に処理するときに行われ、PQconnectPoll がかなり長い時間ブロックすることがあります。）

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

host と hostaddr の両方を指定した場合、hostaddr の値がサーバーのネットワークアドレスになります。認証方式で必要な場合を除き、host の値は無視されます。その場合は、ホスト名として使われます。host がネットワークアドレス hostaddr にあるサーバーの名前でない場合、認証に失敗する可能性が高いことに注意してください。また、host と hostaddr の両方が指定されている場合、パスワードファイル（32.16 節を参照）内の接続を識別するために host が使われます。

カンマ区切りの hostaddr 値のリストも指定できます。この場合、リスト内の各ホストが順番に試されます。リスト内の空の要素は、対応するホスト名を使用します。そのホスト名も空の場合は、デフォルトのホスト名が使われます。詳細は 32.1.1.3 節を参照してください。

ホスト名またはホストアドレスのいずれも指定されていない場合、libpq はローカルの Unix ドメインソケットを使って接続します。Windows では、localhost への接続を試みます。

port #

サーバーホストへの接続に使うポート番号、または Unix ドメイン接続のソケットファイル名の拡張子です。host または hostaddr パラメーターで複数のホストが指定されている場合、このパラメーターにはホストリストと同じ長さのカンマ区切りのポートリストを指定できます。または、すべてのホストに使う単一のポート番号を指定できます。空文字列、またはカンマ区切りのリスト内の空の要素は、PostgreSQL のビルド時に設定されたデフォルトのポート番号を指定します。

dbname #

データベース名です。デフォルトはユーザー名と同じです。特定のコンテキストでは、拡張形式かどうかが値から判定されます。詳細は 32.1.1 節を参照してください。

user #

接続に使う PostgreSQL のユーザー名です。デフォルトは、アプリケーションを実行しているオペレーティングシステムのユーザー名と同じです。

password #

サーバーがパスワード認証を要求した場合に使うパスワードです。

passfile #

パスワードの保存に使うファイル名を指定します（32.16 節を参照）。デフォルトは ~/.pgpass、または Microsoft Windows の場合は %APPDATA%\postgresql\pgpass.conf です。このファイルが存在しなくてもエラーは報告されません。

require_auth #

クライアントがサーバーに要求する認証方式を指定します。サーバーがクライアントの認証に要求された方式を使わない場合、またはサーバーが認証ハンドシェイクを完全に完了しない場合、接続は失敗します。カンマ区切りの方式リストも指定できます。接続を成功させるには、サーバーはそのうち正確に 1 つを使用する必要があります。デフォルトでは、任意の認証方式が受け入れられ、サーバーは認証自体を省略できます。

方式には ! を付けて否定できます。この場合、サーバーは指定した方式を試みてはいけません。それ以外の方式は受け入れられ、サーバーはクライアントを認証しないこともできます。カンマ区切りのリストが指定されている場合、サーバーはいずれの否定された方式も試みてはいけません。否定形と非否定形を同じ設定に組み合わせることはできません。最後に、none 方式は、サーバーが認証チャレンジを使用しないことを要求する特別なケースです。（これを否定して、何らかの認証を要求することもできます。）

次の方式を指定できます。

password サーバーは、平文パスワード認証を要求する必要があります。

md5 サーバーは、MD5 ハッシュ化パスワード認証を要求する必要があります。

警告

MD5 暗号化パスワードのサポートは非推奨となっており、今後の PostgreSQL リリースで削除される予定です。別のパスワード方式への移行の詳細は、20.5 節を参照してください。

gss サーバーは、GSSAPI による Kerberos ハンドシェイクを要求するか、GSS 暗号化チャネルを確立する必要があります（gssencmode も参照してください）。

sspi サーバーは、Windows SSPI 認証を要求する必要があります。

scram-sha-256 サーバーは、クライアントとの SCRAM-SHA-256 認証交換を正常に完了する必要があります。

oauth サーバーは、クライアントに OAuth ベアラートークンを要求する必要があります。

none サーバーは、クライアントに認証交換を要求してはいけません。（TLS 経由のクライアント証明書認証や、暗号化された転送を介した GSS 認証を禁止するものではありません。）

channel_binding #

このオプションは、クライアントによるチャネルバインディングの使用を制御します。require に設定すると接続でチャネルバインディングが必須となり、prefer に設定すると利用可能な場合にクライアントがチャネルバインディングを選択し、disable に設定するとチャネルバインディングを使用しません。PostgreSQL が SSL サポート付きでコンパイルされている場合、デフォルトは prefer です。それ以外の場合、デフォルトは disable です。

チャネルバインディングは、サーバーをクライアントに対して認証する方法です。PostgreSQL 11 以降のサーバーとの SSL 接続で、SCRAM 認証方式を使用する場合にのみサポートされます。

connect_timeout #

接続時に待機する最大時間を秒単位で指定します（10 のように、10 進整数で記述します）。ゼロ、負の値、または未指定の場合は、無期限に待機します。このタイムアウトはホスト名または IP アドレスごとに個別に適用されます。たとえば、2 つのホストを指定し、connect_timeout が 5 の場合、5 秒以内に接続できなければ各ホストでタイムアウトするため、接続待ちの合計時間は最大 10 秒となる可能性があります。

client_encoding #

この接続の client_encoding 設定パラメーターを設定します。対応するサーバーオプションで受け入れられる値に加えて、auto を使うと、クライアントの現在のロケールから適切なエンコーディングを判定できます（Unix システムでは LC_CTYPE 環境変数が使われます）。

options #

接続開始時にサーバーへ送るコマンドラインオプションを指定します。たとえば、これを -c geqo=off または --geqo=off に設定すると、セッションの geqo パラメーターの値が off に設定されます。この文字列内の空白は、バックスラッシュ（\）でエスケープされていない限り、コマンドライン引数の区切りとして扱われます。バックスラッシュを表すには \ と記述します。利用可能なオプションの詳しい説明は、第 19 章を参照してください。

application_name #

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

fallback_application_name #

application_name 設定パラメーターのフォールバック値を指定します。接続パラメーターまたは PGAPPNAME 環境変数で application_name の値が指定されていない場合、この値が使われます。フォールバック名の指定は、デフォルトのアプリケーション名を設定しつつ、ユーザーによる上書きも許可したい汎用ユーティリティプログラムに役立ちます。

keepalives #

クライアント側の TCP keepalive を使用するかどうかを制御します。デフォルト値は 1（有効）ですが、keepalive が不要な場合は 0（無効）に変更できます。このパラメーターは、Unix ドメインソケット経由で行われる接続では無視されます。

keepalives_idle #

TCP がサーバーに keepalive メッセージを送信するまでの無通信時間を秒単位で制御します。値がゼロの場合はシステムのデフォルトが使われます。このパラメーターは、Unix ドメインソケット経由の接続、または keepalives が無効な場合は無視されます。TCP_KEEPIDLE または同等のソケットオプションが利用可能なシステムと Windows でのみサポートされます。それ以外のシステムでは効果がありません。

keepalives_interval #

サーバーから確認応答のない TCP keepalive メッセージを再送信するまでの秒数を制御します。値がゼロの場合はシステムのデフォルトが使われます。このパラメーターは、Unix ドメインソケット経由の接続、または keepalives が無効な場合は無視されます。TCP_KEEPINTVL または同等のソケットオプションが利用可能なシステムと Windows でのみサポートされます。それ以外のシステムでは効果がありません。

keepalives_count #

クライアントとサーバー間の接続が切断されたと判断される前に、クライアントが失ってもよい TCP keepalive の数を制御します。値がゼロの場合はシステムのデフォルトが使われます。このパラメーターは、Unix ドメインソケット経由の接続、または keepalives が無効な場合は無視されます。TCP_KEEPCNT または同等のソケットオプションが利用可能なシステムでのみサポートされます。それ以外のシステムでは効果がありません。

tcp_user_timeout #

接続が強制的に閉じられるまでに、送信データの確認応答がない状態で許容される時間をミリ秒単位で制御します。値がゼロの場合はシステムのデフォルトが使われます。このパラメーターは、Unix ドメインソケット経由で行われる接続では無視されます。TCP_USER_TIMEOUT が利用可能なシステムでのみサポートされます。それ以外のシステムでは効果がありません。

replication #

このオプションは、通常のプロトコルの代わりにレプリケーションプロトコルを使うかどうかを決定します。これは、PostgreSQL のレプリケーション接続や pg_basebackup などのツールで内部的に使われますが、サードパーティ製アプリケーションでも使用できます。レプリケーションプロトコルの説明は、54.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 で暗号化された接続のみを試みます。

Unix ドメインソケット通信では gssencmode は無視されます。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 によって発行されたこと、および要求されたサーバーのホスト名が証明書内のホスト名と一致することを検証します。

これらのオプションの動作の詳細は、32.19 節を参照してください。Unix ドメインソケット通信では sslmode は無視されます。PostgreSQL が SSL サポートなしでコンパイルされている場合、require、verify-ca、verify-full の各オプションを使うとエラーになります。allow と prefer は受け入れられますが、libpq は実際には SSL 接続を試みません。

GSSAPI 暗号化が可能な場合、sslmode の値にかかわらず、SSL 暗号化よりも GSSAPI 暗号化が優先されることに注意してください。GSSAPI インフラストラクチャ（Kerberos サーバーなど）が稼働している環境で SSL 暗号化を強制するには、gssencmode も disable に設定してください。

requiressl #

このオプションは非推奨であり、sslmode 設定の使用が推奨されます。1 に設定すると、サーバーへの SSL 接続が必須になります（これは sslmode require と同等です）。サーバーが SSL 接続を受け入れない場合、libpq は接続を拒否します。0（デフォルト）に設定すると、libpq はサーバーと接続の種類をネゴシエートします（sslmode prefer と同等です）。このオプションは、PostgreSQL が SSL サポート付きでコンパイルされている場合にのみ使用できます。

sslnegotiation #

このオプションは、SSL を使う場合に、サーバーとの SSL 暗号化をどのようにネゴシエートするかを制御します。デフォルトの postgres モードでは、クライアントはまずサーバーに SSL がサポートされているかを尋ねます。direct モードでは、TCP/IP 接続を確立した直後に、クライアントが標準 SSL ハンドシェイクを開始します。従来の PostgreSQL プロトコルネゴシエーションは、さまざまなサーバー設定に対して最も柔軟です。サーバーが direct SSL 接続をサポートしていることが分かっている場合、後者は往復を 1 回減らして接続の遅延を抑え、プロトコルに依存しない SSL ネットワークツールの使用も可能にします。direct SSL オプションは PostgreSQL バージョン 17 で導入されました。

postgres PostgreSQL プロトコルネゴシエーションを実行します。オプションが指定されていない場合のデフォルトです。

direct TCP/IP 接続を確立した直後に SSL ハンドシェイクを開始します。弱い設定では、サーバーが direct SSL ハンドシェイクをサポートしていない場合に、意図せず平文認証にフォールバックする可能性があるため、この指定は sslmode=require 以上の場合にのみ許可されます。

sslcompression #

1 に設定すると、SSL 接続で送信されるデータが圧縮されます。0 に設定すると、圧縮は無効になります。デフォルトは 0 です。SSL を使わない接続では、このパラメーターは無視されます。SSL 圧縮は現在、安全でないと考えられており、使用は推奨されていません。OpenSSL 1.1.0 ではデフォルトで圧縮が無効になっており、それ以前のバージョンでも多くのオペレーティングシステムのディストリビューションで無効にされているため、サーバーが圧縮を受け入れない場合、このパラメーターを on に設定しても効果はありません。PostgreSQL 14 では、バックエンドでの圧縮が完全に無効になりました。

セキュリティが最優先事項ではない場合、ネットワークがボトルネックであれば圧縮によってスループットを向上できることがあります。CPU の性能が制限要因であれば、圧縮を無効にすることで応答時間とスループットを向上できることがあります。

sslcert #

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

sslkey #

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

sslkeylogfile #

このパラメーターは、この SSL コンテキストで使われるキーを libpq が記録する場所を指定します。これは、Wireshark などのネットワーク検査ツールを使って PostgreSQL プロトコルのやり取りやクライアント接続をデバッグする場合に役立ちます。SSL 接続を行わない場合、または LibreSSL を使う場合（LibreSSL はキーの記録をサポートしていません）、このパラメーターは無視されます。キーは NSS 形式で記録されます。

警告

キーの記録により、機密情報が keylog ファイルに漏れる可能性があります。keylog ファイルは sslkey ファイルと同様に慎重に取り扱ってください。

sslpassword #

このパラメーターは、sslkey で指定された秘密鍵のパスワードを指定します。対話型のパスフレーズ入力が実用的でない場合でも、クライアント証明書の秘密鍵を暗号化した状態でディスクに保存できます。このパラメーターに空でない値を指定すると、暗号化されたクライアント証明書キーが libpq に渡された際に、OpenSSL がデフォルトで表示する Enter PEM pass phrase: プロンプトが抑止されます。キーが暗号化されていない場合、このパラメーターは無視されます。OpenSSL エンジンで指定されたキーには、そのエンジンがプロンプトに OpenSSL パスワードコールバック機構を使う場合を除き、このパラメーターは効果がありません。

このオプションに相当する環境変数はなく、.pgpass から検索する仕組みもありません。サービスファイルの接続定義では使用できます。より高度な用途があるユーザーは、OpenSSL エンジンや PKCS#11、USB 暗号オフロードデバイスなどのツールの使用を検討してください。

sslcertmode #

このオプションは、クライアント証明書をサーバーに送信できるかどうか、およびサーバーが証明書を要求する必要があるかどうかを決定します。次の 3 つのモードがあります。

disable クライアント証明書が利用可能でも、送信しません（デフォルトの場所にある証明書も、sslcert で指定された証明書も対象です）。

allow（デフォルト）サーバーがクライアント証明書を要求し、クライアントが送信できる証明書を持っている場合、送信できます。

require サーバーは証明書を要求する必要があります。クライアントが証明書を送信せず、それでもサーバーがクライアントを正常に認証した場合、接続は失敗します。

注記

sslcertmode=require を指定しても、追加のセキュリティは得られません。サーバーが証明書を正しく検証している保証がないためです。PostgreSQL サーバーは通常、証明書を検証するかどうかにかかわらず、クライアントに TLS 証明書を要求します。このオプションは、より複雑な TLS 設定のトラブルシューティングに役立つ場合があります。

sslrootcert #

このパラメーターは、SSL 認証局（CA）証明書を格納したファイル名を指定します。ファイルが存在する場合、サーバーの証明書がこれらの認証局のいずれかによって署名されたことが検証されます。デフォルトは ~/.postgresql/root.crt です。代わりに特殊な値 system を指定すると、SSL 実装が信頼するルート 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 は SSL 対応接続で TLS 拡張の「サーバー名表示」（SNI）を設定します。このパラメーターを 0 に設定すると無効になります。サーバー名表示は、SSL 対応プロキシが SSL ストリームを復号せずに接続をルーティングするために使われます。（ただし、プロキシが PostgreSQL プロトコルのハンドシェイクを認識できない場合、sslnegotiation を direct に設定する必要があることに注意してください。）一方、SNI により接続先のホスト名がネットワークトラフィック上に平文で現れるため、状況によっては望ましくない場合があります。

requirepeer #

このパラメーターは、サーバーのオペレーティングシステム上のユーザー名を指定します。たとえば、requirepeer=postgres と指定します。Unix ドメインソケット接続時にこのパラメーターが設定されている場合、クライアントは接続開始時に、サーバープロセスが指定されたユーザー名で実行されていることを確認します。そうでない場合、エラーを伴って接続が中止されます。

このパラメーターは、TCP/IP 接続の SSL 証明書で利用できるものと同様のサーバー認証を提供するために使用できます。（Unix ドメインソケットが /tmp など、一般ユーザーが書き込み可能な場所にある場合、誰でもそこで待ち受けるサーバーを起動できることに注意してください。このパラメーターを使うと、信頼できるユーザーが実行するサーバーに接続していることを確認できます。）

このオプションは、ピア認証方式が実装されているプラットフォームでのみサポートされています。20.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 のバージョンに依存します。古いバージョンでは、最も新しいプロトコルバージョンがサポートされない場合があります。設定されていない場合、このパラメーターは無視され、バックエンドで上限が設定されていれば、それに従って接続されます。最大プロトコルバージョンの設定は、主にテスト目的、または新しいプロトコルで問題が発生するコンポーネントがある場合に役立ちます。

min_protocol_version #

接続で許可するプロトコルの最小バージョンを指定します。デフォルトでは、libpq がサポートする任意の PostgreSQL プロトコルバージョンが許可されます。現在は 3.0 です。サーバーがこのバージョン以上をサポートしていない場合、接続は閉じられます。現在サポートされている値は 3.0、3.2、latest です。latest は、使用中の libpq バージョンがサポートする最新のプロトコルバージョンと同等で、現在は 3.2 です。

max_protocol_version #

サーバーに要求するプロトコルバージョンを指定します。デフォルトでは、PostgreSQL プロトコルのバージョン 3.0 が使われます。ただし、接続文字列でより高いプロトコルバージョンを必要とする機能が指定されている場合は、libpq がサポートする最新バージョンが使われます。サーバーがクライアントから要求されたプロトコルバージョンをサポートしていない場合、サーバーがサポートするより低いマイナーバージョンに接続が自動的にダウングレードされます。接続試行の完了後、PQprotocolVersion を使ってネゴシエートされた正確なプロトコルバージョンを確認できます。現在サポートされている値は 3.0、3.2、latest です。latest は、使用中の libpq バージョンがサポートする最新のプロトコルバージョンと同等で、現在は 3.2 です。

krbsrvname #

GSSAPI で認証する際に使う Kerberos サービス名です。Kerberos 認証を成功させるには、サーバー設定に指定されたサービス名と一致する必要があります。（20.6 節も参照してください。）デフォルト値は通常 postgres ですが、configure の --with-krb-srvnam オプションを使って PostgreSQL をビルドする際に変更できます。ほとんどの環境では、このパラメーターを変更する必要はありません。Microsoft Active Directory のように、サービス名を大文字（POSTGRES）にする必要がある Kerberos 実装もあります。

gsslib #

GSSAPI 認証に使う GSS ライブラリーです。現在、この設定は、GSSAPI と SSPI の両方を含む Windows ビルド以外では無視されます。その場合、gssapi に設定すると、libpq はデフォルトの SSPI ではなく、認証に GSSAPI ライブラリーを使用します。

gssdelegation #

GSS 認証情報をサーバーに転送（委任）します。デフォルトは 0 で、認証情報はサーバーに転送されません。1 に設定すると、可能な場合に認証情報が転送されます。

scram_client_key #

base64 エンコードされた SCRAM クライアントキーです。外部データラッパーや同様のミドルウェアで、SCRAM 認証のパススルーを有効にするために使えます。そのような実装の例は F.38.1.10 節を参照してください。ユーザーやクライアントアプリケーションが直接指定することを意図したものではありません。

scram_server_key #

base64 エンコードされた SCRAM サーバーキーです。外部データラッパーや同様のミドルウェアで、SCRAM 認証のパススルーを有効にするために使えます。そのような実装の例は F.38.1.10 節を参照してください。ユーザーやクライアントアプリケーションが直接指定することを意図したものではありません。

service #

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

target_session_attrs #

このオプションは、セッションが受け入れ可能であるために特定のプロパティを備えている必要があるかどうかを決定します。通常は複数のホスト名と組み合わせて使い、複数のホストから最初に受け入れ可能な接続先を選択します。次の 6 つのモードがあります。

any（デフォルト）成功した接続であれば、どれでも受け入れ可能です。

read-write セッションはデフォルトで読み書きトランザクションを受け入れる必要があります（つまり、サーバーがホットスタンバイモードであってはならず、default_transaction_read_only パラメーターが off でなければなりません）。

read-only セッションはデフォルトで読み書きトランザクションを受け入れてはいけません（上記の逆です）。

primary サーバーはホットスタンバイモードであってはいけません。

standby サーバーはホットスタンバイモードでなければなりません。

prefer-standby 最初にスタンバイサーバーを探します。リスト内にスタンバイサーバーがない場合は、任意のモードでもう一度試します。

load_balance_hosts #

利用可能なホストとアドレスへの接続をクライアントが試みる順序を制御します。接続の試行が成功すると、ほかのホストやアドレスは試されません。このパラメーターは通常、複数のホスト名、または複数の IP を返す DNS レコードと組み合わせて使います。たとえば、スタンバイサーバー間のみで負荷分散するために、target_session_attrs と組み合わせて使用できます。接続に成功すると、返された接続での後続のクエリはすべて同じサーバーに送信されます。

現在、次の 2 つのモードがあります。

disable（デフォルト）ホスト間での負荷分散は行いません。ホストは指定された順序で試され、アドレスは DNS または hosts ファイルから取得した順序で試されます。

random ホストとアドレスをランダムな順序で試します。この値は、複数の接続を同時に開く場合（複数のマシンから接続する場合など）に主に役立ちます。これにより、複数の PostgreSQL サーバー間で接続の負荷を分散できます。ランダムな負荷分散は、ランダムであるため完全に均等な分布にはほとんどなりませんが、統計的にはかなり均等になります。

ここで重要なのは、このアルゴリズムが 2 段階のランダムな選択を使うことです。まず、ホストがランダムな順序で解決されます。次に、次のホストを解決する前に、現在のホストから解決されたすべてのアドレスがランダムな順序で試されます。この動作により、特定のケースでは各ノードが受け取る接続数が大きく偏ることがあります。たとえば、一部のホストがほかのホストよりも多くのアドレスに解決される場合です。ただし、この偏りを意図的に利用することもできます。たとえば、host 文字列に大規模なサーバーのホスト名を複数回指定すると、そのサーバーの受け取る接続数を増やせます。

この値を使う場合は、connect_timeout に妥当な値を設定することも推奨されます。負荷分散対象のノードが応答しない場合、新しいノードが試されるためです。

oauth_issuer #

サーバーが接続用の OAuth トークンを要求した場合に接続する、信頼できる発行者の HTTPS URL です。このパラメーターはすべての OAuth 接続に必須です。サーバーの HBA 設定にある issuer 設定と完全に一致していなければなりません。

標準の認証ハンドシェイクの一部として、libpq はサーバーにディスカバリードキュメントを要求します。これは OAuth 設定パラメーターの一覧を提供する URL です。サーバーは oauth_issuer の各要素から直接構成された URL を提供する必要があります。また、この値はディスカバリードキュメント自体で宣言されている発行者識別子と完全に一致しなければなりません。一致しない場合、接続は失敗します。これは、OAuth クライアントを狙った「ミックスアップ攻撃」の一種を防ぐために必要です。

OAuth ディスカバリーに使われる /.well-known/ URI を、oauth_issuer に明示的に設定することもできます。この場合、サーバーが別の URL を要求すると接続は失敗しますが、カスタム OAuth フローを使うことで、以前にキャッシュしたトークンを利用して標準ハンドシェイクを高速化できる場合があります。（この場合、oauth_scope も設定することが推奨されます。クライアントが正しいスコープ設定をサーバーに問い合わせる機会がなく、トークンのデフォルトスコープでは接続に不十分な可能性があるためです。）

現在、libpq は次の well-known エンドポイントをサポートしています。

/.well-known/openid-configuration

/.well-known/oauth-authorization-server

警告

OAuth 接続ハンドシェイクでは、発行者には非常に強い権限があります。大まかな目安として、サーバーへのアクセスを任せたり、自分になりすましたりすることを信頼できない URL の運営者は、oauth_issuer として信頼すべきではありません。

oauth_client_id #

認可サーバーが発行した OAuth 2.0 クライアント識別子です。PostgreSQL サーバーが接続用の OAuth トークンを要求し、それを提供するカスタム OAuth フックがインストールされていない場合、このパラメーターを設定する必要があります。設定されていない場合、接続は失敗します。

oauth_client_secret #

OAuth 認可サーバーへの接続時に使うクライアントパスワードです。必要かどうかは OAuth プロバイダーによって決まります。「パブリック」クライアントは通常シークレットを使用しませんが、「コンフィデンシャル」クライアントは通常使用します。

oauth_scope #

認可サーバーに送信するアクセス要求のスコープを、空の場合もある、空白区切りの OAuth スコープ識別子リストで指定します。このパラメーターは省略可能で、高度な用途を対象としています。通常、クライアントは PostgreSQL サーバーから適切なスコープ設定を取得します。このパラメーターを使うと、サーバーから要求されたスコープリストは無視されます。これにより、信頼性の低いサーバーがエンドユーザーに不適切なアクセススコープを要求するのを防げます。ただし、クライアントのスコープ設定にサーバーが必要とするスコープが含まれていない場合、サーバーは発行されたトークンを拒否する可能性が高く、接続は失敗します。空のスコープリストの意味はプロバイダーによって異なります。OAuth 認可サーバーは、プロバイダーにおける「デフォルトスコープ」のトークンを発行する場合もあれば、トークン要求全体を拒否する場合もあります。

PGconn

パターン 2: 32.1.1. 接続文字列 # libpq のいくつかの関数は、ユーザーが指定した文字列を解析して接続パラメーターを取得します。これらの文字列には、キーワード／値形式の文字列と URI の 2 つの形式が使用できます。URI は一般に RFC 3986 に従いますが、以下で詳しく説明するように、複数のホストを指定した接続文字列も使用できます。 32.1.1.1. キーワード／値形式の接続文字列 # キーワード／値形式では、各パラメーター設定は keyword = value の形式で、設定間にはスペースを入れます。設定の等号の前後のスペースは省略できます。空の値、またはスペースを含む値を記述するには、keyword = 'a value' のように単一引用符で囲みます。値の中に単一引用符やバックスラッシュを含める場合は、' および \ のようにバックスラッシュでエスケープする必要があります。例：host=localhost port=5432 dbname=mydb connect_timeout=10 認識されるパラメーターのキーワードは、セクション 32.1.2 に記載されています。 32.1.1.2. 接続 URI # 接続 URI の一般的な形式は次のとおりです。 postgresql://[userspec@][hostspec][/dbname][?paramspec] ここで、userspec は次のとおりです。 user[:password] hostspec は次のとおりです。 [host][:port][,...] paramspec は次のとおりです。 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 に変換される点を除き、セクション 32.1.2 に記載されているキーワードと一致している必要があります。URI の各部分で特別な意味を持つ記号が含まれる場合は、パーセントエンコーディングで接続 URI をエンコードする必要があります。以下は、等号（=）を %3D に、スペース文字を %20 に置き換える例です。 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff host 部分には、ホスト名または IP アドレスを指定できます。IPv6 アドレスを指定するには、角括弧で囲みます。 postgresql://[2001:db8::1234]/database host 部分は、パラメーター host の説明に従って解釈されます。特に、host 部分が空であるか、絶対パス名のように見える場合は Unix ドメインソケット接続が選択され、それ以外の場合は TCP/IP 接続が開始されます。ただし、スラッシュは URI の階層部分で予約文字です。そのため、標準以外の Unix ドメインソケットディレクトリを指定するには、URI の host 部分を省略して host を名前付きパラメーターとして指定するか、URI の host 部分のパスをパーセントエンコードします。 postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 1 つの URI に、ポート部分を省略可能な複数の host 要素を指定できます。形式が postgresql://host1:port1,host2:port2,host3:port3/ の URI は、host=host1,host2,host3 port=port1,port2,port3 形式の接続文字列と同等です。以下で詳しく説明するように、接続が確立されるまで各ホストが順番に試されます。 32.1.1.3. 複数のホストの指定 # 接続先として複数のホストを指定し、指定した順に試すことができます。キーワード／値形式では、host、hostaddr、port オプションに、カンマ区切りの値のリストを指定できます。指定する各オプションでは要素数を一致させる必要があります。たとえば、最初の hostaddr は最初のホスト名に、2 番目の hostaddr は 2 番目のホスト名に対応します。例外として、port を 1 つだけ指定した場合は、すべてのホストに適用されます。接続 URI 形式では、URI の host 部分に、複数の host:port の組をカンマ区切りで列挙できます。いずれの形式でも、1 つのホスト名が複数のネットワークアドレスに変換される場合があります。よくある例として、IPv4 アドレスと IPv6 アドレスの両方を持つホストがあります。複数のホストを指定した場合、または 1 つのホスト名が複数のアドレスに変換された場合は、いずれかで成功するまで、すべてのホストとアドレスが順番に試されます。どのホストにも到達できない場合、接続は失敗します。接続の確立後に認証に失敗した場合、リスト内の残りのホストは試されません。パスワードファイルを使用する場合は、ホストごとに異なるパスワードを設定できます。リスト内のすべてのホストで、その他の接続オプションは同じです。たとえば、ホストごとに異なるユーザー名を指定することはできません。

keyword

**パターン 3：**例：

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

パターン 4： 32.1.1.2. 接続 URI # 接続 URI の一般的な形式は次のとおりです。 postgresql://[userspec@][hostspec][/dbname][?paramspec] userspec は次のとおりです。 user[:password] hostspec は次のとおりです。 [host][:port][,...] paramspec は次のとおりです。 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 名前付きパラメーターはすべて、32.1.2 項に記載されているキーワードに一致する必要があります。ただし、JDBC 接続 URI との互換性のため、ssl=true は sslmode=require に変換されます。接続 URI のいずれかの部分に特別な意味を持つ記号が含まれる場合は、パーセントエンコーディングを使用して URI をエンコードする必要があります。以下の例では、等号（=）を %3D に、空白文字を %20 に置き換えています。 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff host 部分には、ホスト名または IP アドレスを指定できます。IPv6 アドレスを指定する場合は、角括弧で囲みます。 postgresql://[2001:db8::1234]/database host 部分は、host パラメーターについての説明に従って解釈されます。特に、host 部分が空であるか、絶対パス名のように見える場合は、Unix ドメインソケット接続が選択されます。それ以外の場合は、TCP/IP 接続が開始されます。ただし、スラッシュは URI の階層部分で予約文字です。そのため、標準以外の Unix ドメインソケットディレクトリを指定するには、URI の host 部分を省略して host を名前付きパラメーターとして指定するか、URI の host 部分のパスをパーセントエンコードします。 postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 1 つの URI で、それぞれポート部分を省略できる複数の host コンポーネントを指定できます。postgresql://host1:port1,host2:port2,host3:port3/ 形式の URI は、host=host1,host2,host3 port=port1,port2,port3 形式の接続文字列と同等です。以下で詳しく説明するように、接続が正常に確立されるまで、各ホストへの接続が順に試みられます。

postgresql://[userspec@][hostspec][/dbname][?paramspec]

where userspec is:

user[:password]

and hostspec is:

[host][:port][,...]

and paramspec is:

name=value[&...]

パターン 5： 21.5. 定義済みロール # PostgreSQL には、一般的に必要とされる特定の特権機能や情報へのアクセスを提供する、定義済みロールが用意されています。管理者（CREATEROLE 権限を持つロールを含む）は、これらのロールを環境内のユーザーや他のロールに GRANT し、指定された機能や情報へのアクセスをユーザーに許可できます。たとえば、次のようにします。 GRANT pg_signal_backend TO admin_user; 警告 これらのロールを GRANT する際は、必要な場合にのみ使用し、特権情報へのアクセスが許可されることを理解したうえで行ってください。定義済みロールについては、以下で説明します。機能が追加されると、それぞれのロールに対する具体的な権限が将来変更される可能性があることに注意してください。管理者は、変更についてリリースノートを確認してください。 pg_checkpoint # pg_checkpoint は CHECKPOINT コマンドの実行を許可します。 pg_create_subscription # pg_create_subscription は、データベースに対する CREATE 権限を持つユーザーに CREATE SUBSCRIPTION の発行を許可します。 pg_database_owner # pg_database_owner には常に、現在のデータベースの所有者という暗黙のメンバーがちょうど 1 つ存在します。いずれのロールにもメンバーシップを付与できず、pg_database_owner にメンバーシップを付与することもできません。ただし、他のロールと同様に、オブジェクトを所有し、アクセス権限の GRANT を受けることができます。そのため、テンプレートデータベース内で pg_database_owner に権限が与えられると、そのテンプレートから作成された各データベースの所有者がその権限を持つことになります。初期状態では、このロールが public スキーマを所有しているため、各データベースの所有者がそのスキーマのローカルでの使用を管理します。 pg_maintain # pg_maintain は、オブジェクトに対する MAINTAIN 権限を持つ場合と同様に、すべてのリレーションに対して VACUUM、ANALYZE、CLUSTER、REFRESH MATERIALIZED VIEW、REINDEX、LOCK TABLE を実行することを許可します。 pg_monitorpg_read_all_settingspg_read_all_statspg_stat_scan_tables # これらのロールは、データベースサーバーの監視を目的とするロールを管理者が簡単に設定できるようにするものです。これらのロールは、通常はスーパーユーザーに限定されている、さまざまな有用な設定、統計情報、その他のシステム情報を読み取るための一般的な権限を付与します。 pg_monitor は、さまざまな監視用ビューや関数の読み取りと実行を許可します。このロールは pg_read_all_settings、pg_read_all_stats、pg_stat_scan_tables のメンバーです。 pg_read_all_settings は、通常はスーパーユーザーにのみ表示されるものも含め、すべての設定変数の読み取りを許可します。 pg_read_all_stats は、通常はスーパーユーザーにのみ表示されるものも含め、すべての pg_stat_* ビューの読み取りと、さまざまな統計関連の拡張機能の使用を許可します。 pg_stat_scan_tables は、テーブルに対して ACCESS SHARE ロックを長時間取得する可能性のある監視関数の実行を許可します（例：pgrowlocks 拡張機能の pgrowlocks(text)）。 pg_read_all_datapg_write_all_data # pg_read_all_data は、対象オブジェクトに対する SELECT 権限と、すべてのスキーマに対する USAGE 権限を持つ場合と同様に、すべてのデータ（テーブル、ビュー、シーケンス）の読み取りを許可します。このロールは行レベルセキュリティ（RLS）ポリシーを回避しません。RLS を使用している場合、管理者はこのロールが GRANT されるロールに BYPASSRLS を設定することを検討してもよいでしょう。 pg_write_all_data は、対象オブジェクトに対する INSERT、UPDATE、DELETE 権限と、すべてのスキーマに対する USAGE 権限を持つ場合と同様に、すべてのデータ（テーブル、ビュー、シーケンス）の書き込みを許可します。このロールは行レベルセキュリティ（RLS）ポリシーを回避しません。RLS を使用している場合、管理者はこのロールが GRANT されるロールに BYPASSRLS を設定することを検討してもよいでしょう。 pg_read_server_filespg_write_server_filespg_execute_server_program # これらのロールは、データベースサーバー上のファイルにアクセスし、データベースを実行しているユーザーとしてプログラムを実行できる、信頼された非スーパーユーザーロールを管理者が用意できるようにするものです。ファイルに直接アクセスする際、データベースレベルの権限チェックをすべて回避し、スーパーユーザーレベルのアクセス権を得るために使用される可能性があります。そのため、これらのロールをユーザーに GRANT する際は十分に注意してください。 pg_read_server_files は、COPY やその他のファイルアクセス関数を使用して、サーバー上でデータベースがアクセスできる任意の場所からファイルを読み取ることを許可します。 pg_write_server_files は、COPY やその他のファイルアクセス関数を使用して、サーバー上でデータベースがアクセスできる任意の場所にファイルを書き込むことを許可します。 pg_execute_server_program は、COPY やサーバー側プログラムの実行を許可するその他の関数を使用して、データベースサーバー上でデータベースを実行しているユーザーとしてプログラムを実行することを許可します。 pg_signal_autovacuum_worker # pg_signal_autovacuum_worker は、autovacuum ワーカーにシグナルを送信し、現在のテーブルに対する vacuum をキャンセルするか、そのセッションを終了することを許可します。セクション 9.28.2 を参照してください。 pg_signal_backend # pg_signal_backend は、別のバックエンドにシグナルを送信し、クエリをキャンセルするか、そのセッションを終了することを許可します。このロールでは、スーパーユーザーが所有するバックエンドにシグナルを送信できないことに注意してください。セクション 9.28.2 を参照してください。 pg_use_reserved_connections # pg_use_reserved_connections は、reserved_connections を通じて予約された接続スロットの使用を許可します。

CREATEROLE

パターン 6： 6.4. 変更された行からのデータの返却 # 行を操作している間に、変更された行のデータを取得すると便利な場合があります。INSERT、UPDATE、DELETE、MERGE コマンドには、この機能をサポートする省略可能な RETURNING 句があります。RETURNING を使用すると、データを収集するための追加のデータベースクエリが不要になり、変更された行を確実に特定するのが難しい場合に特に役立ちます。RETURNING 句で指定できる内容は、SELECT コマンドの出力リストと同じです（7.3 節を参照）。コマンドの対象テーブルの列名、またはそれらの列を使用する値式を指定できます。よく使われる省略形は RETURNING * で、対象テーブルのすべての列を順番に選択します。INSERT では、RETURNING で利用できるデータは、デフォルトで挿入されたときの行です。単純な INSERT では、クライアントが指定したデータをそのまま繰り返すだけなので、あまり役に立ちません。しかし、計算されたデフォルト値を利用する場合には非常に便利です。たとえば、シリアル列を使用して一意の識別子を割り当てる場合、RETURNING を使って新しい行に割り当てられた ID を返すことができます。

CREATE TABLE users (firstname text, lastname text, id serial primary key); INSERT INTO users (firstname, lastname) VALUES ('Joe', 'Cool') RETURNING id;

RETURNING 句は、INSERT ... SELECT でも非常に便利です。

UPDATE では、RETURNING で利用できるデータは、デフォルトで変更後の行の内容です。たとえば、次のようになります。

UPDATE products SET price = price * 1.10 WHERE price <= 99.99 RETURNING name, price AS new_price;

DELETE では、RETURNING で利用できるデータは、デフォルトで削除された行の内容です。たとえば、次のようになります。

DELETE FROM products WHERE obsoletion_date = 'today' RETURNING *;

MERGE では、RETURNING で利用できるデータは、デフォルトでソース行の内容と、挿入、更新、または削除された対象行の内容です。ソースと対象に同じ列が多く含まれることはよくあるため、RETURNING * を指定すると列が大量に重複することがあります。そのため、ソース行または対象行だけを返すように指定すると、より便利な場合がよくあります。たとえば、次のようになります。

MERGE INTO products p USING new_products n ON p.product_no = n.product_no WHEN NOT MATCHED THEN INSERT VALUES (n.product_no, n.name, n.price) WHEN MATCHED THEN UPDATE SET name = n.name, price = n.price RETURNING p.*;

これらの各コマンドでは、変更された行の変更前と変更後の内容を明示的に返すこともできます。たとえば、次のようになります。

UPDATE products SET price = price * 1.10 WHERE price <= 99.99 RETURNING name, old.price AS old_price, new.price AS new_price, new.price - old.price AS price_change;

この例では、new.price と書くことは単に price と書くのと同じですが、意味がより明確になります。変更前と変更後の値を返すこの構文は、INSERT、UPDATE、DELETE、MERGE コマンドで使用できます。ただし、通常、INSERT では変更前の値は NULL になり、DELETE では変更後の値は NULL になります。それでも、こうしたコマンドで役立つ状況があります。たとえば、ON CONFLICT DO UPDATE 句を含む INSERT では、競合する行の変更前の値は NULL 以外になります。同様に、書き換えルールによって DELETE が UPDATE に変換される場合、変更後の値が NULL 以外になることがあります。対象テーブルにトリガー（第 37 章）がある場合、RETURNING で利用できるデータは、トリガーによって変更された後の行です。そのため、トリガーによって計算された列を調べることも、RETURNING の一般的な用途です。

INSERT

パターン 7： UPDATE では、RETURNING で利用できるデータは、デフォルトで変更後の行の内容です。たとえば、次のようになります。

UPDATE

パターン 8： DELETE では、RETURNING で利用できるデータは、デフォルトで削除された行の内容です。たとえば、次のようになります。

DELETE

コードパターンの例

例 1（javascript）：

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

例 2（javascript）：

PGconn *PQconnectdb(const char *conninfo);

参考ファイル

このスキルには、references/ に包括的なドキュメントが含まれています。

• getting_started.md - はじめにのドキュメント
• sql.md - Sql のドキュメント

詳細情報が必要な場合は、view を使用して特定の参考ファイルを読んでください。

このスキルの使用

初心者向け

基本概念を学ぶには、getting_started または tutorials の参考ファイルから始めてください。

特定の機能について

詳細情報については、該当するカテゴリの参考ファイル（api、guides など）を使用してください。

コード例について

上記のクイックリファレンスには、公式ドキュメントから抜粋した一般的なパターンが含まれています。

リソース

references/

公式ソースから抜粋したドキュメントを整理しています。これらのファイルには、以下が含まれます。

• 詳細な説明
• 言語注釈付きのコード例
• 元のドキュメントへのリンク
• すばやく参照できる目次

scripts/

一般的な自動化タスク用のヘルパースクリプトをここに追加してください。

assets/

テンプレート、ボイラープレート、またはサンプルプロジェクトをここに追加してください。

注記

• このスキルは公式ドキュメントから自動生成されました
• 参考ファイルでは、ソースドキュメントの構造と例が保持されています
• コード例には、シンタックスハイライトを向上させるために言語検出が含まれています
• クイックリファレンスのパターンは、ドキュメント内の一般的な使用例から抜粋されています

更新

更新されたドキュメントでこのスキルを更新するには：

1. 同じ設定でスクレーパーを再実行します
2. 最新情報を使用してスキルが再構築されます