PostgreSQL接続URI入門

はじめに

データベースサーバーへの接続は、通常、データベースを利用するアプリケーションを設計および構成する際に最初に行う必要のあるタスクの1つです。アドレス、リスニングポート、認証情報、その他の詳細をアプリケーションに提供する方法は多数ありますが、接続URI（接続文字列または接続URLとも呼ばれることがあります）は、複雑な構成をコンパクトな形式で指定する最も強力で柔軟な方法の1つです。

このガイドでは、PostgreSQLデータベース情報と認証の詳細を含む接続URIのフォーマット方法について説明します。接続URIはセクションに分かれているため、各部分を順に説明します。

パーセントエンコード値

始める前に、PostgreSQL接続URIはパーセントエンコードされた値を想定していることに言及する必要があります。これは、URL内で特別な意味を持つ文字は、ライブラリやアプリケーションが正しく解釈できるように、パーセントエンコードされた対応するものに変換する必要があることを意味します。

パーセントエンコードする必要がある文字は次のとおりです

• (スペース): %20
• %: %25
• &: %26
• /: %2F
• :: %3A
• =: %3D
• ?: %3F
• @: %40
• [: %5B
• ]: %5D

これらは接続URI内で特別な意味を持ちます。

パスワードが...の場合

pe@ce&lo\/3

...接続URI内で次のように指定する必要があります

pe%40ce%26lo\%2F3

文字をパーセントエンコードする必要があるかどうか不明な場合は、とにかくエンコードするのが通常は最善です。たとえば、\文字が予約されているかどうか不明な場合は、パーセントエンコードされた同等の%5Cを使用して安全を期することができます

pe%40ce%26lo%5C%2F3

接続URIを構築する際には、この点に留意してください。

簡単な概要

詳細に入る前に、PostgreSQL接続URIの仕様を見てみましょう

postgres[ql]://[username[:password]@][host[:port],]/database[?parameter_list]

\_____________/\____________________/\____________/\_______/\_______________/
     |                   |                  |          |            |
     |- schema           |- userspec        |          |            |- parameter list
                                            |          |
                                            |          |- database name
                                            |
                                            |- hostspec

角括弧内の部分はオプションの部分を示しています。URIのほとんどの部分がオプションであることに気付いたかもしれません。また、URIにエンコードできる情報がたくさんあることも明らかかもしれません。

個々のコンポーネントの簡単な説明

• postgres[ql]: スキーマ識別子。postgresqlまたは単にpostgresを使用できます。
• userspec: オプションのURIコンポーネント。接続するユーザーとパスワードを指定するために使用できます。
  • username: オプションのユーザー名。含める場合、2番目のスラッシュ（/）の後から始まり、コロン（:）（パスワードも提供されている場合）またはアットマーク（@）（パスワードが提供されていない場合）まで続きます。
  • password: オプションのパスワード。含める場合、コロン（:）の後から始まり、アットマーク（@）まで続きます。
• hostspec: 接続先のホスト名とポートを指定するために使用されるオプションのコンポーネント。
  • host: 接続先のサーバーのオプションのIPアドレス、DNS名、またはローカルで解決可能な名前。ホストはコロン（:）（ポートが含まれている場合）またはスラッシュ（ポートが含まれていない場合）まで続きます
  • port: サーバー上のPostgreSQLがリッスンしているポートを示すオプションのポート指定。ポートはコロン（:）で始まり、スラッシュ（/）まで続きます
• database name: 接続する個々のデータベースの名前。
• parameter list: 接続動作に影響を与える可能性のある追加パラメータのオプションリスト。パラメータリストは疑問符（?）で始まります。
  • parameter pairs: パラメータリストはキーと値のペアで構成されています。各ペア内のキーと値は等号（=）で区切られ、各ペアはアンパサンド（&）で次のペアから区切られます。

これらすべてのコンポーネントを組み込んだPostgreSQL接続URIの例を次に示します

postgresql://sally:sallyspassword@dbserver.example:5555/userdata?connect_timeout=10&sslmode=require&target_session_attrs=primary
    ^          ^         ^               ^           ^     ^          ^
    |- schema  |         |- password     |- host     |     |          |- parameter list
               |                                     |     |
               |- username                           |     |- database
                                                     |
                                                     |- port

URIタイプの指定

接続URIの最初の項目は、通常、プロトコル仕様またはアプリケーションタイプです。URIはPostgreSQLデータベースへの接続と認証に使用されるため、使用しているアプリケーションとライブラリにそれを知らせる記号を使用する必要があります。

PostgreSQLプロジェクトは、postgresql://とpostgres://の両方を有効なURIスキーマ指定子として受け入れます。したがって、接続URIは、これらの2つの文字列のいずれかで始める必要があります

