PostgreSQL 連線 URI 簡介

簡介

連線到您的資料庫伺服器通常是設計和設定資料庫支援應用程式時，您需要完成的首要任務之一。雖然有很多方法可以將位址、監聽埠、憑證和其他詳細資訊提供給應用程式，但連線 URI（有時稱為連線字串或連線 URL）是以精簡格式指定複雜設定的最強大且靈活的方式之一。

在本指南中，我們將討論如何使用您的 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：選用使用者名稱。如果包含，它應該在第二個斜線 (/) 之後開始，並持續到冒號 (:)（如果也提供了密碼）或直到 at 符號 (@)（如果未提供密碼）。
  • password：選用密碼。如果包含，它會在冒號 (:) 之後開始，並持續到 at 符號 (@)。
• hostspec：選用元件，用於指定要連線的主機名稱和埠號。
  • host：要連線的伺服器的選用 IP 位址、DNS 名稱或本機可解析名稱。主機持續到冒號 (:)（如果包含埠號）或直到斜線（如果未包含埠號）
  • port：選用埠號規格，用於指示 PostgreSQL 在伺服器上監聽的埠號。埠號以冒號 (:) 開頭，並持續到斜線 (/)
• database name：要連線的個別資料庫的名稱。
• parameter list：選用的其他參數清單，可能會影響連線行為。參數清單以問號 (?) 開頭。
  • parameter pairs：參數清單由鍵值對組成。每個配對中的鍵和值以等號 (=) 分隔，並且每個配對與下一個配對之間以 and 符號 (&) 分隔。

以下是包含所有這些元件的 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

postgresql://
postgres://

結構描述指示符將確保後續的資訊在正確的上下文中解譯。

指定使用者名稱和密碼

URI 的下一個部分是使用者憑證。這在規格中稱為 userspec。userspec 在技術上是選用的，但如果您不想依賴應用程式或資料庫設定的預設值，則通常是必需的。

如果包含，userspec 從冒號和雙正斜線 (://) 之後開始，並以 at 符號 (@) 結束。

若僅指定使用者名稱，您可以將其放置在這兩個符號之間

postgresql://username@

若要指定使用者名稱和密碼，請先提供使用者名稱，後跟冒號 (:)，然後是密碼和 at 符號

postgresql://username:password@

應用程式能夠透過注意包含終止 at 符號 (@) 來將此資料解譯為 userspec。如果僅提供一個欄位（如果斜線和 at 符號之間沒有冒號），則它會被解譯為使用者名稱。

指定伺服器監聽位置

在 userspec 之後是 hostspec，它定義了伺服器監聽的位置。hostspec 再次是選用的，但如果您不依賴用戶端或程式庫中設定的預設值，則幾乎總是很有用。

hostspec 由 host 和選用的 port 組成。host 可以是本機可解析的主機名稱、由外部名稱系統（如 DNS）解析的名稱，或 IP 位址或其他直接位址。埠號表示 PostgreSQL 正在監聽的埠號。

若要指定應用程式應嘗試連線到本機電腦上的預設 PostgreSQL 埠號 (5432)，您可以使用

postgresql://127.0.0.1

如果您需要包含使用者名稱和密碼，則該資訊將放在前面，並以 at 符號分隔

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 的最後一部分用於為連線提供其他參數。參數清單由前導問號 (?) 引入，並持續到行尾。

列出的每個參數都定義為以等號 (=) 連接的鍵值對。在第一個參數配對之後，每個額外的鍵值對都以 and 符號 (&) 分隔。

例如，若要指定用戶端應為我們先前定義的連線應用 10 秒逾時，您可以使用

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

如果您想要提供其他參數，您可以在之後新增它們，並在每對之間使用 and 符號 (&)。例如，我們可以另外指定我們需要 SSL，並且只想在伺服器是副本集中主要伺服器時才連線，我們可以額外新增

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

PostgreSQL 文件有一個完整參數清單，您可以閱讀以了解更多資訊。

結論

在本指南中，我們討論了什麼是 PostgreSQL 連線 URI、如何解譯各種元件，以及如何在給定一組連線資訊的情況下建構您自己的 URI。連線 URI 將連線到給定資料庫所需的所有資訊編碼在單一字串中。由於這種靈活性及其廣泛採用，了解如何剖析和建構這些字串可能會非常有幫助。