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: 可選的使用者名稱。如果包含，應在第二個斜槓 (/) 之後開始，並持續到冒號 (:)（如果也提供了密碼）或直到 @ 符號 (@)（如果未提供密碼）。
  • 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 應該以這兩個字串中的任意一個開頭

postgresql://
postgres://

模式指定符將確保後續資訊在正確的上下文中被解釋。

指定使用者名稱和密碼

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

如果包含，userspec 在冒號和雙斜槓 (://) 後開始，並以 @ 符號 (@) 結尾。

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

postgresql://username@

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

postgresql://username:password@

應用程式透過注意終止的 @ 符號 (@) 的包含來將此資料解釋為 userspec。如果只提供一個欄位（如果斜槓和 @ 符號之間沒有冒號），則將其解釋為使用者名稱。

指定伺服器監聽位置

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

hostspec 由一個 host 和一個可選的 port 組成。host 可以是本地可解析的主機名、由DNS等外部命名系統解析的名稱，也可以是IP地址或其他直接地址。埠表示PostgreSQL正在監聽的埠號。

要指定應用程式應嘗試連線到本地計算機上的預設 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 將連線到給定資料庫所需的所有資訊編碼在一個字串中。由於其靈活性和廣泛採用，理解如何解析和構建這些字串會非常有幫助。