postgresql://
postgres://

スキーマ指定子は、後続の情報が正しいコンテキストで解釈されるようにします。

ユーザー名とパスワードの指定

URIの次の部分は、ユーザー認証情報です。これは仕様ではuserspecと呼ばれています。userspecは技術的にはオプションですが、アプリケーションまたはデータベースによって構成されたデフォルトに依存したくない場合は、通常必要になります。

含める場合、userspecはコロンと二重スラッシュ（://）の後から始まり、アットマーク（@）で終わります。

ユーザー名のみを指定するには、それらの2つの記号の間に配置できます

postgresql://username@

ユーザー名とパスワードを指定するには、最初にユーザー名、次にコロン（:）、次にパスワードとアットマークを指定します

postgresql://username:password@

アプリケーションは、終端のアットマーク（@）を含めることで、このデータをuserspecとして解釈できます。フィールドが1つだけ提供されている場合（スラッシュとアットマークの間にコロンがない場合）、ユーザー名として解釈されます。

サーバーがリッスンしている場所の指定

userspecの後に、サーバーがリッスンしている場所を定義するhostspecが続きます。hostspecもオプションですが、クライアントまたはライブラリで設定されたデフォルトに依存していない場合は、ほとんどの場合に役立ちます。

hostspecは、hostとオプションのportで構成されています。hostには、ローカルで解決可能なホスト名、DNSなどの外部名前解決システムによって解決される名前、またはIPアドレスまたはその他の直接アドレスを使用できます。ポートは、PostgreSQLがリッスンしているポート番号を示します。

アプリケーションがローカルコンピューターのデフォルトのPostgreSQLポート（5432）に接続しようとするように指定するには、次を使用できます

postgresql://localhost

ユーザー名とパスワードを含める必要がある場合、その情報は最初に来て、アットマークで区切られます

postgresql://username:password@localhost

非標準ポートで実行されているリモートサーバーを指定するには、それらの詳細をコロンで区切ります。たとえば、198.51.100.22のホストのポート3333に接続するには、次を使用できます

postgresql://username:password@198.51.100.22:3333

実際には、カンマ（,）で区切られた複数のホストとポートのペアを提供して、最初のサーバーに到達できない場合に後者のサーバーを試すようにアプリケーションに指示できます。たとえば、前の例を拡張して、198.51.100.33のポート5555でリッスンしているフォールバックサーバーを含めるには、次を使用できます

postgresql://username:password@198.51.100.22:3333,198.51.100.33:5555

準拠クライアントとアプリケーションは、最初に198.51.100.22:3333でリッスンしているサーバーへの接続を試みます。それが失敗した場合、198.51.100.33:5555でリッスンしているPostgreSQLデータベースへの接続を試みます。

データベース名の提供

hostspecの後、次のデータはデータベース名です。すべてのデータベース管理システムに当てはまるわけではありませんが、PostgreSQLでは、接続を確立するときに特定のデータベースに接続する必要があります。

データベース名は、スラッシュ（/）で始まり、行末または疑問符（?）まで続きます。デフォルト値に依存していない場合は、データベース名を含める必要があります。

198.51.100.22:3333でリッスンしているPostgreSQLサーバーでホストされているsalesという名前のデータベースに接続するには、次のように入力できます

postgresql://username:password@198.51.100.22:3333/sales

追加パラメータの指定

接続URIの最後の部分は、接続の追加パラメータを提供するために使用されます。パラメータのリストは、先頭の疑問符（?）で始まり、行末まで続きます。

リストされている各パラメータは、等号（=）で結合されたキーと値のペアとして定義されます。最初のパラメータペアの後、追加のキーと値のペアはそれぞれアンパサンド（&）で区切られます。

たとえば、クライアントが以前に定義した接続に10秒のタイムアウトを適用するように指定するには、次を使用できます

postgresql://username:password@198.51.100.22:3333/sales?connect_timeout=10

追加のパラメータを提供したい場合は、各ペアの間にアンパサンド（&）を追加して後で追加します。たとえば、SSLが必要であり、サーバーがレプリカセットのプライマリである場合にのみ接続したい場合、次を追加できます

postgresql://username:password@198.51.100.22:3333/sales?connect_timeout=10&sslmode=require&target_session_attrs=primary

PostgreSQLのドキュメントには、詳細を知るために読むことができるパラメータの完全なリストがあります。

結論

このガイドでは、PostgreSQL接続URIとは何か、さまざまなコンポーネントを解釈する方法、および一連の接続情報が与えられた場合に独自のURIを構築する方法について説明しました。接続URIは、特定のデータベースへの接続に必要なすべての情報を単一の文字列にエンコードします。この柔軟性と広範な採用により、これらの文字列を解析および構築する方法を理解することは非常に役立ちます。