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つのフィールドのみが提供された場合（スラッシュとアットマークの間にコロンがない場合）、それはユーザー名として解釈されます。

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

After the userspec comes the hostspec which defines where the server is listening. The hostspec is, again, optional, but almost always useful if you aren't relying on defaults set in your client or library.

The hostspec consists of a host and an optional port. The host can either be a locally resolvable host name, a name resolved by an external name system like DNS, or an IP address or other direct address. The port signifies the port number where PostgreSQL is listening.

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

postgresql://

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

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は、特定のデータベースに接続するために必要なすべての情報を1つの文字列内にエンコードします。この柔軟性とその広範な採用により、これらの文字列を解析および構築する方法を理解することは非常に役立ちます。